签名算法

计算步骤

1. 准备最终要发送的 UTF-8 JSON 文本 rawBody。序列化一次，后面签名和发送使用同一份字节。
2. 计算 bodyHash = lowercaseHex(SHA256(rawBody))。
3. 按下方顺序用换行符 \n 拼接六行，末尾不加换行。
4. 以 Secret 的 UTF-8 字节为密钥计算 HMAC-SHA256，并编码为 64 位小写 hex，填入 X-Signature。

API Key
POST
完整 Path（不含域名）
X-Timestamp
X-Nonce
bodyHash

公式：

canonical = apiKey + "\n" + "POST" + "\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + lowercaseHex(SHA256(rawBody))
signature = lowercaseHex(HMAC_SHA256(UTF8(secret), UTF8(canonical)))

Secret 作为原始文本使用，不先做 hex/Base64 解码。示例代码见各接口的「调用示例」，可直接复制完整脚本。

固定校验向量

此例只验证计算算法；时间戳已过期，不能用来调用线上 API。

输入	值
API Key	key
Secret	secret
Method	POST
Path	/api/v1/open/viewers/upsert
Timestamp	1700000000
Nonce	0123456789abcdef
原始 Body	{}（两个字符，无空格和换行）
bodyHash	44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
Signature	b04fca374e3428b338b6bcc0597f81762d99b21235971184293b9252d304ee65

常见失败原因

• 签名后重新序列化 JSON：空格、字段顺序、换行和中文转义的变化都会改变哈希。
• 使用毫秒时间戳或服务器时钟偏差过大。
• 将完整 URL 放进签名，或签名 Path 与发送 Path 不一致。
• HMAC 结果使用 Base64 或大写 hex。
• 请求经过重定向或中间代理重新编码、压缩请求体。
• 重用同一 nonce。nonce 防重放不是业务幂等键，即使上次业务校验失败，也应为新请求生成新 nonce。

不要打印 Secret、完整签名串和包含观众资料的原始 Body。排查时使用本页固定向量，再携带 requestId 联系部署方。