# 可靠接入波场能量 API：幂等、回调与订单对账

从业务订单号到最终交付，介绍整数 SUN 精度、请求超时处理、重复回调与有界重试，帮助开发者避免重复下单和状态误判。

Canonical: https://tronow.io/zh-CN/guides/reliable-energy-integration/
Reviewed by TRONow · 2026-09-12

## 先创建一笔本地业务订单

为业务操作生成唯一 client_order_id，在自己的数据库中先保存能量数量、租期与接收地址，并对业务编号建立唯一约束，防止并发任务重复创建。本篇描述接入参考实现，不代表某个客户的生产使用成果。

## 获取与下单参数一致的报价

通过 GET /prices/quote 查询实际资源数量与租期，将 quote_id、返回金额和 expires_at 一起保存。金额为整数 SUN 字符串，请使用整数或精确十进制类型。业务数量改变时重新报价，不要修改旧报价所对应的订单数量。

## 签名必须对应实际请求字节

签名凭据仅保存在服务端。请求体只序列化一次，按接口规范与参考客户端对实际发送的字节进行签名，避免“签一种 JSON，发另一种 JSON”。应用日志应隐藏密钥与认证请求头。

## 幂等键也要持久化

POST /orders 除 client_order_id 外，还要求 8–128 个可见 ASCII 字符组成的 Idempotency-Key。提交前保存幂等键与实际请求字节。重试结果不确定的创建请求时，保持二者不变，并生成新的时间戳、nonce 与签名。只有查清前次是否受理后，才能处理报价过期并重新发起。Webhook 验证规则见公开 Skill；地址激活没有回调，应通过查单跟踪。

## 处理结果不确定的下单请求

使用原 client_order_id 调用 POST /orders。连接超时后，优先通过 GET /orders?client_order_id={client_order_id} 查单。已存在的订单应继续跟踪，不应换新业务编号重复提交。如果适合重试，保留相同编号及请求语义；幂等冲突应作为业务异常排查。

## 区分受理、处理中与完成

保存平台订单号及返回状态，依据文档中的终态与交付证据更新本地履约状态。HTTP 成功本身不能证明能量已委托。保留失败和待审核状态，让人员能处理异常，避免静默循环或重复记账。

## 回调验签并去重

按接口规范验证 Webhook，拒绝签名无效的通知，在应用状态变更前按事件编号去重。事件可靠落库或处理完成后再确认接收。应容忍重复投递，本地状态与远端不一致时通过查单接口对账。

## 控制重试并保留可追踪记录

设置请求超时、带上限的指数退避与有限重试次数。记录 client_order_id、平台订单号、状态变化及不含秘密的错误码。未决订单使用应用队列或定时对账处理，不要在浏览器高频轮询。

## 上线前验证异常分支

在受控环境检查余额不足、报价过期、业务编号重复、受理后超时、重复回调及错误签名。每种情况都应最多产生一笔预期业务订单，且本地记录能说明处理经过。下方规范与客户端描述真实接口格式，本文不承诺所有语言都有 SDK。

## 资料中心

- [波场能量是什么？USDT 转账为什么要租能量？](https://tronow.io/zh-CN/guides/tron-energy-usdt/)
- [通过 API 稳定完成波场能量下单](https://tronow.io/zh-CN/guides/tron-energy-api/)
- [关于 TRONow：波场能量租赁与商户 API](https://tronow.io/zh-CN/about/)
- [波场能量价格怎么算？TRONow 报价与付款规则](https://tronow.io/zh-CN/pricing/)
- [TRONow 常见问题：购买能量、充值与 API 接入](https://tronow.io/zh-CN/faq/)

## 开发者接入资料

- [OpenAPI](https://tronow.io/developers/openapi.yaml)
- [Skill: authentication, idempotency, webhook verification](https://tronow.io/developers/tronow-connect/SKILL.md)
- [Node.js](https://tronow.io/developers/tronow-connect/client.mjs)