<aside> <img src="/icons/alert_blue.svg" alt="/icons/alert_blue.svg" width="40px" />

您可以自行选择是否对数据进行加密,如果需要加密,参照以下方法

</aside>

基础要求

  1. 仅 HTTPS 暴露开放 API
  2. 请求体:Content-Type: application/json; charset=utf-8。
  3. UTF-8 编码参与签名的字符串

鉴权 Header

Header 说明
X-Access-Key 即access_key(AK_...)
X-Timestamp Unix 秒或毫秒(与实现统一即可),用于缩窄重放窗口
X-Nonce 随机串(UUID 即可),可选;若实现层做 nonce 缓存可强制防重放
X-Signature 下方 HMAC 输出
X-Sign-Version 签名版本,固定值 v2

签名原文建议格式

  1. 方法、路径:建议用规范化路径(不含域名、不含 query),若带 query 需明确是否包含 query string。
  2. Body:对 原始 JSON 字节 做 SHA-256,十六进制小写写入 canonical string;不要对 JSON 重新排版后再哈希(否则客户端与服务端序列化不一致会验签失败)。
  3. HMAC:HMAC-SHA256(secret, canonical_string),X-Signature 的编码须与实现写死一致(本文 §3.5 示例固定为标准 Base64;若选用 Hex,全链路不得混用)。

示例:

  1. 签名版本:v2
  2. 签名输出:X-Signature 为 HMAC-SHA256 的 标准 Base64(非 Base64URL)
  3. Body 哈希:对 原始请求体字节 做 SHA-256,小写十六进制字符串写入 canonical 最后一行
  4. Secret:完整字符串(含 SK_ 前缀)以 UTF-8 作为 HMAC 密钥材料

POST
/api/v2/antifraud/transaction/verify
X-Timestamp:{timestamp}
X-Nonce:{nonce}
{SHA256_hex_of_raw_body}

常见验签失败原因

  1. path 不一致:少了 context-path、多了网关前缀、或末尾 / 与实现不一致。
  2. body 字节不一致:语言默认 JSON 带空格/字段顺序不同;应用应对同一 dict 固定序列化后再签名并发送。