1、云云对接原理图
对接前建议先查看理解云云对接原理图,可以大幅提高对接效率哦。
2、申请创建酒店项目
参考此文档完成酒店项目创建:酒店项目创建
3、酒店平台房型&房间配置
参考此文档完成酒店平台相关配置:酒店项目之客控配置(云云对接)
4、酒店版音箱配网
参考此文档完成酒店版音箱配网:酒店音箱配网激活
5、客控配置对接
5.1 酒店控制协议文档(version:0.8)
5.1.1 基本说明
请求协议:HTTP/HTTPS 请求方式:POST 请求头 application/json 请求参数格式:json
5.1.2 协议格式
以测试酒店举例:
测试 appName: 测试酒店
测试 appKey: 12ff7d64401340b9a7e7486fcfe68607
控制请求样例:
{
"baseInfo": {
"appName": "测试酒店",// 申请的 APP 名
"authType": "MD5",// 校验方式
"hotelId": "30001",// 酒店 ID
"requestId": "304a1c510f9e4683a43be5f2a7cfeb52",//请求 ID
"requestTime": 1509504894401,// 请求时间,毫秒
"roomNo": "1001",// 房号
"token": "d9e78bc412f0415728ae2cd891f3c764"
// 将 appName,hotelId, requestId, requestTime, roomNo 用竖线拼接完以后附加 appKey 进行 MD5 的结果。
},
"command": {
"commandType": "CONTROL",
"devices": [
{
"name": "Light",
"number": "1",
"switch": 1,
"customContent": "测试" //自定义描述消息(支持在发现设备接口中返回)
}
]
}
}
控制请求返回样例:
{
"success": true,
"message": "success",
"requestId": "304a1c510f9e4683a43be5f2a7cfeb52",
"responseTime": 1506588295432,
"result": {
"status": [
{
"name": "Light",//设备类别
"number": "1", //设备编号
"switch": 1, //指令
"customContent": "测试" //自定义描述消息
}
]
},
"statusCode": 200
}
查询请求样例:
{
"baseInfo": {
"appName": "测试酒店",
"authType": "MD5",
"hotelId": "30001",
"requestId": "a72dca7f80084ba1be282550d92bf08b",
"requestTime": 1506588294932,
"roomNo": "1001",
"token": "bebc35b698bba9f2d6ef002d624def55"
},
"command": {
"commandType": "QUERY",
"devices": [
{
"name": "Aircondition",
"number": "1"
}
]
}
}
查询请求返回样例:
{
"success": true,
"message": "success",
"requestId": " a72dca7f80084ba1be282550d92bf08b",
"responseTime": 1506588295432,
"result": {
"status": [
{
"fanSpeed": 3,
"mode": 1,
"name": "Aircondition",
"number": "1",
"roomTemperature": 32,
"temperature": 23
}
]
},
"statusCode": 200
}
5.1.3 协议说明
5.1.3.1 基本信息 baseInfo
名称 |
类型 |
是否 必须 |
示例值 |
描述 |
appName |
String |
必须 |
测试酒店 |
申请的APP 名称 |
authType |
String |
必须 |
MD5 |
鉴权方式 |
hotelId |
String |
必须 |
30001 |
注册的酒店ID |
requestId |
String |
必须 |
31e38ad651d94e9fb09546acabf55216 |
请求ID,32 位 |
requstTime |
Long |
必须 |
1506588294932 |
请求时间,毫秒 |
roomNo |
String |
必须 |
1001 |
房号 |
token |
String |
必须 |
ed58788c50f61ac4a1122e35d2a0fa4e |
鉴权信息(使用竖线分隔符 “|”连接 appName, hotelId, requestId, requestTime, roomNo)后附 加appKey 进行MD5 的结 果,例如本token 即根据” 测试酒店 |30001|31e38ad651d94e9f b09546acabf55216|150658 8294932|100112ff7d64401 340b9a7e7486fcfe68607″进 行MD5 得到。 |
5.1.3.2 指令体 command
名称 |
类型 |
是否必须 |
示例值 |
描述 |
commandType |
String |
必须 |
CONTROL |
指令类型, CONTROL为控制指令, QUERY为查询指令, QUERYALL为发现设备指令, LOG为工单指令 |
devices |
List |
必须 |
[ { “name”: “DimmingLight”, “number”: “1”, “value”: 32, “customContent”: “测试” }] |
设备属性列表 |
5.1.3.3 返回说明
一:success, message, statusCode
success 为true 代表控制/查询成功,false 代表控制/查询失败;当success 为false 的时候,天猫精灵会根据statusCode 做不同的状态/回复处理;message 为对应状态码的详细信息;
二:requestId为天猫精灵请求中的requestId复制而来,responseTime 为响应生成时间戳,单位毫秒;
三:result 为响应的实体,目前仅包含设备状态列表:
对于控制指令,返回被控制设备的最新状态;
对于查询指令,返回被查询设备的最新状态。
四: 状态码列表:
statusCode |
含义 |
备注 |
200 |
正常 |
执行成功则为200, 与success=true 语义一致 |
500 |
控制系统内部错误 |
RCU 控制出现未知异常,统一返回该代码 |
501 |
不支持的操作 |
例如空调不支持调模式,电视不支持调音量 等情况,则需返回501 |
404 |
不支持的设备 |
没有该设备或者设备被移除则返回本错误码 |
5.1.3.4 指令体 devices
一.开关型灯光设备
设备类别: Light
设备属性:
设备属性名 |
设备属性值 |
说明 |
switch |
数值0/1 |
0 代表关,1 代表开 |
|
|
|
二.调光型灯光设备
设备类别: DimmingLight
设备属性:
设备属性名 |
设备属性值 |
说明 |
value |
数值0~100 |
亮度百分比,0 代表亮度 最小(关),100 代表亮度 最大。值越大越亮 |
value_up |
数值x |
value 调高x |
value_down |
数值x |
value 调低x |
注意:
1.调光型设备,value:0表示关灯,value:100表示开灯
{
"commandType": "CONTROL",
"devices": [
{
"name": "DimmingLight",
"number": "1234",
"value": 100 #value:0表示关灯,value:100表示开灯
}
]
}
2.支持亮度调节
{
"commandType": "CONTROL",
"devices": [
{
"name": "DimmingLight",
"number": "1234",
"value_up": 10 #value_up表示调高,value_down表示调低
}
]
}
3.支持色温调节,action:colorTemperature
{
"commandType": "CONTROL",
"devices": [
{
"action": "colorTemperature", #色温
"name": "DimmingLight",
"number": "1234",
"value_up": 10 #value_up表示调高,value_down表示调低
}
]
}
三.空调设备
设备类别: Aircondition
设备属性:
设备属性名 |
设备属性值 |
说明 |
switch |
数值x |
1:打开 0:关闭 |
mode |
字符auto/cold/heat/dry/fan |
模式,auto 为自动,cold 为制冷,heat 为制热,dry 为除湿,fan 为通风 |
fanSpeed |
数值x |
风速调到x 档,风速自动(255) |
temperature |
数值x |
温度调到x 度 |
roomTemperature |
数值x |
室温,仅返回状态使用, 无法调节 |
fanSpeed_up |
数值x |
风速调高x 档 |
fanSpeed_down |
数值x |
风速调低x 档 |
temperature_up |
数值x |
温度调高x 度 |
temperature_down |
数值x |
温度调低x 度 |
注意:
1.空调打开时会发送switch=1和fanSpeed=3指令,若需要打开时使用前一次风量设置,可以忽略fanSpeed参数;
2.空调关闭时会发送switch=0和fanSpeed=0指令;
3.空调调整风速时会发送fanSpeed=0/1/2/3/255…指令,风速自动的属性值为255;
4.空调风速调到最大/最小时会发送fanSpeed=3/fanSpeed=1指令;
5.风速调节到xx挡 暂不支持。
四.窗帘设备
设备类别:Curtain
设备属性:
设备属性名 |
设备属性值 |
说明 |
switch |
数值0/1 |
0 代表关,1 代表开 |
value |
数值0~100 |
开关百分比,0 代表最小 (关),100 代表打开到最 大。 |
value_up |
数值x |
value 调高x,即拉开窗帘 |
value_down |
数值x |
value 调低x,即关小窗帘 |
action |
字符pause/continue |
pause:暂停 continue:继续 |
五.纱帘设备
设备类别:LaceCurtain
设备属性:
设备属性名 |
设备属性值 |
说明 |
switch |
数值0/1 |
0 代表关,1 代表开 |
value |
数值0~100 |
开关百分比,0 代表最小 (关),100 代表打开到最 大。 |
value_up |
数值x |
value 调高x,即拉开窗帘 |
value_down |
数值x |
value 调低x,即关小窗帘 |
action |
字符pause/continue |
pause:暂停 continue:继续 |
六.电视设备
设备类别:TV
设备属性
设备属性名 |
设备属性值 |
说明 |
switch |
数值0/1 |
0 代表关,1 代表开 |
channelName |
字符 |
频道名称,如中央一套。 |
channelNumber |
数值 |
切换到第几台 |
channelNumber_up |
数值1 |
增加台 |
channelNumber_down |
数值1 |
减少台 |
volume |
数值0~100 |
音量 |
volume_up |
数值0~100 |
电视音量增加(步长为5) |
volume_down |
数值0~100 |
电视音量减少(步长为5) |
mute |
数值0/1 |
电视静音:mute = 1 电视取消静音: mute = 0 |
注:电视音量调节到具体值(目前不支持)
七.门设备
设备类别:Door
设备属性
设备属性名 |
设备属性值 |
说明 |
switch |
数值0/1 |
0 代表关,1 代表开 |
|
|
|
八.排气扇设备
设备类别:ExhaustFan
设备属性
注*:此设备需要在酒店管理后台-客控中配置之后才能生效。
设备属性名 |
设备属性值 |
说明 |
switch |
数值0/1 |
0 代表关,1 代表开 |
|
|
|
5.1.3.5 客需服务工单
参考此文档完成酒店平台客需配置:酒店客需配置
注:消息会主动往rcu服务器推送
一.服务工单请求
服务工单实例
{
"baseInfo": {
"appName": "test-xt",
"authType": "MD5",
"hotelId": "7b15bad09e6b4aa6aa59f10b89125dc9",
"requestId": "103ac492c60a4b87a13fcb6bad6c48f7",
"requestTime": 1714465115108,
"roomNo": "777",
"token": "84386c8d242597dcc06ffca22853e086"
},
"command": {
"commandType": "LOG",
"devices": [
{
"dialog": {
"answer": "好的,您的需求收到,服务员将会尽快和你联系。",
"groupKey": "29140336-dfab-4e13-83af-d680893f17ac29052242",
"item": "洗衣",
"logTime": "2024-04-30 16:18:35",
"question": "我要洗衣",
"serviceCategory": "洗衣类",
"serviceConfirm": true,
"serviceType": "SERVICE"
},
"name": "Service"
}
]
}
}
设备类别:SERVICE
设备属性:
设备属性名 |
设备属性值 |
说明 |
dialog |
Json |
对话体 |
dialog.logTime |
字符 |
对话时间,如2019-09-26 22:25:19 |
dialog.question |
字符 |
用户提问 |
dialog.answer |
字符 |
音箱回答内容 |
dialog.item |
字符 |
用户需要的物品名称 如 用户说:我要可乐,会抽取出 “可乐” |
dialog.groupKey |
字符 |
区分是否是同一轮对话流。 如我要可乐。 天猫追问:可乐3元,是否需要送来。 用户回答:需要。 两个对话的groupKey是相同的 |
dialog.quantity |
数字 Long |
数量 |
dialog.serviceConfirm |
判断 Boolean |
服务确认 true or false |
dialog.serviceType |
字符 |
服务类型,如: GOODS 客用品类 GOODS 餐具类 GOODS 药用类 GOODS 生活用品类 GOODS 收拾类 GOODS 充电类 GOODS 婴童类 GOODS 计生用品类 GOODS 食品类 GOODS 寝具类 GOODS 洗浴用品类 SERVICE 洗衣类 SERVICE 房间类 REPAIR 电器类 REPAIR 家具类 REPAIR 卫生间类 |
dialog.serviceCategory |
字符 |
分类,如: 客用品类 餐具类 药用类 生活用品类 收拾类 充电类 婴童类 计生用品类 食品类 寝具类 洗浴用品类 洗衣类 房间类 电器类 家具类 卫生间类 |
二.维修工单请求
维修工单实例
{
"baseInfo": {
"appName": "test-xt",
"authType": "MD5",
"hotelId": "7b15bad09e6b4aa6aa59f10b89125dc9",
"requestId": "fa7e7da5322e4b3c808daeef9ed1f2b5",
"requestTime": 1714465123912,
"roomNo": "777",
"token": "6d23e34f9344489d9926d77e07e79b29"
},
"command": {
"commandType": "LOG",
"devices": [
{
"dialog": {
"answer": "您的报修工单已经收到,服务员将会尽快来维修。",
"groupKey": "29140336-dfab-4e13-83af-d680893f17ac29053673",
"item": "电视",
"logTime": "2024-04-30 16:18:43",
"question": "我要修电视",
"serviceCategory": "电器类",
"serviceType": "REPAIR"
},
"name": "Repair"
}
]
}
}
设备类别:REPAIR
设备属性: 同服务请求
三.物品工单请求
物品工单实例
{
"baseInfo": {
"appName": "test-xt",
"authType": "MD5",
"hotelId": "7b15bad09e6b4aa6aa59f10b89125dc9",
"requestId": "28d24a34e8504f918f94d9fde8d26147",
"requestTime": 1714465153902,
"roomNo": "777",
"token": "ae9527244b4e76edb9d74ca5f82f60e0"
},
"command": {
"commandType": "LOG",
"devices": [
{
"dialog": {
"answer": "好的,服务员会尽快送来。",
"groupKey": "29140336-dfab-4e13-83af-d680893f17ac29052960",
"item": "矿泉水",
"logTime": "2024-04-30 16:19:13",
"quantity": 1,
"question": "我要一瓶水",
"serviceCategory": "客用品类",
"serviceConfirm": true,
"serviceType": "GOODS"
},
"name": "Service"
}
]
}
}
设备类别:GOODS
设备属性: 同服务请求
5.1.3.6 模式和场景类
5.1.3.6.1 自定义场景
支持通过发现设备接口导入自定义场景信息,详见:附录二:查询房间所有设备
6、联调
开发完成以后,即可进行联调,如有技术疑问,请在对接群里艾特“酒店版天猫精灵机器人”或者联系技术支持答疑。
附录一:设备状态查询
用于同步带屏音箱中设备控制状态
请求参数
{
"baseInfo": {
"appName": "xxxx酒店",
"authType": "MD5",
"hotelId": "af729****42d536",
"requestId": "b46b64fea3****be4b4eb6fa",
"requestTime": 1668500359625,
"roomNo": "2511",
"token": "1a12c43d4dd****4938149ab"
},
"command": {
"commandType": "QUERY",
"devices": [{
"name": "aircondition", // 设备名称
"number": "air_condition" // 设备编号
}, {
"name": "laceCurtain",
"number": "window_screening"
}, {
"name": "curtain",
"number": "window_curtains"
}, {
"name": "tv",
"number": "ali_tv"
}, {
"name": "light",
"number": "light_belt"
}, {
"name": "light",
"number": "night_light"
}, {
"name": "light",
"number": "reading_lamp"
}, {
"name": "light",
"number": "downlight"
}, {
"name": "light",
"number": "corridor_light"
}]
}
}
响应
{
"result": [{
"categoryCnName": "空调",
"deviceName": "房间空调",
"fanSpeed": 3,
"location": "room",
"locationCnName": "房间",
"locationEnName": "room",
"mode": "auto",
"name": "aircondition",
"number": "air_condition",
"switch": 1,
"temperature": 26
}, {
"categoryCnName": "纱帘",
"deviceName": "窗纱",
"location": "room",
"locationCnName": "房间",
"locationEnName": "room",
"name": "laceCurtain",
"number": "window_screening",
"switch": 0
}, {
"categoryCnName": "窗帘",
"deviceName": "窗帘",
"location": "room",
"locationCnName": "房间",
"locationEnName": "room",
"name": "curtain",
"number": "window_curtains",
"switch": 0
}, {
"categoryCnName": "电视",
"deviceName": "房间电视",
"location": "room",
"locationCnName": "房间",
"locationEnName": "room",
"name": "tv",
"number": "ali_tv",
"switch": 0
}, {
"categoryCnName": "灯",
"deviceName": "夜灯",
"location": "room",
"locationCnName": "房间",
"locationEnName": "room",
"name": "light",
"number": "night_light",
"switch": 1
}, {
"categoryCnName": "灯",
"deviceName": "阅读灯",
"location": "room",
"locationCnName": "房间",
"locationEnName": "room",
"name": "light",
"number": "reading_lamp",
"switch": 1
}, {
"categoryCnName": "灯",
"deviceName": "卫浴灯",
"location": "washroom",
"locationCnName": "洗手间",
"locationEnName": "washroom",
"name": "light",
"number": "bathroom_lamp",
"switch": 1
}, {
"categoryCnName": "灯",
"deviceName": "镜前灯",
"location": "washroom",
"locationCnName": "洗手间",
"locationEnName": "washroom",
"name": "light",
"number": "mirror_front_lamp",
"switch": 1
}],
"statusCode": 200,
"success": true
}
附录二:查询房间所有设备
用于语音发现设备技能。
酒店支持的位置:
room 房间
livingroom 客厅
washroom 洗手间
balcony 阳台
passage 走廊
cloakroom 衣帽间
bathroom 淋浴间
tearoom 茶室
bedroom 卧室
masterbedroom 主卧
secondbedroom 次卧
diningroom 餐厅
酒店支持的设备品类:
aircondition 空调
laceCurtain 纱帘
curtain 窗帘
tv 电视
light 灯
exhaustFan 排气扇
dimminglight 调光灯
door 门
fan 风扇
tvbox 电视盒子
projector 投影仪
settopbox 机顶盒
switch 开关
KeyCardSwitch 插卡取电
thermostat 温控器
rollingShutter 卷帘
skyCurtain 天幕
telecontroller 万能遥控器
IR_sensor 人体传感器
door_sensor 门磁传感器
sensirion 温湿度传感器
outlet 插座
doorLock 门锁
humanPresenceSensor 人体存在传感器
{
"baseInfo": {
"appName": "xxxx酒店",
"authType": "MD5",
"hotelId": "ad6b7****7b3ff",
"requestId": "fcd07dd93d****2266e970504",
"requestTime": 1668416399452,
"roomNo": "1201",
"token": "fa4a90bba****b23eedd"
},
"command": {
"commandType": "QUERYALL"
}
}
响应
{
"result": {
//是否支持红外设备标志,默认不传会走保留逻辑,注:
//传入true时,表示会覆盖原本已配置的红外设备信息
//传入false时,表示会保留原本已配置的红外设备信息
"enableInfraredDeviceImport":true,
//是否支持mesh设备标志,默认不传会走覆盖逻辑,注:
//传入true时,表示会覆盖原本已配置的mesh设备信息
//传入false时,表示会保留原本已配置的mesh设备信息
"enableMeshDeviceImport":true,
//客控方语音发现设备,需要设备导入请按以下结构返回设备数据完成服务端配置
"groups": [{
"groupName": "房间", // 位置名称
"groupId": "room", // 位置 必传
"devices": [{
"number": "device-1-10", // 设备编号 必传
"name": "light", // 设备品类名称 必传
"deviceName": "卧室电视灯带", // 设备昵称 必传
"customContent": "测试", //自定义描述消息
"aliasList": [ // 设备别名 可不传 10个以内
"电视灯",
"灯带"
]
}, {
"number": "device-1-11",
"name": "light",
"deviceName": "卧室天花灯带",
"customContent": "测试" //自定义描述消息
}, {
"number": "device-1-13",
"name": "light",
"deviceName": "卧室洗手台灯",
"customContent": "测试" //自定义描述消息
}, { //多键开关
"multiKeySwitchExt": {
"switchList": [
{
"location": "room", //开关子设备的位置
"category": "light", //开关子设备的品类
"deviceIndex": 0, //开关子设备index
"deviceName": "吧台灯", //开关子设备名称
"customContent": "测试", //自定义描述消息
"aliasList": [ //开关子设备别名 10个以内
"餐饮灯",
"氛围灯"
]
},
{
"location": "room",
"category": "light",
"deviceIndex": 1,
"deviceName": "走廊灯",
"customContent": "测试", //自定义描述消息
"aliasList": [
"过道灯",
"顶灯"
]
},
{
"location": "room",
"category": "light",
"deviceIndex": 2,
"deviceName": "洗手台灯",
"customContent": "测试", //自定义描述消息
"aliasList": [
"洗漱灯"
]
}
],
},
"connectType": "mesh", //对接类型 mesh、infrared、rcu(不传默认为rcu)
"name": "switch", //设备品类
"dn": "xxxxxx", //设备dn
"pk": "xxxxx", //设备pk
"deviceName": "三键零火开关", //设备名称
"customContent": "测试", //自定义描述消息
"number":"xxx", //设备唯一标识
"aliasList": [ //设备别名 10个以内
"三键开关",
"零火开关",
"智能开关"
]
},{ //红外设备
"connectType": "infrared",//对接类型 mesh、infrared、rcu(不传默认为rcu)
"name": "tv", //设备品类
"brand":"Addsion", //品牌
"infraredId":"xxx", //红外码库id
"infraredIndex":"1", //红外码库index
"infraredVersion":"4.0", //红外码库版本
"deviceName":"电视", //设备名称
"customContent": "测试", //自定义描述消息
"aliasList": [ //设备别名 10个以内
"视机",
"电机",
"电视机"
]
},{ //一般mesh设备
"aliasList": ["西瓜"], //设备别名 10个以内
"connectType": "mesh", //对接类型 mesh、infrared、rcu(不传默认为rcu)
"deviceName": "廊灯", //设备名称
"customContent": "测试", //自定义描述消息
"dn": "xxxx", //设备dn
"name": "light", //设备品类
"pk": "xxxx", //设备pk
"number":"xxx", //设备唯一标识
}...]
}],
//客控方语音发现设备,需要关联房间的场景模式请按照以下结构返回场景内容完成场景的关联
"sceneModes":[{
//未创建场景,创建对应场景同时完成关联的参数传值,自定义rcu场景及配置
"sceneId": "esports", //自定义场景编码 自定义rcu场景
"name": "电竞模式", //场景名称
"icon":"https://gw.alicdn.com/imgextra/i2/O1CN01PN0NkB1V9swibSl8n_!!6000000002611-2-tps-136-136.png", //场景图标图片
"description":"xxxxxx", //场景描述信息
"isDisplayScreen": 1, //是否带屏显示
"customContent": "测试", //自定义描述消息
"corpusList":["打开电竞模式","我要玩游戏"] //触发语料,精准匹配
}]
},
"success": true,
"requestId": "fcd07dd****e970504",
"responseTime": 1667977280759,
"message": "success",
"statusCode": 200
}
对接完成后,可以语音对音箱说:“天猫精灵,发现设备”就可以批量完成房间内rcu设备同步到平台服务端。
附录三:酒店机器人对接协议
机器人配置,请于平台侧完成配置,具体操作可查看: 酒店项目之客需机器人配置
客需带屏设备发起订单及语音订单发起,若物品配送方式为机器人配送,会对机器人对接方发送一个请求,请求的协议如下:
{
"baseInfo": {
"appName": "xxxx",
"authType": "MD5",
"hotelId": "b3e8a63****af8904b3cdb4",
"requestId": "871d6117f8****8f4d44f3b3",
"requestTime": 1690270270928,
"roomNo": "201",
"token": "c6f7c5774****2059fbab170"
},
"command": {
"category": "客用品类",
"deliveryMethod": "robot", //配送方式
"groupKey": "ca867424-6a7****a9cc80aa13929052134",
"hotelId": "b3e8a63****04b3cdb4", //酒店id
"name": "纸巾", //物品名称
"orderNo": "202307251****7610361", //订单号
"paymentMethod": "robot", //结算方式
"price": 100.000, //金额
"quantity": 1,
"robotName": "xx机器人", //机器人名称
"roomNo": "201", //房间号
"type": "GOODS" //客需类型 目前就GOODS
}
}
响应:
{
"message":"success", //具体返回情况 失败原因
"statusCode":200, //状态code 200成功
"success":true
}
物品送达后,客控方可调用以下接口进行通知
https://open-api.aligenie.com/?version=ip_1.0&apiName=InvokeRobotPush
配送处理完成后,可根据以下接口进行工单完成
https://open-api.aligenie.com/?version=ip_1.0&apiName=UpdateTicket
附录四:其他客控对接接口
参考此文档完成其他常用客控接口对接:客控厂商对接接口列表