项目说明【对接前，务必认真阅读此文档】

业务流程

首先根据用户手机号，查询到本业务系统用户唯一编号，后续所有用户相关交互，都以该用户编号为唯一标识，各对接方注意自身业务系统与本系统中会员对应关系。

对接说明

登录后台，获取appKey、appSecret，同时设置IP白名单、通知回调地址，然后接口才能正常通讯；
测试服与正式服环境，除了域名、appKey、appSecret外，其余均一致，用户开发时，对接完测试服后，正式上线时，只需更换一下域名、appKey、appSecret 即可正常切换环境

接口规范

1. 报文格式及编码

接受及响应格式：JSON；字符编码：UTF-8 ；无BOM头
ContentType：application/json; charset=utf-8

2. 交互协议及请求方式

HTTPS协议，全部接口使用POST请求方式

3. 公共参数

公共请求参数，通过header传输，值、类型及对应释义

参数名	类型	示例值	描述
X-App-Key	string	91856bd5-8622-4b18-aebb-79ce5e010f88	登录网站后台自行获取
X-Timestamp	string	1688194275	请求时间戳（秒级），超出 60s 服务端将拒绝响应
X-Nonce	string	0123456789-_abcd	唯一随机数：长度不小于16位且不大于36位, [0-9, a-z, A-Z, -,_],5分钟内唯一
X-Body-SHA256	string	a1b2c3d4e5f67890... （hex 小写字符）	原始 Body 的 SHA256 摘要，采用小写十六进制编码。编码前不做任何格式化、缩进、转义处理
Authorization	string	HMAC-SHA256 {signature}	HMAC-SHA256 为固定签名算法标识 {signature} 为请求签名串。将结果进行Base64编码的字符串

公共响应参数

参数名	类型	参数值	描述
code	int	0	状态码，非0为异常
message	string	操作成功	提示信息
data	array/object	1688194275	响应详细内容
traceId	string	91856bd5-8622-4b18-aebb-79ce5e010f88	返回请求唯一id，需要技术接入排查时，需要提供此id
timestamp	integer	1767252208	当前服务器时间的 Unix 时间戳(秒)

4. 摘要及签名生成规则

4.1 摘要生成规则

请求体摘要规则（rawBody 的 SHA256）
对原始http请求体原文（JSON字符串） rawBody做 SHA256 哈希计算，将计算结果转换为小写十六进制字符串

4.2 签名生成规则

4.2.1 签名生成规则: 按照下面的顺序拼接参数名和值，拼接为一个字符串
stringToSign:X-App-Key值X-Timestamp值X-Nonce值X-Body-Sha256值
4.2.2 使用 AppSecret 作为密钥，对待签名字符串进行 HMAC-SHA256 计算，得到二进制结果
4.2.3 将上述结果进行 Base64 编码，得到最终签名 signature
4.2.4 签名通过请求头 Authorization 传输，格式为：
Authorization: HMAC-SHA256 {signature}

4.3 规则总结

rawBody 做 SHA256 转小写十六进制
stringToSign:X-App-Key值X-Timestamp值X-Nonce值X-Body-Sha256值
待签字符串做 HMAC-SHA256 再 Base64 编码后传输

4.4 示例

bodySha256 : 小写十六进制(SHA256(rawBody)):2cf24dba5fb0a30e..
stringToSign：X-App-Keymy_app_key_123X-Timestamp1717401600X-Nonceabc123def456X-Body-SHA256e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
signature  = Base64(HMAC-SHA256(appSecret, stringToSign))

5. IP白名单

登录网站后台，自行设置IP白名单，多个时以英文逗号分隔，最多可设置10个，只有白名单内的IP，才可以正常访问接口服务

6. 访问频次

为保证系统安全、稳定的提供服务，接口调用频次不到超过：300次/分钟(滑动窗口)，超过该频次会直接返回请求频繁

7. 回调通知

1. 回调方式

请求方式：POST

Content-Type：application/json; charset=utf-8

回调地址优先级：

优先使用商户请求资产变更时传入的 notifyUrl

如果未传，则使用用户配置的固定资产回调地址

请求体编码：JSON，使用 JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES

要求必须在10秒内正常响应，否则会标记为通知失败；对于失败的通知会进行重试，各业务侧做好幂等处理；

2. 请求头

  Accept: application/json
  Content-Type: application/json; charset=utf-8
  X-App-Key: {appKey}
  X-Timestamp: {timestamp}
  X-Nonce: {nonce}
  X-Sign: {sign}
  X-Sign-Type: HMAC-SHA256

字段说明

参数名	类型	说明
X-App-Key	string	用户appKey
X-Timestamp	string	系统发送回调时 Unix 时间戳（秒）
X-Nonce	string	随机字符串，当前为 16 位 hex
X-Sign	string	Base64 字符串，HMAC-SHA256 签名结果，hex小写，然后进行Base64编码
X-Sign-Type	string	固定 HMAC-SHA256，签名算法标识

3. 签名规则

签名密钥：商户 app_secret。
签名原文：
signContent = X-App-Key{appKey}X-Timestamp{timestamp}X-Nonce{nonce}body{body}
签名生成规则：
X-Sign = Base64( HMAC-SHA256( signContent, appSecret ) )

密钥为平台分配的 appSecret

HMAC 输出为原始二进制，再做 Base64 编码

注意：商户验签时必须使用收到的原始请求 body 字符串参与签名，不要重新格式化 JSON。

4. 通知示例

 {
    "notifyType": "assetChangeResult",
    "eventNo": "EVT202605260001",
    "bizOrderNo": "OAPI202605260001",
    "requestSn": "third_request_001",
    "orderSn": "third_order_001",
    "merchantUid": "merchant_xxx",
    "memberUid": "member_xxx",
    "asset": {
      "type": {
        "code": 1,
        "name": "COUPON",
        "text": "红包"
      },
      "changeType": {
        "code": 1,
        "name": "ADD",
        "text": "增加"
      },
      "amount": 1000,
      "validDays": 30
    },
    "requestStatus": {
      "code": 3,
      "name": "DONE",
      "text": "已完成"
    },
    "resultStatus": {
      "code": 1,
      "name": "SUCCESS",
      "text": "成功"
    },
    "result": {
      "success": true,
      "errorMessage": ""
    },
    "createdAt": "2026-05-26T15:30:00+08:00",
    "processedAt": "2026-05-26T15:35:00+08:00",
    "remark": "红包充值"
  }

核心字段说明

字段	类型	说明
notifyType	string	通知类型，当前固定 assetChangeResult
eventNo	string	本系统通知事件编号
bizOrderNo	string	本系统资产变更业务单号
requestSn	string	商户请求唯一编号
orderSn	string	商户业务系统单号，可能为空字符串
merchantUid	string	商户编号
memberUid	string	会员编号
asset.type	object	资产类型
asset.changeType	object	变更类型
asset.amount	int	变更金额，最小单位
asset.validDays	int	有效天数，红包时有意义
requestStatus	object	请求单状态
resultStatus	object	业务处理结果
result.success	bool	是否处理成功
result.errorMessage	string	失败原因，成功时为空字符串
createdAt	string	商户请求进入本系统时间，RFC3339
processedAt	string	业务处理完成时间，RFC3339；未处理时为空字符串
remark	string	备注

资产类型

code	name	text
1	COUPON	红包
2	BALANCE	储值
3	POINT	积分

变更类型

code	name	text
1	ADD	增加
2	DEDUCT	扣减

请求状态

code	name	text
1	PENDING	已受理
2	PROCESSING	处理中
3	DONE	已完成
4	REJECTED	已拒绝

处理结果

code	name	text
0	PENDING	未处理
1	SUCCESS	成功
2	FAILED	失败

5. 商户响应要求

本系统认为通知成功的条件

HTTP 状态码必须是 200

响应 body 必须是 JSON 且包含 code，code为0表示成功

其余场景均视为通知失败

{
  "code": 0,
  "message": "success"
}

6. 重试规则

默认最多通知 5 次，包含首次立即通知。
首次通知失败后，最多重试 4 次，重试间隔依次为：60s、300s、900s、1800s。

当通知失败且失败原因属于临时异常时，本系统会发起重试。
默认重试场景包括：HTTP 408、429、500、502、503、504、请求超时、网络异常。
HTTP 400、401、403、404、422 等通常视为不可重试失败。

使用说明

项目说明【对接前，务必认真阅读此文档】#

业务流程#

对接说明#

接口规范#

1. 报文格式及编码#

2. 交互协议及请求方式#

3. 公共参数#

4. 摘要及签名生成规则#

4.1 摘要生成规则#

4.2 签名生成规则#

4.3 规则总结#

4.4 示例#

5. IP白名单#

6. 访问频次#

7. 回调通知#

1. 回调方式#

2. 请求头#

3. 签名规则#

4. 通知示例#

5. 商户响应要求#

6. 重试规则#