店铺绑定

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-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考鉴权认证

3.1.2 签名规则

参考《鉴权认证》文档。

3.1.3 公共参数

参数名必填类型说明
app_idstring唯一标识接入身份,联系商米数字店铺提供
randomstring随机字符串,由数字和字母组成,长度范围为6-10位
timestampint当前的unix timestamp,精度到秒级,10位数字
signstring 签名信息,详见上文签名规则

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_idstring第三方对接软件中门店的标识,对接的软件提供shop_id 与 sunmi_shop_no 具有一一对应关系。
对于v2.0 及以后版本的所有接口,建议采用sunmi_shop_no作为店铺标识。
对于已经使用shop_id作为参数的接口保持后向兼容,不需要进行修改。
shop_namestring第三方对接软件中门店的门店名称
sunmi_shop_nostring商米数字店铺的门店【对接店铺编号】,可在数字店铺【基础管理/组织管理/组织详情】中获取
sunmi_shop_keystring商米数字店铺的门店【对接店铺密钥】,可在数字店铺【基础管理/组织管理/组织详情】中获取

请求示例:  

  "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_idstring第三方对接软件中门店的标识,对接的软件提供
sunmi_shop_nostring商米数字店铺的门店【对接店铺编号】

请求示例: 

  "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_idstring第三方对接软件中门店的标识,对接的软件提供
sunmi_shop_nostring商米数字店铺的门店【对接店铺编号】
shop_namestring第三方对接软件中门店的门店名称
industry_idint门店行业类别编号
industry_namestring门店行业类别名称
provincestring所在省份
citystring所在市
districtstring所在区县
addressstring商户门店地址
mailstring联系人邮箱
formatint门店业态 1 – 餐前付款, 2 – 餐后付款,
statusint门店状态 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

接口参数

参数名称是否必须类型说明示例
usernamestring商户管理员账户,目前仅支持手机号码,该手机号需要已经在商米数字店铺进行过注册,或者通过用户管理接口/user/register生成初始用户(参考《用户库》文档)18625776000
company_namestring商户名称company_test
contact_personstring联系人姓名xs
phonestring联系人电话 13813807411
mailstring联系邮箱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商户名字已存在
5082rpc call fail

3.3.5  获取对接软件创建商户列表

接口描述:通过本接口调用,saas合作方可以查看通过开放接口在商米数字店铺平台上创建的商户列表。

请求链接:/company/getList

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
usernamestring商户管理员账户,目前仅支持手机号码,该手机号需要已经在商米数字店铺进行过注册,或者通过用户管理接口/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_nostring商米数字店铺平台商户唯一编码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_idstring第三方对接软件中门店的标识,对接的软件提供
shop_namestring第三方对接软件中门店的名称
sunmi_company_nostring商米数字店铺平台商户唯一标识,可以通过开放接口company相关接口创建并获取,也可以在商米数字店铺【基础管理/商户管理】页面上获取
sunmi_parent_shop_nostring如果是在当前商户下直接创建门店,不用赋值,如果是在其他门店下再创建门店,需要填写其对应的父类门店号,默认为空。
注:父类门店号的tag必须是1
tagint组织类型,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_nostring 商米数字店铺平台商户唯一标识 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_nostring商米数字店铺平台门店唯一标识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_idstring第三方对接软件中门店的标识,对接的软件提供
company_idstring第三方对接软件中商户的标识,对接的软件提供

请求示例:  

  '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_idstring第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。
记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。
对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和商米数字店铺体系中保持一致。
sunmi_company_nostring商米数字店铺的商户【对接商户编号】,可在数字店铺【**/**/**】中获取
sunmi_company_keystring商米数字店铺的商户【对接商户密钥】,可在数字店铺【**/**/**】中获取
company_namestring商户名称
contact_personstring联系人姓名
phonestring联系人电话
mailstring联系人邮箱

请求示例

  "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_idstring第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。
记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。
对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和商米数字店铺体系中保持一致。
sunmi_company_nostring商米数字店铺的商户【对接商户编号】

请求示例

'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_nostring商米数字店铺的商户【对接商户编号】
sunmi_shop_nostring商米数字店铺的店铺【对接店铺编号】
不填表示获取商户下所有组织,
填表示获取对应店铺下的组织。

请求示例

'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_nostring商米数字店铺的店铺【对接店铺编号】

请求示例

'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_nostring商米数字店铺的店铺【对接店铺编号】

请求示例

'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-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考4.1.2签名规则

4.1.2 签名规则

参考《鉴权认证》文档。

4.1.3 公共参数

参数名必填类型说明
app_idstring唯一标识接入身份,联系商米数字店铺提供
randomstring随机字符串,由数字和字母组成,长度范围为6-10位
timestampint当前的unix timestamp,精度到秒级,10位数字
signstring签名信息,详见3.2.2

4.2 门店录入接口列表

接口名称 接口描述
/shop/import录入新门店信息

4.3 接口详情

4.3.1 录入新门店

接口描述:通过本接口调用,用户可以将SaaS上的某门店导入商米数字店铺平台,该门店并未和现有的数字店铺门店进行对齐。

请求链接:/shop/import

接口参数

参数名称是否必须类型说明示例
shop_idstringSaaS对接店铺标识,SaaS厂商提供10096
shop_namestring门店名称myShop
company_id
stringSaasS对接商户唯一ID信息(记录店铺与商户对应关系,
对于单商户-多门店的模式用户,商户-门店对应关系在SaaS合作方与商米数字店铺体系中建议保持一致,
对于后续商户级别业务以及商户内跨门店业务接口需要根据此处记录做相关处理)
10000
company_name
string商户名称myCompany
contact_personstring联系人姓名LiLei
phonestring联系人电话, 后续如果需要门店与商米数字店铺门店打通,需要通过手机号码进行认证13166668888
industry_idint门店行业类别编号1
industry_namestring门店行业类别名称餐饮
provincestring所在省份江苏省
citystring所在市南京市
districtstring所在区县鼓楼区
addressstring商户门店地址华侨路
mailstring联系人邮箱lei.li@outlook.com
formatint门店业态 0-无 1 – 餐前付款, 2 – 餐后付款,默认01
statusint门店状态 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厂商
5038SaaS店铺信息已存在

附录

行业目录

鉴权认证

1 背景介绍

鉴权认证是为了保证所有开放接口openAPI的安全性而设计的,商米数字开放平台所有HTTP接口都需要经由本文档描述方式进行鉴权。以下内容描述的是如何通过接口的健全认证机制,接入商米数字店铺开放平台。

2 接口规范

2.1 协议说明

对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。

2.2 签名规则

对于所有的接入者,数字店铺开放平台会分配以下内容:

  • app_id: 唯一标识接入身份
  • secret_key: 该用户独有的签名校验

签名规则应用于对HTTP请求中的参数进行MD5签名,规则顺序如下:

  1. 参数必须包含random字段,为一个随机字符串,由数字和字母组成,长度范围为6-10位
  2. 参数必须包含timestamp字段 ,为当前的unix timestamp,精度到秒级,10位数字, 格式可以参考 https://tool.chinaz.com/tools/unixtime.aspx
  3. 参数必须包含app_id字段
  4. 首先对于所有包含key的传递参数按照ASCII码顺序从小到大排序,将key-value键值对依此组成字符串 (文件参数不参与验签)
  5. 在字符串尾部拼接该SaaS厂商独有的签名校验secret_key值,拼接方法见例子详述
  6. 对字符串进行MD5签名
  7. 对生成的MD5签名转化为全大写

示例:

假如需要传入的参数如下:

product_id: 389238
user_id: 29389
content: newproductmask
environment: test

则按照规则生成签名为

str1 = "app_id=2039dds&content=newproductmask&environment=test&product_id=389238&random=289192×tamp=1593029283&user_id=29389"
str2 = str1 + "&key=kdsofkdsnflke9382938k"
sign = MD5(str2).upper()

最终输出的参数为:

商米服务云平台会校验sign是否符合要求,sign校验不正确,返回code:5090;

timestamp的请求是否在合理范围时间内,请求过期,返回code:5091

3 校验顺序

商米数字店铺云平台会按照以下顺序进行校验

4 返回值检查

4.1 返回错误分类

作为HTTP消息返回,如果消息签名认证失败,HTTP消息会返回 401等作为提示。 如果消息签名认证通过,则进入业务层处理,此次HTTP请求返回200 OK。

具体业务层面的操作返回JSON值在消息体中。常见的消息返回类型为:

4.2 返回错误代码列表

错误代码错误原因
0成功
5090sign校验不正确
5091timestamp的请求过期

数字店铺介绍

介绍: