设备安装单对接

1.背景介绍

用于外部工单系统与内部基多的安装单进行数据更新同步

2. 接口规范

2.1 协议说明

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

Content-Typeapplication/json
数据格式返回为Json格式
字符编码UTF-8字符编码
签名算法RSA
签名规则参考2.2

2.2 签名规则

使用非对称加密方式，请求方生成密钥对，保留密钥对的私钥，并对请求体进行加签后再作请求，防止消息被篡改。提供接口的一方保留密钥对的公钥，对请求体进行签名验证。

2.2.1 生成密钥对

  1. 使用openssl工具生成RSA私钥和公钥 (2048 bit)
  2. 把RSA私钥转换成PKCS8格式
  3. 将RSA公钥发送给需要验签的一方

2.2.2 加签步骤

  1. 获取请求体 post 内容，不包括字节类型参数，如文件、字节流，剔除 sign 字段，剔除值为空的参数;
  2. 按照第一个字符的键值 ASCII 码递增排序（字母升序排序），如果遇到相同字符则按照第二个字符的键值 ASCII 码递增排序，以此类推；
  3. 将排序后的参数与其对应值，组合成 参数=参数值 的格式，并且把这些参数用 & 字符连接起来，此时生成的字符串为待签名字符串。示例：
原请求体：
{"app_id":"20210021","time_stamp":1643093114,"biz_content":{"order_no":"","shop_no":""}}

处理完成后："app_id='20210021'&time_stamp=1643093114&biz_content={'order_no':'','shop_no':'','shop_name':''}"
  • 使用rsa 私钥对字符串进行加签(使用sha1算法，并进行base64处理)。

2.3 公共参数

参数名必填类型说明示例
app_id是string唯一标识接入身份，联系商米数字店铺提供“20210021”
time_stamp是int当前的unix timestamp，精度到秒级，10位数字1643093114
sign是string签名信息skdsaijaowpeoqpo

3. 安装单接口

3.1 基多服务端同步接口

接口描述：通过此接口将工单数据同步到基多服务中

请求链接：http://quito.sunmi.com/quito/api/mgt/order/subOrder/updateInfo

接口版本：v 1.0

加密之前的字段：

安装单字段

参数名称必须类型说明
sub_order_no是string设备安装单编号（子订单编号）
shop_no是string门店编号
shop_name是string门店名称
sn否string设备号
install_mode否string安装方式
WALL_MOUNTING 挂壁安装
RACK_MOUNTING 底架支座安装
install_pic否string安装照片，英文逗号分隔，最多5张
install_video否string安装视频，一个
order_process_status是string安装进度
WAIT_ORDER 待预约
ORDER_FAILED 预约失败
WAIT_INSTALL 待上门
WAIT_ACCEPT 待验收
ACCEPTED 已验收
ACCEPT_FAILED 验收失败
INSTALL_CANCEL 取消安装
installer_sp否string安装网点
installer否string安装人员
install_cancel_reason否string取消安装原因
install_date否string安装日期 YY/MM/DD
book_visit_date否string预约上门日期 YY/MM/DD
device_apply_type否string设备用途
device_mode是string设备型号

请求示例：

{"app_id":"20210021",
"time_stamp":1643093114,
"sign":"skdsaijaowpeoqpo",
"biz_content":{"order_no":"BOb676d92478b9c94096",
              "shop_no":"910553061572",
              "shop_name":"我的店铺",
              "order_process_status":"WAIT_ORDER",
              "device_mode":"NPE01",
}}

返回值：

{"code":1,"msg":"success"}

错误码：

code说明
1更新成功
-1其他错误
5000数据库错误
5026验签失败
6055sn与门店绑定不一致
6056设备未完成回收/维保换机流程
6057 订单状态不能回退
6088设备型号不匹配

3.2 第三方工单系统创建接口

接口描述：通过此接口将安装订单数据导入进第三方工单系统

请求链接：/api/order/create

接口版本：v 1.0

加密之前的字段：

安装订单字段属性

参数名称必须类型说明
order_no是string主订单编号
apply_time是int订单申请时间戳
created_time是int订单创建时间戳
shop_no是string门店编号
shop_name是string门店名称
city是string市
district是string区
address是string详细地址
house_no是string门牌号
comment是string备注
remark是string审核备注
sub_order_list是list[sub_order]子订单列表，每一笔子订单对应一台设备安装
pictures是list[string]现场照片
reference_company否string推荐人公司
reference_name否string推荐人姓名
reference_phone否string推荐人联系方式
contact_name是string店家联系人
contact_tel是string店家联系电话
router_cnt是int路由数量
router_model否string路由型号

sub_order 子订单属性

参数名称必须类型说明
sub_order_no是string子订单编号
device_mode是string设备型号, NPG01: 32寸商业显示器, NPE01: 24寸商业显示器设备型号,NPH01: 43寸商业显示器（4G）,NPH02: 43寸商业显示器

请求示例：

{"app_id":"20210021",
"time_stamp":1643093114,
"sign":"skdsaijaowpeoqpo",
"biz_content":{
    "order_no":"BOb676d92478b9c94096",
    "created_time":1643093114,
    "shop_no":"910553061572",
    "shop_name":"我的店铺",
    "city":"上海市",
    "district":"杨浦区",
    "address":"淞沪路388号",
    "house_no":"203",
    "commment":"",
    "remark":"",
    "sub_order_list":[{
        "sub_order_no":"SBOC12CEF63480CE180640009",
        "device_mode":"NPG01"}
        ],
    "pictures":["http://sunmi.cdn.com/1234.jpg"],
    "reference_company":"商米",
    "reference_name":"张三",
    "reference_phone":"17239123321",
    "contact_name":"李四",
    "contact_tel":"241244124",
    "router_cnt":1,
    "router_model":""
}

返回值：

{"code":1,"msg":"success"}

错误码：

code说明
1导入成功
-1其他错误
5000数据库错误
5020无效参数
5021无效路径
5023参数缺失
5026验签失败

3.3 第三方工单系统更新接口

接口描述：通过此接口修改第三方工单系统的订单数据

请求链接：/api/order/update

接口版本：v 1.0

加密之前的字段：

参数名称必须类型说明
order_no是string主订单编号
shop_name否string门店名称
city否string市
district否string区
address否string详细地址
house_no否string门牌号
comment否string备注
remark否string审核备注
sub_order_list否list[sub_order]子订单列表，每一笔子订单对应一台设备安装
pictures否list[string]现场照片
reference_company否string推荐人公司
reference_name否string推荐人姓名
reference_phone否string推荐人联系方式
contact_name否string店家联系人
contact_tel否string店家联系电话
router_cnt否int路由数量
router_model否string路由型号

sub_order 子订单属性

参数名称必须类型说明
sub_order_no是string子订单编号
device_mode是string设备型号, NPG01: 32寸商业显示器, NPE01: 24寸商业显示器设备型号,NPH01: 43寸商业显示器（4G）,NPH02: 43寸商业显示器

请求示例：

{"app_id":"20210021",
"time_stamp":1643093114,
"sign":"skdsaijaowpeoqpo",
"biz_content":{
    "order_no":"BOb676d92478b9c94096",
    "shop_no":"910553061572",
    "shop_name":"我的店铺",
    "city":"上海市",
    "district":"杨浦区",
    "address":"淞沪路388号",
    "house_no":"203",
    "commment":"",
    "remark":"",
    "sub_order_list":[{
        "sub_order_no":"SBOC12CEF63480CE180640009",
        "device_mode":"NPG01"}
        ],
    "pictures":["http://sunmi.cdn.com/1234.jpg"],
    "reference_company":"商米",
    "reference_name":"张三",
    "reference_phone":"17239123321",
    "contact_name":"李四",
    "contact_tel":"241244124",
    "router_cnt":1,
    "router_model":""
}

返回值：

{"code":1,"msg":"success"}
code说明
1成功
-1其他错误
5000数据库错误
5020无效参数
5021无效路径
5023参数缺失
5026验签失败
5047无效订单

员工对齐

1 概要

1.1 简介

商米数字店铺（SUNMI Store）中的合法用户可以拥有有指定组织下的员工身份。

2 接口规范

2.1 协议说明

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

注：消息体大小不得超过1M，超过1M的请求，直接拒绝！

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考2.2 签名规则

2.2 签名规则

参考《鉴权认证》文档。

2.3 公共参数

参数名必填类型说明示例
app_id是string唯一标识接入身份，联系商米数字店铺提供 LMWWQVTW4QGCC
random是string随机字符串，由数字和字母组成，长度范围为6-10位 5dsf6698
timestamp是int当前的unix timestamp，精度到秒级，10位数字 1581333970
sign是string签名信息，详见2.2 2E7CED3164B6BBDB81145F3CBE204597

3 开放API接口

3.1 用户注册

接口描述：通过本接口调用，实现商米数字平台用户注册。

请求链接：/employee/create

接口版本：v1.0.0

接口参数：

参数名称 是否必须 类型 说明 示例
user_id是stringuser_id
sunmi_company_no是string商户编号
name是int名称1
number是string员工工号
username是string员工账号(手机号/邮箱)
gender否string性别(男/女)
sso_username否string员工用户名(手机号)
mapping_list否string员工能管理的店铺列表

返回值： 

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

错误码：

错误码说明
204手机号码已经存在

巡店

1 背景介绍

商米巡店功能开放，支持H5实现的SDK调用

2 接口规范

2.1 协议说明

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

注：消息体大小不得超过1M，超过1M的请求，直接拒绝！

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
授权方式Auth2.0
授权规则参考商米OAuth2.0授权http://docs.test.sunmi.com/htmls/商米oauth2-0/

2.2 请求头设置

略，要带token

3 巡店业务接口

3.1 获取门店列表

接口描述：通过本接口调用，用户可以获取可查看的所有门店

请求链接：/patrol/org/getList

接口版本：v2.0

参数：

参数名称是否必须类型说明示例
sunmi_company_no是string商户编号
inspection_user_id否string巡检人id
plan_start_time否integer巡店计划开始时间
plan_end_time否integer巡店计划结束时间

请求示例：

略

返回值：

{
	"code": 0,
	"msg": "",
	"data": {
		"org_list": [{
			"org_pid": 2945,
			"org_tag": 442,
			"level": 2,
			"org_id":3812,
			"org_name": "Lorem occaecat",
			"sunmi_shop_no": "298374832745742387",
			"org_status": 1,
			"business_status": 1,
			"type_one": 1,
			"type_two": 1,
			"type_name": "1",
			"province": 1,
			"city": 1,
			"area": 1,
			"lat": "38",
			"lng": "98",
			"address": "铁岭",
			"business_area": 40854915,
			"region": "aliqua",
			"business_hours": "nulla",
			"contact_person": "anim exercitation",
			"contact_tel": "irure ut",
			"contact_email": "mollit exerc",
			"created_time": -98259710,
			"modified_time": 15094789,
			"patrol_service_status": -36606166,
			"patrol_plan_status": 82471639,
			"inspection_user_auth": 22425348,
			"patrol_service_active_duration": -57840792,
			"patrol_service_active_status": 2411480,
			"children": [{
				"org_pid": 86480169,
				"org_tag": -62506489,
				"level": 86737874,
				"org_id": 99824037,
				"org_status": -13855870,
				"org_name": "do qui aute non",
				"sunmi_shop_no": "occaecat id",
				"business_status": -32078036,
				"type_one": 98245914,
				"type_two": 5120503,
				"type_name": "et cillum ",
				"province": 86019116,
				"city": -26065136,
				"area": "consequat in dolore",
				"lat": "officia labore",
				"lng": "eiusmod occaecat consequat et",
				"address": "dolore officia cupidatat eiusmod et",
				"business_area": 44639054,
				"region": "Ut tempor ex ea laboris",
				"business_hours": "sed mollit in",
				"contact_person": "sint Lorem",
				"contact_tel": "reprehenderit",
				"created_time": 9669190,
				"modified_time": 28811257,
				"patrol_service_status": 67245690,
				"patrol_plan_status": 46486322,
				"inspection_user_auth": "consectetur",
				"patrol_service_active_status": "id est non",
				"patrol_service_active_duration": "consequat magna dolor ad"
			}]
		}]
	}
}

商米OAuth2.0授权

1 背景介绍

商米支持 OAuth2.0 协议认证和授权，支持通用的 OAuth2.0 方案，例如 Web 服务应用，客户端应用等

2 接口规范

2.1 协议说明

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

注：消息体大小不得超过1M，超过1M的请求，直接拒绝！

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考2.2 签名规则


2.2 签名规则

参考《鉴权认证》文档

2.3 公共参数

参数名必填类型说明示例
app_id是string唯一标识接入身份，联系商米数字店铺提供 LMWWQVTW4QGCC
random是string随机字符串，由数字和字母组成，长度范围为6-10位 5dsf6698
timestamp是int当前的unix timestamp，精度到秒级，10位数字 1581333970
sign是string签名信息，详见3.2.2 2E7CED3164B6BBDB81145F3CBE204597

3 授权接口

3.1 获取Authorization Code

略

3.2 获取Access Token

接口描述：通过本接口调用，用户可以获取相关门店下所有设备列表。

请求链接：/oauth/getToken

口版本：v2.0

备注：此接口可不使用公共参数

参数：

参数名称是否必须类型说明示例
code是string一次性code，使用后立即失效
user_id是string用户id
app_id是string唯一标识接入身份

请求示例：

略

返回值：

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

密码保护：友盟广告投放接口

这是一篇受密码保护的文章，您需要提供访问密码：

会员库接口

1 背景介绍

商米数字店铺（SUNMI Store）是商米提供的围绕商户店铺中物联网设备基础上的店铺管理系统。

商米数字店铺作为一个开放平台，支持与第三方SaaS厂商进行各种数据的对接，包括商品信息对接，交易信息对接，会员体系对接等。

2 接口规范

2.1 协议说明

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

注：消息体大小不得超过1M，超过1M的请求，直接拒绝！

Content-Type application/x-www-form-urlencoded
数据格式 返回为JSON格式
字符编码 UTF-8字符编码
签名算法 MD5
签名规则 参考2.2 签名规则

2.2 签名规则

参考《鉴权认证》文档。

2.3 公共参数

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

3 开放API接口

3.1 会员库对接 v1.0

3.1.1 会员字段属性

以下属性均为会员基础属性。

商米数字平台会员参数 类型 说明 是否必须 参数说明
member_id string 会员编号 是
name string 会员姓名
address string 地址
phone string 联系电话
ali_id string 会员阿里ID
wechat_id string 会员微信ID
gender int 性别 1-男， 2-女
age int 年龄
total_purchase_amount double(精确到小数点后四位） 总计消费金额
member_points double 会员积分
pic file 会员照片
attributes list[{‘attribute_key’: ‘attribute_value’}] 自定义会员属性，最大可支持5个自定义属性。
可以指定 attribute_key 和 attribet_value的key-value组添加属性，类型皆为string
group_id string 如果需要将会员直接录入指定人脸分组，则需要设定group_id，pic参数需要同时生效，以确保会员人脸被识别和录入

以下属性均为会员消费记录属性：

商米数字平台会员消费记录参数 类型 说明 是否必须 参数说明
member_id string 会员编号 是
shop_id string 会员消费门店编号 是
shop_name string 会员消费门店名称
order_id string 订单编号 是
order_time int 订单时间
coupon_id string 卡券编号
order_amount double(精确到小数点后四位） 订单消费金额
total_purchase_amount double(精确到小数点后四位） 总计消费金额
valid_member_points double 有效会员积分

3.2 接口列表

接口名称 接口描述
/member/create 添加会员
/member/assign 将会员与指定门店的IPC设备关联

3.3 接口详情

3.3.1 添加会员

接口描述：通过本接口调用，用户可以添加会员。

请求链接：/member/create

接口参数：

参数名称 是否必须 类型 说明
sunmi_company_no 是 string 商米数字店铺平台商户唯一编号
member_list 是 array 新建会员对象列表

total_purchase_amount 否 double(精确到小数点后四位） 会员总消费金额
member_points 否 double 会员积分
ali_id 否 string 会员阿里ID
wechat_id 否 string 会员微信ID


pic 否 file 会员照片
attributes 否 list[{‘attribute_key’: ‘attribute_value’}] 自定义会员属性，最大可支持5个自定义属性。
可以指定 attribute_key 和 attribet_value的key-value组添加属性，类型皆为string

返回值： 

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

错误码：

错误码 说明
5000 数据库错误
5006 文件存储错误
5520 已经达到最大人脸分组数量或已经达到最大人脸容量

3.3.2 将会员与指定门店的IPC设备关联

接口描述：通过本接口调用，将会员与指定门店的IPC设备关联，IPC会根据member的录入照片生成的FaceID同步到店内所有IPC上。

请求链接：/member/assign

接口参数：

参数名称 是否必须 类型 说明
sunmi_company_no 是 string 商米数字店铺平台商户唯一编号
sunmi_shop_no 是 string 商米数字店铺平台店铺唯一编号
group_id 是 string 会员分组编号
member_id_list 是 list[string] 会员编号列表

返回值： 

 {
    "code": 0, /* 其他错误参考错误列表 */
    "msg": "succeed",
    "data": {       
        "success_list": [
              {
                  "member_id": "263",
                  "msg": "",
                   "errcode": 0
              }
          ],
          "failed_list": [
              {
                  "member_id": "262",
                  "msg": "member info has no faceId",
                  "errcode": 5700
              }
          ]
    }               
}

错误码：

错误码 说明
5000 数据库错误
5520 已经达到最大人脸分组数量或已经达到最大人脸容量
5521 人脸信息不存在
5522 人脸库不存在
5528 会员人脸关联失败
5032 非法店铺
5700 无人脸信息的会员