微信硬件設備接入接口協議

微信硬件設備接入接口協議
（公開使用）
Tencent Technologies Co., Ltd.
騰訊科技有限公司
All rights reserved
產品版本 密級
V2.0Beta 請輸入密級：公開
Tencent.
騰訊科技有限公司
項目名稱： 微信硬件設備接入接口協議 共 頁
第 2 頁 共 29頁
第 3 頁 共 29頁
文檔歷史記錄
第 4 頁 共 29頁
部門 微信產品部\開放平臺中心\平臺開發組\架構優化組
起始人員 koukoutan
文檔版本 描述 撰寫人員 更新時間
V1.0Beta 初稿 koukoutan 2013/12/16
V1.1Beta 二維碼增長設備接入類型(ble、wifi)
koukoutan 2014/1/7
v1.2Beta 加入Q&A koukoutan 2014/2/12
v1.3Beta
修改設備發消息、綁定、解綁協議格式，採
用xml格式替換之前的json格式
koukoutan 2014/2/13
v1.4Beta
二維碼connect_protocol字段含義調整
增長設備受權api
koukoutan 2014/2/14
v1.5Beta
設備受權api：明確mac和auth_key字段格式
，第三方的服務url再也不增長device路徑
koukoutan 2014/2/19
v1.6Beta
設備受權新增： crypt_method和 
auth_ver字段
koukoutan 2014/2/24
v1.7Beta 增長設備狀態狀態查詢api koukoutan 2014/2/27
v1.8Beta 修改二維碼響應結果，再也不提供二維碼圖片
下載，僅提供二維碼生成的ticket
koukoutan 2014/2/28
v1.9Beta
調用設備受權api時，通訊採用不加密方式，
字段的取值定義；全部的api使用https協議，
而且放到外網環境，加入ios優化鏈接彈窗
koukoutan 2014/3/11
v1.9.1Beta 1.6節增長「更新設備屬性」功能 koukoutan 2014/4/10
v1.9.2Beta 1.6節修改「conn_strategy」字段定義 koukoutan 2014/4/11
v2.0Beta
增長1.8章，消息接口接入社交功能
增長1.9章，二維碼驗證
QA增長api頻率說明，常見錯誤排查
jashuang
koukoutan
2014/4/30
v2.1
設備受權api增長conn strategy和close 
strategy類型
受權接口，二維碼獲取接口，約束第三方批
量操做的device id數的上限
koukoutan 2014/8/22
第 5 頁 共 29頁
第 6 頁 共 29頁
目 錄
1. 第三方協議.......................................................................................................................................5
1.1. 消息接口：設備經過微信發消息給第三方...........................................................................5
1.2. 消息接口：「綁定/解綁」設備.............................................................................................8
1.3. API：第三方主動發送消息給設備......................................................................................10
1.4. API：獲取設備綁定openID................................................................................................11
1.5. API：獲取設備二維碼..........................................................................................................12
1.6. API：設備受權......................................................................................................................14
1.7. API：設備狀態查詢..............................................................................................................19
1.8. 消息接口：接入社交功能消息.............................................................................................20
1.9. API：驗證二維碼..................................................................................................................21
2. Q&A...............................................................................................................................................23
2.1. 流程.........................................................................................................................................23
2.2. 權限申請.................................................................................................................................23
2.3. 錯誤處理.................................................................................................................................24
2.4. 特殊邏輯.................................................................................................................................25
插 圖
圖 第三方服務url .....................................................................................................................................5
表 格
設備經過微信發送消息給第三方請求協議描述...................................................................................7
設備經過微信發送消息給第三方響應協議描述...................................................................................7
第 7 頁 共 29頁
用戶「綁定/解綁」設備請求協議描述..................................................................................................9
用戶「綁定/解綁」設備響應協議描述................................................................................................10
第三方主動發送消息給設備協議描述.................................................................................................11
獲取設備綁定openID協議描述...........................................................................................................12
批量獲取二維碼請求協議描述.............................................................................................................13
批量獲取二維碼響應協議描述.............................................................................................................14
設備受權請求協議描述.........................................................................................................................17
設備受權響應協議描述.........................................................................................................................18
查詢設備id狀態請求協議描述..............................................................................................................19
查詢設備id狀態響應協議描述..............................................................................................................20
回覆社交功能消息.................................................................................................................................21
二維碼驗證請求協議.............................................................................................................................22
驗證二維碼響應協議描述.....................................................................................................................22
api頻率控制............................................................................................................................................24
第 8 頁 共 29頁
設備接入接口協議
關鍵詞：設備接入，微信，公衆平臺，http，json，post，get，xml
摘要： 
協議分爲兩類：消息接口、API，消息接口是指公衆平臺將用戶發送的消息發送給第三方
並接收第三方的回覆，API是指公衆平臺提供給第三方主動調用的接口。
1. 第三方協議
第三方與微信公衆平臺之間的協議
1.1.消息接口：設備經過微信發消息給第三方
【接口說明】
設備經過微信同第三方通訊，而且接收第三方的響應
【請求方式】
http請求的post方式
【請求url】
由第三方設定，可在公衆平臺「高級功能==》開發模式」下查看和設置，舉例以下：
圖 第三方服務url
公衆平臺會在device url上追加三個參數：signature=SIGNATURE& 
timestamp=12345678& nonce=NONCE，最終的請求url以下：
http://10.148.150.116:22341/cgi-bin/uly_test?signature=SIGNATURE& 
timestamp=12345678& nonce=NONCE
【請求內容】方倍工做室
第 9 頁 共 29頁
<xml>
<ToUserName><![CDATA[%s]]></ToUserName>
<FromUserName><![CDATA[%s]]></FromUserName>
<CreateTime>%u</CreateTime>
<MsgType><![CDATA[%s]]></MsgType>
<DeviceType><![CDATA[%s]]></DeviceType>
<DeviceID><![CDATA[%s]]></DeviceID>
<Content><![CDATA[%s]]></Content>
<SessionID>%lu</SessionID>
<MsgID>%lu</MsgID>
<OpenID><![CDATA[%s]]></OpenID>
</xml>
【請求參數說明】
字段 是否必須 說明
signature 是
認證簽名，公衆平臺經過第三方appid能夠拿到
第三方的認證token，signature爲token、time
stamp、隨機數組成
timestamp 是 請求發送的時間戳
nonce 是 隨機數
ToUserName 是 接收方（公衆號）的user name
FromUserName 是 發送方（微信用戶）的user name
CreateTime 是 消息建立時間，消息後臺生成
MsgType 是 消息類型：device_text
DeviceType 是 設備類型，目前爲「公衆帳號原始ID」
DeviceID 是 設備ID，第三方提供
Content 是 消息內容，BASE64編碼
SessionID 是
微信客戶端生成的session 
id，用於request和response對應，所以響應中
該字段第三方須要原封不變的帶回方倍工做室
第 10 頁 共 29頁
MsgId 是 消息id，微信後臺生成
OpenID 是 微信用戶帳號的OpenID
設備經過微信發送消息給第三方請求協議描述
【響應】：
<xml>
<ToUserName><![CDATA[%s]]></ToUserName>
<FromUserName><![CDATA[%s]]></FromUserName>
<CreateTime>%u</CreateTime>
<MsgType><![CDATA[%s]]></MsgType>
<DeviceType><![CDATA[%s]]></DeviceType>
<DeviceID><![CDATA[%s]]></DeviceID>
<SessionID>%u</SessionID>
<Content><![CDATA[%s]]></Content>
</xml>
【響應參數說明】
字段 是否必須 說明
ToUserName 是 接收方（微信用戶）的user name
FromUserName 是 發送方（公衆號）的user name
CreateTime 是 消息建立時間，第三方本身取當前秒級時間戳
MsgType 是 消息類型（同請求參數）：device_text
DeviceType 是 設備類型（同請求參數）
DeviceID 是 設備ID（同請求參數）
SessionID 是 微信客戶端生成的session id（同請求參數）
Content 是 消息內容，BASE64編碼
設備經過微信發送消息給第三方響應協議描述
【注意】方倍工做室
第 11 頁 共 29頁
公衆平臺會將Content對應的base64編碼的數據發送給微信終端，微信終端會進行解
碼，並將解碼後的數據發送給設備
1.2.消息接口：「綁定/解綁」設備
【接口說明】
微信用戶綁定設備後，設備會經過微信給第三方發送消息
【請求方式】
http請求的post方式
【請求url】
同1.1.章【請求url】
【請求內容】
<xml>
<ToUserName><![CDATA[%s]]></ToUserName>
<FromUserName><![CDATA[%s]]></FromUserName>
<CreateTime>%u</CreateTime>
<MsgType><![CDATA[%s]]></MsgType>
<Event><![CDATA[%s]]></Event>
<DeviceType><![CDATA[%s]]></DeviceType>
<DeviceID><![CDATA[%s]]></DeviceID>
<Content><![CDATA[%s]]></Content>
<SessionID>%u</SessionID>
<OpenID><![CDATA[%s]]></OpenID>
</xml>
【請求參數說明】
字段 是否必須 說明
signature 是
認證簽名，公衆平臺經過第三方appid能夠拿到
第三方的認證token，signature爲token、time
stamp、隨機數組成
timestamp 是 請求發送的時間戳
nonce 是 隨機數方倍工做室
第 12 頁 共 29頁
ToUserName 是 接收方（公衆號）的user name
FromUserName 是 發送方（微信用戶）的user name
CreateTime 是 消息建立時間，消息後臺生成
MsgType 是 消息類型：device_event
Event 是
事件類型，取值爲bind/unbind
bind：綁定設備
unbind：解除綁定
DeviceType 是 設備類型，目前爲「公衆帳號原始ID」
DeviceID 是 設備ID，第三方提供
Content 是 消息內容，BASE64編碼
SessionID 是
微信客戶端生成的session 
id，用於request和response對應，所以響應中
該字段第三方須要原封不變的帶回
OpenID 是 微信帳號的OpenID
用戶「綁定/解綁」設備請求協議描述
【響應】：
<xml>
<ToUserName><![CDATA[%s]]></ToUserName>
<FromUserName><![CDATA[%s]]></FromUserName>
<CreateTime>%u</CreateTime>
<MsgType><![CDATA[%s]]></MsgType>
<Event><![CDATA[%s]]></Event>
<DeviceType><![CDATA[%s]]></DeviceType>
<DeviceID><![CDATA[%s]]></DeviceID>
<SessionID>%u</SessionID>
<Content><![CDATA[%s]]></Content>
</xml>
【響應參數說明】方倍工做室
第 13 頁 共 29頁
字段 是否必須 說明
ToUserName 是 接收方（微信用戶）的user name
FromUserName 是 發送方（公衆號）的user name
CreateTime 是 消息建立時間，第三方本身取當前秒級時間戳
MsgType 是 消息類型（同請求參數）：device_event
Event 是 事件類型（同請求參數）
DeviceType 是 設備類型（同請求參數）
DeviceID 是 設備ID （同請求參數）
SessionID 是 微信客戶端生成的session id（同請求參數）
Content 是 消息內容，BASE64編碼
用戶「綁定/解綁」設備響應協議描述
【注意】
公衆平臺會將響應的Content字段對應的base64編碼的數據發送給微信終端，微信終
端會進行解碼，並將解碼後的數據發送給設備
1.3. API：第三方主動發送消息給設備
【接口說明】
第三方發送消息給設備主人的微信終端，並最終送達設備
【請求方式】
http請求方式: POST
【請求url】
https://api.weixin.qq.com/device/transmsg?access_token=ACCESS_TOKEN
【請求內容】
{
"device_type":"DEVICETYPE",
"device_id":"DEVICEID",
"open_id": " OPEN_ID",
"content": " BASE64編碼內容",
}
【參數說明】方倍工做室
第 14 頁 共 29頁
字段 是否必須 說明
access_token 是 調用接口憑證
device_type 是
設備類型，目前爲「公衆帳號原始I
D」
device_id 是 設備ID
content 是 消息內容，BASE64編碼
open_id 是 微信用戶帳號的openid
第三方主動發送消息給設備協議描述
【請求示例】
curl 
https://api.weixin.qq.com/device/transmsg?access_token=ACCESS_TOKEN -d 
"{\"device_type\":\"DEVICE_TYPE\",\"device_id\":\"DEVICE_ID\",\"open_id\":\"OPEN
_ID\",\"content\":\"CENTENT\"}"
【響應】
正確的Json返回結果：
{"ret":0,"ret_info":"this is ok"}
錯誤的Json返回示例:
{"errcode":-1,"errmsg":""}
【注意】
第三方調用該服務，須要向公衆平臺申請權限，權限的申請須要向公衆平臺提供第三
方的appid
1.4. API：獲取設備綁定openID
【接口說明】
經過device type和device id獲取設備主人的openid；
【請求方式】
http請求方式: GET
【請求url】
https://api.weixin.qq.com/device/get_openid?access_token=ACCESS_TOKEN&
device_type=DEVICE_TYPE&device_id=DEVICE_ID方倍工做室
第 15 頁 共 29頁
【參數說明】
字段 是否必須 描述
access_token 是 調用接口憑證
device_type 是
設備類型，目前爲「公衆帳號原始I
D」
device_id 是 設備的deviceid
獲取設備綁定openID協議描述
【請求示例】
curl 
"https://api.weixin.qq.com/device/get_openid?access_token=ACCESS_TOKEN
& device_type=DEVICE_TYPE&device_id=DEVICE_ID"
【響應】
返回頭：
HTTP/1.1 200 OK
Connection: close
Date: Mon, 16 Dec 2013 07:48:31 GMT
Content-Type: application/json; encoding=utf-8
Content-Length: 98
正確返回:
{"open_id":["omN7ljrpaxQgK4NW4H5cRzFRtfa8","omN7ljtqrTZuvYLkjPEX_t_P
mmlg",],"resp_msg":{"ret_code":0,"error_info":"get open id list OK!"}} 
【注意】
第三方調用該服務，須要申請權限，權限的申請須要向公衆平臺提供第三方的appid
1.5. API：獲取設備二維碼
【接口說明】
第三方公衆帳號經過設備id從公衆平臺批量獲取設備二維碼
【請求方式】：
http請求的post方式方倍工做室
第 16 頁 共 29頁
【請求url】：
https:// api.weixin.qq.com/device/create_qrcode?access_token=ATOKEN
【請求內容】（json格式）：
{
"device_num":"2",
"device_id_list":["01234","56789"]
}
【字段說明】：
字段 是否必須 描述
access_token 是 調用接口憑證
device_num 是 設備id的個數
device_id_list 是
設備id的列表，json的array格式，其size必須
等於device_num
批量獲取二維碼請求協議描述
【請求示例】
curl https://api.weixin.qq.com/device/create_qrcode?access_token=ATOKEN -
d "{\"device_num\":\"2\", \"device_id_list\":[\"ID1\",\"ID2\"]}"
【響應】：
成功：json方式返回二維碼的生成ticket，舉例以下：
{
"errcode":0,
"errmsg":"succ",
"device_num":1,
"code_list":[{"device_id":"id1","ticket":"t1"}]
}
失敗：返回失敗的錯誤碼和錯誤信息，譬如：
{"errcode":42001,"errmsg":""}
【響應參數說明】
字段 是否必須 說明方倍工做室
第 17 頁 共 29頁
errcode 是 錯誤碼，0表示設置成功，非0表示失敗
errmsg 是 錯誤信息（同errcode對應）
device_num 是 成功生成二維碼的數量
code_list 否
二維碼列表（json的數組形式），當errcode爲0
且device_num不爲0時數組纔有內容
device_id 是 設備id
ticket 是 設備id對應的二維碼
批量獲取二維碼響應協議描述
【注意】
一、第三方調用該服務，須要申請權限，權限的申請須要向公衆平臺提供第三方的app
id
二、建議deviceid爲英文字母、下劃線、數字三類字符的串或者組合，不帶其餘標點
符號，以避免json串解析失敗
三、二維碼的生成有可能失敗，所以請求的devcie num和響應的devcie 
num不必定相等；若是不相等，第三方須要覈對下請求中哪些device 
id沒有生成成功
四、響應中的ticket爲二維碼的生成串，第三方須要用這些串來生成二維碼（點陣圖）
，爲了提升二維碼的掃碼成功率，咱們建議第三方：使用qrencode庫，QR碼版
本5，糾錯等級爲Q級，容錯率不低於20%
五、返回的ticket字符串，會帶有json的敏感字符，所以，公衆平臺對於敏感字符作了
轉義（如：/字符會被轉義成\/），第三方須要將這些敏感字符轉義回來
六、設備二維碼ticket生成須要耗費系統資源，所以，建議公衆號開發者一次操做不超
過5個
1.6. API：設備受權
【接口說明】
第三方公衆帳號將device id及其屬性信息提交公衆平臺進行受權
【請求方式】：
http請求的post方式方倍工做室
第 18 頁 共 29頁
【請求url】：
https://api.weixin.qq.com/device/authorize_device?access_token=ATOKEN
【請求內容】（json格式）：
{
"device_num":"2",
"device_list":[
{"id":"dev1","mac":"mac","connect_protocol":"1|2","auth_key":"","close_stra
tegy":"1","conn_strategy":"1","crypt_method":"0","auth_ver":"1","manu_mac_p
os":"-1","ser_mac_pos":"-2"}
],
"op_type":"0"
}
【字段說明】：
字段 是否必須 描述
access_token 是 調用接口憑證
device_num 是 設備id的個數
device_list 是
設備id的列表，json的array格式，其size必須
等於device_num
id 是 設備的deviceid
mac 是
設備的mac地址（48bit）格式採用16進制串的
方式（長度爲12字節），不須要0X前綴，如：
1234567890AB
connect_protocol 是
支持如下四種鏈接協議：
android classic bluetooth – 1
ios classic bluetooth – 2
ble – 3
wifi -- 4
一個設備能夠支持多種鏈接類型，用符號"|"作
分割，客戶端優先選擇靠前的鏈接方式（優先
級按|關係的排序依次下降），舉例：
1：表示設備僅支持andiod classic bluetooth方倍工做室
第 19 頁 共 29頁
1|2：表示設備支持andiod 和ios 兩種classic 
bluetooth，可是客戶端優先選擇andriod 
classic bluetooth 協議，若是andriod classic 
bluetooth協議鏈接失敗，再選擇ios classic 
bluetooth協議進行鏈接
auth_key 是
auth及通訊的加密key，第三方須要將key燒製
在設備上（128bit），格式採用16進制串的方
式（長度爲32字節），不須要0X前綴，如：
1234567890ABCDEF1234567890ABCDEF
close_strategy 是
斷開策略，目前支持：
1：退出公衆號頁面時即斷開鏈接
2：退出公衆號以後保持鏈接不斷開
3：退出公衆號以後一直保持鏈接（設備主動斷
開鏈接後，微信嘗試重連）
conn_strategy 是
鏈接策略，32位整型，按bit位置位，目前僅第
1bit和第3bit位有效（bit置0爲無效，1爲有效
；第2bit已被廢棄），且bit位能夠按或置位（
如1|4=5），各bit置位含義說明以下：
1：（第1bit置位）在公衆號對話頁面，不停的
嘗試鏈接設備
4：（第3bit置位）處於非公衆號頁面（如主界
面等），微信自動鏈接。當用戶切換微信到前
臺時，可能嘗試去鏈接設備，連上後必定時間
會斷開
8：（第4bit置位），進入微信後即刻開始鏈接
。只要微信進程在運行就不會主動斷開
crypt_method 是
auth加密方法，目前支持兩種取值：
0：不加密
1：AES加密（CBC模式，PKCS7填充方式）
auth_ver 是
auth 
version，設備和微信進行auth時，會根據該版方倍工做室
第 20 頁 共 29頁
本號來確認auth buf和auth 
key的格式（各version對應的auth 
buf及key的具體格式能夠參看「客戶端藍牙外
設協議」），該字段目前支持取值：
0：不加密的version
1：version 1
manu_mac_pos 是
表示mac地址在廠商廣播manufature 
data裏含有mac地址的偏移，取值以下：
-1：在尾部、
-2：表示不包含mac地址
其餘：非法偏移
ser_mac_pos 是
表示mac地址在廠商serial 
number裏含有mac地址的偏移，取值以下：
-1：表示在尾部
-2：表示不包含mac地址
其餘：非法偏移
op_type 否
請求操做的類型，限定取值爲：
0：設備受權（缺省值爲0）
1：設備更新（更新已受權設備的各屬性值）
設備受權請求協議描述
【請求示例】
curl 
https://api.weixin.qq.com/device/authorize_device?access_token=ATOKEN -d 
'{"device_num":"1","device_list":[{"id":"dev1","mac":"123456789ABC","connect_
protocol":"1|2","auth_key":"","close_strategy":"1","conn_strategy":"1","crypt_m
ethod":"0","auth_ver":"0","manu_mac_pos":"-1","ser_mac_pos":"-
2"}],"op_type":"0"}'
【響應】：
成功：以json格式返回每一個device id對應的受權狀態：
{"resp":[{"base_info":{"device_type":"your_devcie_type","device_id":"id"},"errco方倍工做室
第 21 頁 共 29頁
de":0,"errmsg":"ok"}]}
失敗：返回失敗的錯誤碼和錯誤信息，譬如：
{"errcode":42001,"errmsg":""}
【響應參數說明】
字段 是否必須 說明
resp 是 設備id受權的response（json數組形式）
base_info 是
設備基本信息（包括device typ和device 
id，目前device type爲用戶的原始id）
errcode 是 錯誤碼，0表示設置成功，非0表示失敗
errmsg 是 錯誤信息（同errcode對應）
設備受權響應協議描述
上表中參數描述爲服務請求成功時的響應描述
【注意】
一、第三方調用該服務，須要申請權限，權限的申請須要向公衆平臺提供第三方的app
id
二、建議id字段爲英文字母、下劃線、數字三類字符的串或者組合，不帶其餘標點符
號，以避免json串解析失敗
三、connec_protocol爲設備鏈接的協議類型，目前有四種鏈接方式（見字段說明）
，能夠支持四種鏈接方式的任意組合，而且能夠設置客戶端優先選擇的鏈接方式
，客戶端會優先選擇該鏈接方式進行鏈接，若制定的優先協議沒法鏈接成功，客
戶端回嘗試指定的其餘協議方式鏈接；其餘類型能夠後續再添加，請第三方同窗
確保值有效
四、conn_strategy鏈接策略，按位進行定義取值（第2bit不能置位；全部bit均不置位
也不支持，即取值爲 
0），譬如手環類產品，可能須要及時同步數據，能夠填5，表示在公衆號對話頁
面，不停的嘗試鏈接設備（取值1），而且處於非公衆號頁面時，微信有機會去連
接設備，保證數據能及時同步（取值4）
五、crypt_method目前支持取值爲0和1，對於計算能力弱的設備能夠設置爲0（不進
行加密處理，此時auth_ver也須要爲0），目前的加密方法只支持AES
六、auth_ver目前只支持取值爲0或1，不一樣的取值會影響「設備---微信---方倍工做室
第 22 頁 共 29頁
後臺」的auth過程的數據包的格式，具體的取值請參看「客戶端藍牙外設協議」
，而且，若是不須要加密，則crypt_method和auth_ver都須要爲0，
七、對於ios藍牙2.0和4.0設備，微信客戶端作了鏈接創建的彈框優化操做：對於ios藍
牙4.0協議，廣播包必須帶上mac地址，即：manu_mac_pos必須設置（且爲-
1，非ios藍牙4.0設備才能夠設置爲-2）；對於ios藍牙2.0協議，iap的accessory 
Info的serial number能夠不帶mac地址，ser_mac_pos設置爲-
2，也能夠在尾部帶上mac地址，設置有效（-
1），對於除以上兩種協議之外的其餘協議，該兩個值的設置均無效，能夠設置爲
0
八、op_type爲請求操做類型，字段缺省值爲0，即：設備受權，字段取值爲1，則將
請求中的設備屬性更新已有的設備屬性（若設備不存在，則更新失敗）
九、受權接口的處理邏輯比較複雜，所以，約束公衆號分開發者：一次批量受權的dev
ice id不能超過5個
1.7. API：設備狀態查詢
【接口說明】
第三方公衆帳號經過設備id查詢該id的狀態（三種狀態：未受權、已受權、已綁定）
【請求方式】：
http請求的get方式
【請求url】：
https://api.weixin.qq.com/device/get_stat?access_token=ATOKEN&device_id=
DEVICE_ID
【字段說明】：
字段 是否必須 描述
access_token 是 調用接口憑證
device_id 是 設備id
查詢設備id狀態請求協議描述
【請求示例】
curl 方倍工做室
第 23 頁 共 29頁
https://api.weixin.qq.com/device/get_stat?access_token=ATOKEN&device_id=
DEVICE_ID
【響應】：
成功：以json格式返回device id的狀態，舉例以下：
{"errcode":0,"errmsg":"ok","status":2,"status_info":"bind"}
失敗：返回失敗的錯誤碼和錯誤信息，譬如：
{"errcode":42001,"errmsg":""}
【響應參數說明】
字段 是否必須 說明
errcode 是 錯誤碼（0服務請求成功，非0爲失敗）
errmsg 是 錯誤信息
status 是
設備狀態，目前取值以下：
0：未受權
1：已經受權（還沒有被用戶綁定）
2：已經被用戶綁定
status_info 是 status對應的描述
查詢設備id狀態響應協議描述
上表中參數描述爲服務請求成功時的響應描述
【注意】
一、第三方調用該服務，須要申請權限，權限的申請須要向公衆平臺提供第三方的app
id
1.8.消息接口：接入社交功能消息
【接入說明】
當用戶與第三方進行交互（消息、自定義菜單等）時，第三方可經過消息接口返回特
定xml結構，可讓用戶收取到社交功能消息（如排行版消息等）
【請求方式】：
消息接口返回串
【返回格式】：方倍工做室
第 24 頁 共 29頁
<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>
<FromUserName><![CDATA[fromUser]]></FromUserName>
<CreateTime>123456789</CreateTime>
<MsgType><![CDATA[hardware]]></MsgType>
<HardWare>
<MessageView><![CDATA[myrank]]></MessageView>
<MessageAction><![CDATA[ranklist]]></MessageAction>
</HardWare>
<FuncFlag>0</FuncFlag>
</xml>
【字段說明】：
字段 是否必須 描述
ToUserName 是 開發者微信號
FromUserName 是 發送方賬號（一個OpenID）
CreateTime 是 建立時間 （整型）
MsgType 是 填寫hardware
HardWare.MessageView 是 消息展現，目前支持myrank（排行版）
HardWare.MessageAction 是
消息點擊動做，目前支持ranklist（點擊跳轉排行版
）
回覆社交功能消息
1.9. API：驗證二維碼
【接口說明】
第三方公衆帳號經過獲取設備二維碼的api獲得ticket後，能夠經過該api拿到對應的
設備屬性
【請求方式】：
http請求的post方式方倍工做室
第 25 頁 共 29頁
【請求url】：
https://api.weixin.qq.com/device/verify_qrcode?access_token=ATOKEN
【請求內容】
{
"ticket":"QRCODE_TICKET",
}
【字段說明】：
字段 是否必須 描述
access_token 是 調用接口憑證
ticket 是 設備二維碼的ticket
二維碼驗證請求協議
【請求示例】
curl https://api.weixin.qq.com/device/verify_qrcode?access_token=ATOKEN
【響應】：
成功：以json格式返回device id的狀態，舉例以下：
{"errcode":0,"errmsg":"ok","device_type":"gh_xxxxxx","device_id":"DEVICE_ID","
mac":"MAC"}
失敗：返回失敗的錯誤碼和錯誤信息，譬如：
{"errcode":-1,"errmsg":""}
【響應參數說明】
字段 是否必須 說明
errcode 是 錯誤碼（0服務請求成功，非0爲失敗）
errmsg 是 錯誤信息
device_type 是 設備類型
device_id 是 設備id
mac 是 設備的mac地址
驗證二維碼響應協議描述
上表中參數描述爲服務請求成功時的響應描述方倍工做室
第 26 頁 共 29頁
【注意】
一、第三方調用該服務，須要申請權限，權限的申請須要向公衆平臺提供第三方的app
id
2. Q&A
2.1.流程
Q：第三方進行設備相關功能的開發和調試，須要哪些步驟進行？
A：主要按照如下步驟進行：
一、須要先熟悉公衆平臺已有功能
二、詳細閱讀本文檔的「第三方協議」相關章節
三、向公衆平臺後臺提交「設備功能」的API使用權限申請，不然沒法使用相關API（
申請方法見「權限申請」章節）
四、向公衆平臺提交device id的受權，不然devcie 
id沒法被用戶綁定（申請方法見「權限申請」章節）
五、確保第三方服務url可用，第三方服務url的修改：登陸公衆平---功能---高級功能-
--開發模式---URL---修改
六、獲取二維碼，開發、調試
2.2.權限申請
Q：如何申請「設備功能」API的使用權限？
A：第三方提供該公衆帳號的appid給到公衆平臺產品或者後臺負責人，appid的獲取
：登陸公衆平---功能---高級功能---開發模式---appid
Q：如何申請device id的使用權限？
A：向公衆平臺提交device 
id的受權（須要提供設備類型（目前支持藍牙、WIFI兩種設備）、device 
id、原始id，原始id的獲取：登陸公衆平臺---設置---帳號信息---原始ID）
Q：api調用的頻率控制：
目前，公衆平臺的api調用是有頻率控制的，設備api的頻率控制以下：方倍工做室
第 27 頁 共 29頁
api 功能 頻率
transmsg 第三方主動發送消息給設備 20w/day
get_openid 獲取設備綁定openID 2k/day
create_qrcode 獲取設備二維碼 2w/day
authorize_device 設備受權 2w/day
get_stat 設備狀態查詢 2k/day
verify_qrcode 驗證二維碼 50w/day
api頻率控制
每一個api調用超過頻率限制後，須要等到次日凌晨0點，才能夠恢復服務
2.3.錯誤處理
Q：調用設備功能相關的API，返回錯誤信息」user unauthorized」
A：第三方沒有使用API的權限，須要向公衆平臺後臺提交「設備功能」的API使用權
限（申請方法見「權限申請章節」）
Q：爲何設備發給微信的數據和第三方雲端接收到的公衆平臺平臺發送的請求數據
不同？
A：公衆平臺目前對第三方的協議採用的是「文本協議」方式，所以，對於設備消息
數據是通過base64加密後的數據，所以：
一、對於設備給第三方發數據，數據流是：設備數據---微信---
公衆平臺base64加密數據---
第三方雲；所以，第三方收到的數據是對設備原始數據進行base64加密的數據，
第三方須要base64解密，才能獲得原始數據
二、對於第三方給設備發送響應，數據流是：第三方base64加密數據---公衆平臺---
微信終端base64解密獲得原始數據---
設備；所以第三方雲發送給設備的數據必定是通過base64加密的，而設備收到的
數據則是base64解密後的原始數據
Q：爲何掃描設備二維碼，提示設備不存在？
A：確認device id是否已經申請受權（受權方式見「權限申請」章節）方倍工做室
第 28 頁 共 29頁
Q：爲何調用「主動發消息給設備」的API提示「get device_id error」？
A：請確認公衆帳號是否申請受權了該device 
id，而且詳細確認調用API中的device_id，device_type，opend_id是否正確？device_ty
pe目前爲公衆帳號的原始ID，open_id必須綁定了該device_id
Q：爲何調用「主動發消息給設備」的API提示成功，可是設備沒有收到消息？
A：確保發送的消息中content字段是通過base64加密的數據，確保openid對應的用
戶已經掃描且綁定了該device id，確保該公衆號帳號擁有且受權了該device id，
Q：爲何第三方收到的base64解碼後的數據和設備發送的原始數據不同？
A：base64算法有不少變種：被編碼字符長度不是3的倍數的時候，則都用0代替，對
應的輸出字符爲=，固然，這個輸出字符是能夠定製爲其餘符號，公衆平臺平臺採用的是
原始默認的=做爲補充字符
此外，不少framework在http的包體中將英文=字符識別爲特殊字符，所以用到相關f
ramework的第三方開發人員須要作好兼容處理
Q：發現文檔中示例，最終返回失敗
A：目前連調發現api調用失敗的主要緣由有：
一、請求的url中帶有空格，致使取ulr參數出錯
二、post請求包的json串中有多餘空格、有中文標點（引號，冒號等），json的字段
順序和文檔描述不符
2.4.特殊邏輯
Q：對於綁定、解綁定、設備通訊三類請求，第三方是否能夠不回給公衆平臺回包？
A：這三類請求，都須要第三方回包，由於公衆平臺後臺給第三方發包後，會超時等
待第三方的回包，若是第三方不回包，會嚴重影響公衆平臺後臺性能，一經發現，咱們將
會踢掉該公衆帳號。
對於「綁定」和「解綁定」請求，第三方能夠回一個空包，即：post響應只包含http
包頭，不包含數據，對於空數據，公衆平臺後臺會直接屏蔽掉該消息，而不會下發給微信
客戶端，也到達不了設備。對於「設備通訊」請求，是須要回復非空的符合消息協議的htt方倍工做室
第 29 頁 共 29頁
p的post響應
Q：我有兩個公衆帳號，能否用一個公衆帳號來給另外一個帳號的device 
id綁定的用戶發消息？
A：不行！很多第三方用戶混淆了兩個帳號，致使消息沒法送達設備，用戶綁定失敗
等錯誤，所以出現錯誤，請先確保<公衆帳號，device id，open 
id>之間的關聯是徹底正確的，而後再進行下一步排查