商米开发者文档

1 基本描述

商米数字店铺开放平台与SaaS合作方的数据交互可以是双向实时。一方面SaaS合作方可以将数据通过openAPI传入数字店铺，也可以对商米的IoT设备进行远程控制。

除此之外，商米数字店铺开放平台也可以通过消息推送中心，将系统中的消息实时反馈给SaaS合作方。根据合作平台需求订阅实时消息推送，商米数字店铺开放平台会将消息和事件推送给SaaS合作方。

2 接口规范

2.1 协议说明

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

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 店铺设计规范

参考《商户店铺》文档。

4 SaaS合作方提供HTTP回调地址

SaaS合作方添加监听事件时，需要提供相应的HTTP回调地址，并提供需要监听的设备以及事件。当商米数字开放平台收到该设备的该事件时，会调用该HTTP接口。

4.1 回调HTTP鉴权方式

对于该回调HTTP回调的鉴权方式，遵照商米数字店铺开放平台的鉴权方式。 请参考《鉴权认证》文档。

4.2 回调HTTP接口参数

回调HTTP需要带以下接口参数：

参数名称	是否必须	类型	说明
sunmi_shop_no	是	string	商米数字店铺平台门店唯一编号
shop_id	是	string	店铺在SaaS软件体系下的唯一标识
event	是	int	触发消息的类型
payload	是	string	消息的具体格式（根据消息不同会有不同的json）

消息的具体格式请参考相关业务的《事件及消息示例》文档。

4.3 消息重传

如果回调消息发送失败，会触发重传机制。一共会触发4次重传，时间间隔分别为15秒, 30 秒, 1分钟和2分钟。

5 消息监听接口

5.1 接口描述

消息监听接口用来管理需要监听的事件和相应的回调HTTP地址。

5.2 接口列表

接口名称	接口描述
/hook/add	增加消息监听的HTTP回调地址
/hook/delete	取消消息监听的HTTP回调地址

5.3 接口详情

5.3.1 增加消息监听

接口描述：通过本接口调用，用户可以增加消息监听的HTTP回调地址。

请求链接：/hook/add

接口版本： v2.0

接口参数：

参数名称	是否必须	类型	说明
sunmi_shop_no	否	string	商米数字店铺平台门店唯一编号（v2.0之后为必填项）
shop_id	否	string	店铺在SaaS软件体系下的唯一标识（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
http_callback	是	string	HTTPS回调地址链接
event_list	是	array[int]	需要监听的事件的列表

返回值： 

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

5.3.2 取消消息监听

接口描述：通过本接口调用，用户可以取消消息监听的HTTP回调地址。

请求链接：/hook/delete

接口版本： v2.0

接口参数：

参数名称	是否必须	类型	说明
sunmi_shop_no	否	string	商米数字店铺平台门店唯一编号（v2.0之后为必填项）
shop_id	否	string	店铺在SaaS软件体系下的唯一标识（此参数为后向兼容v2.0之前版本的字段，在v2.0及以后版本使用sunmi_shop_no替代，作为门店唯一标识即可）
event_list	是	array[int]	需要取消监听的事件的列表

返回值： 

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