# 生成带参数的二维码
接口应在服务器端调用,不可在前端(小程序、网页、APP等)直接调用,具体可参考接口调用指南
接口英文名:createQRCode
创建二维码ticket,用于生成带参数的二维码
目前有2种类型的二维码:
- 临时二维码,是有过期时间的,最长可以设置为在二维码生成后的30天(即2592000秒)后过期,但能够生成较多数量。临时二维码主要用于账号绑定等不要求二维码永久保存的业务场景。
- 永久二维码,是无过期时间的,但数量较少(目前为最多10万个)。永久二维码主要用于适用于账号绑定、用户来源统计等场景。
用户扫描带场景值二维码时,可能推送以下两种事件:
- 如果用户还未关注公众号,则用户可以关注公众号,关注后微信会将带场景值关注事件推送给开发者。
- 如果用户已经关注公众号,在用户扫描后会自动进入会话,微信也会将带场景值扫描事件推送给开发者。
# 1. 调用方式
# HTTPS 调用
POST https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=ACCESS_TOKEN
# 云调用
调用方法:officialAccount.qrcode.create
出入参和 HTTPS 调用相同,调用方式可查看 云调用 说明文档
# 第三方调用
本接口支持第三方平台代商家调用。
该接口所属的权限集 id 为:3
服务商获得其中之一权限集授权后,可通过使用 authorizer_access_token 代商家进行调用,具体可查看 第三方调用 说明文档。
# 2. 请求参数
# 查询参数 Query String parameters
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
access_token | string | 是 | 接口调用凭证,可使用 access_token、authorizer_access_token |
# 请求体 Request Payload
参数名 | 类型 | 必填 | 示例 | 说明 |
---|---|---|---|---|
expire_seconds | number | 否 | 604800 | 二维码有效时间(秒),最大2592000,仅临时二维码需要 |
action_name | string | 是 | QR_SCENE | 二维码类型:QR_SCENE(临时整型)/QR_STR_SCENE(临时字符串)/QR_LIMIT_SCENE(永久整型)/QR_LIMIT_STR_SCENE(永久字符串) |
action_info | object | 是 | - | 二维码详细信息 |
# Body.action_info Object Payload
二维码详细信息
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
scene | object | 否 | 场景信息 |
# Body.action_info.scene Object Payload
场景信息
参数名 | 类型 | 必填 | 示例 | 说明 |
---|---|---|---|---|
scene_id | number | 否 | 123 | 场景值ID,临时二维码时为32位非0整型,永久二维码时最大值为100000(目前参数只支持1--100000) |
scene_str | string | 否 | test | 场景值ID(字符串形式的ID),字符串类型,长度限制为1到64 |
# 3. 返回参数
# 返回体 Response Payload
参数名 | 类型 | 说明 |
---|---|---|
ticket | string | 获取的二维码ticket,凭借此ticket可以在有效时间内换取二维码。 |
expire_seconds | number | 该二维码有效时间,以秒为单位。 最大不超过2592000(即30天)。 |
url | string | 二维码图片解析后的地址,开发者可根据该地址自行生成需要的二维码图片 |
# 4. 注意事项
支持临时二维码和永久二维码两种类型:
- 临时二维码通过QR_SCENE/QR_STR_SCENE创建,需要设置expire_seconds
- 永久二维码通过QR_LIMIT_SCENE/QR_LIMIT_STR_SCENE创建
# 通过ticket换取二维码
获取二维码ticket后,开发者可用ticket换取二维码图片。请注意,本接口无须登录态即可调用。
GET https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET
提醒:TICKET记得进行UrlEncode
返回内容:ticket正确情况下,http 返回码是200,是一张图片,可以直接展示或者下载。
HTTP头(示例)如下:
Accept-Ranges:bytes
Cache-control:max-age=604800
Connection:keep-alive
Content-Length:28026
Content-Type:image/jpg
Date:Wed, 16 Oct 2013 06:37:10 GMT
Expires:Wed, 23 Oct 2013 14:37:10 +0800
Server:nginx/1.4.1
错误情况下(如ticket非法)返回HTTP错误码404。
# 5. 代码示例
请求示例
{
"expire_seconds": 604800,
"action_name": "QR_SCENE",
"action_info": {
"scene": {
"scene_id": 123
}
}
}
返回示例
{
"ticket": "gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGlu...",
"expire_seconds": 60,
"url": "http://weixin.qq.com/q/kZgfwMTm72WWPkovabbI"
}
# 6. 错误码
以下是本接口的错误码列表,其他错误码可参考 通用错误码
错误码 | 错误描述 | 解决方案 |
---|---|---|
-1 | system error | 系统繁忙,此时请开发者稍候再试 |
0 | ok | 成功 |
40001 | invalid credential access_token isinvalid or not latest | 获取 access_token 时 AppSecret 错误,或者 access_token 无效。请开发者认真比对 AppSecret 的正确性,或查看是否正在为恰当的公众号调用接口 |
40052 | invalid action name | action值有误 |
40053 | invalid action info please checkdocument |
# 7. 适用范围
本接口支持「服务号(仅认证)」账号类型调用。其他账号类型如无特殊说明,均不可调用。