小氢云商城系统同系统对接 `keys` 加签与验签文档

1. 文档说明

本文档适用于以下同系统对接接口：

/api/getCategoryList

/api/getGoodsList

/api/getGoodsDetail

/api/getOrderList

/api/getRemoteOrderDetail

/api/createOrder

/api/getBalance

上述接口统一要求通过 keys + timestamp + sign 进行验签。

2. 后端实际验签规则

后端当前实现的签名规则为：

sign = sha1(timestamp + data + keys)

说明：

sha1 输出为 32 进制小写十六进制字符串

timestamp 为 13 位毫秒时间戳

data 为参与签名的数据 JSON 字符串

keys 为用户在系统中配置的对接密钥

3. 参数获取优先级

后端对参数的读取优先级如下：

3.1 `keys`

优先读取请求头：Keys

请求头没有时，读取查询参数：keys

3.2 `timestamp`

优先读取请求头：Timestamp

请求头没有时，读取查询参数：timestamp

3.3 `sign`

优先读取请求头：Sign

请求头没有时，读取查询参数：sign

4. `data` 的生成规则

这是对接时最关键的部分。

4.1 GET 请求

如果请求方法不是 POST / PUT，后端会从 URL Query 中取业务参数生成 data：

会排除：sign、timestamp

不会排除：keys

也就是说：

如果你把 keys 放在 Query 里，keys 会参与 data 的 JSON 生成

如果你把 keys 放在 Header 里，keys 不会进入 data

因此，强烈建议把 Keys、Timestamp、Sign 全部放到 Header 中，避免 GET 场景签名口径不一致。

4.2 POST / PUT 请求

后端会读取原始请求体：

如果请求体是合法 JSON，则使用该 JSON 反序列化后的对象参与签名

如果请求体不是合法 JSON，则 data 按空对象 {} 处理

这意味着：

POST/PUT 最稳妥的方式是：Content-Type: application/json

如果你提交的是 application/x-www-form-urlencoded 或其他非 JSON 格式，当前后端验签时实际上按 {} 参与签名

4.3 排序规则

后端会先对 data 顶层字段按 ASCII 升序排序，再序列化为紧凑 JSON 字符串。

建议客户端统一按以下规则处理：

对对象字段按 ASCII 升序排序

JSON 使用紧凑格式，不要带空格、换行、缩进

数字保持数字类型，不要随意转成字符串

布尔值使用 true/false

空值使用 null

5. 时间戳校验规则

后端要求：

timestamp 必须能转成整数

必须是毫秒时间戳

与服务端当前时间误差不能超过 5 分钟

超过范围会返回：

{
  "code": -1,
  "msg": "签名验证失败: 时间戳已过期或无效"
}

6. 推荐对接规范

为避免和后端当前实现产生偏差，推荐统一使用以下方式：

6.1 GET 接口

业务参数放 Query

Keys、Timestamp、Sign 放 Header

data 仅对业务 Query 参数做排序后转 JSON

6.2 POST / PUT 接口

请求体统一使用 JSON

Content-Type: application/json

Keys、Timestamp、Sign 放 Header

data 取整个 JSON Body

7. 通用签名步骤

准备业务参数对象 dataObj

对对象字段按 ASCII 升序排序

转成紧凑 JSON 字符串 data

生成 13 位毫秒时间戳 timestamp

拼接待签名字符串：

raw = timestamp + data + keys

对 raw 做 SHA1

转成小写十六进制字符串，得到 sign

8. 验签步骤

收到请求后，服务端会按同样规则重新生成签名并比较：

expectedSign == requestSign

一致则通过，不一致则返回：

{
  "code": -1,
  "msg": "签名验证失败"
}

9. 示例说明

假设：

keys = your_keys_value

timestamp = 1710000000123

data = {"id":123,"page":1,"size":10}

则待签名原文为：

1710000000123{"id":123,"page":1,"size":10}your_keys_value

再对这段原文做 SHA1，即得到 sign。

10. 各语言加签与验签示例

以下示例均按推荐规范实现：

GET：业务参数签名

POST：JSON Body 签名

keys/timestamp/sign 放 Header

11. Go 示例

12. Python 示例

13. PHP 示例

14. Java 示例

15. Node.js 示例

16. C# 示例

17. 请求示例

17.1 GET 示例：获取商品详情

此时参与签名的 data 为：

{"id":"123"}

说明：

GET Query 参数在服务端会以字符串形式参与签名

因此 GET 场景建议客户端也按字符串值组装

17.2 POST 示例：创建订单

此时参与签名的 data 为整个请求体 JSON。

18. `createOrder` 接口特别说明

根据当前后端代码实现，/api/createOrder 有以下注意点：

18.1 固定支付方式

后端内部会强制：

pay = type_money

对接方不需要额外传支付方式。

18.2 回调地址字段

当前同系统对接代码里，读取的是：

url

不是 callback_url。

如果你要传异步回调地址，请按当前实现传：

{
  "url": "https://xxx.com/callback"
}

18.3 `inputs` 字段

当前代码要求 inputs 为对象，例如：

{
  "inputs": {
    "value0": "手机号",
    "value1": "验证码"
  }
}

后端会自动把 value0、value1 转换为内部使用的 0、1。

19. 常见失败原因

以下问题最容易导致验签失败：

timestamp 不是 13 位毫秒时间戳

客户端 JSON 带空格、换行、缩进，和服务端紧凑 JSON 不一致

字段顺序未按 ASCII 升序

GET 把 keys 放到了 Query，导致 data 里多了一个 keys

POST 使用了表单提交，但签名却不是按 {} 计算

数字和字符串类型不一致，例如 123 和 "123" 混用

sign 使用了大写，而服务端期望小写十六进制

使用了错误的 keys

20. 最佳实践

建议所有接入方统一遵循以下方案：

Keys、Timestamp、Sign 一律放 Header

GET 只对业务 Query 参数签名

POST/PUT 一律使用 JSON Body

JSON 一律使用紧凑格式

SHA1 结果统一使用小写十六进制

调用前先同步服务器时间，避免时间戳误差超过 5 分钟

21. 说明

本文档依据当前系统后端的同系统对接实现整理。

如后端后续调整了签名逻辑，请以最新实现同步更新本文档。

加签规则

小氢云商城系统同系统对接 keys 加签与验签文档#

1. 文档说明#

2. 后端实际验签规则#

3. 参数获取优先级#

3.1 keys#

3.2 timestamp#

3.3 sign#

4. data 的生成规则#

4.1 GET 请求#

4.2 POST / PUT 请求#

4.3 排序规则#

5. 时间戳校验规则#

6. 推荐对接规范#

6.1 GET 接口#

6.2 POST / PUT 接口#

7. 通用签名步骤#

8. 验签步骤#

9. 示例说明#

10. 各语言加签与验签示例#

11. Go 示例#

12. Python 示例#

13. PHP 示例#

14. Java 示例#

15. Node.js 示例#

16. C# 示例#

17. 请求示例#

17.1 GET 示例：获取商品详情#

17.2 POST 示例：创建订单#

18. createOrder 接口特别说明#

18.1 固定支付方式#

18.2 回调地址字段#

18.3 inputs 字段#

19. 常见失败原因#

20. 最佳实践#

21. 说明#