> For the complete documentation index, see [llms.txt](https://docs.catfee.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catfee.io/api-reference/create-order.md).

# 购买能量

{% openapi src="/files/X0GExwrGaywXyFiL8Yfs" path="/v1/order" method="post" %}
[api.json](https://1836196186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6OSDuieZV2PmhnU7qYgh%2Fuploads%2Fgit-blob-4c80f5c197caa6aaac0b9eb606e3908753d86e49%2Fapi.json?alt=media)
{% endopenapi %}

**关键 API：创建订单（POST /v1/order）**

在通过 CatFee.IO 的 API 创建订单时，需要特别关注以下三个返回值：

1. **`id`（支付哈希/订单 ID）：**
   * 每个订单的唯一标识符。
   * 可通过 **GET `/v1/order/{id}`** 接口查询该订单的详细信息。
2. **`status`（订单状态）：**
   * 反映订单的执行进度。
   * 当 `status` 为 `DELEGATE_SUCCESS` 时，表示能量交易已成功提交到波场区块链。
   * 注意：存在极小概率（约 0.1%）交易未能上链的情况。
3. **`confirm_status`（链上确认状态）：**
   * 确认能量是否已成功发送至目标地址。
   * 当 `confirm_status` 为 `DELEGATION_CONFIRMED` 时，表示能量已成功发送并在链上确认。
4. **client\_order\_id (客户端自定义的订单 ID）:**

   用户幂等请求，详见：[API支持幂等请求](/getting-started/api-supports-idempotent-requests.md)

***

**Q：如何百分百保证能量已发送到目标地址？**

您可以通过以下两种方式确认能量已发送成功：

1. **通过波场 API 查询目标地址的能量余额：**
   * 使用波场官方 API 或钱包工具（如 TronLink）查询目标地址的能量余额。
   * 示例 API 请求（波场官方接口）：

     Copy

     ```
     curl --request POST \
          --url https://api.trongrid.io/wallet/getaccountresource \
          --header 'accept: application/json' \
          --header 'content-type: application/json' \
          --data '
     {
       "address": "TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
       "visible": true
     }
     '
     ```

     在返回的响应中查看能量相关字段，如 `energy_limit` 和 `energy_used` 字段。
2. **查询订单的 `confirm_status`：**
   * 使用 **GET `/v1/order/{id}`** 接口查询订单详情。
   * 如果 `confirm_status` 为 `DELEGATION_CONFIRMED`，表示能量交易已成功在链上确认，目标地址已收到能量。

***

**操作流程示例**

**1. 创建订单**

请求示例：

Copy

```
POST /v1/order?count=1&target_address=TRON_ADDRESS&peroid=1
Host: https://api.catfee.io
Headers: 
  Content-Type: application/json
  CF-ACCESS-KEY: {api_key}
  CF-ACCESS-SIGN: {signature}
  CF-ACCESS-TIMESTAMP: {timestamp}

```

响应示例：

Copy

```
{
  "code":0,
  "data":{
    "id": "abcd1234",
    "status": "DELEGATE_SUCCESS",
    "confirm_status": "UNCONFIRMED"
  }
}
```

***

**2. 查询订单状态**

请求示例：

Copy

```
GET /v1/order/abcd1234
Host: https://api.catfee.io
Headers: 
  Content-Type: application/json
  CF-ACCESS-KEY: {api_key}
  CF-ACCESS-SIGN: {signature}
  CF-ACCESS-TIMESTAMP: {timestamp}
```

响应示例：

Copy

```
{
  "code":0,
  "data":{
    "id": "abcd1234",
    "status": "DELEGATE_SUCCESS",
    "confirm_status": "DELEGATION_CONFIRMED"
  }
}
```

***

**3. 确认能量是否发送成功**

* 如果 `confirm_status` 为 `DELEGATION_CONFIRMED`，说明能量已发送成功。
* 您也可以通过波场 API 查询目标地址的能量余额，以进一步验证。

***

**常见问题说明**

1. **订单状态为 `DELEGATE_SUCCESS` 但能量未到账？**
   * 原因：可能交易未能上链（概率约为 0.1%）。
   * 解决方案：稍等一段时间后查询订单状态或通过波场区块链查看交易详情。
2. **能量到账延迟问题？**
   * 原因：可能与区块链网络拥堵有关。
   * 解决方案：确保订单状态为 `DELEGATION_CONFIRMED` 后即可确认能量已到账。

***

通过关注订单的 **`id`** 和 **`confirm_status`**，以及链上验证方法，您可以确保能量交易的可靠性。如果仍有问题，可联系 CatFee 客服([@CatFee\_James](https://t.me/CatFee_James))获取支持。