消息中心

1 基本描述

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

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

2 接口规范

2.1 协议说明

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

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

2.2 签名规则

参考《鉴权认证》文档。

2.3 公共参数

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

3 店铺设计规范

参考《商户店铺》文档。

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

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

4.1 回调HTTP鉴权方式

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

4.2 回调HTTP接口参数

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

参数名称是否必须类型说明
sunmi_shop_nostring 商米数字店铺平台门店唯一编号
shop_idstring 店铺在SaaS软件体系下的唯一标识
eventint触发消息的类型
payloadstring消息的具体格式(根据消息不同会有不同的json)

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

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_idstring店铺在SaaS软件体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
http_callbackstringHTTPS回调地址链接
event_listarray[int]需要监听的事件的列表

返回值: 

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

5.3.2 取消消息监听

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

请求链接:/hook/delete

接口版本: v2.0

接口参数

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

返回值: 

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