1 背景介绍
在商米数字店铺体系中,存在商户和门店的组织架构设计。
商户是用户使用数字店铺的基础组织,所有的数据和设备都是隶属于商户的。在一个商户下,用户可以创建一到多级的门店结构。
所有设备和数据都是基于门店聚合的,也就是说所有设备都是“绑定”在指定门店上的,用户每次对于设备和数据的操作也是基于门店的。
第三方软件如果需要接入商米设备和服务,先要建立双方店铺的对应关系,然后再基于这种绑定关系进行数据的打通。
商米数字店铺提供了三种对接绑定的模式,分别为:
- 对接软件通过openAPI直接创建商户门店实现自动绑定;
- 从对接软件发起绑定操作与已有的商米门店进行绑定;
- 从数字店铺发起绑定操作与已有的对接软件门店进行绑定。
具体描述请参考第二章,第三方对接软件可以根据需求选择任意一种合适的对接绑定方式。
2 店铺绑定方式及流程
2.1 对接软件创建商户门店自动绑定
这种绑定方式需要用户有一个商米账号,中国大陆为手机号码,其他地区为邮箱地址,用户可以在商米助手APP或者商米数字店铺网页( https://store.sunmi.com )上进行注册。(通过openAPI直接开通账号的接口正在开发中)
在完成对接的开发(使用商米提供的app_id、secret_key),并且有了账号之后再通过接口【创建商户】和【创建门店】在对接软件中完成商户门店的创建,返回的sunmi_company_no和sunmi_shop_no可作为后续所有接口唯一的商户和门店标识。
创建商户门店可以发生在添加绑定设备或者进行某项操作时,通过这种方式创建的门店将会自动和对接软件的门店进行绑定。
2.2 从对接软件发起绑定
这种绑定方式需要用户在商米助手APP或者 https://store.sunmi.com 上进行注册商米账号,并创建商户和门店。
在完成对接的开发(使用商米提供的app_id、secret_key),并且创建了门店之后,用户可以在【基础数据/组织管理/组织详情】中获取sunmi_shop_no 和 sunmi_shop_key,为了保证信息的有效性和安全性,对接凭证的有效期为24小时,过期之后可以重新获取。
用户可以在第三方对接软件指定页面输入这两个字段信息,然后再通过商米数字店铺开放平台提供的绑定接口进行校验。
关于shop_id 和 sunmi_shop_no的说明:
在当前版本的接口中,推荐使用sunmi_shop_no替代shop_id作为唯一标识,可以保证门店唯一性,便于数据汇总。以前版本接口中的shop_id仍然可以使用。
shop_id 和 sunmi_shop_no的对应关系,可以由通过获取对接软件门店绑定状态接口获取。
3 店铺对接绑定接口
3.1 接口规范
3.1.1 协议说明
对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。
Content-Type | application/x-www-form-urlencoded |
---|---|
数据格式 | 返回为JSON格式 |
字符编码 | UTF-8字符编码 |
签名算法 | MD5 |
签名规则 | 参考鉴权认证 |
3.1.2 签名规则
参考《鉴权认证》文档。
3.1.3 公共参数
参数名 | 必填 | 类型 | 说明 |
---|---|---|---|
app_id | 是 | string | 唯一标识接入身份,联系商米数字店铺提供 |
random | 是 | string | 随机字符串,由数字和字母组成,长度范围为6-10位 |
timestamp | 是 | int | 当前的unix timestamp,精度到秒级,10位数字 |
sign | 是 | string | 签名信息,详见上文签名规则 |
3.2 门店对接接口列表
接口名称 | 接口 |
---|---|
创建商户 | /company/create |
获取对接软件创建商户列表 | /company/getList |
获取对接软件创建商户详情 | /company/getInfo |
绑定商米商户 | /company/bind |
解绑商米商户 | /company/unbind |
创建门店 | /shop/create |
更新门店信息 | /shop/update |
绑定商米门店 | /shop/bind |
解绑商米门店 | /shop/unbind |
启用商米门店 | /shop/enable |
禁用商米门店 | /shop/disable |
获取对接软件创建门店列表 | /shop/getList |
获取对接软件创建门店详情 | /shop/getInfo |
获取对接软件门店绑定状态 | /shop/getBindInfo |
获取商米店铺组织树 | /shop/getOrgTree |
3.3 接口详情
3.3.1 绑定商米门店
接口描述: 通过本接口调用,用户可以将第三方对接软件上的某门店与商米数字店铺中的门店进行绑定。
请求链接:/shop/bind
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
shop_id | 是 | string | 第三方对接软件中门店的标识,对接的软件提供shop_id 与 sunmi_shop_no 具有一一对应关系。 对于v2.0 及以后版本的所有接口,建议采用sunmi_shop_no作为店铺标识。 对于已经使用shop_id作为参数的接口保持后向兼容,不需要进行修改。 |
shop_name | 是 | string | 第三方对接软件中门店的门店名称 |
sunmi_shop_no | 是 | string | 商米数字店铺的门店【对接店铺编号】,可在数字店铺【基础管理/组织管理/组织详情】中获取 |
sunmi_shop_key | 是 | string | 商米数字店铺的门店【对接店铺密钥】,可在数字店铺【基础管理/组织管理/组织详情】中获取 |
请求示例:
"method": "POST",
"url": "https://store.uat.sunmi.com/openapi/shop/bind",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
formData: {
"shop_id": "10096",
"shop_name": "myShop",
"sunmi_shop_no": "560279010307",
"sunmi_shop_key": "MG4LJ5ERHUBDMF5XOOU8",
"app_id": "LMWWQVTW4QGCC",
"timestamp": 1581383983,
"random": "5dsf6698",
"sign": "33C18A18282733A71F998BB5A5E4319D"
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5032 | 非法店铺 |
5041 | 非法对接软件 |
5042 | 对接软件中的门店已绑定 |
5043 | 对接商米店铺密钥错误 |
3.3.2 解绑商米门店
接口描述:通过本接口调用,用户可以将SaaS上的某门店与商米数字店铺中的门店解除绑定。
请求链接:/shop/unbind
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
shop_id | 是 | string | 第三方对接软件中门店的标识,对接的软件提供 |
sunmi_shop_no | 否 | string | 商米数字店铺的门店【对接店铺编号】 |
请求示例:
"method": "POST",
"url": "https://store.uat.sunmi.com/openapi/shop/unbind",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
formData: {
"shop_id": "10096",
"app_id": "LMWWQVTW4QGCC",
"timestamp": 1581383983,
"random": "5dsf6698",
"sign": "33C18A18282733A71F998BB5A5E4319D"
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5032 | 非法店铺 |
5041 | 非法对接软件 |
5000 | 数据库错误 |
3.3.3 更新门店信息
接口描述:
通过本接口调用,用户可以将第三方对接软件上的店铺信息同步到商米数字店铺。(联系人姓名和电话暂时不支持更改)
请求链接:/shop/update
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
shop_id | 是 | string | 第三方对接软件中门店的标识,对接的软件提供 |
sunmi_shop_no | 否 | string | 商米数字店铺的门店【对接店铺编号】 |
shop_name | 否 | string | 第三方对接软件中门店的门店名称 |
industry_id | 否 | int | 门店行业类别编号 |
industry_name | 否 | string | 门店行业类别名称 |
province | 否 | string | 所在省份 |
city | 否 | string | 所在市 |
district | 否 | string | 所在区县 |
address | 否 | string | 商户门店地址 |
否 | string | 联系人邮箱 | |
format | 否 | int | 门店业态 1 – 餐前付款, 2 – 餐后付款, |
status | 否 | int | 门店状态 1 – 启用, 2 – 停用 |
请求示例:
"method": "POST",
"url": "https://store.uat.sunmi.com/openapi/shop/update",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
formData: {
"shop_id": "10096",
"shop_name": "myShopNew",
"app_id": "LMWWQVTW4QGCC",
"timestamp": 1581383983,
"random": "5dsf6698",
"sign": "33C18A18282733A71F998BB5A5E4319D"
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5032 | 非法店铺 |
5041 | 非法对接软件 |
5000 | 数据库错误 |
3.3.4 创建商户
接口描述:通过本接口调用,用户可以在商米数字店铺平台上创建一个商户组织,在之后的操作中,可以在该商户下创建多级门店进行管理。
请求链接:/company/create
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
username | 是 | string | 商户管理员账户,目前仅支持手机号码,该手机号需要已经在商米数字店铺进行过注册,或者通过用户管理接口/user/register生成初始用户(参考《用户库》文档) | 18625776000 |
company_name | 是 | string | 商户名称 | company_test |
contact_person | 是 | string | 联系人姓名 | xs |
phone | 是 | string | 联系人电话 | 13813807411 |
否 | string | 联系邮箱 | lei.li@outlook.com | |
company_id | 否 | 第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。 记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。 对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和商米数字店铺体系中保持一致。 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/company/create',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583299191',
'random': '5dsf6698',
'sign': 'A9D0BA14993A3222E7C7FB860D0C51A1',
'company_name': 'company_test',
'contact_person': 'xs',
'phone': '13813807411',
'username': '18625776000'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {
"sunmi_company_no": "476934507308"
}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5010 | 管理员用户不存在 |
5000 | 数据库错误 |
5041 | 非法SaaS厂商 |
5035 | 商户名字已存在 |
5082 | rpc call fail |
3.3.5 获取对接软件创建商户列表
接口描述:通过本接口调用,saas合作方可以查看通过开放接口在商米数字店铺平台上创建的商户列表。
请求链接:/company/getList
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
username | 是 | string | 商户管理员账户,目前仅支持手机号码,该手机号需要已经在商米数字店铺进行过注册,或者通过用户管理接口/user/create生成初试用户和密码(暂未开放) | 18625776000 |
page_num | 否(默认1) | int | 当前页码 | 1 |
page_size | 否 (默认10) | int | 当前页条目数量 | 10 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/company/getList',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583299623',
'random': '5dsf6698',
'sign': 'EDA422052152701EC2579F97BF068D18',
'username': '18625776000'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {
"total_count": 3,
"company_list": [
{
"sunmi_company_no": "476934507308",
"username": "18625776000",
"company_name": "company_test",
"contact_person": "xs",
"contact_tel": "13813807411",
"contact_email": ""
},
{
"sunmi_company_no": "476934506958",
"username": "18625776000",
"company_name": "xs_test_01",
"contact_person": "xs",
"contact_tel": "13813807411",
"contact_email": ""
},
{
"sunmi_company_no": "476934506957",
"username": "18625776000",
"company_name": "xs_test_02",
"contact_person": "xs",
"contact_tel": "13813807411",
"contact_email": ""
}
]
}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5041 | 非法对接软件 |
3.3.6 获取对接软件创建商户详情
接口描述: 通过本接口调用,第三方对接软件可以查看通过开放接口在商米数字店铺平台上创建的商户列表。
请求链接:/company/getInfo
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
sunmi_company_no | 是 | string | 商米数字店铺平台商户唯一编码 | 476934507308 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/company/getInfo',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583300101',
'random': '5dsf6698',
'sign': 'F59845336C9492CE61BF63AA8F84B609',
'sunmi_company_no': '476934507308'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {
"sunmi_company_no": "476934507308",
"username": "18625776000",
"company_name": "company_test",
"contact_person": "xs",
"contact_tel": "13813807411",
"contact_email": ""
}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5033 | 非法sunmi company no |
5041 | 非法对接软件 |
3.3.7 创建门店
接口描述:
通过本接口调用,第三方对接软件可以在商米数字店铺平台上在指定商户下创建门店。
请求链接:/shop/create
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
shop_id | 是 | string | 第三方对接软件中门店的标识,对接的软件提供 |
shop_name | 是 | string | 第三方对接软件中门店的名称 |
sunmi_company_no | 是 | string | 商米数字店铺平台商户唯一标识,可以通过开放接口company相关接口创建并获取,也可以在商米数字店铺【基础管理/商户管理】页面上获取 |
sunmi_parent_shop_no | 否 | string | 如果是在当前商户下直接创建门店,不用赋值,如果是在其他门店下再创建门店,需要填写其对应的父类门店号,默认为空。 注:父类门店号的tag必须是1 |
tag | 否 | int | 组织类型,1-部门, 0-门店, 默认0 |
请求示例:
'method': 'POST',
'url': 'http://store.dev.sunmi.com/openapi/shop/create',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583301592',
'random': '5dsf6698',
'sign': '4C0C0516EC44BE0022BE80CED28E2A45',
'sunmi_company_no': '476934507308',
'company_id': '1000',
'shop_id': '0001',
'shop_name': 'shop_test'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {
"sunmi_shop_no": "803743210109"
}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5032 | 非法店铺 |
5033 | 非法sunmi company no |
5041 | 非法对接软件 |
5042 | 对接软件的门店已绑定 |
5444 | 非法的sunmi_parent_shop_no, 应该选择tag=1的门店 |
登录商米数字店铺,点击个人中心,在我的商户中,点击选中得店铺即可获取sunmi_company_no:
3.3.8 获取对接软件创建门店列表
接口描述:通过本接口调用,用户可以获取门店详情信息。
请求链接:/shop/getList
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
sunmi_company_no | 是 | string | 商米数字店铺平台商户唯一标识 | 476934507308 |
page_num | 否(默认1) | int | 当前页码 | 1 |
page_size | 否 (默认10) | int | 当前页条目数量 | 10 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/shop/getList',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302143',
'random': '5dsf6698',
'sign': '98F0E7619590B36E5BA34B94E815A97C',
'sunmi_company_no': '476934507308'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {
"total_count": 1,
"shop_list": [
{
"saas_shop": {
"company_id": "1000",
"shop_id": "0001",
"company_name": "company_test",
"shop_name": "shop_test",
"contact_person": "xs",
"phone": "13813807411",
"mail": "",
"industry_id": 0,
"industry_name": "",
"province": "",
"city": "",
"district": "",
"address": "",
"format": 0,
"status": 1
},
"sunmi_shop": {
"sunmi_shop_no": "803743210109",
"shop_name": "shop_test",
"contact_person": "xs",
"phone": "13813807411",
"mail": "",
"industry_id": 0,
"industry_name": "",
"province": "",
"city": "",
"district": "",
"address": "",
"format": 0,
"status": 1
}
}
]
}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5041 | 非法对接软件 |
5000 | 数据库错误 |
5033 | 非法sunmi company no |
5020 | 非法参数 |
5905 | 内部调用远端接店铺中心口出错 |
3.3.9 获取对接软件创建门店详情
接口描述:通过本接口调用,用户可以获取门店详情信息。
请求链接:/shop/getInfo
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
sunmi_shop_no | 是 | string | 商米数字店铺平台门店唯一标识 | 803743210109 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/shop/getInfo',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302480',
'random': '5dsf6698',
'sign': 'FF37DC3C9563263BB97528AF0E065C9D',
'sunmi_shop_no': '803743210109 '
}
返回值:
{
"data": {
"saas_shop": {
"company_id": "1000",
"shop_id": "0001",
"company_name": "company_test",
"shop_name": "shop_test",
"contact_person": "xs",
"phone": "13813807411",
"mail": "",
"industry_id": 0,
"industry_name": "",
"province": "",
"city": "",
"district": "",
"address": "",
"format": 0,
"status": 1
},
"sunmi_shop": {
"sunmi_shop_no": "803743210109",
"shop_name": "shop_test",
"contact_person": "xs",
"phone": "13813807411",
"mail": "",
"industry_id": 0,
"industry_name": "",
"province": "",
"city": "",
"district": "",
"address": "",
"format": 0,
"status": 1
}
}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5041 | 非法对接软件 |
5000 | 数据库错误 |
5032 | 非法店铺 |
3.3.10 获取对接软件门店绑定状态
接口描述:通过本接口调用,用户可以查看saas店铺绑定商米店铺的状态。
请求链接:/shop/getBindInfo
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
shop_id | 是 | string | 第三方对接软件中门店的标识,对接的软件提供 |
company_id | 否 | string | 第三方对接软件中商户的标识,对接的软件提供 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/shop/getBindInfo',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302789',
'random': '5dsf6698',
'sign': '8F889204B0600F25A4C121E6FF16D0D8',
'shop_id': '0001'
}
已经绑定商米店铺返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {
"status": 1, /*已绑定状态*/
"bound_info": {
"company_id": "1000",
"shop_id": "0001",
"sunmi_company_no": "476934507308",
"sunmi_shop_no": "803743210109"
}
}
}
未绑定商米店铺返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed"
"data": {
"status": 2, /*未绑定状态*/
"bound_info": {
"company_id": "",
"shop_id": "",
"sunmi_company_no": "",
"sunmi_shop_no": ""
}
}
}
返回字段描述:status
status | 说明 |
---|---|
1 | 已绑定商米店铺 |
2 | 未绑定任何商米店铺 |
返回字段描述: bound_info
参数名称 | 说明 |
---|---|
shop_id | 对接软件中门店标识 |
company_id | 对接软件中商户标识 |
sunmi_shop_no | 商米数字店铺中对应门店标识 |
错误列表:
错误编号 | 错误原因 |
---|---|
5032 | 非法店铺 |
5041 | 非法对接软件 |
5000 | 数据库错误 |
3.3.11 绑定商米商户
接口描述:通过本接口调用,用户可以将第三方对接软件上的某商户与商米数字店铺中的商户进行绑定。
请求链接:/company/bind
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
company_id | 是 | string | 第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。 记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。 对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和商米数字店铺体系中保持一致。 |
sunmi_company_no | 是 | string | 商米数字店铺的商户【对接商户编号】,可在数字店铺【**/**/**】中获取 |
sunmi_company_key | 是 | string | 商米数字店铺的商户【对接商户密钥】,可在数字店铺【**/**/**】中获取 |
company_name | 是 | string | 商户名称 |
contact_person | 是 | string | 联系人姓名 |
phone | 是 | string | 联系人电话 |
否 | string | 联系人邮箱 |
请求示例:
"method": "POST",
"url": "https://store.uat.sunmi.com/openapi/company/bind",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
formData: {
"company_id": "10000",
"sunmi_company_no": "560279010307",
"sunmi_company_key": "MG4LJ5ERHUBDMF5XOOU8",
"company_name": "myCompany",
"contact_person": "LiLei",
"phone": "13166668888",
"app_id": "LMWWQVTW4QGCC",
"timestamp": 1581383983,
"random": "5dsf6698",
"sign": "33C18A18282733A71F998BB5A5E4319D"
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5033 | 非法sunmi company no |
5041 | 非法对接软件 |
5042 | 对接软件中的商户已绑定 |
5043 | 对接商米店铺密钥错误 |
3.3.12 解绑商米商户
接口描述:通过本接口调用,用户可以将SaaS上的某商户与商米数字店铺中的商户解除绑定。
请求链接:/company/unbind
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
company_id | 是 | string | 第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。 记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。 对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和商米数字店铺体系中保持一致。 |
sunmi_company_no | 是 | string | 商米数字店铺的商户【对接商户编号】 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/company/unbind',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302789',
'random': '5dsf6698',
'sign': '8F889204B0600F25A4C121E6FF16D0D8',
'company_id': '1673',
'sunmi_company_no': '560279010307'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5033 | 非法sunmi company no |
5041 | 非法对接软件 |
5906 | 未找到绑定记录 |
3.3.13 获取商米店铺组织树
接口描述:通过本接口调用,用户可以获取数字店铺店铺列表,以树形结构返回。
请求链接:/shop/getOrgTree
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
sunmi_company_no | 是 | string | 商米数字店铺的商户【对接商户编号】 |
sunmi_shop_no | 否 | string | 商米数字店铺的店铺【对接店铺编号】 不填表示获取商户下所有组织, 填表示获取对应店铺下的组织。 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/shop/getOrgTree',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302789',
'random': '5dsf6698',
'sign': '8F889204B0600F25A4C121E6FF16D0D8',
'sunmi_company_no': '560279010307',
'sunmi_shop_no': '4529018395'
}
返回值:
{
"data": {
"shop_list": [
{
"shop_name": "网咖111",
"sunmi_shop_no": "474358470706",
"sunmi_parent_shop_no": "",
"tag": 0,
"status": 1,
"children": [
{
"shop_name": "网咖222",
"sunmi_shop_no": "474358470708",
"sunmi_parent_shop_no": "474358470706",
"tag": 0,
"status": 1,
"children": []
}
]
},
{
"shop_name": "sdfsdf",
"sunmi_shop_no": "474358470707",
"sunmi_parent_shop_no": "",
"tag": 0,
"status": 1,
"children": []
}
]
},
"code": 0,
"msg": "succeed"
}
返回字段描述:
字段 | 描述 |
---|---|
tag | 组织类型 1-部门, 0-门店 |
status | 门店状态 1-启用, 2-停用 |
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5041 | 非法对接软件 |
5033 | 非法sunmi company no |
5904 | 商户未授权 |
5905 | 内部调用远端接店铺中心口出错 |
3.3.14 启用店铺
接口描述:通过本接口调用,用户可以启用一个店铺,与禁用店铺相对。
请求链接:/shop/enable
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
sunmi_shop_no | 是 | string | 商米数字店铺的店铺【对接店铺编号】 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/shop/enable',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302789',
'random': '5dsf6698',
'sign': '8F889204B0600F25A4C121E6FF16D0D8',
'sunmi_shop_no': '4529018395'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5013 | 非法SaaS厂商 |
5032 | 非法店铺 |
5039 | 查询结果超过1条 |
5041 | 非法对接软件 |
3.3.15 禁用店铺
接口描述:通过本接口调用,用户可以禁用一个店铺,与启用店铺相对。
请求链接:/shop/disable
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 |
---|---|---|---|
sunmi_shop_no | 是 | string | 商米数字店铺的店铺【对接店铺编号】 |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/shop/disable',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'app_id': 'APPID6917LTY',
'timestamp': '1583302789',
'random': '5dsf6698',
'sign': '8F889204B0600F25A4C121E6FF16D0D8',
'sunmi_shop_no': '4529018395'
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
---|---|
5000 | 数据库错误 |
5013 | 非法SaaS厂商 |
5032 | 非法店铺 |
5039 | 查询结果超过1条 |
5041 | 非法对接软件 |
4 店铺录入接口
4.1 接口规范
4.1.1 协议说明
对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。
Content-Type | application/x-www-form-urlencoded |
---|---|
数据格式 | 返回为JSON格式 |
字符编码 | UTF-8字符编码 |
签名算法 | MD5 |
签名规则 | 参考4.1.2签名规则 |
4.1.2 签名规则
参考《鉴权认证》文档。
4.1.3 公共参数
参数名 | 必填 | 类型 | 说明 |
---|---|---|---|
app_id | 是 | string | 唯一标识接入身份,联系商米数字店铺提供 |
random | 是 | string | 随机字符串,由数字和字母组成,长度范围为6-10位 |
timestamp | 是 | int | 当前的unix timestamp,精度到秒级,10位数字 |
sign | 是 | string | 签名信息,详见3.2.2 |
4.2 门店录入接口列表
接口名称 | 接口描述 |
---|---|
/shop/import | 录入新门店信息 |
4.3 接口详情
4.3.1 录入新门店
接口描述:通过本接口调用,用户可以将SaaS上的某门店导入商米数字店铺平台,该门店并未和现有的数字店铺门店进行对齐。
请求链接:/shop/import
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
shop_id | 是 | string | SaaS对接店铺标识,SaaS厂商提供 | 10096 |
shop_name | 是 | string | 门店名称 | myShop |
company_id | 是 | string | SaasS对接商户唯一ID信息(记录店铺与商户对应关系, 对于单商户-多门店的模式用户,商户-门店对应关系在SaaS合作方与商米数字店铺体系中建议保持一致, 对于后续商户级别业务以及商户内跨门店业务接口需要根据此处记录做相关处理) | 10000 |
company_name | 是 | string | 商户名称 | myCompany |
contact_person | 是 | string | 联系人姓名 | LiLei |
phone | 是 | string | 联系人电话, 后续如果需要门店与商米数字店铺门店打通,需要通过手机号码进行认证 | 13166668888 |
industry_id | 否 | int | 门店行业类别编号 | 1 |
industry_name | 否 | string | 门店行业类别名称 | 餐饮 |
province | 否 | string | 所在省份 | 江苏省 |
city | 否 | string | 所在市 | 南京市 |
district | 否 | string | 所在区县 | 鼓楼区 |
address | 否 | string | 商户门店地址 | 华侨路 |
否 | string | 联系人邮箱 | lei.li@outlook.com | |
format | 否 | int | 门店业态 0-无 1 – 餐前付款, 2 – 餐后付款,默认0 | 1 |
status | 否 | int | 门店状态 1 – 启用, 2 – 停用, 默认1 | 1 |
请求示例:
"method": "POST",
"url": "https://store.uat.sunmi.com/openapi/shop/import",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
formData: {
"shop_id": "10096",
"shop_name": "myShop",
"company_id": "10000",
"company_name": "myCompany",
"contact_person": "LiLei",
"phone": "13166668888",
"app_id": "LMWWQVTW4QGCC",
"timestamp": 1581383983,
"random": "5dsf6698",
"sign": "33C18A18282733A71F998BB5A5E4319D"
}
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}
错误列表:
错误编号 | 错误原因 |
5013 | 非法SaaS厂商 |
5038 | SaaS店铺信息已存在 |