接口签名鉴权说明

适用对象：本 API 的对接方（渠道商户 / 系统集成商）
文档版本：v1.0（2026-11-13）
配套文档：接口对接指南

一、概述

本 API 采用 appId + 签名（sign） 机制进行身份认证。贵方在商务开通后，会获得两个凭证：

凭证	说明	保密要求
`appId`	渠道标识，随每个请求的公共参数传递	可公开
`secret`	签名密钥，用于计算签名	严禁泄露（请存储在服务端，勿下放到前端页面/小程序代码中）

签名原理：贵方将本次请求的所有参数（排除 sign 本身）按固定规则排序、拼接，末尾追加 secret，再取 MD5 得到 sign 值。我方以相同方式校验，一致则放行，不一致返回 code=101（签名不匹配）。

secret 一旦泄露，任何拿到它的人都可以冒充贵方调用接口，请务必妥善保管。

二、公共参数

每个请求（含 GET / POST）的查询串必须携带以下 4 个公共参数：

参数	类型	必填	说明
`appId`	string	是	渠道标识
`timestamp`	string	是	请求时间戳（Unix 秒级），参与签名
`nonce`	string	是	随机字符串，每次请求随机生成，参与签名
`sign`	string	是	签名值（不参与签名计算）

三、签名算法

步骤

汇总参数：取请求全部参数——GET 请求取全部查询参数；POST 请求取 body（JSON）与查询参数的并集。

剔除 sign：sign 本身不参与签名。

展平嵌套结构：

普通对象：key 用 . 连接，如 {"address":{"cityCode":"330100"}} → address.cityCode；

数组：按下标 [i] 展开，如 {"cars":[{"id":"1"}]} → cars[0].id。

字典序排序：按展平后的 key 从小到大排序（ASCII 字典序）。

拼接字符串：按排序结果，将 key=value 用 & 连接；值为空的参数跳过，不参与拼接。

追加 secret：在拼接结果末尾直接追加 secret（无任何分隔符）。

计算 MD5：对最终字符串按 UTF-8 编码计算 MD5，输出 32 位小写十六进制，即为 sign。

重要：value 直接使用原始值（字符串、数字、中文原样），不进行 URL 编码。

四、签名示例

示例一：GET 请求

请求：

GET /api/goods?cityCode=330100&appId=100001&timestamp=1700000000&nonce=9f2c1a&sign=<sign>

汇总参数（剔除 sign）：

appId     = 100001
cityCode  = 330100
nonce     = 9f2c1a
timestamp = 1700000000

字典序排序后拼接（均非空，全部参与）：

appId=100001&cityCode=330100&nonce=9f2c1a&timestamp=1700000000

假设 secret = SECRET123，末尾追加：

appId=100001&cityCode=330100&nonce=9f2c1a&timestamp=1700000000SECRET123

MD5（UTF-8，小写 32 位）：

sign = baf836d826a61b9faee58d820a57ba62

完整请求：

GET /api/goods?cityCode=330100&appId=100001&timestamp=1700000000&nonce=9f2c1a&sign=baf836d826a61b9faee58d820a57ba62

示例二：POST 请求（含 body 与查询参数）

请求体（application/json）：

{
  "cityCode": "330100",
  "count": 2
}

查询串携带公共参数：appId=100001&timestamp=1700000000&nonce=9f2c1a&sign=<sign>

汇总参数 = body + 查询参数（剔除 sign）：

appId     = 100001
cityCode  = 330100
count     = 2
nonce     = 9f2c1a
timestamp = 1700000000

排序后拼接 + 追加 secret（secret = SECRET123）：

appId=100001&cityCode=330100&count=2&nonce=9f2c1a&timestamp=1700000000SECRET123

MD5：

sign = 0582087a8102cb2142b1924bbee5bfde

完整请求：

POST /api/order/check?appId=100001&timestamp=1700000000&nonce=9f2c1a&sign=0582087a8102cb2142b1924bbee5bfde
Content-Type: application/json

{"cityCode":"330100","count":2}

五、实现示例

Python 3

注意：值为数字时按字面拼接（2 即 2）；若参数值为布尔型，请按 true / false 小写拼接。

Java（Spring / Hutool 参考）

六、常见错误与排查

现象	原因	排查建议
`code=101` 签名不匹配	签名计算与服务端不一致	① 是否漏了某个参数（body + query 全参与）；② 是否对 value 做了 URL 编码（不要编码）；③ `sign` 是否被当成参与参数；④ 空值参数是否被跳过；⑤ secret 是否正确
`code=301` 参数错误	必填参数缺失或格式不对	按接口文档核对参数名与必填项
`code=501/502/503`	服务端异常	稍后重试；如持续出现请联系我方

七、注意事项

secret 仅存服务端：请勿将 secret 下发到小程序、H5、App 前端代码中，否则任何用户均可通过抓包拿到密钥，伪造请求。

timestamp / nonce 每次请求更新：建议每次请求重新生成时间戳与随机串，避免参数雷同。

中文参数值：签名时使用原始中文（UTF-8）拼接，不要转码后再计算。

数组参数：body 中的数组按下标展开参与签名（如 cars[0].cakeGoodsId），注意与字段顺序无关（最终统一字典序排序）。

签名失败日志：建议贵方在收到 code=101 时打印参与签名的参数与拼接串，便于快速定位。

联调建议：先用本指南「示例一」的固定值自测，能算出 baf836d826a61b9faee58d820a57ba62 即说明实现正确，再接入真实请求。

一、概述#

二、公共参数#

三、签名算法#

步骤#

四、签名示例#

示例一：GET 请求#

示例二：POST 请求（含 body 与查询参数）#

五、实现示例#

Python 3#

Java（Spring / Hutool 参考）#

六、常见错误与排查#

七、注意事项#