本文档主要是详细介绍消息订阅模块功能使用与接口规范
平台消息订阅功能，支持自定义订阅客控、客需、房态等消息，在订阅的消息类型更新时，将消息主动推送至您配置的接收URL地址。
消息订阅配置
-
点击【设置】—【消息订阅】进入消息订阅模块。
-
点击新增消息订阅，填写接收的URL，异常联系人信息及消息接收类型，以下是相关字段的定义与填写规范：
|
字段 |
定义与填写规范 |
|
接收URL |
订阅消息将推送至您填写的URL服务地址，http服务存在数据泄露风险，建议使用https服务。 |
|
异常联系人与邮箱 |
当消息推送异常时（如接收方服务不稳定），系统将自动发送消息推送失败告警邮件至异常联系人邮箱，包含此次推送失败的具体信息，包括日志信息和错误代码。 |
|
消息接收配置 |
勾选您需要推送的消息类型：
|
-
启用：新增消息订阅后，默认为禁用状态，请在完成接口对接后手动启用，启用后系统将开启消息推送。
-
健康状态：当您填写的接收服务地址持续推送失败时，系统将自动禁用该地址的消息推送服务，并将订阅的健康状态标为异常，同时会发送一条服务异常自动禁用的邮件到您的异常联系人邮箱。为防止影响相关业务的正常运行，请及时协调相关团队进行处理。请注意，问题修复后，需要您再次手动启用该订阅，系统才会再次开启消息推送。
相关接口技术对接
消息体定义
必带信息 baseInfo
|
名称 |
类型 |
示例值 |
描述 |
|
hotelId |
String |
5ed5c0****65b9c92d7 |
酒店id |
|
roomNo |
String |
101 |
房间号 |
|
roomName |
String |
101 |
房间名 |
|
requstTime |
Long |
1506588294932 |
请求时间 |
|
requestId |
String |
bd5d003****22820 |
请求Id |
|
topic |
String |
deviceStatus |
客控消息 |
注意：可达请求结构
topic:connect
解释：平台侧开启消息订阅时，会发送以下内容至配置的url地址，只有请求可达，才可以开启。
示例JSON
{
"baseInfo": {
"hotelId": "ed***3356",
"requestId": "9cc***bb",
"requestTime": 1748231566531,
"topic": "connect"
}
}指令内容 command
客控结构
topic:deviceStatus
|
名称 |
类型 |
示例值 |
描述 |
|
deviceId |
String |
a80171****6404833b |
设备id |
|
pk |
String |
21929772 |
设备pk |
|
dn |
String |
f4d****56b |
设备dn |
|
deviceName |
String |
开关面板 |
设备名称 |
|
changeStatus |
Map |
{ “onlinestate”: { “preValue”: “offline”, “time”: 1748311258090, “value”: “online” } } |
变更属性内容 注：preValue为触发前状态 value为变更状态 time为触发时间
若值为0则表示关闭 若值为1则表示开启 |
示例JSON
{
"baseInfo": {
"hotelId": "ed***3356",
"requestId": "7f***f4ae",
"requestTime": 1748311258581,
"roomNo": "409",
"topic": "deviceStatus"
},
"command": {
"changedStatus": {
"onlinestate": {
"preValue": "offline",
"time": 1748311258090,
"value": "online"
}
},
"connectType": "MESH",
"deviceId": "a80171ea844401f1ea3da7d0f404833b",
"deviceName": "空调",
"dn": "f4d0a73deaf1",
"pk": "21267690"
}
}房态结构
topic:roomStatus
|
名称 |
类型 |
示例值 |
描述 |
|
changeStatus |
Map |
{ “SOS”: { “preValue”: “0”, //触发前状态 “time”: 1747882683437,//触发时间 “value”: “1”//当前状态 } } |
变更属性内容 注： 状态值0为关闭 1为打开 |
示例JSON
{
"baseInfo": {
"hotelId": "ed***356",
"requestId": "ff***851",
"requestTime": 1747882684136,
"roomName": "409",
"roomNo": "409",
"topic": "roomStatus"
},
"command": {
"changedStatus": {
"SOS": {
"preValue": "0",
"time": 1747882683437,
"value": "1"
}
}
}
}客需结构
topic:customer
|
名称 |
类型 |
示例值 |
描述 |
|
type |
String |
GOODS |
客需类型 |
|
orderNo |
String |
202504****1783 |
订单号 |
|
name |
String |
拖鞋 |
物品名称 |
|
quantity |
Long |
2 |
数量 |
|
applyAmt |
Long |
1000 |
金额（单位分） |
|
paymentMethod |
String |
room |
结算方式:room 房费结算 robot 机器人结算 |
|
deliveryMethod |
String |
waiter |
物品配送方式:waiter 服务员 robot 机器人 |
|
operationType |
String |
addOrder |
操作类型 新增工单:addOrder 工单状态变更（完成、撤销): orderStatus 工单变更:updateOrder |
示例JSON
{
"baseInfo": {
"hotelId": "ed***f3356",
"requestId": "37***074e2",
"requestTime": 1747878272254,
"roomName": "409",
"roomNo": "409",
"topic": "customer"
},
"command": {
"customerMessages": [{
"applyAmt": 0,
"deliveryMethod": "waiter",
"name": "棉签",
"orderNo": "20***1325",
"paymentMethod": "room",
"quantity": 1,
"type": "GOODS"
}],
"operationType": "addOrder"
}
}物品类型对应值
"客房服务": "RS";
"餐饮服务": "FOOD";
"宴会服务": "BS");
"游泳健身服务": "SF";
"休闲娱乐活动": "LEA";
"SPA与理疗服务": "SWS";
"商务与会议服务": "BCS";
"交通接驳服务": "TSS";
"洗衣服务": "LS";
"个性化服务": "PS";
"酒店同款": "IHB";
"办公用品": "OS";
"日用品": "DN";
"基础药品": "BM";
"美妆护肤用品": "BSP";
"零食饮料": "S&B";
"礼品与纪念品": "G&S";
"计生用品": "Contraceptives";
"情趣用品": "AP";
"亲子活动": "PCA";
"家庭出游": "FO";
"周边景点门票": "NAT";
"周边娱乐": "NE";
"周边餐饮": "ND";
"物品": "GOODS";
"服务": "SERVICE";
"维修": "REPAIR";
"打车": "CAR_SERVICE";
客户返回结构
|
名称 |
类型 |
示例值 |
描述 |
|
success |
Boolean |
true |
表示请求成功 |
|
message |
String |
success |
请求返回的消息，成功为success， 失败将对应失败原因返回 |
|
requestId |
String |
bd5d003****22820 |
请求ID，同猫精请求requestId |
|
responseTime |
Long |
1506588295432 |
响应时间 |
|
statusCode |
Long |
200 |
响应码 |
|
result |
Object |
|
返回内容 |
示例JSON
{
"result": null,
"success": true,
"message": "success",
"statusCode": 200,
"requestId":"bd5d003****22820",
"responseTime":1506588295432
}
