# 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）交易更加顺畅无忧！🚀


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catfee.io/getting-started/api-supports-idempotent-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.