对接前必读

对接前必读说明（重要）

在开始接口对接前，请务必完整阅读并理解以下规则，未按规范调用将直接返回错误。

1. 请求有效期（防重放）

所有接口请求均有时效限制

请求中的 timestamp 为 毫秒级时间戳

服务端仅接受 5 分钟内 的请求

超过 5 分钟的请求将返回：1003 请求已过期

建议客户端与服务器时间保持一致（可使用 NTP 校时），避免因时间偏差导致验签失败。

2. 请求方式与数据格式（统一规范）

HTTP Method：POST

Content-Type：application/json

请求参数统一放在 Body 中

不支持 URL QueryString 方式传参

3. 请求体公共参数（所有接口必传）

以下参数为所有接口公共参数，缺失任一参数将直接返回错误：

参数名	类型	必填	说明
userNo	string	是	用户编号，后台我的资料获取
timestamp	number	是	毫秒级时间戳（1764249192274），5分钟内有效
sign	string	是	根据下面签名规则生成的签名

⚠️ 注意：userNo、timestamp 属于签名参数，必须参与签名计算。

4. 签名机制说明（强制）

所有接口请求必须进行签名

签名用于校验请求参数是否被篡改

签名校验失败将返回：1002 签名不正确

secretKey 为平台分配，请妥善保管，严禁泄露

5. 参数规范约束（非常重要）

为避免验签失败，请严格遵守以下规则：

❌ 参数值不可为空

null / undefined / "" 的参数请不要传

❌ 不允许传 JSON / Object / Array 类型参数

所有参数值必须为字符串或数字

❌ 字段名大小写必须严格一致

❌ 签名字符串不进行 URL Encode

✅ secretKey 仅用于签名拼接，不作为请求参数传输

详细签名生成规则请查看下方【签名说明】章节。

签名规则说明（Sign 生成机制）

为保证接口请求参数在传输过程中不被篡改，所有接口请求均需按照以下规则生成 sign 参数。

1. 参与签名的参数

所有请求体（Body）中的参数均参与签名

排除字段：sign

其余所有参数（如 userNo、timestamp 等）均需参与签名

⚠️ 注意
参数值 不可为空
null / undefined / "" 的参数 请勿传递，也不参与签名

示例请求参数：

{
  "userNo": "A000012",
  "timestamp": 1764249192274,
  "amount": 48.5
}

2. 参数排序规则

将参与签名的参数按参数名（key）进行 ASCII 字典升序排序 a-b-c-d

排序仅针对参数名，与参数值无关
排序后示例：

amount
timestamp
userNo

3. 拼接签名字符串

将排序后的参数按以下格式拼接：

示例：

4. 追加密钥（secretKey）

在拼接字符串 末尾追加密钥，密钥不参与排序：

最终签名字符串示例：

⚠️ 注意

secretKey 必须放在最后

secretKey 不作为请求参数传输

拼接字符串不进行 URL Encode

参数名大小写需保持一致

5. MD5 生成签名

使用 MD5 算法

字符串编码：UTF-8

生成 32 位大写十六进制字符串

sign = MD5(最终签名字符串).toUpperCase()

生成示例：

18BFE2813CDBC4D52914FF8F4CC7D0E2

6. Node.js 示例代码（参考）

7. 签名注意事项（重点）

所有接口必须携带 sign

参与签名的参数必须与服务端保持完全一致

任何一个参数缺失、多余、顺序错误都会导致验签失败

timestamp 必须为毫秒级时间戳，并在 5 分钟内有效

请妥善保管 secretKey，严禁泄露给第三方

返回结构说明（统一格式）

所有接口返回统一结构

无论成功或失败，HTTP 状态码均为 200

业务结果以 code 字段为准

字段	说明
code	0 成功，其它错误码（详见错误码表）
message	错误或成功的具体信息
data	具体的业务数据失败为null
timestamp	服务端时间戳

成功示例：

失败示例：

错误码

错误码	错误信息	说明
0	success	成功
1001	用户不存在	userNo 不正确或已被删除
1002	签名不正确	sign 校验失败
1003	请求已过期	请求已过期
1004	缺少必要的签名参数	userNo、timestamp、sign 等签名参数不存在
1005	用户已被禁用	用户已被禁用
1006	IP 不在白名单内	IP 不在白名单内
2001	参数错误	业务参数错误
2002	缺少必填参数	缺少业务必填参数
2003	未查询到数据	未查询到业务数据
9000	服务错误	服务出现错误

完整错误码：

常见对接失败原因（重点排查）

timestamp 超过 5 分钟或客户端时间偏差过大

参与签名的参数不完整（漏签 / 多签）

sign 字段误参与签名

参数未按 key 升序排序

secretKey 错误

MD5 未转大写

传入对象 / 数组参数导致签名串不一致