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

微信硬件設備接入接口協議
（公開使用）
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對應的二維碼
批量獲取二維碼響應協議描述
【注意】
1、第三方調用該服務，需要申請權限，權限的申請需要向公眾平台提供第三方的app
id
2、建議deviceid為英文字母、下划線、數字三類字符的串或者組合，不帶其他標點
符號，以免json串解析失敗
3、二維碼的生成有可能失敗，因此請求的devcie num和響應的devcie
num不一定相等；如果不相等，第三方需要核對下請求中哪些device
id沒有生成成功
4、響應中的ticket為二維碼的生成串，第三方需要用這些串來生成二維碼（點陣圖）
，為了提高二維碼的掃碼成功率，我們建議第三方：使用qrencode庫，QR碼版
本5，糾錯等級為Q級，容錯率不低於20%
5、返回的ticket字符串，會帶有json的敏感字符，因此，公眾平台對於敏感字符做了
轉義（如：/字符會被轉義成\/），第三方需要將這些敏感字符轉義回來
6、設備二維碼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對應）
設備授權響應協議描述
上表中參數描述為服務請求成功時的響應描述
【注意】
1、第三方調用該服務，需要申請權限，權限的申請需要向公眾平台提供第三方的app
id
2、建議id字段為英文字母、下划線、數字三類字符的串或者組合，不帶其他標點符
號，以免json串解析失敗
3、connec_protocol為設備連接的協議類型，目前有四種連接方式（見字段說明）
，可以支持四種連接方式的任意組合，並且可以設置客戶端優先選擇的連接方式
，客戶端會優先選擇該連接方式進行連接，若制定的優先協議無法連接成功，客
戶端回嘗試指定的其他協議方式連接；其他類型可以后續再添加，請第三方同學
確保值有效
4、conn_strategy連接策略，按位進行定義取值（第2bit不能置位；所有bit均不置位
也不支持，即取值為
0），譬如手環類產品，可能需要及時同步數據，可以填5，表示在公眾號對話頁
面，不停的嘗試連接設備（取值1），並且處於非公眾號頁面時，微信有機會去連
接設備，保證數據能及時同步（取值4）
5、crypt_method目前支持取值為0和1，對於計算能力弱的設備可以設置為0（不進
行加密處理，此時auth_ver也需要為0），目前的加密方法只支持AES
6、auth_ver目前只支持取值為0或1，不同的取值會影響“設備---微信---方倍工作室
第 22 頁 共 29頁
后台”的auth過程的數據包的格式，具體的取值請參看“客戶端藍牙外設協議”
，並且，如果不需要加密，則crypt_method和auth_ver都需要為0，
7、對於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
8、op_type為請求操作類型，字段缺省值為0，即：設備授權，字段取值為1，則將
請求中的設備屬性更新已有的設備屬性（若設備不存在，則更新失敗）
9、授權接口的處理邏輯比較復雜，因此，約束公眾號分開發者：一次批量授權的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狀態響應協議描述
上表中參數描述為服務請求成功時的響應描述
【注意】
1、第三方調用該服務，需要申請權限，權限的申請需要向公眾平台提供第三方的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頁
【注意】
1、第三方調用該服務，需要申請權限，權限的申請需要向公眾平台提供第三方的app
id
2. Q&A
2.1.流程
Q：第三方進行設備相關功能的開發和調試，需要哪些步驟進行？
A：主要按照以下步驟進行：
1、需要先熟悉公眾平台已有功能
2、詳細閱讀本文檔的“第三方協議”相關章節
3、向公眾平台后台提交“設備功能”的API使用權限申請，否則無法使用相關API（
申請方法見“權限申請”章節）
4、向公眾平台提交device id的授權，否則devcie
id無法被用戶綁定（申請方法見“權限申請”章節）
5、確保第三方服務url可用，第三方服務url的修改：登錄公眾平---功能---高級功能-
--開發模式---URL---修改
6、獲取二維碼，開發、調試
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加密后的數據，因此：
1、對於設備給第三方發數據，數據流是：設備數據---微信---
公眾平台base64加密數據---
第三方雲；因此，第三方收到的數據是對設備原始數據進行base64加密的數據，
第三方需要base64解密，才能得到原始數據
2、對於第三方給設備發送響應，數據流是：第三方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調用失敗的主要原因有：
1、請求的url中帶有空格，導致取ulr參數出錯
2、post請求包的json串中有多余空格、有中文標點（引號，冒號等），json的字段
順序和文檔描述不符
2.4.特殊邏輯
Q：對於綁定、解綁定、設備通信三類請求，第三方是否可以不回給公眾平台回包？
A：這三類請求，都需要第三方回包，因為公眾平台后台給第三方發包后，會超時等
待第三方的回包，如果第三方不回包，會嚴重影響公眾平台后台性能，一經發現，我們將
會踢掉該公眾賬號。
對於“綁定”和“解綁定”請求，第三方可以回一個空包，即：post響應只包含http
包頭，不包含數據，對於空數據，公眾平台后台會直接屏蔽掉該消息，而不會下發給微信
客戶端，也到達不了設備。對於“設備通信”請求，是需要回復非空的符合消息協議的htt方倍工作室
第 29 頁 共 29頁
p的post響應
Q：我有兩個公眾賬號，可否用一個公眾賬號來給另一個賬號的device
id綁定的用戶發消息？
A：不行！不少第三方用戶混淆了兩個賬號，導致消息無法送達設備，用戶綁定失敗
等錯誤，因此出現錯誤，請先確保<公眾賬號，device id，open
id>之間的關聯是完全正確的，然后再進行下一步排查