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

# 回收资源

支持通过订单 ID 单笔回收，或通过接收地址和资源类型批量回收能量直达订单的能量或带宽，适用于合作方余额支付和合作方终端用户支付两种方式。

## 按订单 ID 回收

{% openapi src="/files/mASYqPqYbNkoFrs0gDaT" path="/v1/mate/open/transaction/reclaim/{order\_id}" method="post" %}
[mate-transaction-api.json](https://1836196186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6OSDuieZV2PmhnU7qYgh%2Fuploads%2Fgit-blob-62fdeda133f249e9bd7adbb71207855d05bf6296%2Fmate-transaction-api.json?alt=media)
{% endopenapi %}

### 请求说明

* `order_id` 为创建订单返回的 `data.order_id`，不是代理交易 `data.hash` 或 `client_order_id`。只能回收当前账户的订单。
* 请求无需请求体，需携带 API 鉴权头。签名使用 `POST` 和替换订单 ID 后的完整路径，详见 [API概览](https://docs.catfee.io/getting-started/buy-energy-via-api-on-catfee/api-overview.md)。

### 回收结果

`code=0` 表示回收请求已受理，**不代表链上回收已经完成**。暂时无法回收时，订单会提前到期并继续处理；代理尚未确认的订单也可以申请提前回收。

响应中的 `data` 为订单信息。通过 [查询订单信息](https://docs.catfee.io/api-reference/transaction/get-transaction.md) 查看 `confirm_status`：

| `confirm_status`         | 含义             |
| ------------------------ | -------------- |
| `RECLAIM_CONFIRMING`     | 回收交易等待链上确认。    |
| `RECLAIM_CONFIRMED`      | 回收已在链上确认。      |
| `RECLAIM_CONFIRMED_FAIL` | 回收确认失败，尚未完成回收。 |

返回其他确认状态时，也不能视为回收完成。`status=CONFIRMED` 仅表示代理交易已确认，请以 `confirm_status=RECLAIM_CONFIRMED` 判断回收完成。

## 按接收地址批量回收

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

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

### 请求说明

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

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

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

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

```http
POST /v1/mate/open/transaction/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
```

### 处理范围

* 仅处理当前认证会员名下、接收地址和资源类型匹配、代理已确认（`confirm_status=DELEGATION_CONFIRMED`）的能量直达订单。与按订单 ID 回收不同，代理尚未确认的订单不在批量回收范围内。
* 每次最多匹配并处理 100 条订单。
* 优先尝试回收；暂时无法回收时，提前订单到期时间，由后台继续处理。受理成功不代表链上回收完成。

### 响应与结果确认

响应 `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)。
* 没有匹配订单时，返回 `matched_count=0`、`accepted_count=0` 和 `failed_order_ids=[]`。
* 当 `matched_count=100` 时，可能仍有剩余订单。先查询订单确认处理进度，再决定是否继续申请；不要将多次调用的受理数直接相加作为已回收订单总数。
* 对失败订单或结果不确定的订单，通过 `GET /v1/mate/open/transaction/{order_id}` [查询订单信息](https://docs.catfee.io/api-reference/transaction/get-transaction.md)，以 `confirm_status=RECLAIM_CONFIRMED` 判断链上回收完成。不要仅凭 `status=CONFIRMED` 或批次受理数判断回收完成。
