分利客权益平台开放API对接文档

1. 名词解释

渠道账号
渠道如需接入分利客权益平台，对接平台优惠，首先需要注册一个分利客权益平台账号。目前账号不对外公开注册，请联系平台客服提供账号。

渠道媒体
一个渠道账号下面可以有多个渠道媒体（注：渠道媒体也暂时不对外公开创建，请联系分利客平台客服创建媒体），一个媒体相当于渠道的一个产品，同渠道媒体共用渠道账号余额及配置，后期可以按渠道媒体区分数据。

API密钥
注册账号之后，平台会为每个渠道账号生成API密钥。为了接口安全，开发者后续调用平台开放API时，需要使用该API密钥对请求参数进行签名及验签。具体签名及验签见后续签名验签介绍文档。

IP白名单
为了安全，渠道需要提供调用平台API的终端IP地址，只有通过配置了IP白名单的终端发起的请求才会被平台认定为有效请求进行处理。

回调地址
当订单状态变化（订单成功或失败）时，平台会通过渠道在平台配置的回调地址将最新的订单同步给渠道，渠道可以在接收到平台回调后进行相应的业务处理。具体回调数据及验签参照后续的文档。

2. HTTP请求

平台所有接口均需使用HTTP的POST方式请求，请求参数使用application/json方式（请求Content-Type: application/json;charset=UTF-8）。接口响应的数据类型为JSON格式（响应Content-Type: application/json;charset=UTF-8）。具体请求传参方式如下图：

其中，nonceStr、timestamp、sign这三个参数为基础请求参数，所有接口均需要这三个参数。具体参数说明如下：

参数	是否必传	类型	说明
nonceStr	是	String	请求随机串（需唯一，每次请求不同。32位小写。可使用MD5(uuid)生成）
timestamp	是	long	请求毫秒级时间戳（基于 Unix 纪元 1970-01-01 00:00:00 UTC）当前通常为 13 位十进制数字
sign	是	String	签名（将除sign参数外所有非空请求参数按照key升序排列后获取对应value值+API密钥拼接后MD5的32位小写，详细见文档【参数签名】）

响应数据格式如下：

{"code":0,"msg":"请求成功","data":{}}

参数	类型	说明
code	int	响应码（参照响应码）
msg	String	响应消息
data	Object	响应数据

3. 参数签名

为了接口安全，所有的接口请求均需要签名，生成签名方法是：将除sign参数外所有非空请求参数按照key升序排列后获取对应value值+API密钥拼接后MD5的32位小写。比如下单接口请求参数如下：

{"caMid":1,"nonceStr":"7b81e425bbb0998b5efdca25094d3e3f","timestamp":1770040185294,"sign":"ce7a4f1b4e65de7f2ddcf040dec4439c","caOid":"2018248059768307712","gid":35,"gNum":1,"account":"13623094462"}

将除sign参数外所有非空参数按照key升序排列如下：

key:account , value:13623094462
key:caMid , value:1
key:caOid , value:2018248059768307712
key:gNum , value:1
key:gid , value:35
key:nonceStr , value:7b81e425bbb0998b5efdca25094d3e3f
key:timestamp , value:1770040185294

假如渠道API密钥为：8a8e308f19f587bca3e10d1922b61d46f4865f5618c1e67478404966480aad64，则参与签名的数据为（account的值+caMid的值+caOid的值+gNum的值+gid的值+nonceStr的值+timestamp的值+API密钥）：
13623094462120182480597683077121357b81e425bbb0998b5efdca25094d3e3f17700401852948a8e308f19f587bca3e10d1922b61d46f4865f5618c1e67478404966480aad64
生成签名为：
sign=MD5(13623094462120182480597683077121357b81e425bbb0998b5efdca25094d3e3f17700401852948a8e308f19f587bca3e10d1922b61d46f4865f5618c1e67478404966480aad64)的小写：
ce7a4f1b4e65de7f2ddcf040dec4439c

4. 回调说明

创建订单成功时会返回待处理订单，订单是否处理成功需要异步回调。当订单状态发生改变（订单状态变为处理成功或处理失败）时，平台会通过渠道配置的回调地址将最新的订单信息回调给渠道，渠道可以在接收到回调请求后按自己的业务流程处理。渠道接收到回调之后，需要返回文本"success"，若渠道应答回调接收失败，或超时未应答时，平台会按照（15s/30s/3min/10min/30min）的频次重复发送回调通知，直至平台接收到渠道应答成功（success），或达到最大发送次数（8次）。回调数据如下：

 {
        "account": "13623094462",
        "amount": 22800,
        "caMid": 1,
        "caOid": "2018248059768307712",
        "caid": 1,
        "gNum": 1,
        "gid": 35,
        "oid": "2018248700698648576",
        "status": 4,
        "sign":"c2f5b99a1d7c970f01a42a425d98f6c1"
    }

参数	是否必传	类型	说明
oid	是	String	平台订单id
caid	是	int	渠道账号id
caMid	是	int	渠道媒体id
caOid	是	String	渠道订单id
account	是	String	充值账号
gid	是	int	商品id
gNum	是	int	商品数量
amount	是	int	订单总金额（厘）
status	是	int	订单状态
sign	是	String	签名

渠道接收到回调后，需要验签。将回调的数据按参数签名的方式生成签名（将除sign参数外所有非空请求参数按照key升序排列后获取对应value值+API密钥拼接后MD5的32位小写，可参照参数签名），并与回调的sign进行匹配，如果一致表示验签通过。

5. 响应码

响应码	响应消息
-1	请求异常，请稍后再试。
0	请求成功。
10000	请求方法非法。
10001	非法请求。
10002	签名错误。
10003	参数非法。
10004	请求已过期。
10005	状态未知。
10006	渠道账号不存在。
10007	渠道账号已暂停，请联系客服。
10008	渠道媒体不匹配。
10009	媒体不存在。
10010	媒体不可用，请联系客服。
10011	渠道配置非法，请联系客服。
10012	渠道账号余额不足，请先充值。
10013	渠道账号余额充值失败，请稍后再试。
10014	商品不存在或不可用，请联系客服。
10015	请求下单异常。
10016	请求下单失败。
10017	下单失败。
10018	查询订单异常。
10019	请求查询订单失败。
10020	查询订单不存在。
10021	订单不存在。

分利客权益平台开放API对接文档

分利客权益平台开放API对接文档#

1. 名词解释#

2. HTTP请求#

3. 参数签名#

4. 回调说明#

5. 响应码#

分利客权益平台开放API对接文档

1. 名词解释

2. HTTP请求

3. 参数签名

4. 回调说明

5. 响应码