认证与安全

每一次业务调用都需要满足两层要求：请求整体带签名防篡改/防重放，请求体单独加密。

1. 请求签名 access_signature

每个请求需要携带 access_signature 请求头，格式为 时间戳.随机数.签名。 签名算法为 HMAC-SHA256：

签名算法
canonical = METHOD + '|' + path + '|' + ts + '|' + nonce + '|' + sha256(请求体密文)
signature = base64(HMAC_SHA256(canonical, 平台分配的签名密钥))
access_signature = ts + '.' + nonce + '.' + signature
  • 时间戳窗口：与服务器时间偏差超过 ±300 秒的请求会被拒绝
  • 随机数（nonce）在窗口期内不可重复使用，用于防重放
  • 签名密钥由平台在接入时分配，不同企业/应用各自独立

2. 请求体加密

请求体使用 SM4（ECB 模式）对称加密后传输，密文使用 Base64 编码， Content-Type: application/text。 加密密钥同样由平台在接入时分配。

3. 响应结构

响应采用三层结构：

JSON
{
  "httpStatusCode": 200,
  "body": "{\\"Response\\":{\\"RequestId\\":\\"...\\",\\"Data\\":\\"<SM4 密文 Base64>\\"}}"
}
  • httpStatusCode 是数字，业务失败时 HTTP 状态仍可能是 200，需要看内层字段判断成败
  • body 是字符串，需要二次 JSON.parse
  • Data 用同一把 SM4 密钥解密后得到业务数据，业务成败看其中的 returncode（见错误码）
  • 网关层失败（如签名校验不通过）不会有 Data，而是 Response.Error