Contract

上海商米科技集团股份有限公司

[软件商授权接口协议]

[v1-9]

上海商米科技集团股份有限公司

目录

1 版本说明 2

2 概要 2

3 接入流程 4

3.1 业务流程图 4

3.2 开发流程 5

4 接口协议 1

4.1 接入准备 1

4.2 协议规则 1

4.3 公共参数 1

4.4 签名算法 2

4.5 API 列表 4

4.5.1 检测商户是否存在 4

4.5.2 创建店铺 7

4.5.3 订购软件许可 10

4.5.4 状态码 12

5 附录 13

上海商米科技集团股份有限公司

1 版本说明

版本号	更新时间	修改人
V1.9	2019-12-20	xx
版本说明
1.删除”检测商户是否存在接口”中的请求字段”手机号”
2.在”检测商户是否存在接口”中新增请求字段“账户”
3.修改”检测商户是否存在接口”中的返回字段“状态”的枚举值
4.在”检测商户是否存在接口”中新增返回字段“商户 ID”、“店铺 ID”、“生效的软件”、“可购软件”、“是否在试用中”
5.在“创建商户接口”中新增请求字段“账户”
6.在“订购软件许可接口”中新增请求字段“交易类型”
7.在“订购软件许可接口”中新增请求字段“店铺 ID”
8.新增返回码”10005”,当订购失败时可以返回此码

2 概要

x文档的阅读对象为软件商，如果文档内容存在错误或者对此文

上海商米科技集团股份有限公司

档有疑问还请及时沟通。

3 接入流程

上海商米科技集团股份有限公司

3.1业务流程图

上海商米科技集团股份有限公司

3.2开发流程

第一步 软件商开发者将本企业待售的各个软件应用进行编码，生成唯一的规格码(已有的可以忽略本步骤)。比如 XX 软件基础一年版 规格码:BS00001；XX 软件豪华两年版 XS000001

第二步 软件商开发者根据本文档完成 2.1 检测商户是否存在、2.2 创建商户、2.3 订购软件许可

第三步 与米商平台进行联调对接(自主测试平台 xxxxxx.xxxxx.xxx)

第四步 软件应用上架米商测试平台进行全面购买测试第五步 上架米商正式环境进行初步售卖

注意:须提供一套联调（test）环境的接口及一套正式环境的接口

4 接口协议

4.1接入准备

通过对接人 获取商米的渠道编号和密钥 key

4.2协议规则

传输方式	为保证安全性，采用 HTTPS 传输
提交方式	采用 POST 方法提交
数据格式	请求数据为表单格式 返回数据为 json 格式
字符编码	统一采用 UTF-8 字符编码
签名算法	MD5
签名要求	请求和接收数据均需要校验签名

4.3公共参数

请求公共参数

字段名	变量名	是 否 必选	类型	描述
请求流 水号	request_number	否	String	用来匹配请求的 唯一
时间戳	timestamp	是	UInt(10)	当前 unix 时间戳

签名	sign	是	String(32)	请求签名用来验证请 求的合法性
渠道编 号	channel_code	是	String	固定值：SUNMI

返回公共参数

字段名	变量名	类型	示例	描述
错误码	code	Int	0	公共错误码。0 表示成功，其 他值表示失败
信息描 述	message	String	请 求 不 合法	错误信息描述
时间戳	timestam p	UInt(10)	1500239 02	调用接口时提交的时间戳

4.4签名算法

生成签名有三个步骤。

一、请求参数中非必传字段若传值为 null 或者空字符串，则排除此字段，不参与下面排序拼接生成签名 sign。

二、将请求参数(除签名以外)按参数名 ASCII 码从小到大排序并且以键值对(即 key1=value1&key2=value2&key3=value3…)拼接方式拼接成原始字符串 stringA。

三、在 stringA 最后拼接上密钥 key 得到 stringSignTemp 字符串，并对 stringSignTemp 进行 md5，并将得到的字符串转为大写，即可得到签名的值 sign。

举例：

假设传送的参数如下（其中 request_number、address 和 email 为非必传字段，且分别为 10002304、null 和空字符串）：

request_number 10002304

timestamp 1501463464 channel_code XS0000000001

app_id

A223340002

device_info 10002 address null

email

第一步排除 address 和 email 两个字段

request_number 10002304

timestamp 1501463464 channel_code XS0000000001

app_id

A223340002

device_info 10002

第二步按键值对拼接字符串，并且以 ASCII 码排序 stringA=”app_id=A223340002&channel_code=XS0000000001&device_in fo=10002& request_number=10002304& timestamp=1501463464”

第三步拼接密钥 key，md5 之后转大写

stringSignTemp=stringA+"&key=290987730b4c09247ec02edce67sc9d2" sign=MD5(stringSignTemp).toUpperCase()="DB09F317E6E76A7E7F2083

BE9F446910"

4.5API 列表

4.5.1 检测店铺是否存在

接口地址

接口名称 checkMchExist

请求参数

字段名	变量名	是否必选	类型	描述
请求流水号	request_number	否	String	用来匹配请求的 唯一
时间戳	timestamp	是	UInt(10)	当前 unix 时间戳
签名	sign	是	String(32)	请求签名用来验证请求 的合法性
渠道编号	channel_code	是	String	固定值：SUNMI
店铺名称	company_name	是	String	跟营业执照的一致

账户 account 是 String 软件商登录账号

返回

字段名	变量名	类型	示例	描述
状态码	code	Int	0	公共错误码。0 表 示成功，其他值表示失败
状态码说明	message	String	请求不合法	错误信息描述
时间戳	timestamp	UInt(10)	150023902	调用本接口提交 的时间戳
状态	status	Uint(1)	0 可以正常走后续创建商户以及订购软件流程 1 可以订购 软件流程	0：账号不存在 1：店铺已存在可进行购买； 2: 店铺已存在且 不允许当前渠道购买
商户 ID	mch_id	String		如果状态为 1，必 须要传入此值
店铺 ID	store_id	String		如果状态为 1 必须传入此值，商户 ID 和店铺 ID 可相 同；

该店铺是否在试 用中	trial	Uint(1)		0：不在试用中 1：在试用中
生效中软件规格码	auth_list	Array		如果状态为 1，需返回此字段，返回与 商 x 约 定 的 SKU 编码。 同时如果没有生 效中的 SKU，请返回 null。
可订购软件规格码	app_list	Array		返回当前店铺状态下可订购的软 件 SKU 编码

auth_list 包含以下字段

软件规格码	app_code	String	WM2000001	已开通软件的规格 码
授权 ID	auth_id	String	20823231201	已开通软件的授权 id
授权开始日期	auth_start	Date	2017-09-19
授权结束日期	auth_end	Date	2018-09-19

app_list 包含以下字段

软件规格码 app_code String WM2000001 软件的规格码

4.5.2 创建店铺

接口地址

接口名称 createMch

请求参数

字段名	变量名	是否必选	类型	描述
请求流水 号	request_number	否	String	用来匹配请求的 唯一
时间戳	timestamp	是	UInt(10)	当前 unix 时间戳
签名	sign	是	String(32)	请求签名用来验证请 求的合法性
渠道编号	channel_code	是	String	固定值：SUNMI
商户名称	company_name	是	String	跟营业执照的一致
默认门店 名称	store_name	是	String	创建商户时默认开一 个门店
行业类别 ID	trade_type_id	是	Int	默认门店行业类别 ID， 参考附录
行业类别 名称	trade_type_name	是	String	默认门店行业类别名 称，参考附录
商户所在 省	province	否	String	湖南省 注意：新增省 市区字段(20190708)，

				对之前已对接没传省市区的软件商不影响，按需传过去
商户所在 市	city	否	String	长沙市
商户所在 区	region	否	String	雨花区
商户地址	address	是	String	商户/默认门店地址
联系人	contactor	是	String	商家联系人姓名
账户	account	是	String	用户登录的账号
手机号	mobile	是	String	联系人手机号码(可以 作为软件商系统登录的用户名)
密码	password	是	String	8 位数字字母组合
邮箱	email	否	String	联系电子邮箱
备注	remark	否	String
门店业态	payment_mode	否	Int	0 餐前付款 1 餐后付 款
门店座机 电话	telephone	否	String	000-0000000

返回

注:如果软件商商户系统，登录用户名是手机号，支持 8 位数字字母作为密码，login_username,login_password,login_other 可不给

字段名	变量名	类型	示例	描述
状态码	code	Int	0	公共错误码。0 表示成功，其 他值表示失败
状态码说明	message	String	请 求 不 合 法	错误信息描述
时间戳	timestamp	UInt(10)	150023902	调用本接口提交的时间戳
商户 ID	mch_id	String	1001	软件商分配的商户编号
商户名称	company_na me	String	新 美 x 餐 饮 有 限 公 司	调用本接口提交的商户名称
默认门店 ID	store_id	String	XW001	软件商分配的门店编号
默认门店名称	store_name	String	新 美 x 餐 饮( 平江路 店)
登录用户名	login_userna me	String	test_admin	【可选】如果软件商商户体系用户名不一定是手机号，可以生成一个新的用户名返 回；不返回此字段或为空默

如果软件商支持商户对应多个店铺的逻辑，会出现传入的商户 ID 相同，店铺 ID 不同的情况。

				认用户名请求参数传过去的 手机号
登录密码	login_passwo rd	String		【可选】如果软件商商户体系登录密码不是 8 位数字字母组合，可以生成一个新密码返回；不返回此字段或为空默认登录密码是请求参数 传过去的密码
其他登录信息	login_other	String		【可选】如果软件商商户体系不是用户名密码方式登录，那么将登录信息写清楚 返回到该字段

4.5.3 订购软件许可

接口地址

接口名称 orderAuth

请求参数

字段名	变量名	是否必选	类型	描述
请 求 流 水 号	request_number	否	String	用来匹配请求的 唯 一
时间戳	timestamp	是	UInt(10)	当前 unix 时间戳

签名	sign	是	String(32)	请求签名用来验证请 求的合法性
渠道编号	channel_code	是	String	固定值：SUNMI
商户 ID	mch_id	是	String	商户编号
店铺 ID	store_id	是	String	店铺 ID
交易类型	trade_type	是	UInt(1)	1:新购/试用 2:续费 3:升级 4:增值服务
软 件 规 格 码	app_code	是	String	应用软件编码( 唯一 标识应用及规格) 参考规则:app 的英文 +版本( 如 standard)+ 几年(如 01 标识 1 年 09 标识永久)
应用数量	app_num	是	Int	应用授权数量 目前 固定给 1

返回

字段名	变量名	类型	示例	描述
状态码	code	Int	0	公共错误码。0 表示成 功，其他值表示失败

状态码说明	message	String	请求不合法	错误信息描述
时间戳	timestamp	UInt(10)	150023902	调用本接口提交的时 间戳
商户 ID	mch_id	String	1001	调用本接口提交的商 户编号
应用授权列表	auth_list	Array		应用授权的列表，1 个 或多个

auth_list 包含以下字段

软件规格码	app_code	String	WM2000001	调用本接口提交的 软件规格码
授权 ID	auth_id	String	20823231201	该应用软件的授权 ID 无则给随机数
授权开始日期	auth_start	Date	2017-09-19
授权结束日期	auth_end	Date	2018-09-19

4.5.4 状态码

状态码(code)	状态码描述
0	处理成功
10000	系统异常
10001	签名校验失败

10002	渠道号不存在
10004	缺少参数
10005	订购失败（接口 4.5.3 使用）

5 附录

商米-商户行业类别.xlsx