认证与签名

本页说明 API 请求、响应及 Webhook 的签名规则。使用 SDK 时，签名和验签由 SDK 处理，接入步骤见接入指南。

请求头

请求头	填写方式	说明
`X-Api-Key`	初始化配置	API Key 调用凭证
`X-API-VERSION`	调用时传入	接口版本，必填
`X-Timestamp`	SDK 自动生成	Unix 毫秒时间戳
`X-Nonce`	SDK 自动生成	每次请求唯一
`X-Signature`	SDK 自动生成	标准 Base64 签名
`X-Signature-Algorithm`	SDK 自动携带	`RSA-SHA256`
`X-Request-Id`	SDK 自动生成，可调用时传入	请求关联 ID；加密请求还用于 AAD
`X-Idempotency-Key`	调用时传入	按具体接口要求填写；同一业务重试复用
`X-Platform-Encryption-Key-Id`	SDK 根据密钥生成	加密请求使用的平台加密公钥指纹
`Content-Type`	SDK 自动携带	JSON 请求使用 `application/json`

敏感响应的加密时间戳从信封 AAD 获取，处理方式见加密与解密。

请求签名

当前生产规范串为 7 行，UTF-8 编码，以 LF 连接，末尾不加换行；空 query 保留空行：

METHOD
EXTERNAL_PATH
CANONICAL_QUERY
TIMESTAMP
NONCE
API_VERSION
BODY_SHA256_HEX

使用客户端鉴权私钥执行 RSA-SHA256，RSA padding 为 PKCS#1 v1.5，结果编码为标准 Base64。X-Api-Key、X-Signature-Algorithm 和幂等键不在此版本规范串中。

METHOD 使用大写；路径不包含域名或 query，不自行增加内部前缀。

GET、HEAD、DELETE 使用空 body 摘要；其余方法对实际发送的原始字节计算 SHA-256 小写 hex。

JSON 只序列化一次。加密请求对信封 JSON 计算摘要，而不是业务明文。

空 body 摘要为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。

Query 规范化

当前生产规则：拆分键值对 → percent 解码（+ 按空格解码）→ 按解码后的 key、value 的 UTF-16 码元顺序排序 → 重编码 → 用 & 连接。

重编码保留字母、数字及 -._*，其余使用 UTF-8 percent 编码和大写 hex；空格输出 %20，字面加号输出 %2B，~ 输出 %7E。重复 key 保留，空值保留 =。

原 query	规范化结果
`b=2&a=1`	`a=1&b=2`
`a=2&a=10&a=1`	`a=1&a=10&a=2`
`flag`	`flag=`
`q=hello+world`	`q=hello%20world`

使用 SDK 的 query 参数构造 URL，不手工重复编码。

响应验签

先保留原始响应体字节，再验证 X-Response-Signature。当前生产规范串为 5 行，LF 连接，末尾无换行：

REQUEST_ID
HTTP_STATUS
CONTENT_TYPE
RESPONSE_TIMESTAMP
RESPONSE_BODY_SHA256_HEX

字段	来源
`REQUEST_ID`	响应 `X-Request-Id`；缺失时使用本次发送的请求 ID
`HTTP_STATUS`	HTTP 状态码十进制字符串
`CONTENT_TYPE`	响应头原始 `Content-Type`
`RESPONSE_TIMESTAMP`	`X-Response-Timestamp`
`RESPONSE_BODY_SHA256_HEX`	原始响应体 SHA-256 小写 hex

使用平台鉴权公钥、RSA-SHA256 / PKCS#1 v1.5 验签。验签失败不得使用业务数据；不要先解析并重新序列化响应体。

SDK 默认验证带签名的响应；成功 HTTP 响应缺少签名时报错。非 2xx 且无签名的网关错误仅作未验签错误处理，不当作可信业务响应。

Webhook 验签

使用平台鉴权公钥验证 X-SlaunchX-Signature。规范串固定 4 行，LF 连接，末尾无换行：

DELIVERY_ID
EVENT_TYPE
TIMESTAMP
BODY_SHA256_BASE64

前三行分别取自 X-SlaunchX-Delivery-Id、X-SlaunchX-Event-Type、X-SlaunchX-Timestamp；第四行是原始 HTTP body 的 SHA-256 标准 Base64，不是 hex。签名算法仍为 RSA-SHA256 / PKCS#1 v1.5。

验签后按加密与解密核对接收方、AAD 和信封，再按Webhook 通知处理事件。

请求头#

请求签名#

Query 规范化#

响应验签#

Webhook 验签#

请求头

请求签名

Query 规范化

响应验签

Webhook 验签