微信公众平台二次开发技术文档
本文档基于腾讯公司微信二次开发的相关规范,对微信二次开发的流程、步骤做了相关的说明,方便程序设计和开发人员快速掌握微信公众平台开发技术,便于提高代码的编写效率以及减少出现错误概率。
本文档适合:系统设计人员、程序开发人员。
登录微信公众平台官网后,在公众平台后台管理页面 - 开发者中心页,点击“修改配置”按钮,填写服务器地址(URL)、Token和EncodingAESKey,其中URL是开发者用来接收微信消息和事件的接口URL。Token可由开发者可以任意填写,用作生成签名(该Token会和接口URL中包含的Token进行比对,从而验证安全性)。EncodingAESKey由开发者手动填写或随机生成,将用作消息体加解密密钥。
开发者提交信息后,微信服务器将发送GET请求到填写的服务器地址URL上,GET请求携带四个参数:
参数 |
描述 |
signature |
微信加密签名,signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。 |
timestamp |
时间戳 |
nonce |
随机数 |
echostr |
随机字符串 |
开发者通过检验signature对请求进行校验(下面有校验方式)。若确认此次GET请求来自微信服务器,请原样返回echostr参数内容,则接入生效,成为开发者成功,否则接入失败。
加密/校验流程如下:
1. 将token、timestamp、nonce三个参数进行字典序排序
2. 将三个参数字符串拼接成一个字符串进行sha1加密
3. 开发者获得加密后的字符串可与signature对比,标识该请求来源于微信
验证URL有效性成功后即接入生效,成为开发者。如果公众号类型为服务号(订阅号只能使用普通消息接口),可以在公众平台网站中申请认证,认证成功的服务号将获得众多接口权限,以满足开发者需求。
此后用户每次向公众号发送消息、或者产生自定义菜单点击事件时,开发者填写的服务器配置URL将得到微信服务器推送过来的消息和事件,然后开发者可以依据自身业务逻辑进行响应,例如回复消息等。
用户向公众号发送消息时,公众号方收到的消息发送者是一个OpenID,是使用用户微信号加密后的结果,每个用户对每个公众号有一个唯一的OpenID。
access_token是公众号的全局唯一票据,公众号调用各接口时都需使用access_token。开发者需要进行妥善保存。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时,需定时刷新,重复获取将导致上次获取的access_token失效。
公众平台的API调用所需的access_token的使用及生成方式说明:
1、为了保密appsecrect,第三方需要一个access_token获取和刷新的中控服务器。而其他业务逻辑服务器所使用的access_token均来自于该中控服务器,不应该各自去刷新,否则会造成access_token覆盖而影响业务;
2、目前access_token的有效期通过返回的expire_in来传达,目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新access_token。在刷新过程中,中控服务器对外输出的依然是老access_token,此时公众平台后台会保证在刷新短时间内,新老access_token都可用,这保证了第三方业务的平滑过渡;
3、access_token的有效时间可能会在未来有调整,所以中控服务器不仅需要内部定时主动刷新,还需要提供被动刷新access_token的接口,这样便于业务服务器在API调用获知access_token已超时的情况下,可以触发access_token的刷新流程。
如果第三方不使用中控服务器,而是选择各个业务逻辑点各自去刷新access_token,那么就可能会产生冲突,导致服务不稳定。
公众号可以使用AppID和AppSecret调用本接口来获取access_token。AppID和AppSecret可在微信公众平台官网-开发者中心页中获得(需要已经成为开发者,且帐号没有异常状态)。注意调用所有微信接口时均需使用https协议。
接口调用请求说明
http请求方式: GET
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
参数说明
参数 |
是否必须 |
说明 |
grant_type |
是 |
获取access_token填写client_credential |
appid |
是 |
第三方用户唯一凭证 |
secret |
是 |
第三方用户唯一凭证密钥,即appsecret |
返回说明
正常情况下,微信会返回下述JSON数据包给公众号:
{"access_token":"ACCESS_TOKEN","expires_in":7200}
参数 |
说明 |
access_token |
获取到的凭证 |
expires_in |
凭证有效时间,单位:秒 |
错误时微信会返回错误码等信息,JSON数据包示例如下(该示例为AppID无效错误):
{"errcode":40013,"errmsg":"invalid appid"}
请注意:
1、自定义菜单最多包括3个一级菜单,每个一级菜单最多包含5个二级菜单。
2、一级菜单最多4个汉字,二级菜单最多7个汉字,多出来的部分将会以“...”代替。
3、创建自定义菜单后,菜单的刷新策略是,在用户进入公众号会话页或公众号profile页时,如果发现上一次拉取菜单的请求在5分钟以前,就会拉取一下菜单,如果菜单有更新,就会刷新客户端的菜单。测试时可以尝试取消关注公众账号后再次关注,则可以看到创建后的效果。
接口调用请求说明
http请求方式:POST(请使用https协议) https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
click和view的请求示例
{
"button":[
{
"type":"click",
"name":"今日歌曲",
"key":"V1001_TODAY_MUSIC"
},
{
"name":"菜单",
"sub_button":[
{
"type":"view",
"name":"搜索",
"url":"http://www.soso.com/"
},
{
"type":"view",
"name":"视频",
"url":"http://v.qq.com/"
},
{
"type":"click",
"name":"赞一下我们",
"key":"V1001_GOOD"
}]
}]
}
其他新增按钮类型的请求示例
{
"button": [
{
"name": "扫码",
"sub_button": [
{
"type": "scancode_waitmsg",
"name": "扫码带提示",
"key": "rselfmenu_0_0",
"sub_button": [ ]
},
{
"type": "scancode_push",
"name": "扫码推事件",
"key": "rselfmenu_0_1",
"sub_button": [ ]
}
]
},
{
"name": "发图",
"sub_button": [
{
"type": "pic_sysphoto",
"name": "系统拍照发图",
"key": "rselfmenu_1_0",
"sub_button": [ ]
},
{
"type": "pic_photo_or_album",
"name": "拍照或者相册发图",
"key": "rselfmenu_1_1",
"sub_button": [ ]
},
{
"type": "pic_weixin",
"name": "微信相册发图",
"key": "rselfmenu_1_2",
"sub_button": [ ]
}
]
},
{
"name": "发送位置",
"type": "location_select",
"key": "rselfmenu_2_0"
},
{
"type": "media_id",
"name": "图片",
"media_id": "MEDIA_ID1"
},
{
"type": "view_limited",
"name": "图文消息",
"media_id": "MEDIA_ID2"
}
]
}
参数说明
参数 |
是否必须 |
说明 |
button |
是 |
一级菜单数组,个数应为1~3个 |
sub_button |
否 |
二级菜单数组,个数应为1~5个 |
type |
是 |
菜单的响应动作类型 |
name |
是 |
菜单标题,不超过16个字节,子菜单不超过40个字节 |
key |
click等点击类型必须 |
菜单KEY值,用于消息接口推送,不超过128字节 |
url |
view类型必须 |
网页链接,用户点击菜单可打开链接,不超过1024字节 |
media_id |
media_id类型和view_limited类型必须 |
调用新增永久素材接口返回的合法media_id |
返回结果
正确时的返回JSON数据包如下:
{"errcode":0,"errmsg":"ok"}
错误时的返回JSON数据包如下(示例为无效菜单名长度):
{"errcode":40018,"errmsg":"invalid button name size"}
使用接口创建自定义菜单后,开发者还可使用接口查询自定义菜单的结构。另外请注意,在设置了个性化菜单后,使用本自定义菜单查询接口可以获取默认菜单和全部个性化菜单信息。
请求说明
http请求方式:GET
https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN
返回说明(无个性化菜单时)
对应创建接口,正确的Json返回结果:
{"menu":{"button":[{"type":"click","name":"今日歌曲","key":"V1001_TODAY_MUSIC","sub_button":[]},{"type":"click","name":"歌手简介","key":"V1001_TODAY_SINGER","sub_button":[]},{"name":"菜单","sub_button":[{"type":"view","name":"搜索","url":"http://www.soso.com/","sub_button":[]},{"type":"view","name":"视频","url":"http://v.qq.com/","sub_button":[]},{"type":"click","name":"赞一下我们","key":"V1001_GOOD","sub_button":[]}]}]}}
返回说明(有个性化菜单时)
{
"menu": {
"button": [
{
"type": "click",
"name": "今日歌曲",
"key": "V1001_TODAY_MUSIC",
"sub_button": [ ]
}
],
"menuid": 208396938
},
"conditionalmenu": [
{
"button": [
{
"type": "click",
"name": "今日歌曲",
"key": "V1001_TODAY_MUSIC",
"sub_button": [ ]
},
{
"name": "菜单",
"sub_button": [
{
"type": "view",
"name": "搜索",
"url": "http://www.soso.com/",
"sub_button": [ ]
},
{
"type": "view",
"name": "视频",
"url": "http://v.qq.com/",
"sub_button": [ ]
},
{
"type": "click",
"name": "赞一下我们",
"key": "V1001_GOOD",
"sub_button": [ ]
}
]
}
],
"matchrule": {
"group_id": 2,
"sex": 1,
"country": "中国",
"province": "广东",
"city": "广州",
"client_platform_type": 2
},
"menuid": 208396993
}
]
}
注:menu为默认菜单,conditionalmenu为个性化菜单列表。字段说明请见个性化菜单接口页的说明。
使用接口创建自定义菜单后,开发者还可使用接口删除当前使用的自定义菜单。另请注意,在个性化菜单时,调用此接口会删除默认菜单及全部个性化菜单。
请求说明
http请求方式:GET
https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN
返回说明
对应创建接口,正确的Json返回结果:
{"errcode":0,"errmsg":"ok"}
当普通微信用户向公众账号发消息时,微信服务器将POST消息的XML数据包到开发者填写的URL上。
1348831860
1234567890123456
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
text |
Content |
文本消息内容 |
MsgId |
消息id,64位整型 |
1348831860
1234567890123456
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
image |
PicUrl |
图片链接 |
MediaId |
图片消息媒体id,可以调用多媒体文件下载接口拉取数据。 |
MsgId |
消息id,64位整型 |
1357290913
1234567890123456
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
语音为voice |
MediaId |
语音消息媒体id,可以调用多媒体文件下载接口拉取数据。 |
Format |
语音格式,如amr,speex等 |
MsgID |
消息id,64位整型 |
使用网页调试工具调试该接口
请注意,开通语音识别后,用户每次发送语音给公众号时,微信会在推送的语音消息XML数据包中,增加一个Recongnition字段(注:由于客户端缓存,开发者开启或者关闭语音识别功能,对新关注者立刻生效,对已关注用户需要24小时生效。开发者可以重新关注此帐号进行测试)。开启语音识别后的语音XML数据包如下:
1357290913
1234567890123456
多出的字段中,Format为语音格式,一般为amr,Recognition为语音识别结果,使用UTF8编码。
1357290913
1234567890123456
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
视频为video |
MediaId |
视频消息媒体id,可以调用多媒体文件下载接口拉取数据。 |
ThumbMediaId |
视频消息缩略图的媒体id,可以调用多媒体文件下载接口拉取数据。 |
MsgId |
消息id,64位整型 |
使用网页调试工具调试该接口
1357290913
1234567890123456
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
小视频为shortvideo |
MediaId |
视频消息媒体id,可以调用多媒体文件下载接口拉取数据。 |
ThumbMediaId |
视频消息缩略图的媒体id,可以调用多媒体文件下载接口拉取数据。 |
MsgId |
消息id,64位整型 |
使用网页调试工具调试该接口
1351776360
23.134521
113.358803
20
1234567890123456
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
location |
Location_X |
地理位置维度 |
Location_Y |
地理位置经度 |
Scale |
地图缩放大小 |
Label |
地理位置信息 |
MsgId |
消息id,64位整型 |
使用网页调试工具调试该接口
1351776360
1234567890123456
参数 |
描述 |
ToUserName |
接收方微信号 |
FromUserName |
发送方微信号,若为普通用户,则是一个OpenID |
CreateTime |
消息创建时间 |
MsgType |
消息类型,link |
Title |
消息标题 |
Description |
消息描述 |
Url |
消息链接 |
MsgId |
消息id,64位整型 |
在微信用户和公众号产生交互的过程中,用户的某些操作会使得微信服务器通过事件推送的形式通知到开发者在开发者中心处设置的服务器地址,从而开发者可以获取到该信息。其中,某些事件推送在发生后,是允许开发者回复用户的,某些则不允许,详细说明请见本页末尾的微信推送消息与事件说明。
用户在关注与取消关注公众号时,微信会把这个事件推送到开发者填写的URL。方便开发者给用户下发欢迎消息或者做帐号的解绑。
微信服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次
关于重试的消息排重,推荐使用FromUserName + CreateTime 排重。
假如服务器无法保证在五秒内处理并回复,可以直接回复空串,微信服务器不会对此作任何处理,并且不会发起重试。
推送XML数据包示例:
123456789
参数说明:
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
消息类型,event |
Event |
事件类型,subscribe(订阅)、unsubscribe(取消订阅) |
使用网页调试工具调试该接口
用户扫描带场景值二维码时,可能推送以下两种事件:
1. 用户未关注时,进行关注后的事件推送
推送XML数据包示例:
123456789
参数说明:
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
消息类型,event |
Event |
事件类型,subscribe |
EventKey |
事件KEY值,qrscene_为前缀,后面为二维码的参数值 |
Ticket |
二维码的ticket,可用来换取二维码图片 |
2. 用户已关注时的事件推送
推送XML数据包示例:
123456789
参数说明:
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
消息类型,event |
Event |
事件类型,SCAN |
EventKey |
事件KEY值,是一个32位无符号整数,即创建二维码时的二维码scene_id |
Ticket |
二维码的ticket,可用来换取二维码图片 |
使用网页调试工具调试该接口
用户同意上报地理位置后,每次进入公众号会话时,都会在进入时上报地理位置,或在进入会话后每5秒上报一次地理位置,公众号可以在公众平台网站中修改以上设置。上报地理位置时,微信会将上报地理位置事件推送到开发者填写的URL。
推送XML数据包示例:
123456789
23.137466
113.352425
119.385040
参数说明:
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
消息类型,event |
Event |
事件类型,LOCATION |
Latitude |
地理位置纬度 |
Longitude |
地理位置经度 |
Precision |
地理位置精度 |
使用网页调试工具调试该接口
用户点击自定义菜单后,微信会把点击事件推送给开发者,请注意,点击菜单弹出子菜单,不会产生上报。
推送XML数据包示例:
123456789
参数说明:
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
消息类型,event |
Event |
事件类型,CLICK |
EventKey |
事件KEY值,与自定义菜单接口中KEY值对应 |
推送XML数据包示例:
123456789
参数说明:
参数 |
描述 |
ToUserName |
开发者微信号 |
FromUserName |
发送方帐号(一个OpenID) |
CreateTime |
消息创建时间 (整型) |
MsgType |
消息类型,event |
Event |
事件类型,VIEW |
EventKey |
事件KEY值,设置的跳转URL |
使用网页调试工具调试该接口
当用户发送消息给公众号时(或某些特定的用户操作引发的事件推送时),会产生一个POST请求,开发者可以在响应包(Get)中返回特定XML结构,来对该消息进行响应(现支持回复文本、图片、图文、语音、视频、音乐)。严格来说,发送被动响应消息其实并不是一种接口,而是对微信服务器发过来消息的一次回复。 |
12345678
参数 |
是否必须 |
描述 |
ToUserName |
是 |
接收方帐号(收到的OpenID) |
FromUserName |
是 |
开发者微信号 |
CreateTime |
是 |
消息创建时间 (整型) |
MsgType |
是 |
text |
Content |
是 |
回复的消息内容(换行:在content中能够换行,微信客户端就支持换行显示) |
12345678
参数 |
是否必须 |
说明 |
ToUserName |
是 |
接收方帐号(收到的OpenID) |
FromUserName |
是 |
开发者微信号 |
CreateTime |
是 |
消息创建时间 (整型) |
MsgType |
是 |
image |
MediaId |
是 |
通过素材管理接口上传多媒体文件,得到的id。 |
12345678
参数 |
是否必须 |
说明 |
ToUserName |
是 |
接收方帐号(收到的OpenID) |
FromUserName |
是 |
开发者微信号 |
CreateTime |
是 |
消息创建时间戳 (整型) |
MsgType |
是 |
语音,voice |
MediaId |
是 |
通过素材管理接口上传多媒体文件,得到的id |
12345678
参数 |
是否必须 |
说明 |
ToUserName |
是 |
接收方帐号(收到的OpenID) |
FromUserName |
是 |
开发者微信号 |
CreateTime |
是 |
消息创建时间 (整型) |
MsgType |
是 |
video |
MediaId |
是 |
通过素材管理接口上传多媒体文件,得到的id |
Title |
否 |
视频消息的标题 |
Description |
否 |
视频消息的描述 |
12345678
参数 |
是否必须 |
说明 |
ToUserName |
是 |
接收方帐号(收到的OpenID) |
FromUserName |
是 |
开发者微信号 |
CreateTime |
是 |
消息创建时间 (整型) |
MsgType |
是 |
music |
Title |
否 |
音乐标题 |
Description |
否 |
音乐描述 |
MusicURL |
否 |
音乐链接 |
HQMusicUrl |
否 |
高质量音乐链接,WIFI环境优先使用该链接播放音乐 |
ThumbMediaId |
否 |
缩略图的媒体id,通过素材管理接口上传多媒体文件,得到的id |
12345678
2
参数 |
是否必须 |
说明 |
ToUserName |
是 |
接收方帐号(收到的OpenID) |
FromUserName |
是 |
开发者微信号 |
CreateTime |
是 |
消息创建时间 (整型) |
MsgType |
是 |
news |
ArticleCount |
是 |
图文消息个数,限制为10条以内 |
Articles |
是 |
多条图文消息信息,默认第一个item为大图,注意,如果图文数超过10,则将会无响应 |
Title |
否 |
图文消息标题 |
Description |
否 |
图文消息描述 |
PicUrl |
否 |
图片链接,支持JPG、PNG格式,较好的效果为大图360*200,小图200*200 |
Url |
否 |
点击图文消息跳转链接 |
如果用户在微信客户端中访问第三方网页,公众号可以通过微信网页授权机制,来获取用户基本信息,进而实现业务逻辑。
关于网页授权回调域名的说明
1、在微信公众号请求用户网页授权之前,开发者需要先到公众平台官网中的开发者中心页配置授权回调域名。请注意,这里填写的是域名(是一个字符串),而不是URL,因此请勿加 http:// 等协议头;
2、授权回调域名配置规范为全域名,比如需要网页授权的域名为:www.qq.com,配置以后此域名下面的页面http://www.qq.com/music.html 、 http://www.qq.com/login.html 都可以进行OAuth2.0鉴权。但http://pay.qq.com 、 http://music.qq.com 、 http://qq.com无法进行OAuth2.0鉴权
3、如果公众号登录授权给了第三方开发者来进行管理,则不必做任何设置,由第三方代替公众号实现网页授权即可
关于网页授权的两种scope的区别说明
1、以snsapi_base为scope发起的网页授权,是用来获取进入页面的用户的openid的,并且是静默授权并自动跳转到回调页的。用户感知的就是直接进入了回调页(往往是业务页面)
2、以snsapi_userinfo为scope发起的网页授权,是用来获取用户的基本信息的。但这种授权需要用户手动同意,并且由于用户同意过,所以无须关注,就可在授权后获取该用户的基本信息。
3、用户管理类接口中的“获取用户基本信息接口”,是在用户和公众号产生消息交互或关注后事件推送后,才能根据用户OpenID来获取用户基本信息。这个接口,包括其他微信接口,都是需要该用户(即openid)关注了公众号后,才能调用成功的。
关于网页授权access_token和普通access_token的区别
1、微信网页授权是通过OAuth2.0机制实现的,在用户授权给公众号后,公众号可以获取到一个网页授权特有的接口调用凭证(网页授权access_token),通过网页授权access_token可以进行授权后接口调用,如获取用户基本信息;
2、其他微信接口,需要通过基础支持中的“获取access_token”接口来获取到的普通access_token调用。
在确保微信公众账号拥有授权作用域(scope参数)的权限的前提下(服务号获得高级接口后,默认拥有scope参数中的snsapi_base和snsapi_userinfo),引导关注者打开如下页面:
https://open.weixin.qq.com/connect/oauth2/authorize?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
若提示“该链接无法访问”,请检查参数是否填写错误,是否拥有scope参数对应的授权作用域权限。
尤其注意:由于授权操作安全等级较高,所以在发起授权请求时,微信会对授权链接做正则强匹配校验,如果链接的参数顺序不对,授权页面将无法正常访问
参考链接(请在微信客户端中打开此链接体验)
Scope为snsapi_base
https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx520c15f417810387&redirect_uri=https%3A%2F%2Fchong.qq.com%2Fphp%2Findex.php%3Fd%3D%26c%3DwxAdapter%26m%3DmobileDeal%26showwxpaytitle%3D1%26vb2ctag%3D4_2030_5_1194_60&response_type=code&scope=snsapi_base&state=123#wechat_redirect
Scope为snsapi_userinfo
https://open.weixin.qq.com/connect/oauth2/authorize?appid=wxf0e81c3bee622d60&redirect_uri=http%3A%2F%2Fnba.bluewebgame.com%2Foauth_response.php&response_type=code&scope=snsapi_userinfo&state=STATE#wechat_redirect
尤其注意:跳转回调redirect_uri,应当使用https链接来确保授权code的安全性。
参数说明
参数 |
是否必须 |
说明 |
appid |
是 |
公众号的唯一标识 |
redirect_uri |
是 |
授权后重定向的回调链接地址,请使用urlencode对链接进行处理 |
response_type |
是 |
返回类型,请填写code |
scope |
是 |
应用授权作用域,snsapi_base (不弹出授权页面,直接跳转,只能获取用户openid),snsapi_userinfo (弹出授权页面,可通过openid拿到昵称、性别、所在地。并且,即使在未关注的情况下,只要用户授权,也能获取其信息) |
state |
否 |
重定向后会带上state参数,开发者可以填写a-zA-Z0-9的参数值,最多128字节 |
#wechat_redirect |
是 |
无论直接打开还是做页面302重定向时候,必须带此参数 |
下图为scope等于snsapi_userinfo时的授权页面:
用户同意授权后
如果用户同意授权,页面将跳转至 redirect_uri/?code=CODE&state=STATE。若用户禁止授权,则重定向后不会带上code参数,仅会带上state参数redirect_uri?state=STATE
code说明 :
code作为换取access_token的票据,每次用户授权带上的code将不一样,code只能使用一次,5分钟未被使用自动过期。
首先请注意,这里通过code换取的是一个特殊的网页授权access_token,与基础支持中的access_token(该access_token用于调用其他接口)不同。公众号可通过下述接口来获取网页授权access_token。如果网页授权的作用域为snsapi_base,则本步骤中获取到网页授权access_token的同时,也获取到了openid,snsapi_base式的网页授权流程即到此为止。
尤其注意:由于公众号的secret和获取到的access_token安全级别都非常高,必须只保存在服务器,不允许传给客户端。后续刷新access_token、通过access_token获取用户信息等步骤,也必须从服务器发起。
请求方法
获取code后,请求以下链接获取access_token:
https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
参数说明
参数 |
是否必须 |
说明 |
appid |
是 |
公众号的唯一标识 |
secret |
是 |
公众号的appsecret |
code |
是 |
填写第一步获取的code参数 |
grant_type |
是 |
填写为authorization_code |
返回说明
正确时返回的JSON数据包如下:
{
"access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE"
}
参数 |
描述 |
access_token |
网页授权接口调用凭证,注意:此access_token与基础支持的access_token不同 |
expires_in |
access_token接口调用凭证超时时间,单位(秒) |
refresh_token |
用户刷新access_token |
openid |
用户唯一标识,请注意,在未关注公众号时,用户访问公众号的网页,也会产生一个用户和公众号唯一的OpenID |
scope |
用户授权的作用域,使用逗号(,)分隔 |
错误时微信会返回JSON数据包如下(示例为Code无效错误):
{"errcode":40029,"errmsg":"invalid code"}
全局返回码说明
由于access_token拥有较短的有效期,当access_token超时后,可以使用refresh_token进行刷新,refresh_token拥有较长的有效期(7天、30天、60天、90天),当refresh_token失效的后,需要用户重新授权。
请求方法
获取第二步的refresh_token后,请求以下链接获取access_token:
https://api.weixin.qq.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
参数 |
是否必须 |
说明 |
appid |
是 |
公众号的唯一标识 |
grant_type |
是 |
填写为refresh_token |
refresh_token |
是 |
填写通过access_token获取到的refresh_token参数 |
返回说明
正确时返回的JSON数据包如下:
{
"access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE"
}
参数 |
描述 |
access_token |
网页授权接口调用凭证,注意:此access_token与基础支持的access_token不同 |
expires_in |
access_token接口调用凭证超时时间,单位(秒) |
refresh_token |
用户刷新access_token |
openid |
用户唯一标识 |
scope |
用户授权的作用域,使用逗号(,)分隔 |
错误时微信会返回JSON数据包如下(示例为Code无效错误):
{"errcode":40029,"errmsg":"invalid code"}
全局返回码说明
如果网页授权作用域为snsapi_userinfo,则此时开发者可以通过access_token和openid拉取用户信息了。
请求方法
http:GET(请使用https协议)
https://api.weixin.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN
参数说明
参数 |
描述 |
access_token |
网页授权接口调用凭证,注意:此access_token与基础支持的access_token不同 |
openid |
用户的唯一标识 |
lang |
返回国家地区语言版本,zh_CN 简体,zh_TW 繁体,en 英语 |
返回说明
正确时返回的JSON数据包如下:
{
"openid":" OPENID",
" nickname": NICKNAME,
"sex":"1",
"province":"PROVINCE"
"city":"CITY",
"country":"COUNTRY",
"headimgurl": "http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46",
"privilege":[
"PRIVILEGE1"
"PRIVILEGE2"
],
"unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL"
}
参数 |
描述 |
openid |
用户的唯一标识 |
nickname |
用户昵称 |
sex |
用户的性别,值为1时是男性,值为2时是女性,值为0时是未知 |
province |
用户个人资料填写的省份 |
city |
普通用户个人资料填写的城市 |
country |
国家,如中国为CN |
headimgurl |
用户头像,最后一个数值代表正方形头像大小(有0、46、64、96、132数值可选,0代表640*640正方形头像),用户没有头像时该项为空。若用户更换头像,原有头像URL将失效。 |
privilege |
用户特权信息,json 数组,如微信沃卡用户为(chinaunicom) |
unionid |
只有在用户将公众号绑定到微信开放平台帐号后,才会出现该字段。详见:获取用户个人信息(UnionID机制) |
错误时微信会返回JSON数据包如下(示例为openid无效):
{"errcode":40003,"errmsg":" invalid openid "}