使用说明

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

此项目为我司对外API接口项目，主要职责为API接口用户提供红包充值、扣减，储值充值、扣减，红包、储值余额变更通知等接口服务。

业务流程

1、首先与我司商务对接，走完商务对接流程后，可登录我司后台，在：系统管理--》API管理 菜单下，点击申请、设置与API交互的基础信息；
2、充值、扣减余额等业务，同步返回错误时，则业务流程处理完结；同步返回成功后，是否实际到账，需等待异步回调通知为准；
3、单据回调通知，响应时间在5秒内，超过5秒的响应，视为通知失败，通知频次0s/30s/60s/180s/600s 最多总计5次通知，超过5次后不再通知；
4、回调通知不保证一定送达，所有用户业务系统需有对应的策略，主动调用对应单据的详情，返回单据处理的最新状态；
5、单据详情的状态的终态为：处理成功或处理失败，终态状态的单据，意味着该条数据处理完结，不会再有后续的处理；

接口对接说明

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

接口规范

1. 报文格式及编码

接收及响应格式：JSON，字符编码：UTF-8
ContentType：application/json; charset=utf-8

2. 交互协议及请求方式

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

3. 公共参数

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

参数名	类型	参数值	描述
appKey	string	91856bd5-8622-4b18-aebb-79ce5e010f88	线下方式申请获取，标识用户唯一身份
timestamp	string	1688194275	请求时间戳（秒级），超出 30s 服务端将拒绝响应
nonce	string	2888788876	请求随机数
token	string	3DE3F432C376423D6CD69A8FB7BF0DC8	用户访问token，通过接口获取
signature	string	5DE3F432C376423D6CD69A8FB7BFBB00	根据签名规则生成的签名,防止数据被篡改，生成规则参考4

公共响应参数

参数名	类型	参数值	描述
status	int	200	非200 为请求失败
msg	string	操作成功	提示信息
requestId	int	21062921043033790720	返回请求唯一id，异常数据排查时，需提供此id
content	array/object		响应详细内容

4. 签名生成规则

签名生成规则: 按照下面的顺序拼接参数名和值，拼接为一个字符串，然后执行 md5，将md5后生成的字符串全部转为大写，则为此次请求的 signature
$param = appKey值timestamp值token值nonce值appSecret值
$signature = strtoupper(md5($param));

5. IP白名单

API接口用户需提供调用接口使用的服务器IP，只有用户白名单内的IP，才可以正常访问接口服务

6. 访问频次

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

7. 回调地址

单据信息处理完结时，会主动发送对应的通知，由于网络、队列延迟等原因，可能到账回调未能及时送达，所以在收到系统通知或者超过自定义时间未收到通知的时候，可以主动请求对应详情接口，会返回最新状态信息

接口使用说明

签署商务合同----》登录网站后台申请API权限----》设置IP白名单、回调地址----》接口对接----》开发测试----》测试服联调测试----》正式服部署上线

专用术语

红包：业务系统营销活动的一种类型，C端会员购买商品时，可用红包抵扣对应金额

其他

对接过程中遇到的问题，可参考帮助中心常见问题，或者联系对应商务经理，加入接口对接沟通群

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

业务流程#

接口对接说明#

接口规范#

1. 报文格式及编码#

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

3. 公共参数#

4. 签名生成规则#

5. IP白名单#

6. 访问频次#

7. 回调地址#

接口使用说明#

专用术语#

其他#