微信硬件设备接入接口协议

微信硬件设备接入接口协议
（公开使用）
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>之间的关联是完全正确的，然后再进行下一步排查