代公众号调用接口
概述
公众号在登录授权给第三方平台后,许多公众号业务的实现,需要依靠调用接口来实现。本页介绍了公众号第三方平台开发者在授权流程中需要用到的API,以及获得公众号的授权后,如何代替公众号调用接口。另外,微信服务器会将粉丝发给公众号的消息,以及微信服务器发给公众号的事件推送(如粉丝取消关注通知),发给开发者服务器(会发送到公众号消息与事件接收URL,详见申请资料说明页)上,开发者需要对这些消息在5秒内进行处理(如粉丝取消关注通知需要开发者返回success,详见http://mp.weixin.qq.com/wiki/14/89b871b5466b19b3efa4ada8e577d45e.html)。
1、代替授权公众号调用接口
第三方平台方在获得公众号授权后,可以使用authorizer_access_token(即授权公众号的令牌)作为凭证,代替公众号调用API,调用方式和公众号使用自身API的方式一样(只是需将调用API时提供的公众号自身access_token参数,替换为authorizer_access_token),具体详见 http://mp.weixin.qq.com/wiki
2、各类型公众号的接口权限说明
各类型的公众号具体拥有哪些API权限(每个授权的公众号,都可以通过下文将提到的接口获知公众号类型),请详见:http://mp.weixin.qq.com/wiki/7/2d301d4b757dedc333b9a9854b457b47.html
3、代替公众号使用微信JS-SDK
微信JS-SDK的使用方法,请参阅“接口说明”-“代公众号使用JS SDK说明”。
4、报警排查指引
在授权公众号以及第三方平台的开发和业务运营过程中遇到报警时,请参阅报警排查指引来解决问题:http://mp.weixin.qq.com/wiki/6/01405db0092f76bb96b12a9f954cd866.html
具体第三方平台API列表(不包括公众号自身已有的、第三方平台可代替公众号调用的接口)如下:
功能 | API名称 |
---|---|
1、获取第三方平台access_token | api_component_token |
2、获取预授权码 | api_create_preauthcode |
3、使用授权码换取公众号的授权信息 | api_query_auth |
4、获取(刷新)授权公众号的令牌 | api_authorizer_token |
5、获取授权方信息 | api_get_authorizer_info |
6、获取授权方的选项设置信息 | api_get_authorizer_option |
7、设置授权方的选项信息 | api_set_authorizer_option |
8、推送component_verify_ticket协议 | 每隔10分钟定时推送 |
9、推送取消授权通知 | 公众号取消授权时推送给开发者 |
特别注意,所有API调用需要验证调用者IP地址。只有在第三方平台申请时填写的白名单IP地址列表内的IP地址,才能合法调用,其他一律拒绝。
1、获取第三方平台access_token
由于第三方平台方可能托管了大量的公众号,第三方平台方安全问题造成的影响会更加严重,故API中增加了2项安全策略。
-
A)所有API调用端只能是第三方平台申请时填写的白名单客户端IP
-
B)获取第三方平台令牌(component_access_token),增加了component_verify_ticket参数。component_verify_ticket由公众平台每隔10分钟,持续推送给第三方平台方(在创建公众号第三方平台审核通过后,才会开始推送)。
该API用于获取第三方平台令牌(component_access_token)
接口调用请求说明
http请求方式: POST(请使用https协议)
https://api.weixin.qq.com/cgi-bin/component/api_component_token
POST数据示例:
{
"component_appid":"appid_value" ,
"component_appsecret": "appsecret_value",
"component_verify_ticket": "ticket_value"
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 第三方平台appid |
component_appsecret | 第三方平台appsecret |
component_verify_ticket | 微信后台推送的ticket,此ticket会定时推送,具体请见本页末尾的推送说明 |
返回结果示例
{
"component_access_token":"61W3mEpU66027wgNZ_MhGHNQDHnFATkDa9-2llqrMBjUwxRSNPbVsMmyD-yq8wZETSoE5NQgecigDrSHkPtIYA",
"expires_in":7200
}
结果参数说明
参数 | 说明 |
---|---|
component_access_token | 第三方平台access_token |
expires_in | 有效期 |
2、获取预授权码
该API用于获取预授权码。预授权码用于公众号授权时的第三方平台方安全验证。
接口调用请求说明
http请求方式: POST(请使用https协议)
https://api.weixin.qq.com/cgi-bin/component/api_create_preauthcode?component_access_token=xxx
POST数据示例:
{
"component_appid":"appid_value"
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 第三方平台方appid |
返回结果示例
{
"pre_auth_code":"Cx_Dk6qiBE0Dmx4EmlT3oRfArPvwSQ-oa3NL_fwHM7VI08r52wazoZX2Rhpz1dEw",
"expires_in":600
}
结果参数说明
参数 | 说明 |
---|---|
pre_auth_code | 预授权码 |
expires_in | 有效期,为20分钟 |
3、使用授权码换取公众号的授权信息
该API用于使用授权码换取授权公众号的授权信息,并换取authorizer_access_token和authorizer_refresh_token。 授权码的获取,需要在用户在第三方平台授权页中完成授权流程后,在回调URI中通过URL参数提供给第三方平台方。
接口调用请求说明
http请求方式: POST(请使用https协议)
https://api.weixin.qq.com/cgi-bin/component/api_query_auth?component_access_token=xxxx
POST数据示例:
{
"component_appid":"appid_value" ,
" authorization_code": "auth_code_value"
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 第三方平台appid |
authorization_code | 授权code,会在授权成功时返回给第三方平台,详见第三方平台授权流程说明 |
返回结果示例
{
"authorization_info": {
"authorizer_appid": "wxf8b4f85f3a794e77",
"authorizer_access_token": "QXjUqNqfYVH0yBE1iI_7vuN_9gQbpjfK7hYwJ3P7xOa88a89-Aga5x1NMYJyB8G2yKt1KCl0nPC3W9GJzw0Zzq_dBxc8pxIGUNi_bFes0qM",
"expires_in": 7200,
"authorizer_refresh_token": "dTo-YCXPL4llX-u1W1pPpnp8Hgm4wpJtlR6iV0doKdY",
"func_info": [
{
"funcscope_category": {
"id": 1
}
},
{
"funcscope_category": {
"id": 2
}
},
{
"funcscope_category": {
"id": 3
}
}
]
}
结果参数说明
参数 | 说明 |
---|---|
authorization_info | 授权信息 |
authorizer_appid | 授权方appid |
authorizer_access_token | 授权方令牌(在授权的公众号具备API权限时,才有此返回值) |
expires_in | 有效期(在授权的公众号具备API权限时,才有此返回值) |
authorizer_refresh_token | 刷新令牌(在授权的公众号具备API权限时,才有此返回值),刷新令牌主要用于公众号第三方平台获取和刷新已授权用户的access_token,只会在授权时刻提供,请妥善保存。 一旦丢失,只能让用户重新授权,才能再次拿到新的刷新令牌 |
func_info | 公众号授权给开发者的权限集列表(请注意,当出现用户已经将消息与菜单权限集授权给了某个第三方,再授权给另一个第三方时,由于该权限集是互斥的,后一个第三方的授权将去除此权限集,开发者可以在返回的func_info信息中验证这一点,避免信息遗漏),1到8分别代表: 消息与菜单权限集 用户管理权限集 帐号管理权限集 网页授权权限集 微信小店权限集 多客服权限集 业务通知权限集 微信卡券权限集 |
4、获取(刷新)授权公众号的令牌
该API用于在授权方令牌(authorizer_access_token)失效时,可用刷新令牌(authorizer_refresh_token)获取新的令牌。
接口调用请求说明
http请求方式: POST(请使用https协议)
https:// api.weixin.qq.com /cgi-bin/component/api_authorizer_token?component_access_token=xxxxx
POST数据示例:
{
"component_appid":"appid_value",
"authorizer_appid":"auth_appid_value",
"authorizer_refresh_token":"refresh_token_value",
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 第三方平台appid |
authorizer_appid | 授权方appid |
authorizer_refresh_token | 授权方的刷新令牌,刷新令牌主要用于公众号第三方平台获取和刷新已授权用户的access_token,只会在授权时刻提供,请妥善保存。 一旦丢失,只能让用户重新授权,才能再次拿到新的刷新令牌 |
返回结果示例
{
"authorizer_access_token": "aaUl5s6kAByLwgV0BhXNuIFFUqfrR8vTATsoSHukcIGqJgrc4KmMJ-JlKoC_-NKCLBvuU1cWPv4vDcLN8Z0pn5I45mpATruU0b51hzeT1f8",
"expires_in": 7200,
"authorizer_refresh_token": "BstnRqgTJBXb9N2aJq6L5hzfJwP406tpfahQeLNxX0w"
}
结果参数说明
参数 | 说明 |
---|---|
authorizer_access_token | 授权方令牌 |
expires_in | 有效期,为2小时 |
authorizer_refresh_token | 刷新令牌 |
5、获取授权方的账户信息
该API用于获取授权方的公众号基本信息,包括头像、昵称、帐号类型、认证类型、微信号、原始ID和二维码图片URL。
需要特别记录授权方的帐号类型,在消息及事件推送时,对于不具备客服接口的公众号,需要在5秒内立即响应;而若有客服接口,则可以选择暂时不响应,而选择后续通过客服接口来发送消息触达粉丝。
接口调用请求说明
http请求方式: POST(请使用https协议)
https://api.weixin.qq.com/cgi-bin/component/api_get_authorizer_info?component_access_token=xxxx
POST数据示例:
{
"component_appid":"appid_value" ,
"authorizer_appid": "auth_appid_value"
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 服务appid |
authorizer_appid | 授权方appid |
返回结果示例
{
"authorizer_info": {
"nick_name": "微信SDK Demo Special",
"head_img": "http://wx.qlogo.cn/mmopen/GPyw0pGicibl5Eda4GmSSbTguhjg9LZjumHmVjybjiaQXnE9XrXEts6ny9Uv4Fk6hOScWRDibq1fI0WOkSaAjaecNTict3n6EjJaC/0",
"service_type_info": { "id": 2 },
"verify_type_info": { "id": 0 },
"user_name":"gh_eb5e3a772040",
"alias":"paytest01"
},
"qrcode_url":"URL",
"authorization_info": {
"appid": "wxf8b4f85f3a794e77",
"func_info": [
{ "funcscope_category": { "id": 1 } },
{ "funcscope_category": { "id": 2 } },
{ "funcscope_category": { "id": 3 } }
]
}
}
结果参数说明
参数 | 说明 |
---|---|
authorizer_info | 授权方昵称 |
head_img | 授权方头像 |
service_type_info | 授权方公众号类型,0代表订阅号,1代表由历史老帐号升级后的订阅号,2代表服务号 |
verify_type_info | 授权方认证类型,-1代表未认证,0代表微信认证,1代表新浪微博认证,2代表腾讯微博认证,3代表已资质认证通过但还未通过名称认证,4代表已资质认证通过、还未通过名称认证,但通过了新浪微博认证,5代表已资质认证通过、还未通过名称认证,但通过了腾讯微博认证 |
user_name | 授权方公众号的原始ID |
alias | 授权方公众号所设置的微信号,可能为空 |
qrcode_url | 二维码图片的URL,开发者最好自行也进行保存 |
authorization_info | 授权信息 |
appid | 授权方appid |
func_info | 公众号授权给开发者的权限集列表(请注意,当出现用户已经将消息与菜单权限集授权给了某个第三方,再授权给另一个第三方时,由于该权限集是互斥的,后一个第三方的授权将去除此权限集,开发者可以在返回的func_info信息中验证这一点,避免信息遗漏),1到9分别代表: 消息与菜单权限集 用户管理权限集 帐号管理权限集 网页授权权限集 微信小店权限集 多客服权限集 业务通知权限集 微信卡券权限集 微信扫一扫权限集 |
6、获取授权方的选项设置信息
该API用于获取授权方的公众号的选项设置信息,如:地理位置上报,语音识别开关,多客服开关。注意,获取各项选项设置信息,需要有授权方的授权,详见权限集说明。
接口调用请求说明
http请求方式: POST(请使用https协议)https://api.weixin.qq.com/cgi-bin/component/ api_get_authorizer_option?component_access_token=xxxx
POST数据示例
{
"component_appid":"appid_value",
"authorizer_appid": " auth_appid_value ",
"option_name": "option_name_value"
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 第三方平台appid |
authorizer_appid | 授权公众号appid |
option_name | 选项名称 |
返回结果示例
{
"authorizer_appid":"wx7bc5ba58cabd00f4",
"option_name":"voice_recognize",
"option_value":"1"
}
结果参数说明
参数 | 说明 |
---|---|
authorizer_appid | 授权公众号appid |
option_name | 选项名称 |
option_value | 选项值 |
7、设置授权方的选项信息
该API用于设置授权方的公众号的选项信息,如:地理位置上报,语音识别开关,多客服开关。注意,设置各项选项设置信息,需要有授权方的授权,详见权限集说明。
接口调用请求说明
http请求方式: POST(请使用https协议)https://api.weixin.qq.com/cgi-bin/component/ api_set_authorizer_option?component_access_token=xxxx
POST数据示例
{
"component_appid":"appid_value",
"authorizer_appid": " auth_appid_value ",
"option_name": "option_name_value",
"option_value":"option_value_value"
}
请求参数说明
参数 | 说明 |
---|---|
component_appid | 第三方平台appid |
authorizer_appid | 授权公众号appid |
option_name | 选项名称 |
option_value | 设置的选项值 |
返回结果示例
{
"errcode":0,
"errmsg":"ok"
}
结果参数说明
参数 | 说明 |
---|---|
errcode | 错误码 |
errmsg | 错误信息 |
选项名和选项值表
option_name | option_value | 选项值说明 |
---|---|---|
location_report(地理位置上报选项) | 0 | 无上报 |
1 | 进入会话时上报 | |
2 | 每5s上报 | |
voice_recognize(语音识别开关选项) | 0 | 关闭语音识别 |
1 | 开启语音识别 | |
customer_service(客服开关选项) | 0 | 关闭多客服 |
1 | 开启多客服 |
8、推送component_verify_ticket协议
在公众号第三方平台创建审核通过后,微信服务器会向其“授权事件接收URL”每隔10分钟定时推送component_verify_ticket。第三方平台方在收到ticket推送后也需进行解密(详细请见【消息加解密接入指引】),接收到后必须直接返回字符串success。
POST数据示例
<xml>
<AppId> </AppId>
<CreateTime>1413192605 </CreateTime>
<InfoType> </InfoType>
<ComponentVerifyTicket> </ComponentVerifyTicket>
</xml>
字段说明
字段名称 | 字段描述 |
---|---|
Appid | 第三方平台appid |
CreateTime | 时间戳 |
InfoType | component_verify_ticket |
ComponentVerifyTicket | Ticket内容 |
9、推送取消授权通知
当授权方(即授权公众号)在公众平台的授权管理中,取消了对第三方平台方的授权托管后,微信服务器会向第三方平台方的授权事件接收URL(创建第三方平台时填写)推送取消授权通知。
POST数据示例
<xml>
<AppId></AppId>
<CreateTime>1413192760</CreateTime>
<InfoType> </InfoType>
<AuthorizerAppid></AuthorizerAppid>
</xml>
第三方平台方在收到取消授权通知后也需进行解密(详细请见【消息加解密接入指引】),接收到后之后只需直接返回字符串success。为了加强安全性,postdata中的xml将使用服务申请时的加解密key来进行加密,具体请见【公众号第三方平台的加密解密技术方案】
字段说明:
字段名称 | _(字段描述) |
---|---|
InfoType | none,代表该消息推送给服务 |
Appid | 第三方平台appid |
CreateTime | 时间戳 |
InfoType | unauthorized |
AuthorizerAppid | 取消授权的公众号 |