## 使用說明
接口地址：
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不合法。"}
上傳家居信息接口可新增與更新用戶家居信息，注意更新時用戶該房間信息保證完整！
上傳接口只可新增與更新用戶家居信息，注意更新時用戶該房間信息保證完整！
