开放 API 适合需要批量下单、自动补能量或把租赁能力嵌入自有系统的团队。
这篇文章说明接入流程、签名算法、下单与轮询的正确姿势，以及如何用幂等键安全重试。
接口能力概览
| 能力 | 接口示例 | 说明 |
|---|---|---|
| 探活 | /api/v1/ping | 检查服务与鉴权是否正常 |
| 价格查询 | /api/v1/query_price | 按资源类型、数量、租期查询价格 |
| 购买能量 | /api/v1/buy_energy | 异步受理，返回订单号 |
| 订单结果 | /api/v1/query_result | 轮询订单最终状态 |
| 账户信息 | /api/v1/user_info | 查询余额与账户信息 |
| 智能托管 | /api/v1/delegate_energy_smart | 按地址监控并自动补能量 |
| 笔数模式 | /api/v1/delegate_energy_times | 按笔数批量委托 |
认证：请求级 HMAC-SHA256 签名
每个请求都需要携带 x-api-key、x-timestamp、x-nonce、x-signature 四个请求头，下单接口还需要 x-idempotency-key。
签名串由请求方法、路径、查询串、请求体 SHA-256 哈希、时间戳、随机串、API Key 与幂等键依次拼接而成，任何一个字段变化都必须重新签名。
string_to_sign = "\n".join([
method, # GET / POST
path, # /api/v1/buy_energy
raw_query, # 查询串，没有则为空字符串
sha256(raw_body), # 请求体的 SHA-256 十六进制
timestamp, # 10 位 Unix 时间戳
nonce, # 每次请求唯一的随机串
api_key,
idempotency_key, # 非下单接口传空字符串
])
signature = hmac_sha256(api_secret, string_to_sign).lower()时间戳允许与服务端相差 ±5 分钟，nonce 不允许重复使用。签名失败通常来自这三点：请求体被序列化过两次、查询串与实际发送不一致、复用了旧的 nonce。
下单与状态轮询
下单接口在校验、扣款后立即返回订单号，委托在后台异步执行。正确做法是拿到订单号后每 1~2 秒轮询一次订单结果，直到状态进入终态。
| 状态 | 含义 | 建议动作 |
|---|---|---|
| pending | 订单已创建，等待处理 | 继续轮询 |
| processing | 已受理并扣款，委托执行中 | 每 1~2 秒轮询 |
| completed | 能量已成功委托 | 结束流程 |
| failed | 执行失败，余额已退回 | 检查参数后重试 |
| refund_pending | 失败待退款审核 | 等待平台确认，不要重复下单 |
| refunded | 已退款 | 结束流程 |
幂等与重试策略
- 下单请求必须携带 x-idempotency-key，网络超时后沿用同一个键重试，服务端只会创建一个订单。
- 收到 425（相同幂等键处理中）时不要换键重试，稍后用同一个键查询或重试。
- 收到 429（请求过于频繁）时降低频率，默认每个 API Key 每分钟 300 次，轮询间隔建议不低于 1 秒。
- 请求 body 序列化方式要固定，JSON 键顺序与空格差异都会导致签名不一致。
错误码速查
| HTTP 状态 | 含义 | 处理方式 |
|---|---|---|
| 401 | 认证失败 | 核对 API Key、时间戳、nonce 与签名串 |
| 403 | IP 不在白名单 | 在 API Key 设置中添加当前出口 IP |
| 409 | 判定为重放 | 更换新的 nonce 与时间戳后重新签名 |
| 425 | 相同幂等键处理中 | 沿用同一个幂等键稍后重试 |
| 429 | 请求过于频繁 | 降低请求频率 |
| 503 / 504 | 服务繁忙或超时 | 用同一个幂等键重试，或用订单结果接口确认状态 |
上线前的检查清单
- API Key 已配置 IP 白名单，密钥保存在服务端而不是前端。
- 签名逻辑有单元测试，覆盖 GET 与 POST、带查询串与不带查询串的情况。
- 下单流程带幂等键，超时重试不会重复下单。
- 订单状态有终态判断，轮询不会无限执行。
- 对账逻辑：记录订单号、状态、金额，定期核对平台订单记录。
需要直接下单？注册后即可选择能量档位与租期，能量通常数秒内委托到账；下单前可以用 费用计算器 估算成本。