目录
2.1协议规则
|
传输方式 |
为保证交易安全性，采用HTTPS传输 |
|
提交方式 |
采用POST方式提交 |
|
数据格式 |
提交的数据格式为application/x-www-form-urlencoded， 返回的数据格式为application/json |
|
字符编码 |
统一采用UTF-8字符编码 |
|
签名算法 |
RSA2或SM2 |
|
签名要求 |
请求和接收数据均需要校验签名 |
2.2参数规定
报文规范中各参数如果不可空，则必须填写，否则报错。如果参数为空，那么该参数可以在JSON报文中出现，也可以不出现。金额单位以具体接口的说明为准。
2.3安全规范
2.3.1 签名机制
1、筛选并排序
获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除sign、signType字段，剔除值为空的参数，并按照第一个字符的键值ASCII码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值ASCII码递增排序，以此类推。
2、拼接
将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。
3、调用签名函数
使用各自语言对应的RSA2或SM2(参考2.1协议规则-签名算法)签名函数利用对接方私钥对待签名字符串进行签名，并进行Base64编码。
4、把生成的签名赋值给sign参数，拼接到请求参数中。
2.3.2 响应验签机制
返回的 json值内容包含首尾的“{”和“}”两个大括号，双引号也需要参与验签
如返回报文为：
{"appId":"661520093552836608","bizContent":"4sTBwwhyy/XWRQ2cKqhEROoy9kTfvUTQPU3+wiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun/aS/Q/fDLj+QB2456RApKqBxHIh69jw5OQudStiiu/+aBp8oBS3GJPWNkM9D+bZ7tw==","charset":"UTF-8","format":"JSON","method":"allinpay.shopoint.couponService.couponQuery","timestamp":"2020-01-13 17:06:36","token":"3Fuda7Vd983p6lKPT7V/MQ==","version":"1.0","reqSeq":"1451283028312393","respSeq":"1764893872302","sign":"53NwD69xZBqpr6TONWh6jHyG2AkwUczzMP5oI8tKeHMF0klZoUPLUszZN+iSzf1PL5r3yU99PfpUk8SqwnFsLw==","signType":"SM2"}
则待验签字段为：
{"appId":"661520093552836608","bizContent":"4sTBwwhyy/XWRQ2cKqhEROoy9kTfvUTQPU3+wiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun/aS/Q/fDLj+QB2456RApKqBxHIh69jw5OQudStiiu/+aBp8oBS3GJPWNkM9D+bZ7tw==","charset":"UTF-8","format":"JSON","method":"allinpay.shopoint.couponService.couponQuery","timestamp":"2020-01-13 17:06:36","token":"3Fuda7Vd983p6lKPT7V/MQ==","version":"1.0","reqSeq":"1451283028312393","respSeq":"1764893872302"}
同时取出签名值sign:
53NwD69xZBqpr6TONWh6jHyG2AkwUczzMP5oI8tKeHMF0klZoUPLUszZN+iSzf1PL5r3yU99PfpUk8SqwnFsLw==
1将签名参数（sign）使用base64解码为字节码串。
2、调用验签函数：使用各自语言对应的RSA2或SM2(参考2.1协议规则-签名算法)签名验证函数，传入待验签字段、服务提供方公钥、签名内容进行验签，根据返回结果判定是否验签通过。
2.3.3 异步通知验签机制
报文是通过http post请求，x-www-form-urlencoded数据,url encode后的body体示例如下：
charset=UTF-8&method=allinpay.shopoint.couponService.couponQuery&appId=661520093552836608&bizContent=4sTBwwhyy%2FXWRQ2cKqhEROoy9kTfvUTQPU3%2BwiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun%2FaS%2FQ%2FfDLj%2BQB2456RApKqBxHIh69jw5OQudStiiu%2F%2BaBp8oBS3GJPWNkM9D%2BbZ7tw%3D%3D&format=JSON¬ifyId=C0A8023B030E2E5D6D97926168D40008&sign=53NwD69xZBqpr6TONWh6jHyG2AkwUczzMP5oI8tKeHMF0klZoUPLUszZN%2BiSzf1PL5r3yU99PfpUk8SqwnFsLw%3D%3D&signType=RSA2&version=1.0×tamp=2020-01-13+17%3A06%3A36&token=3Fuda7Vd983p6lKPT7V%2FMQ%3D%3D
1、筛选并排序
获取所有请求参数，不包括字节类型参数，如文件、字节流，剔除sign、signType字段，剔除值为空的参数，并按照第一个字符的键值ASCII码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值ASCII码递增排序，以此类推。
2、拼接
将排序后的参数与其对应值，组合成“参数=参数值”的格式，并且把这些参数用&字符连接起来，此时生成的字符串为待签名字符串。
3、将签名参数（sign）使用 base64 解码为字节码串。
4、调用验签函数：使用各自语言对应的RSA2或SM2(参考2.1协议规则-签名算法)签名验证函数，传入待验签字段、服务提供方公钥、签名内容进行验签，根据返回结果判定是否验签通过。
2.3.4 报文加密传输
- 关于不同签名算法下参数报文加密的说明：
1、当签名算法（signType）为RSA2或SM2时，由于请求、响应或通知的参数集合（bizContent）已经整体加密，因此对接方无需再对参数进行额外加密。
2、当签名算法（signType）为SHA256WithRSA，对接方无需对请求、响应或通知的参数集合（bizContent）进行加密。如需了解具体请求参数的加密要求，请查阅对应接口的“取值”说明。若“取值”说明中明确要求“加密传输”，则应使用AES算法对字段明文进行加密（AES加密key将在接口开通流程中提供）。
- 请求参数集合（bizContent，详见2.4公共请求参数）使用对称加密算法加密后传输，具体方式如下：
1、当签名算法是RSA2(ECB/PKCS1Padding)时，对称加密算法为AES(ECB/ZeroPadding)。
2、当签名算法是SM2(密文排列:C1C3C2)时，对称加密算法为SM4(ECB/ZeroPadding)。
3、对接方随机生成长度128位的对称加密秘钥并对请求参数集合进行对称加密。
4、对接方使用服务提供方的公钥加密对称加密秘钥并将结果使用base64编码后通过token（详见2.4公共请求参数）传输给服务提供方。
5、服务提供方使用token对请求参数进行解密。
- 返回参数集合（bizContent，详见2.5公共响应参数）使用对称加密算法加密后传输，具体方式如下：
1、当签名算法是RSA2(ECB/PKCS1Padding)时，对称加密算法为AES(ECB/ZeroPadding)。
2、当签名算法是SM2(密文排列:C1C3C2)时，对称加密算法为SM4(ECB/ZeroPadding)。
3、服务提供方随机生成长度128位的对称加密秘钥并对响应参数集合进行对称加密。
4、服务提供方使用对接方的公钥加密对称加密秘钥并将结果使用base64编码后通过token（详见2.5公共响应参数）传输给对接方。
5、对接方在验签通过后对返回参数集合进行解密，解密步骤如下：
第一步：使用base64解码token；
第二步：使用对接方自己的签名算法私钥解密token；
第三步：使用解密后的token采用对称加密算法解密返回参数集合。
- 异步通知的请求参数集合（bizContent，详见2.8.1异步通知公共参数）使用对称加密算法加密后传输，具体方式同上。
2.4公共请求参数
|
参数 |
类型 |
必填 |
最大长度 |
描述 |
示例值 |
|
appId |
String |
是 |
32 |
由数字化营销平台分配的应用ID |
|
|
method |
String |
是 |
128 |
接口名称,详见具体接口的method值 |
allinpay.shopoint.memberService.memberQuery |
|
format |
String |
是 |
20 |
仅支持JSON |
JSON |
|
charset |
String |
是 |
10 |
请求使用的编码格式，UTF-8 |
UTF-8 |
|
signType |
String |
是 |
10 |
生成签名字符串所使用的签名算法类型，目前支持RSA2、SM2 |
SM2 |
|
sign |
String |
是 |
- |
请求参数的签名串（base64编码，详见2.3.1签名机制） |
|
|
timestamp |
String |
是 |
19 |
发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"; 6小时前的请求报文将做失效处理，不能重复发送 |
2023-07-20 09:01:50 |
|
version |
String |
是 |
5 |
调用的接口版本,详见具体接口的version值 |
1.0 |
|
bizContent |
String |
是 |
- |
请求参数集合，除公共参数外所有请求参数都必须放在这个参数中传递。（明文为JSON格式的字符串，采用对称加密算法整体加密，详见：2.3.4报文加密传输） |
明文示例："{\"couponNo\":\"100000000000016122346\" }" |
|
token |
String |
是 |
- |
报文解密随机令牌（base64编码，详见2.3.4报文加密传输） |
|
|
reqSeq |
String |
是 |
64 |
请求方流水号 |
|
2.5公共响应参数
|
参数 |
类型 |
必填 |
最大长度 |
描述 |
示例值 |
|
appId |
String |
是 |
32 |
由数字化营销平台分配的应用ID |
|
|
method |
String |
是 |
128 |
接口名称,详见具体接口的method值 |
allinpay.shopoint.memberService.memberQuery |
|
format |
String |
是 |
20 |
仅支持JSON |
JSON |
|
charset |
String |
是 |
10 |
请求使用的编码格式，UTF-8 |
UTF-8 |
|
signType |
String |
是 |
10 |
生成签名字符串所使用的签名算法类型，目前支持RSA2、SM2 |
SM2 |
|
sign |
String |
是 |
- |
响应报文的签名串,（base64编码，详见2.3.1签名机制） |
|
|
timestamp |
String |
是 |
19 |
发送响应的时间，格式"yyyy-MM-dd HH:mm:ss" |
2023-07-20 09:01:51 |
|
version |
String |
是 |
5 |
调用的接口版本,详见各个接口的version值 |
1.0 |
|
bizContent |
String |
是 |
- |
响应参数集合。（明文为JSON格式的字符串，采用对称加密算法整体加密，详见：2.3.4报文加密传输） |
明文示例： {"code":"0","data":"{\"name\":\"xxx\"}"} |
|
token |
String |
是 |
- |
报文解密随机令牌（base64编码，详见2.3.4报文加密传输） |
|
|
reqSeq |
String |
是 |
64 |
请求方流水号 |
|
|
respSeq |
String |
是 |
64 |
响应方流水号 |
|
2.6请求/响应/异常示例
请求示例
请求数据JSON格式如下：
{"appId":"661520093552836608","bizContent":"4sTBwwhyy/XWRQ2cKqhEROoy9kTfvUTQPU3+wiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun/aS/Q/fDLj+QB2456RApKqBxHIh69jw5OQudStiiu/+aBp8oBS3GJPWNkM9D+bZ7tw==","charset":"UTF-8","format":"JSON","method":"allinpay.shopoint.couponService.couponQuery","reqSeq":"1235432325242342","sign":"XjFCQnLXrMKxDw+VI1W7jjZlHe9PztnL4bnyphEyYylWui0OGx/KXPAPhlkvt1ShNh1NtiXXL9+T/xeE2F3cUUYDDr2IF/ogx8Cm0r7WqXWbYymEzvJtg5L30tucjwDdp1g7Ulrx6uZVg0f/iXyr40rMTBX2VfKJ8F24HcZDkQU=","signType":"RSA2","timestamp":"2020-01-13 17:06:36","token":"3Fuda7Vd983p6lKPT7V/MQ==","version":"1.0"}
其中待签名部分（除sign和signType以及空值外其余字段按ASCII码递增排序，组成k=v的形式用&连接）：
appId=661520093552836608&bizContent=4sTBwwhyy/XWRQ2cKqhEROoy9kTfvUTQPU3+wiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun/aS/Q/fDLj+QB2456RApKqBxHIh69jw5OQudStiiu/+aBp8oBS3GJPWNkM9D+bZ7tw==&charset=UTF-8&format=JSON&method=allinpay.shopoint.couponService.couponQuery&reqSeq=1235432325242342×tamp=2020-01-13 17:06:36&token=3Fuda7Vd983p6lKPT7V/MQ==&version=1.0
实际是通过http post请求，x-www-form-urlencoded数据,url encode后的body体如下：
charset=UTF-8&method=allinpay.shopoint.couponService.couponQuery&appId=661520093552836608&bizContent=4sTBwwhyy%2FXWRQ2cKqhEROoy9kTfvUTQPU3%2BwiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun%2FaS%2FQ%2FfDLj%2BQB2456RApKqBxHIh69jw5OQudStiiu%2F%2BaBp8oBS3GJPWNkM9D%2BbZ7tw%3D%3D&format=JSON$&reqSeq=1235432325242342&sign=53NwD69xZBqpr6TONWh6jHyG2AkwUczzMP5oI8tKeHMF0klZoUPLUszZN%2BiSzf1PL5r3yU99PfpUk8SqwnFsLw%3D%3D&signType=RSA2&version=1.0×tamp=2020-01-13+17%3A06%3A36&token=3Fuda7Vd983p6lKPT7V%2FMQ%3D%3D
响应示例
{"appId":"661520093552836608","bizContent":"4sTBwwhyy/XWRQ2cKqhEROoy9kTfvUTQPU3+wiZAtSMvj9c1QmrHS1iixaXpbKMdTlVuO5mL0dicCneXCiun/aS/Q/fDLj+QB2456RApKqBxHIh69jw5OQudStiiu/+aBp8oBS3GJPWNkM9D+bZ7tw==","charset":"UTF-8","format":"JSON","method":"allinpay.shopoint.couponService.couponQuery","timestamp":"2020-01-13 17:06:36","token":"3Fuda7Vd983p6lKPT7V/MQ==","version":"1.0","reqSeq":"1451283028312393","respSeq":"1764893872302","sign":"53NwD69xZBqpr6TONWh6jHyG2AkwUczzMP5oI8tKeHMF0klZoUPLUszZN+iSzf1PL5r3yU99PfpUk8SqwnFsLw==","signType":"RSA2"}
2.7请求地址
测试环境接口地址：https://dms-api-test.shopoint.cn/shopoint-openapis-web/apis/v3
生产环境接口地址：https://dms-api.shopoint.cn/shopoint-openapis-web/apis/v3
2.8异步通知
2.8.1 异步通知公共参数
|
参数 |
类型 |
必填 |
最大长度 |
描述 |
示例值 |
|
appId |
String |
是 |
32 |
由数字化营销平台分配的应用ID |
|
|
method |
String |
是 |
128 |
通知接口名称,详见具体接口的method值 |
allinpay.shopoint.couponService.checkNotify |
|
format |
String |
是 |
20 |
仅支持JSON |
JSON |
|
charset |
String |
是 |
10 |
通知内容使用的编码格式，UTF-8 |
UTF-8 |
|
signType |
String |
是 |
10 |
生成签名字符串所使用的签名算法类型，目前支持RSA2、SM2 |
RSA2 |
|
sign |
String |
是 |
- |
通知内容的签名串（base64编码，详见2.3.1签名机制） |
|
|
timestamp |
String |
是 |
19 |
发送通知时间，格式"yyyy-MM-dd HH:mm:ss" |
2023-07-20 09:01:52 |
|
version |
String |
是 |
5 |
通知接口版本,详见具体接口的version值 |
1.0 |
|
bizContent |
String |
是 |
- |
通知内容集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递。（JSON格式的字符串） |
"{\"couponNo\":\"100000000000016122346\" }" |
|
token |
String |
是 |
- |
通知内容（bizContent）解密随机令牌（base64编码，详见2.3.4报文加密传输） |
|
|
respSeq |
String |
是 |
64 |
通知流水号 |
ff2c8ec4183874e4 |
|
notifyId |
String |
是 |
50 |
通知唯一ID |
12d694c9976084882657640d2ad506f9 |
2.8.2 异步通知公共响应参数
|
参数 |
类型 |
必填 |
最大长度 |
描述 |
示例值 |
|
code |
String |
是 |
- |
通知响应返回码 |
10000-成功 （当通知响应返回码不等于10000时，数字化营销平台会重试通知，详见5.通知相关/通知重发机制） |
{"code":"10000"}
2.8.3 网络关系配置
对接方开通通知接口网络关系用(通联调用对接方的接口):
产线环境:
101.132.34.44、 106.14.134.117、47.103.129.98、 106.15.93.89、 47.100177.170、 139196.165.11、 139.224.129.121、47.101.196.64
测试环境:
47.100.220.163、106.15.190.45、47.116.118.115
二、对接方开通接口调用网络关系用(对接方调用通联的接口):
产线环境:
dms-api.shopoint.cn(lP:47.102.253.125 端口:443)
测试环境:
dms-api-test.shopoint.cn (lP: 47.103.163.7 端口:443)