Contract

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

[软件商授权接口协议]

[v1-9]

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

目录

1 版本说明 ................................................................................................

2 概要 ........................................................................................................

3 接入流程 ................................................................................................

3.1 业务流程图 .................................................................................

3.2 开发流程 .....................................................................................

4 接口协议 ................................................................................................

4.1 接入准备 .....................................................................................

4.2 协议规则 .....................................................................................

4.3 公共参数 .....................................................................................

4.4 签名算法 .....................................................................................

4.5 API 列表........................................................................................

4.5.1 检测商户是否存在 ..........................................................

4.5.2 创建店铺 ..........................................................................

4.5.3 订购软件许可 ..................................................................

4.5.4 状态码 ..............................................................................

5 附录 ........................................................................................................

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

1 版本说明

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

2 概要

x文档的阅读对象为软件商，如果文档内容存在错误或者对此文档有疑问还请及时沟通。

3. 接入流程

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

2.1业务流程图

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

2.2开发流程

第一步：软件商需要将本企业待售的各个软件应用进行软件规格码编码，生成唯一的规格码(已有的可以忽略本步骤)。

比如：XX 软件基础一年版，规格码：BS00001；XX 软件豪华两年版，

规格码：XS000001。

第二步：软件商根据本文档完成以下接口对接：

2.1 检测商户是否存在

2.2 创建商户

2.3 订购软件

第 三 步 ： 使 用 商 x 软 件 自 测 平 台 进 行 联 调 对 接 ( 地 址 ：

xxxxx://xxxxxxxx.xxxxx.xxx/xxxxx)。

第四步：商米配置商品，上架正式环境进行售卖。

注意

1）软件商需要分别提供联调（test）环境的接口和正式环境的接口；

2）商米和软件商测试环境联调完成后，商米运营人员会在商米 UAT环境中配置软件商正式环境配置，进行最后上线测试。因此会产生一部分测试数据。

3 接口协议

3.1接入准备

登录软件自测平台，获取密钥 key。

3.2协议规则

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

3.3公共参数

请求公共参数

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

返回公共参数

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

3.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"

3.5API 列表

3.5.1 检测店铺是否存在

接口地址

接口名称 checkMchExist

请求参数：

字段名	变量名	类型	必填	描述	示例值
请 求 流 水号	request_num ber	String	否	用来匹配请求的唯一
时间戳	timestamp	UInt(10)	是	当前 unix 时间戳
签名	sign	String(32)	是	请求签名用来验证请求的合 法性
渠 道 编 号	channel_code	String	是	固定值：SUNMI	SUNMI
店 铺 名 称	company_na me	String	是	跟营业执照的一致	人民路沙县小 吃店
账号	account	String	是	商户在软件商平台的登录账 号	186163XX797

返回参数：

字段名	变量名	类型	必填	描述	示例
状态码	code	Int	是	公共错误码。0 表示成功， 其他值表示失败	0
状 态 码 说明	message	String	是	错误信息描述，如果 code 不 为 0，需要返回具体错误信息	请求不合法
时间戳	timestamp	UInt(10)	是	调用本接口提交的时间戳 错误信息描述	150023902

状态	status	Uint(1)	是	0: 账号不存在或账号已存在，店铺不存在 1:账号和店铺已存在； 2:账号或店铺已存在且不允许当前渠道购买 /账号已存在，店铺存在多个且无法确认	返回值： =0 时，后续进行创建商户和店铺 =1 时，后续进行订购软件 =2 时,后续无法购买
商户 ID	mch_id	String	否	状态为 1，必须要传入此值	51034
店铺 ID	store_id	String	否	如果状态为 1 必须传入此 值，商户 ID 和店铺 ID 可相同；	43221
生 效 中 软 件 规 格码	auth_list	Array	否	如果状态为 1，则必须返回和商米约定的软件规格码 （SKU）。 如果没有生效中的 SKU，请返回 null，auth_list 可返回 null。
可 订 购 软 件 规 格码	app_list	Array	否	返回当前店铺状态下可订购的软件 SKU 编码。 如果没有，请返回 null ， app_list 可返回 null

auth_list 包含以下字段

字段名	变量名	类型	必填	描述	示例
软 件 规 格码	app_code	String	是	已开通的软件规格码	WM2000001
授权 ID	auth_id	String	是	已开通的软件授权 id	20823231201
授 权 开 始日期	auth_start	Date	是		2017-09-19
授 权 结 束日期	auth_end	Date	是	永久可以返回 2099-12-31	2099-12-31

app_list 包含以下字段：

字段名	变量名	类型	必填	描述	示例
软 件 规 格码	app_code	String	是	可订购软件的规格码	WM2000001

3.5.2 创建店铺

接口地址

接口名称 createMch

请求参数：

字段名	变量名	类型	必填	描述	示例
请求流水 号	request_ number	String	否	用来匹配请求的 唯一
时间戳	timestam p	UInt(10)	是	当前 unix 时间戳
签名	sign	String(32)	是	请求签名用来验证请求的 合法性
渠道编号	channel_ code	String	是	固定值：SUNMI	SUNMI
商户名称	company _name	String	是	跟营业执照的一致	xxxx 公司
店铺名称	store_na me	String	是	1.不存在商户时，创建商户时默认同时创建店铺 2.存在商户无店铺时，创建 店铺	人民路沙县小吃店
行业类别 ID	trade_typ e_id	Int	是	默认门店行业类别 ID 参考附录	8
行业类别名称	trade_typ e_name	String	是	默认门店行业类别名称，参考附录	10
商户所在省	province	String	否	省份名称	湖南省
商户所在市	city	String	否	城市名称	长沙市
商户所在区	region	String	否	县区名称	雨花区
商户地址	address	String	是	门店详细地址，不含省市 区	人民路 15 号

联系人	contactor	String	是	商家联系人姓名	王某某
账号	account	String	是	商家登录的账号	186163XX797
手机号码	mobile	String	是	联系人手机号码(可以作为 软件商系统登录的用户名)	186163XX797
密码	password	String	是	8 位数字和字母随机组合	fg52Sg7g
邮箱	email	String	否	联系人电子邮箱	186163XX797@qq.c om
备注	remark	String	否
门店业态	payment_ mode	Int	否	0 餐前付款 1 餐后付款	0
门店座机 电话	telephon e	String	否		021-1000000

返回参数：

字段名	变量名	类型	必填	描述	示例
状态码	code	Int	是	公共错误码。0 表示成功， 其他值表示失败	0
状态码说明	message	String	是	错误信息描述，如果 code 不为 0，需要返回具体错误信息	请求不合法
时间戳	timestam p	UInt(10)	是	调用本接口提交的时间戳	150023902
商户 ID	mch_id	String	是	软件商分配的商户唯一 ID	1001
商户名称	company _name	String	否	调用本接口提交的商户名 称	新美达餐饮有限公 司
默认店铺 ID	store_id	String	是	软件商分配的店铺唯一 ID	XW001
默认店铺 名称	store_na me	String	否	软件商返回的店铺名称	新美达餐饮( 平江 路店)
登录用户名	login_use rname	String	否	【可选】如果软件商商户账户体系用户名没有使用手机号作为用户名，可以生成一个新的用户名返回； 不返回此字段或为空默认 用户名请求参数传过去的手机号。	186163XX797 或 Shanxian1988
登录密码	login_pas sword	String	否	【可选】软件商可以返回 SUNMI 生成的密码，也可	fg52Sg7g

				以可以生成新密码返回；不返回此字段或为空，则默认登录密码是请求过去 的密码。
其他登录信息	login_oth er	String	否	【可选】如果软件商商户账户体系不是使用用户名密码方式登录，则可以将登录信息返回到该字段，比如使用短信登录或者其 他登录方式。	举例：请使用 186163XX797 通过 短信验证的方式进行登录

注:

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

3.5.3 订购软件许可

接口地址

接口名称 orderAuth

请求参数：

字段名	变量名	类型	必填	描述	举例
请 求 流 水号	request_nu mber	String	否	用来匹配请求的 唯一
时间戳	timestamp	UInt(10)	是	当前 unix 时间戳
签名	sign	String(32)	是	请求签名用来验证请求的合 法性
渠 道 编 号	channel_co de	String	是	固定值：SUNMI	SUMMI
商户 ID	mch_id	String	是	商户编号	1001
店铺 ID	store_id	String	是	店铺 ID	XW001
交 易 类型	trade_type	UInt(1)	是	1:新购/试用 2:续费 4:增值服务	1
软 件 规 格码	app_code	String	是	应用软件编码(唯一标识应用 及规格)

				参考规则:app 的英文+版本 (如 standard)+几年(如 01 标识 1 年 09 标识永久)
应 用 数 量	app_num	Int	是	应用授权数量，目前固定给 1 个	1

注：

在 SUNMI 平台上软件的试用不再单独区分交易类型，因此软件商需要单独提供试用软件规格码。试用结束后，商户需要另外购买正式版本的软件规格，暂时不支持直接从试用版升级到正式版本。

返回参数：

字段名	变量名	类型	必填	描述	示例
状态码	code	Int	是	公共错误码。0 表示成功，其他 值表示失败	0
状态码说 明	message	String	是	错误信息描述，如果 code 不为 0，需要返回具体错误信息	请求不合法
时间戳	timestamp	UInt(10)	是	调用本接口提交的时间戳	150023902
商户 ID	mch_id	String	是	调用本接口提交的商户编号	1001
应用授权 列表	auth_list	Array	是	应用授权的列表，1 个或多个

auth_list 包含以下字段：

字段名	变量名	类型	必填	描述	示例
软件规格码	app_code	String	是	调用本接口提交的软件规格 码	WM2000001
授权 ID	auth_id	String	是	该应用软件的授权 ID 无则 给随机数	20823231201
授权开始日期	auth_start	Date	是		2017-09-19
授权结束日期	auth_end	Date	是	永久可以返回 2099-12-31	2099-09-31

3.5.4 状态码

状态码(code)	状态码描述
0	处理成功
10000	系统异常
10001	签名校验失败
10002	渠道号不存在
10004	缺少参数
10005	订购失败，失败原因可返回在 message。