商户接口

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_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

3.3 接口详情

3.3.1 创建商户

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

请求链接：/company/create

接口参数：

参数名称是否必须类型说明示例
username是string商户管理员账户，目前仅支持手机号码,该手机号需要已经在商米数字店铺进行过注册，或者通过用户管理接口/user/register生成初始用户（参考《用户管理》文档）18625776000
company_id是string第三方对接软件中商户的标识，对接的软件提供商户是门店的上一级组织。COM39208
company_name是string商户名称company_test
contact_person是string联系人姓名xs
phone是string联系人电话 13813807411
mail否string联系邮箱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.2  获取对接软件创建商户列表

接口描述：通过本接口调用，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.3 获取对接软件创建商户详情

接口描述： 通过本接口调用，第三方对接软件可以查看已授权的商户详情。

请求链接：/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.4 绑定授权商米商户

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

请求链接：/company/bind

接口版本：v2.0

接口参数：

参数名称是否必须类型说明
company_id是string第三方对接软件中商户的标识，对接的软件提供商户是门店的上一级组织。
记录商户与门店对应关系，可以据此处理后续商户级别业务，以及商户内跨门店业务。
sunmi_company_no是string商米数字店铺的商户【对接商户编号】，可在数字店铺【**/**/**】中获取
sunmi_company_key是string商米数字店铺的商户【对接商户密钥】，可在数字店铺【**/**/**】中获取
company_name是string商户名称
contact_person是string联系人姓名
phone是string联系人电话
mail否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.5 解绑商米商户授权

接口描述：通过本接口调用，用户可以将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未找到绑定记录