> 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/reclaim-energy.md).

# 回收能量

通过订单 ID 或接收地址申请回收已租赁的能量或带宽

支持通过订单 ID 单笔回收，或通过接收地址和资源类型批量回收能量或带宽。

## 按订单 ID 回收

通过 `POST /v1/reclaim/{id}` 为指定订单申请回收能量。

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

### 请求说明

* 将路径中的 `{id}` 替换为创建订单时返回的 `data.id`，不要使用 `client_order_id`。
* 请求需要携带 `CF-ACCESS-KEY`、`CF-ACCESS-SIGN` 和 `CF-ACCESS-TIMESTAMP` 三个鉴权头；该接口无需请求体。
* 签名时使用 HTTP 方法 `POST` 和替换订单 ID 后的完整路径，例如 `/v1/reclaim/your_order_id`。签名规则见 [API概览](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-overview.md)。

请求示例（请替换订单 ID、鉴权信息和时间戳）：

```http
POST /v1/reclaim/your_order_id HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: your_api_key
CF-ACCESS-SIGN: generated_signature
CF-ACCESS-TIMESTAMP: current_utc_timestamp
```

### 响应与结果确认

接口返回订单数据，字段定义与[订单详情](https://docs.catfee.io/api-reference/order-detail.md)一致。

* `code=0` 表示本次申请调用成功，**不表示链上回收已经完成**。非零码的含义及处理方式见 [API 错误码与处理说明](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-error-codes.md)。
* 申请后可通过 `GET /v1/order/{id}` 查询订单，结合 `reclaim_hash`、`reclaim_timestamp` 和链上资源情况确认回收结果。
* `status` 和 `confirm_status` 表示订单的代理进度，回收后仍可能保持 `DELEGATE_SUCCESS` 和 `DELEGATION_CONFIRMED`。不要等待这两个字段变为回收状态，也不要据此判断能量仍可使用。
* `balance` 为用户当前余额，单位是 SUN（1 TRX = 1,000,000 SUN），不是本次回收金额。

遇到超时、连接中断或操作结果无法确认时，先查询原订单；无法确认时联系支持，避免反复提交回收申请。

## 按接收地址批量回收

使用 `POST /v1/reclaim`，按接收地址和资源类型批量申请回收当前会员的订单，无需逐个传入订单 ID。

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

### 请求说明

参数通过 URL 查询字符串传入，无需请求体。

| 参数              | 类型     | 必填 | 说明                                                                |
| --------------- | ------ | -- | ----------------------------------------------------------------- |
| `receiver`      | string | 是  | 接收资源的有效 TRON 地址。                                                  |
| `resource_type` | string | 否  | `ENERGY`（能量）或 `BANDWIDTH`（带宽），默认 `ENERGY`。回收带宽时需明确传入 `BANDWIDTH`。 |

请求需要携带与单笔回收相同的三个鉴权头。签名使用 HTTP 方法 `POST` 和**包含完整查询字符串的请求路径**；参数顺序及编码应与实际请求一致。签名规则见 [API概览](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-overview.md)。

请求示例（请替换接收地址、鉴权信息和时间戳）：

```http
POST /v1/reclaim?receiver=TJRabPrwbZy45sbavfcjinPJC18kjpRTv8&resource_type=ENERGY HTTP/1.1
Host: api.catfee.io
CF-ACCESS-KEY: your_api_key
CF-ACCESS-SIGN: generated_signature
CF-ACCESS-TIMESTAMP: current_utc_timestamp
```

### 处理范围

* 仅处理当前认证会员名下、接收地址和资源类型匹配、内部订单状态为 `DELEGATE_SUCCESS` 的订单，不限制确认状态；代理尚未确认的订单也可能被匹配。
* 每次最多匹配 100 条订单并逐笔处理。未代理成功、正在回收或已回收的订单不在本次筛选范围内。订单详情中的 `status` 会映射内部回收状态，因此仅凭其返回 `DELEGATE_SUCCESS` 不能判断订单是否会被匹配。
* 每笔订单先尝试直接回收；回收失败或未执行时，将到期时间提前至当前时间（已到期的保持原值），由后台继续处理。
* 单笔订单的到期更新或重新查询失败时，将该订单计入失败列表，并继续处理其他订单；批次查询失败时，接口仍返回错误。

### 响应与结果确认

响应 `data` 为批次处理结果，不是订单详情。以下为部分订单未受理的响应示例：

```json
{
  "code": 0,
  "msg": "",
  "data": {
    "matched_count": 3,
    "accepted_count": 2,
    "failed_order_ids": ["failed_order_id"]
  }
}
```

| 字段                 | 类型        | 说明                                      |
| ------------------ | --------- | --------------------------------------- |
| `matched_count`    | integer   | 本次匹配的订单数，最多 100；不是该地址的订单总数。             |
| `accepted_count`   | integer   | 已受理的订单数，包括直接回收或成功进入到期兜底处理的订单；不代表链上回收完成。 |
| `failed_order_ids` | string\[] | 本次未能受理的订单 ID；全部受理时为空数组。                 |

* `code=0` **不表示所有订单均已受理，也不表示链上回收完成**。请同时检查计数及 `failed_order_ids`，非零码见 [API 错误码与处理说明](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-error-codes.md)。
* 没有匹配订单时，返回 `code=0`、`matched_count=0`、`accepted_count=0` 和 `failed_order_ids=[]`。
* 当 `matched_count=100` 时，可能仍有剩余订单，可再次调用处理。进入到期兜底处理的订单若内部状态尚未变化，后续调用仍可能匹配到它们，因此不要将多次调用的计数直接相加作为已回收订单总数。
* 对失败订单或结果不确定的订单，先通过 `GET /v1/order/{id}` 查询，结合 `reclaim_hash`、`reclaim_timestamp` 和链上资源情况确认结果，再决定是否重试。不要仅凭 `status` 和 `confirm_status` 判断回收是否完成。
