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 |
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 |
否 | 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 | 企业名字已存在 |
5082 | rpc 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 | 企业名称 |
请求示例:
"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 | 未找到绑定记录 |