店铺绑定

[toc]

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的对应关系,可以由通过获取对接软件门店绑定状态接口获取。

2.3 从商米数字店铺发起绑定

2.3.1 对接绑定流程

当选择从商米数字店铺发起绑定请求时,第三方对接软件需要预先提供以下两部分内容:

  • 能够唯一标识某一个店铺的相关信息,例如门店编号,用户账号密码等
  • 能够发起校验输入内容正确性的HTTP接口

在完成对接的开发,有了上述信息后,用户在对接配置中选择对接的软件平台,输入相应的认证信息后,商米数字店铺会根据用户录入信息去指定软件平台提供的接口进行校验。

验证通过之后,商米数字店铺会绑定用户输入的对接软件门店和用户此时登录的商米门店。

第三方对接软件后续的请求中,只要将shop_id设定为该门店的id,后续所有的数据和业务请求会指定发送到用户当前数字店铺的门店当中。

2.3.2 对接软件提供的门店绑定接口 (示例)

接口说明:本接口是商米数字开放平台发起到第三方对接软件的请求,用于验证用户在商米数字平台录入的SaaS对接数据的准确性。

对于不同的第三方对接软件,唯一标识门店的方式可能会有不同,例如采用唯一id的模式,采用用户名和密码的模式等等。本示例以门店ID+验证码的模式作为范例,具体模式需要在对接时进行确认。

接口链接https://example.SaaS.com/api/verifyShop (示例接口,仅供参考)

接口参数

参数名称是否必须类型说明
shop_idstring第三方对接软件中门店的标识,对接的软件提供
verify_codestring店铺对应的校验码

返回值: 

{
    code:0
    msg: "succeed"
    data: {}
}

返回值(错误): 

{
    code:1
    msg: "invalid verify code"
    data: {}
}

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 门店对接接口列表

接口名称接口
绑定商米门店/shop/bind
解绑商米门店/shop/unbind
更新门店信息/shop/update
创建商户/company/create
获取对接软件创建商户列表/company/getList
获取对接软件创建商户详情/company/getInfo
创建门店/shop/create
获取对接软件创建门店列表/shop/getList
获取对接软件创建门店详情/shop/getInfo
获取对接软件门店绑定状态/shop/getBindInfo

3.3 接口详情

3.3.1 绑定商米门店

接口描述: 通过本接口调用,用户可以将第三方对接软件上的某门店与商米数字店铺中的门店进行绑定。

请求链接:/shop/bind

接口参数

参数名称是否必须类型说明
shop_idstring第三方对接软件中门店的标识,对接的软件提供shop_id 与 sunmi_shop_no 具有一一对应关系。
对于v2.0 及以后版本的所有接口,建议采用sunmi_shop_no作为店铺标识。
对于已经使用shop_id作为参数的接口保持后向兼容,不需要进行修改。
company_idstring第三方对接软件中商户的标识,对接的软件提供商户是门店的上一级组织。
记录商户与门店对应关系,可以据此处理后续商户级别业务,以及商户内跨门店业务。
对于单商户-多门店模式的用户,建议商户-门店的对应关系在第三方对接软件和商米数字店铺体系中保持一致。
shop_namestring第三方对接软件中门店的门店名称
company_namestring商户名称
sunmi_shop_nostring商米数字店铺的门店【对接店铺编号】,可在数字店铺【基础管理/组织管理/组织详情】中获取
sunmi_shop_keystring商米数字店铺的门店【对接店铺密钥】,可在数字店铺【基础管理/组织管理/组织详情】中获取
contact_personstring联系人姓名
phonestring联系人电话
industry_idint门店行业类别编号
industry_namestring门店行业类别名称
provincestring所在省份
citystring所在市
districtstring所在区县
addressstring商户门店地址
mailstring联系人邮箱
formatint门店业态 0-无 1 – 餐前付款, 2 – 餐后付款,默认0
statusint门店状态 1 – 启用, 2 – 停用, 默认1

请求示例:  

  "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",
    "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": {}
}

错误列表:

错误编号错误原因
5000数据库错误
5032非法店铺
5041非法对接软件
5042对接软件中的门店已绑定
5043对接商米店铺密钥错误

3.3.2 解绑商米门店

接口描述:通过本接口调用,用户可以将SaaS上的某门店与商米数字店铺中的门店解除绑定。

请求链接:/shop/unbind

接口参数

参数名称是否必须类型说明
shop_idstring第三方对接软件中门店的标识,对接的软件提供
company_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第三方对接软件中门店的标识,对接的软件提供
company_idstring第三方对接软件中商户的标识,对接的软件提供
sunmi_shop_nostring商米数字店铺的门店【对接店铺编号】
shop_namestring第三方对接软件中门店的门店名称
company_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",
    "company_name": "myCompanyNew",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

返回值: 

{
    "code": 0,   /* 其他错误参考错误列表 */
    "msg": "succeed",
    "data": {}
}

错误列表:

错误编号错误原因
5032非法店铺
5041 非法对接软件
5000数据库错误

3.3.4 创建商户

接口描述:通过本接口调用,用户可以在商米数字店铺平台上创建一个商户组织,在之后的操作中,可以在该商户下创建多级门店进行管理。

请求链接:/company/create

接口参数

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

请求示例:  

  '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 comany no
5041 非法对接软件

3.3.7 创建门店

接口描述

通过本接口调用,第三方对接软件可以在商米数字店铺平台上在指定商户下创建门店。

请求链接:/shop/create

接口参数

参数名称是否必须类型说明
shop_idstring第三方对接软件中门店的标识,对接的软件提供
company_idstring第三方对接软件中商户的标识,对接的软件提供
shop_namestring第三方对接软件中门店的名称
sunmi_company_nostring商米数字店铺平台商户唯一标识,可以通过开放接口company相关接口创建并获取,也可以在商米数字店铺【基础管理/商户管理】页面上获取
sunmi_parent_shop_nostring如果是在当前商户下直接创建门店,不用赋值如果是在其他门店下再创建门店,需要填写其对应的父类门店号默认为空
contact_personstring联系人姓名
phonestring联系人电话
industry_idint门店行业类别编号
industry_namestring门店行业类别名称
provincestring所在省份
citystring所在市
districtstring所在区县
addressstring商户门店地址
mailstring联系人邮箱
formatint门店业态 0-无 1 – 餐前付款, 2 – 餐后付款,默认0
statusint门店状态 1 – 启用, 2 – 停用, 默认1

请求示例:  

  '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',
    'contact_person': 'xs',
    'phone': '18625776019',
    '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 comany no
5041 非法对接软件
5042 对接软件的门店已绑定

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 comany no
5020非法参数

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数据库错误

附录

行业目录