## 使用说明
接口地址：
Post http://openapi.tuling123.com/openapi/api
#### 输入协议
~~~
{
"info": "打开电视",
"userid": "1767022",
key:"key"//测试apikey
}
~~~
>字段说明
| 参数名称 | 参数介绍 |
| --- | --- |
| key | 该apikey关联家居场景（官网关联） |
| userid | 家庭唯一标识 |
| info | 用户输入信息 |
#### 输出协议
~~~
{
"appState": {
"appKey": "furniture.tv",
"operateState": 1100,
"parametes": {
"roomId": "103"
}
},
"tts": "...."
}
~~~
>字段说明
| 参数名称 | 参数介绍 | 参数字段 | 字段详情 | 示例 |
| --- | --- | --- | --- | --- |
| appState | 应用信息 | appKey | 当前家居唯一标识 | 电视:furniture.tv |
| appState | 应用信息 | operateState | 当前家居操作 | 开启电视：1100 |
| appState | 应用信息 | parametes | 应用相关参数 | 一定存在房间id,"roomId": "103" |
| tts | 语音输出内容 | tts | | |
#### 家居信息上传接口地址
Post http://openapi.tuling123.com/openapi/upload
###### 家居信息上传协议
~~~
{
"apiKey": "apikey",
"info": "[
{
'userid': 100,
'roomInfos': [
{
'furniture_id': '733100|733200',
'room_id': '102',
'room_name': '卧室',
'room_type': 1,
'use_state': 1
},
{
'furniture_id': '733200|733100',
'room_id': '103',
'room_name': '客厅|大厅',
'room_type': 0,
'use_state': 1
}
]
}
]"
}
~~~
>字段说明
| 参数名称 | 参数介绍 | 参数字段 | 字段详情 |
| --- | --- | --- | --- |
| apiKey | 该apikey关联家居场景（官网关联） | apiKey | - |
| info | 家庭的家居信息集合 | userid | 家庭唯一标识 |
| info | 家庭的家居信息集合 | roomInfos | 房间家居信息 |
注：roomInfos所含对象字段说明
~~~
{
'furniture_id': 包含设备id用'|'隔离,
'room_id': 房间唯一id与userid联合唯一,
'room_name': 房间名称用'|'隔离,
'room_type': 房间类型,
'use_state': 是否可用1可用，0不可用
}
~~~
###### 家居信息上传信息输出
~~~
{'intent':{'code':0}}
~~~
注：code值详见异常编码
#### 加密输入协议
###### 用户须知
（1）请求方式必须为HTTP POST；
（2）需在个人中心“我的机器人》机器人详情》接入”（微信公众号除外）开启加密功能secret，开启之后原HTTP GET请求将被禁止；
（3）加密示例demo可在个人中心“我的机器人》机器人详情》接入”（微信公众号除外）中下载文档获取。
###### 调用说明
>编码方式
UTF-8（调用图灵API的各个环节的编码方式均为UTF-8）
###### 加密算法规则
>参数说明
（1）时间戳用户校验请求，请尽可能的准确
（2）在图灵官网个人中心”我的机器人》机器人详情》接入“页获取APIKey，secret，计算当前的时间戳
示例如下：
~~~
secret=123
timestamp=1483949141576
apiKey=key
~~~
>生成密钥
（1）说明：MD5为32位算法，生成的aesKey为全小写keyParam = secret+timestamp+apiKey
（2）对keyParam进行MD5（32位算法）加密，生成aesKey，对“123456789key”进行加密之后得到aesKey = 912194e51267870e9283e9a035360a78;
>执行AES加密
（1）说明：AES采用128位加密算法
请求参数，例如：
~~~
param = {"info":"你好"}
~~~
（2）通过上面生成的aesKey,对请求参数param进行AES加密，得到data
data = TwPFGlIQk/yl2qDbNyuSQg9JMeV6aLdCS7yo6lT5Ia0=
>封装请求图灵API的json参数
~~~
{
key:key,
timestamp:456789,
data:TwPFGlIQk/yl2qDbNyuSQg9JMeV6aLdCS7yo6lT5Ia0=
}
~~~
注：以上请求参数中的key与apikey值一致
#### 设备相关协议
>[info] 电视
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 电视 | furniture.tv |733100|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2010 | 增大声音 |
| 2011 | 减小声音 |
| 3000 | 静音 |
| 3010 | 上一个台 |
| 3011 | 下一个台 |
| 3030 | 换台 |
| operateState | operateState详情 | parametes内字段 | parametes字段详解 |
| --- | --- |--- |--- |
| 3030 | 换台 |channelID | 电视台id |
| 3030 |换台 |channelNum | 频道数字 |
>[info] 冰箱
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 冰箱 |furniture.refrigerator |733200|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 2010 | 升高温度 |
| 2011 | 降低温度 |
| 2200 | 节能模式 |
| 2300 | 普通模式 |
>[info] 空调
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 空调 | furniture.airConditioning |733300|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2010 | 升高温度 |
| 2011 | 降低温度 |
| 2200 | 制冷模式 |
| 2500 | 调节温度 |
| operateState | operateState详情 | parametes内字段 | parametes字段详解 |
| --- | --- |--- |--- |
| 2500 | 调节温度 |parseTem | 调节温度值 |
>[info] 音响
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 音响 | furniture.audio |733400|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2010 | 增大声音 |
| 2011 | 减小声音 |
| 3000 | 静音 |
>[info] 灯
| 设备名称 | appkey | 设备id|
| --- | --- | --- |
| 灯 | furniture.lighting |733500|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2010 | 增大亮度 |
| 2011 | 减小亮度 |
>[info] 台灯
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 台灯 | furniture.tableLamp |733600|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2010 | 增大亮度 |
| 2011 | 减小亮度 |
>[info] 扫地机
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 扫地机 | furniture.floorSweeping |733700|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2100 | 定时操作 |
| operateState | operateState详情 | parametes内字段 | parametes字段详解 |
| --- | --- |--- |--- |
| 2100 | 定时操作 |startTime | 开始时间毫秒：0立即开始，-1没有开始时间 |
| 2100 | 定时操作 |endTime | 结束时间毫秒-1没有时间 |
>[info] 机顶盒
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 机顶盒 | furniture.tvBox |733800|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开 |
| 1000 | 关闭 |
| 2010 | 增大声音 |
| 2011 | 减小声音 |
| 3000 | 静音 |
| 3010 | 上一个台 |
| 3011 | 下一个台 |
| 3030 | 换台 |
| operateState | operateState详情 | parametes内字段 | parametes字段详解 |
| --- | --- |--- |--- |
| 3030 | 换台 |channelID | 电视台id |
| 3030 |换台 |channelNum | 频道数字 |
>[info] 风扇
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 风扇 | furniture.electricFan |733900|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 开启 |
| 1000 | 关闭 |
| 2010 | 增大风速 |
| 2011 | 减小风速 |
>[info] 窗帘
| 设备名称 | appkey |设备id|
| --- | --- | --- |
| 窗帘 |furniture.curtain |733000|
>字段说明
| operateState | operateState详情 |
| --- | --- |
| 1100 | 打开窗帘 |
| 1000 | 关闭窗帘 |
>[info] 语音对话
| 应用名称 | appkey |
| --- | --- |
| 语音对话|platform.chat |
>[info] 知识库
| 应用名称 |appkey |
| --- | --- |
| 知识库 |platform.faq |
#### 返回异常码
以下参数代表：
1，上传家居信息接口返回code值
2，当appkey值为system.error时的operateState值
| 参数 | 参数说明 |
| --- | --- |
| 5000 | 暂不支持该功能 |
| 6000 | 暂不支持该功能 |
| 4000 | 请求参数格式错误 |
| 4001 | 加密方式错误 |
| 4002 | 无功能权限 |
| 4003 | 该apikey没有可用请求次数 |
| 4005 | 无功能权限 |
| 4006 | 自定义输出格式异常（只出现在log日志中） |
| 4100 | userid获取失败 |
| 4200 | 上传格式错误 |
| 4300 | 批量操作超过限制 |
| 4400 | 没有上传合法userid |
| 4500 | userid申请个数超过限制 |
| 40000 | 用户（userid）没有上传家居信息 |
| 0 | 成功操作！ |
#### 房间类型
| 房间类型 | 编号 |
| --- | --- |
| 客厅 | 0 |
| 卧室 | 1 |
| 客房 | 2 |
| 书房 | 3 |
| 儿童房 | 4 |
| 餐厅 | 5 |
| 阳台 | 6 |
| 卫生间 | 7 |
| 储藏室 | 8 |
| 其他 | 9 |
#### 附错误码
>1,上传家居信息时，最大批量操作家庭数（即userid个数）必须小于20！
2,userid上传id只能是数字取值范围-2147483648~2147483647
openapi/api 接口异常返回码包含：
apikey不对错误，返回结果：{"ret":1,"text":"亲爱的，未找到对应的用户信息，请稍后重试。"}
加密逻辑错误，返回结果：{"ret":1,"text":"解密失败，您的加密逻辑存在异常！"}
userid不合法，返回结果：{"ret":1,"text":"亲爱的，userid不合法。"}
上传家居信息接口可新增与更新用户家居信息，注意更新时用户该房间信息保证完整！
上传接口只可新增与更新用户家居信息，注意更新时用户该房间信息保证完整！
