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 | 第三方对接软件中门店的标识 |
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 | 商米数字店铺平台的门店组织编号 |
shop_id | 否 | string | 第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与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 | 商米数字店铺平台的门店组织编号 |
shop_id | 否 | string | 第三方对接软件中门店的标识,对接的软件提供 (作为门店唯一标识即可,shop_id与sunmi_shop_no可互为替代,使用时传输任意一个即可) |
event_list | 是 | array[int] | 需要取消监听的事件的列表 |
返回值:
{
"code": 0, /* 其他错误参考错误列表 */
"msg": "succeed",
"data": {}
}