请求认证与签名

请求头

请求头	必填	说明
X-App-Id	是	管理后台创建的 App ID
X-Timestamp	是	当前 Unix 秒，服务端允许 ±5 分钟
X-Nonce	是	每次请求使用新的随机字符串
X-Signature	是	小写十六进制 HMAC-SHA256
Content-Type	POST 是	application/json

签名原文

METHOD + PATH + CANONICAL_JSON_BODY + TIMESTAMP + NONCE

• METHOD 使用大写，例如 POST、GET。
• PATH 只包含 URL 路径，例如 /api/v1/messages，不含域名与查询串。
• 请求体解析为 JSON 对象后，按键名排序并以紧凑 JSON 序列化；空请求体使用空字符串。
• TIMESTAMP 和 NONCE 直接拼接，不添加 &、换行或空格。
• 以 App Secret 为 HMAC key，SHA-256 结果输出小写 hex。

Go 示例

func sign(secret, method, path string, body map[string]any, ts int64, nonce string) string {
    canonical := ""
    if len(body) > 0 {
        // encoding/json 对 map key 进行确定性排序。
        raw, _ := json.Marshal(body)
        canonical = string(raw)
    }
    text := method + path + canonical + strconv.FormatInt(ts, 10) + nonce
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(text))
    return hex.EncodeToString(mac.Sum(nil))
}

防重放与排错

客户端应使用 NTP 保持时钟同步，并确保每次请求生成新的 nonce。出现 20003 invalid signature 时，逐字比较方法、路径、紧凑 JSON、时间戳和 nonce；出现 20004 invalid timestamp 时检查秒/毫秒单位和时区无关的 Unix 时间。

相关页面：应用接入 · 多语言示例与错误码