归集开放平台

完整业务配置流程 ​

这套配置可以全部由三方服务端通过API完成。使用appID和密钥换取accessToken，每个请求带Bearer令牌并重新计算HMAC-SHA256签名。

1. 获取并缓存 accessToken ​

先调用获取accessToken，把当前令牌交给共享令牌管理器；每次成功换取都会撤销旧令牌。后续所有接口都带逐请求签名，JSON中的request_id也属于签名正文。

2. 创建收款钱包 ​

调用创建钱包，为每个钱包指定同租户唯一的custom_id和已持久化的request_id。保存返回的钱包ID与地址。

3. 设置统一USDT归集目标 ​

POST /open/v1/settings/addresses/collection

json
{
  "address": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8",
  "request_id": "collection-address-20300101-0001"
}

此地址只是统一收款目标，必须使用合法的平台外 TRON 地址，不需要向平台提供私钥。不能填写通过本平台创建的钱包，也不能填写平台内其他租户的钱包，否则返回 HTTP 400 / COLLECTION_ADDRESS_MANAGED，以避免循环归集。示例地址仅演示格式，实际填写你控制的目标。所有收款钱包从统一配置读取目标，不逐钱包设置。

目标变化会取消尚未签名的旧目标归集任务；已签名交易继续使用原目标。详见设置归集地址。

4. 保存自动归集策略 ​

POST /open/v1/settings/automation

下面开启100 USDT阈值的自动归集：

json
{
  "enabled": true,
  "usdt_minimum": "100000000",
  "request_id": "automation-20300101-0001"
}
  • GMT+8每天10:00：符合USDT阈值的收款钱包全额归集。

配置保存前的计划时间不补执行；同request_id重试不会再次推进配置时间。完整策略参数。

5. 配置并开启Webhook ​

先准备可以处理加密回调的公网HTTPS接收服务，再调用 POST /open/v1/settings/webhook：

json
{
  "url": "https://merchant.example.com/guiji/webhook",
  "enabled": true,
  "request_id": "webhook-config-20300101-0001"
}

把示例域名换成你的域名，仅支持443端口。接收方验证AES-GCM并解密，把事件去重与业务处理在同一数据库事务提交，然后返回HTTP200和{"code":"SUCCESS"}。设置回调配置 · 回调解密。

配置变更供新轮次使用，已经开始的轮次保留原URL。未配置或关闭时事件会明确记录异常；修复配置后用新request_id重新推送异常事件。

6. 核对到账和归集结果 ​

使用钱包列表与到账流水核对已确认链数据。余额可能有同步延迟，balance_block为"0"代表首次同步尚未完成。

手动归集前可批量预览钱包和预估手续费，再创建归集任务。预估不锁定余额或目标，提交后要读取归集详情或接收最终结果回调，不能把HTTP200当作链上成功。

通过通知列表、推送轮次和尝试记录检查回调状态。到账或归集成功与通知成功是独立状态。

重试保持业务编号 ​

所有配置写入和通知重推使用JSON request_id；同租户、同操作、同键同参数返回原结果，同键异参409。保存同一业务请求的编号和参数，使用新时间戳和当前令牌重新签名重试。幂等与重试。