HTTP API

API 信息与接口说明

面向集成方说明如何调用开放接口：基地址与版本、鉴权方式、可选的 HMAC 请求签名、示例代码与常见错误。文中域名为示例，请替换为实际部署。

概述

开放 API 采用 HTTPS JSON 语义：除特别说明外，请求与响应体均为 UTF-8 JSON，Accept 建议使用 application/json。

所有示例仅用于说明字段与流程；生产环境请使用控制台颁发的密钥，并妥善保管私钥与 Webhook Secret。

环境与基地址

生产：基地址示例为 https://api.example.com，路径以 /v1 为版本前缀。

预发 / 沙箱：建议使用独立子域与密钥，避免与生产数据混用；可在控制台切换环境并复制对应的 Base URL。

鉴权

推荐在 Authorization 头携带 Bearer Token，格式为「Bearer 」后拼接访问令牌（控制台下发的 JWT 或访问令牌字符串）。

部分内部或机到机场景可支持 API Key（X-Api-Key），具体以控制台开通的能力为准；切勿在浏览器前端暴露长期密钥。

建议在 X-Request-Id 传入 UUID，便于链路追踪与排障。

请求签名（可选）

在开启「签名校验」的应用中，除鉴权头外还需携带 X-Timestamp（Unix 秒）与 X-Nonce（随机串），并提供 X-Signature。

签名字符串按固定顺序拼接 METHOD、PATH（含查询串）、TIMESTAMP、NONCE、以及请求体字节经 SHA256 的十六进制小写摘要；空体使用空串的摘要占位。

使用控制台下发的 Signing Secret 对 canonical 串做 HMAC-SHA256，输出十六进制小写，放入 X-Signature。服务端使用同一算法重算并比对，拒绝重放与篡改。

规范摘要（伪代码）

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + SHA256(UTF8(BODY_OR_EMPTY))
signature = HMAC_SHA256(secret, UTF8(canonical)) // hex 小写输出

使用 cURL 调用

下列示例展示最小只读请求：替换域名与 Token 后即可在终端验证连通性与鉴权是否生效。

curl -X GET 'https://api.example.com/v1/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-Request-Id: 550e8400-e29b-41d4-a716-446655440000'

在 JavaScript / Node 中调用

浏览器或 Node 18+ 可使用原生 fetch；在服务端集成时优先把密钥放在环境变量或密钥管理系统中，不要写入仓库。

const res = await fetch('https://api.example.com/v1/me', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Request-Id': crypto.randomUUID(),
  },
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
const data = await res.json()

错误码与排障

401 Unauthorized：Token 缺失、过期或无效；请刷新令牌或重新授权。

403 Forbidden：权限不足或签名未通过；核对签名算法、时钟偏移与密钥环境是否一致。

429 Too Many Requests：触发频控；请阅读 Retry-After 并做指数退避。

5xx：服务端异常；请携带 X-Request-Id 联系支持并稍后重试。

频率限制

默认按「应用 + IP」或「应用 + 主体」维度滑动窗口限流，响应头包含 X-RateLimit-Remaining 与 X-RateLimit-Reset。

批量任务请使用异步任务接口或申请提高配额；突发流量建议接入队列与退避重试。

Webhook 回调验签

事件投递 HTTP POST 至你登记的 URL，请求体为 JSON，头中包含 X-Webhook-Timestamp 与 X-Webhook-Signature。

将 timestamp + "." + rawBody 作为消息，使用 Webhook Secret 做 HMAC-SHA256，与头中签名比对（注意时间窗防重放）。

验签通过后应尽快返回 2xx；失败重试策略为指数退避，请保证接口幂等。