# API支持幂等请求

🚀 **CatFee 购买能量 API 现已支持幂等性！** 通过新增可选参数 `client_order_id`，用户可确保相同请求不会被重复执行，有效避免**重复扣款**、**订单状态不一致**等问题，让交易更加安全可靠！

***

### **🔍 什么是幂等性？为什么重要？**

幂等性（Idempotency）指的是**无论同一个请求被提交多少次，最终的结果都是一致的，不会导致重复执行**。这对于支付类、购买类的 API 尤其重要，能够有效防止：

* **网络超时导致的重复扣费**
* **系统异常引发的状态不一致**
* **用户误操作的多次提交**

**🚀 现在，CatFee 购买能量 API 通过 `client_order_id` 实现幂等性，确保相同请求不会被重复执行，交易更安全可靠！**

***

### **🛠 如何使用 CatFee 购买能量 API 进行幂等请求？**

#### **📌 请求示例**

根据 CatFee.IO Rest API 规则，**所有请求参数通过 query parameter 方式传递**，签名计算方式**不包含 query parameters**，请求示例如下：

**示例 POST 请求**

假设用户希望购买 65000 能量，并使用 `client_order_id=abc123` 实现幂等性，完整请求如下：

```http
POST https://api.catfee.io/v1/order?quantity=65000&receiver=TRON_ADDRESS&duration=1h&client_order_id=abc123
```

#### **📌 请求头**

```http
Content-Type: application/json
CF-ACCESS-KEY: your_api_key
CF-ACCESS-SIGN: generated_signature
CF-ACCESS-TIMESTAMP: 2023-08-26T12:34:56.789Z
```

#### **📌 参数说明**

| 参数名                   | 类型     | 是否必填 | 说明                  |
| --------------------- | ------ | ---- | ------------------- |
| `quantity`            | int    | 是    | 购买的能量数量（单位：Energy）  |
| `receiver`            | string | 是    | 接收能量的 TRON 地址       |
| `duration`            | string | 是    | 能量租赁时长，例如 `1h`      |
| `client_order_id`     | string | 否    | 客户端自定义的订单 ID，用于幂等请求 |
| `CF-ACCESS-KEY`       | string | 是    | API 访问密钥            |
| `CF-ACCESS-SIGN`      | string | 是    | 请求签名，确保请求安全性        |
| `CF-ACCESS-TIMESTAMP` | string | 是    | 当前 UTC 时间戳（用于签名）    |

**🔹 幂等性逻辑**

* **如果 `client_order_id` 是第一次提交**，则系统创建新的能量购买订单，并返回订单详情。
* **如果 `client_order_id` 已提交过**，系统会直接返回之前的订单结果，而不会重新扣款或创建新订单。

***

### **📄 返回示例**

#### **🎯 第一次请求成功**

```json
{
  "code": 0,
  "data": {
    "id": "xyz987",
    "client_order_id":"abc123",
    "pay_timestamp": 1700000000,
    "receiver": "TRON_ADDRESS",
    "delegate_hash": "abc123def456",
    "delegate_timestamp": 1700000050,
    "reclaim_hash": "ghi789jkl012",
    "reclaim_timestamp": 1700000100,
    "pay_amount_sun": 10500000,
    "activate_amount_sun": 10500000,
    "quantity": 65000,
    "staked_sun": 10000000,
    "duration": 1,
    "expired_timestamp": 1700003600,
    "balance": 65000,
    "resource_type": "ENERGY",
    "billing_type": "TRANSFER",
    "status": "PAYMENT_SUCCESS",
    "activate_status": "DEACTIVATE",
    "confirm_status": "UNCONFIRMED"
  }
}
```

#### **🔄 相同 `client_order_id` 再次提交**

如果用户因网络问题或超时而重复提交相同 `client_order_id`，API 会返回**相同的订单信息**，避免重复购买：

```json
{
  "code": 0
  "sub_code": "SUCCESS",
  "sub_msg": "Duplicate order request, returning existing order",
  "data": {
    "id": "xyz987",
    "client_order_id":"abc123",
    "pay_timestamp": 1700000000,
    "receiver": "TRON_ADDRESS",
    "delegate_hash": "abc123def456",
    "delegate_timestamp": 1700000050,
    "reclaim_hash": "ghi789jkl012",
    "reclaim_timestamp": 1700000100,
    "pay_amount_sun": 10500000,
    "activate_amount_sun": 10500000,
    "quantity": 65000,
    "staked_sun": 10000000,
    "duration": 1,
    "expired_timestamp": 1700003600,
    "balance": 65000,
    "resource_type": "ENERGY",
    "billing_type": "TRANSFER",
    "status": "PAYMENT_SUCCESS",
    "activate_status": "DEACTIVATE",
    "confirm_status": "UNCONFIRMED"
  },

}
```

**✅ 这样可以有效避免因误操作或网络抖动导致的重复扣款问题！**

***

### **🎯 适用场景：幂等 API 如何提高交易安全性？**

#### **📌 1. 解决网络超时导致的重复提交**

* 用户调用 API 购买能量，但因网络波动未及时收到响应，误以为交易失败并再次提交请求。
* **使用 `client_order_id`，即使请求重复提交，也不会执行重复购买。**

#### **📌 2. 避免批量交易时的异常扣费**

* 自动化脚本或程序批量购买能量时，可能因异常中断导致部分请求未完成。
* **通过 `client_order_id` 追踪请求状态，防止某些订单被重复执行，确保交易准确性。**

#### **📌 3. 提高 API 调用的可靠性**

* 许多支付系统、交易所 API 都要求请求具备幂等性，以确保交易安全。
* **CatFee 现在支持幂等性，适用于各种业务场景，提高系统的可靠性和稳定性。**

***

### **🚀 CatFee 让能量交易更高效、更安全！**

CatFee 一直致力于优化用户体验，现在**购买能量 API 已支持幂等性**，通过 `client_order_id` 让交易更安全、避免重复扣费，让 API 调用更加稳定可靠！

立即体验 **CatFee 购买能量 API**，让您的波场（TRON）交易更加顺畅无忧！🚀