同铸商务—SIP系统交易接口规范

软件工程 评论

同铸商务—SIP系统交易接口规范

一、创修记录

日期 版本 创修说明 创修人
2021-09-27 V1.0 创建文档 张维喜
2021-09-29 V1.1 新增流程图 张维喜
2021-10-09 v1.2 修改接口，流程图 张维喜
2021-10-18 v1.3 确定各接口地址 张维喜

二、适用范围

本文档将说明同铸商务—荣数信息资源整合平台（以下简称：SIP）与同铸商务相关系统（以下简称：同铸）进行交互。本文档仅提供同铸商务相关开发及维护人员使用，为了业务系统安全，请严格保密；
本文档主要提供信用卡积分查询、扣减等相关接口和交易查询、退款等相关接口的对接说明。

三、接口规范

类型 说明
传输方式 为保证交易安全性，采用 HTTPS 传输
提交方式 采用 POST 方法提交
MIME 类型 application/x-www-form-urlencoded;charset=UTF-8
数据格式 请求和响应数据均为 JSON 格式，
字符编码 统一采用 UTF-8 字符编码
签名算法 RSA算法
签名要求 请求和响应数据均需要校验签名
加密算法 RSA算法
加密要求 接口中注明加密的请求字段需要加密

四、样例说明

4.1 加密验签说明

SIP传输请求参数时，使用RSA算法对数据加密和加签。同铸接收到请求后，对数据进行
验签和解密等逻辑处理，处理成功后，在返回响应数据时，使用RSA算法对返回数据加密和加签。

4.2 ☆加密验签规范说明

**假设传送的数据如下： 

1
2
userId=1234
userName=Tomas

第一步：转化为Json串 

1
String origData ="{ 'userName': 'Thomas', 'userId': '123'}";

第二步：对Json串进行RSA加密和加签： 

1
2
3
4
5
6
7
8
9
// 供应商公私钥
RSAPublicKey orgPubKeyObj = RSAHelper.getPemRSAPublicKey(orgPubKey);
RSAPrivateKey orgPriKeyObj = RSAHelper.getPemRSAPrivateKey(orgPrivateKey);
// sip公私钥
RSAPublicKey sipPubKeyObj = RSAHelper.getPemRSAPublicKey(sipPubKey);
RSAPrivateKey sipPriKeyObj = RSAHelper.getPemRSAPrivateKey(sipPrivateKey);
// sip公钥对数据加密，供应商私钥对数据加签
String dataEn = encrypt(sipPubKeyObj, origData);
String dataEnSign = sign(origData, orgPriKeyObj);

第三步：拼接发送数据为： 

1
String sendData = "data=" + dataEn + "&sign=" + dataEnSign

最终发送数据： 

1
HttpsUtils.dopost('url',sendData,'application/x-www-form-urlencoded;charset=UTF-8')

五、接口规范说明

5.1 城市区域接口

5.1.1功能描述

有与拍摄服务在不同的城市有不同的价格，因此用户在下单前，要确定好下单的城市。将所有城市分为3个区域，不同的区域价格不同，同一区域同一产品价格相同

5.1.2 请求路径

5.1.3 请求参数

顺 序 字段名称 字段解 释 类型 是否必传 （Y/N） 示例 备注
1 productNo 产品编号 String(50) Y
2 cityType 城市类型 String(10) Y A,B,C 分别代表3个区域
3 timestamp 时间撮 Number(10) Y 1632794947 单位为妙
4 sign 签名 String Y 无 生成的签名

5.1.4 响应参数

顺序 字段名称 字段解释 类型 是否必传（Y/N） 示例 备注
1 resCode 响应码 String(6) Y 000000 无
2 resMsg 响应信息 String(100) Y 成功 无
3 data 区域 Map[] N 只有当resCode为000000时

region元素数据格式如下：

顺 序 字段名称 字段解释 类型 是否必传 （Y/N） 示 例 备注
1 name 省份名字 String(20） Y
2 code 地区编号 String(10) Y
3 children 下属区域 Map[] N 三节无此字段

5.1.5 整体返回案例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
    resCode: "000000",
    resMsg: "成功",
	data:[
    {
        "code": "10",
        "name": "江苏",
        "children":[
            {
                "code": "1011",
                "name": "南京",
                "children": [
                    {
                        "code": "2019",
                        "name": "玄武区",
                    }
                ]
            }
        ]
    }
    {
        "code":"11",
        "name":"北京市",
        "children":[
            {
                "code":"1101",
                "name":"市辖区",
                "children":[
                    {
                        "code":"110101",
                        "name":"东城区"
                    }
                ]
            }
        ]
    }
]
}

5.2 用户下单接口

5.2.1 功能描述

用户支付成功后，SIP平台调用同铸获取用户专有预约链接。

5.2.2 请求路径

5.2.3 请求参数

顺 序 字段名称 字段解 释 类型 是否必传 （Y/N） 示例 备注
1 userId 用户ID String(200) Y 123
2 productNo 商品编号 String(50） Y 无 同铸商品编号
3 sipOrderNo sip订单号 String(20) Y 无 字母或数字组成的随机 数，全局唯一
4 mobileNo 手机号 String(11) Y 无 手机号
5 cityId 城市ID String(20) Y 12
6 timestamp 时间撮 Number(10) Y
6 sign 签名 String Y 无 生成的签名

5.2.4 响应参数

顺序 字段名称 字段解释 类型 是否必传（Y/N） 示例 备注
1 resCode 响应码 String(6) Y 000000 无
2 resMsg 响应信息 String(100) Y 成功 无

只有当resCode为“000000”时会返回以下参数：

顺 序 字段名称 字段解释 类型 是否必传 （Y/N） 示 例 备注
1 userLink 用户专属 预定链接 String(200） Y 无 用户可以凭此链接跳转到 同铸进行预定服务
2 sipOrderNo sip订单号 String(50) Y 无 字母或数字组成的随机 数，全局唯一
3 venderOrderNo 商户订单号 String(50) Y 无 商户订单号
4 userStatus 使用状态 String（1） Y 0 0-未使用
1-使用

5.2.5 整体响应示例

1
2
3
4
5
6
7
8
{
    resCode: "000000",
    resMsg: "成功",
    userLink: "http://www.xx.com/path?data=xxx",
    sipOrderNo: "",
    venderOrderNo: "12356",
    userStatus: "0"
}

5.3 用户回调接口

5.3.1 功能描述

①用户在同铸平台预约成功后，同铸平台通知SIP平台用户已预约
②用户在同铸平台使用成功后，同铸平台通知SIP平台用户已使用

5.3.2 请求路径

测试地址：SIP提供
生产地址：SIP提供

5.3.3 请求参数

顺 序 字段名称 字段解 释 类型 是（否Y/必N）传 示 例 备注
1 venderOrderNo 商户订 单号 String(50) Y 无 商户订单号
2 userStatus 使用状 态 String（1） Y 1 0-未使用 1-使用
3 sipOrderNo sip订 单号 String(20) Y 无 字母或数字组成的随机数，全局 唯一
4 type 回调类 型 String(1) Y 无 0-预约
1-使用
5 useTime 使用时间 String(14) N 无 type = 1 时在传入，格式 为“yyyyMMddHHmmss”
6 timestamp 时间撮 String(10) Y 无
7 sign 签名 String Y 无 生成的签名

5.3.4 响应参数

顺序 字段名称 字段解释 类型 是否必传（Y/N） 示例 备注
1 resCode 响应码 String(6) Y 000000 无
2 resMsg 响应信息 String(100) Y 成功 无

5.4 用户退款前验证接口

5.4.1 功能描述

用户在荣放平台平台发起退款时，向同铸请求是否满足退款的条件

5.4.2 请求路径

测试地址：http://qupai.yyclub.me:800/api/sip/refund/check
生产地址：同铸提供

5.4.3 请求参数

顺 序 字段名称 字段解释 类型 是否必传 （Y/N） 示 例 备注
1 sipOrderNo sip订单号 String(20) Y 无 字母或数字组成的随机数， 全局唯一
2 timestamp 时间撮 String(10) Y
3 sign 签名 String Y 无 生成的签名

5.4.4 响应参数

顺序 字段名称 字段解释 类型 是否必传（Y/N） 示例 备注
1 resCode 响应码 String(6) Y 000000：可以退款
000001：不可退款
2 resMsg 响应信息 String(100) Y 成功 当返回000001时，会返回具体不可退款的原因

5.5 用户退款前验证接口

5.5.1 功能描述

用户在荣放平台平台发起退款时，应先向同铸平台发起退款申请，申请通过后，同铸会冻结用户当前的订单状态

5.5.2 请求路径

测试地址：http://qupai.yyclub.me:800/api/sip/refund/apply
生产地址：同铸提供

5.5.3 请求参数

顺 序 字段名称 字段解释 类型 是否必传 （Y/N） 示 例 备注
1 sipOrderNo sip订单号 String(20) Y 无 字母或数字组成的随机数， 全局唯一
2 timestamp 时间撮 String(10) Y
3 sign 签名 String Y 无 生成的签名

5.5.4 响应参数

顺序 字段名称 字段解释 类型 是否必传（Y/N） 示例 备注
1 resCode 响应码 String(6) Y 000000：申请成功
000001：申请失败
2 resMsg 响应信息 String(100) Y 成功 当返回000001时，会返回具体不可退款的原因

5.6 用户退款确认接口

5.6.1 功能描述

用户在荣放平台平台退款成功后，向同铸平台通知退款结果

5.6.2 请求路径

测试地址：http://qupai.yyclub.me:800/api/sip/refund/confirm
生产地址：同铸提供

5.6.3 请求参数

顺 序 字段名称 字段解释 类型 是否必传 （Y/N） 示 例 备注
1 sipOrderNo sip订单号 String(20) Y 无 字母或数字组成的随机数， 全局唯一
2 refundTime 退款时间 String(10) Y 无 为“yyyyMM格d式dHHmmss”
3 timestamp 时间撮 String(10) Y
5 sign 签名 String Y 无 生成的签名

5.6.4 响应参数

顺序 字段名称 字段解释 类型 是否必传（Y/N） 示例 备注
1 resCode 响应码 String(6) Y 000000 如不能退款，则返回非000001
2 resMsg 响应信息 String(100) Y 成功 如不能退款，返回不能退款原因

六、交互流程图