投放卡券

更新日志

版本号	更新内容	更新时间
V1.1	1.新增卡券货架创建接口，支持开发者调用接口创建卡券货架进行卡券投放 2. 新增导入code接口，支持自定义code开发者通过导入code通过群发、客服等渠道 派发卡券	2015-8-12
V1.2	新增扫描二维码批量领取接口，用户扫描二维码可以同时领取多张卡券	2015-8-31

1 创建二维码接口

开发者可调用该接口生成一张卡券二维码供用户扫码后添加卡券到卡包。

自定义Code码的卡券调用接口时，POST数据中需指定code，非自定义code不需指定，指定openid同理。指定后的二维码只能被用户扫描领取一次。

获取二维码ticket后，开发者可用通过ticket换取二维码接口。

接口调用请求说明

HTTP请求方式: POST URL:https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

参数说明

参数	是否必须	说明
POST数据	是	JSON数据
access_token	是	调用接口凭证

POST数据

开发者可以设置扫描二维码领取单张卡券，此时POST数据为：

{ "action_name": "QR_CARD", "expire_seconds": 1800, "action_info": { "card": { "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc", "code": "198374613512", "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA", "is_unique_code": false , "outer_str":"12b" } } }

当开发者设置扫描二维码领取多张卡券，此时POST数据为：

{ "action_name": "QR_MULTIPLE_CARD", "action_info": { "multiple_card": { "card_list": [ { "card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo88", "code":"2392583481", "outer_str":"12b" }, { "card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo98", "code":"2392583482", "outer_str":"12b" } ] } } }

参数说明

参数名	必填	类型	示例值	描述
code	是	string(20)	110201201245	卡券Code码,use_custom_code字段为true的卡券必须填写，非自定义code和导入code模式的卡券不必填写。
card_id	否	string(32)	pFS7Fjg8kV1IdD z01r4SQwMkuCKc	卡券ID。
openid	否	string(32)	oXch-jkrxp42VQu8ld weCwDt97qo	指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，非指定openid不必填写。
expire_seconds	否	unsigned int	60	指定二维码的有效时间，范围是60 ~ 1800秒。不填默认为365天有效
is_unique_code	否	bool	false	指定下发二维码，生成的二维码随机分配一个code，领取后不可再次扫描。填写true或false。默认false，注意填写该字段时，卡券须通过审核且库存不为0。
outer_id	否	int	12	领取场景值，用于领取渠道的数据统计，默认值为0，字段类型为整型，长度限制为60位数字。用户领取卡券后触发的事件推送中会带上此自定义场景值。
outer_str	否	string(128)	13b	outer_id字段升级版本，字符串类型，用户首次领卡时，会通过领取事件推送给商户； 对于会员卡的二维码，用户每次扫码打开会员卡后点击任何url，会将该值拼入url中，方便开发者定位扫码来源

返回数据

{ "errcode": 0, "errmsg": "ok", "ticket": "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",//获取ticket后需调用换取二维码接口获取二维码图片，详情见字段说明。 "expire_seconds": 1800, "url": "http://weixin.qq.com/q/BHWya_zlfioH6fXeL16o ", "show_qrcode_url": " https://mp.weixin.qq.com/cgi-bin/showqrcode? ticket=gQH98DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0czVzRlSWpsamlyM2plWTNKVktvAAIE6SfgVQMEgDPhAQ%3D%3D" }

参数说明

参数名	描述
errcode	错误码
errmsg	错误信息
ticket	获取的二维码ticket，凭借此ticket调用通过ticket换取二维码接口可以在有效时间内换取二维码。
url	二维码图片解析后的地址，开发者可根据该地址自行生成需要的二维码图片
show_qrcode_url	二维码显示地址，点击后跳转二维码页面

注意事项：

1.自定义code的卡券，生成的二维码每次只能领取一次，若开发者想要使用自己的串码系统并且想要用微信的二维码

投放，须先将自定义code导入；

2.领取多张的二维码一次最多填入5个card_id，否则报错。

2 HTML5线上发券（JS-SDK接口）

微信 JS-SDK 仅支持在微信内置浏览器中使用,其他浏览器调用无效。

微信提供addCard接口供商户前端网页调用,用于将一张或多张卡券添加到用户卡包。详情见批量添加卡券接口。

3 通过卡券货架投放卡券

卡券货架简介

卡券货架支持开发者通过调用接口生成一个卡券领取H5页面，并获取页面链接，进行卡券投放动作。目前卡券货架仅支持非自定义code的卡券，自定义code的卡券需先调用导入code接口将code导入才能正常使用。

3.1 创建货架接口

接口说明

开发者需调用该接口创建货架链接，用于卡券投放。创建货架时需填写投放路径的场景字段。

接口调用请求说明

HTTP请求方式: POST URL:https://api.weixin.qq.com/card/landingpage/create?access_token=$TOKEN

请求参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
buffer	是	文件的数据流

POST数据

{ "banner":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7h icFN", "page_title": "惠城优惠大派送", "can_share": true, "scene": "SCENE_NEAR_BY", "card_list": [ { "card_id": "pXch-jnOlGtbuWwIO2NDftZeynRE", "thumb_url": "www.qq.com/a.jpg" }, { "card_id": "pXch-jnAN-ZBoRbiwgqBZ1RV60fI", "thumb_url": "www.qq.com/b.jpg" } ] }

参数说明

字段	说明	是否必填
banner	页面的banner图片链接，须调用，建议尺寸为640*300。	是
title	页面的title。	是
can_share	页面是否可以分享,填入true/false	是
scene	投放页面的场景值； SCENE_NEAR_BY 附近 SCENE_MENU 自定义菜单 SCENE_QRCODE 二维码 SCENE_ARTICLE 公众号文章 SCENE_H5 h5页面 SCENE_IVR 自动回复 SCENE_CARD_CUSTOM_CELL 卡券自定义cell	是
card_list	卡券列表，每个item有两个字段	是
card_id	所要在页面投放的card_id	是
thumb_url	缩略图url	是

返回数据说明

{ "errcode":0, "errmsg":"ok", "url":"www.test.url", "page_id":1 }

字段说明

字段	说明
errcode	错误码，0为正常。
errmsg	错误信息。
url	货架链接。
page_id	货架ID。货架的唯一标识。

4 群发卡券

请开发者特别注意，目前群发卡券接口仅支持投放非自定义Code码的卡券。自定义code码的商户若想使用该功能需调用导入code接口将自定义code先导入微信服务器。

4.1 导入自定义code(仅对自定义code商户)

接口简介

该模块只针对自定义code商户，非自定义code开发者请自动忽略。开发者可以将自定义code提前导入至微信服务器，以获得和非自定义code商户同样的投放能力，如分组群发、客服消息下发卡券等。

导入code后的卡券在投放时等同于非自定义code卡券

新创建卡券

如果开发者打算新创建一张支持导入code模式的卡券，不同于以往的创建方式，建议开发者采用以下流程创建预存code模式卡券，否则会报错。

步骤一：创建预存模式卡券，将库存quantity初始值设置为0，并填入get_custom_code_mode字段;

步骤二：待卡券通过审核后，调用导入code接口并核查code;

步骤三：调用修改库存接口，须令卡券库存小于或等于导入code的数目。(为了避免混乱建议设置为相等)

非新创建卡券

如果开发者已经有一张卡券，想把它改为预存code模式，建议开发者按照以下流程对卡券进行更新。

步骤一：调用导入code接口导入一定量的自定义code并核查code;

步骤二：调用更改卡券信息接口填入get_custom_code_mode字段;

步骤三：调用修改库存接口将卡券库存quantity设置为与导入code数目相等的数字。

4.1.1 填入/更新导入code必需字段

接口说明

自定义code的卡券仅支持API创建，创建时务必在base_info中加入以下字段(详情见接口文档CreateCard创建卡券接口)， 加入以下两个指定字段后，才可以调用code导入接口进行code导入

字段	示例	说明
base_info
get_custom_code_mode	GET_CUSTOM_CODE_MODE_DEPOSIT	填入该字段后，自定义code卡券方可进行导入code并投放的动作。
use_custom_code	true	将卡券设置为自定义code

创建卡券时JSON示例

{ "card": { "card_type": "GROUPON", "groupon": { "base_info": { ·········· "use_custom_code":true, "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT", }, "advanced_info": { ·········· }, "deal_detail": "示例" } } }

更新卡券时JSON示例

{ "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg", "groupon": { "base_info": { ········· "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT", ········· } } }

注意事项：

创建/更新填入get_custom_code_mode时，须检查库存数与已经导入code数目的关系，当导入code的数目小于库存数时，会报错。

4.1.2 导入code接口

在自定义code卡券成功创建并且通过审核后，必须将自定义code按照与发券方的约定数量调用导入code接口导入微信后台。

接口说明

开发者可调用该接口将自定义code导入微信卡券后台，由微信侧代理存储并下发code。

注： 1）单次调用接口传入code的数量上限为100个。

2）每一个 code 均不能为空串。

3）导入结束后系统会自动判断提供方设置库存与实际导入code的量是否一致。

4）导入失败支持重复导入，提示成功为止。

接口调用请求说明

HTTP请求方式: POST URL:http://api.weixin.qq.com/card/code/deposit?access_token=ACCESS_TOKEN

请求参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
buffer	是	文件的数据流

POST数据

{ "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA", "code": [ "11111", "22222", "33333", "44444", "55555" ] }

字段说明

字段	说明	是否必填
card_id	需要进行导入code的卡券ID。	是
code	需导入微信卡券后台的自定义code，上限为100个。	是

返回数据说明

{ "errcode":0, "errmsg":"ok" }

字段说明

字段	说明
errcode	错误码，0为正常；40109：code数量超过100个
errmsg	错误信息。
succ_code	成功个数
duplicate_code	重复导入的code会自动被过滤。
fail_code	失败个数。

4.1.3 查询导入code数目接口

接口说明

支持开发者调用该接口查询code导入微信后台成功的数目。

接口调用请求说明

HTTP请求方式: POST URL:http://api.weixin.qq.com/card/code/getdepositcount?access_token=ACCESS_TOKEN

请求参数说明

参数	是否必须	说明
access_token	是	调用接口凭证

POST数据

{ "card_id" : " pDF3iY0_dVjb_Pua96MMewA96qvA " }

字段说明

字段	说明	是否必填
card_id	进行导入code的卡券ID。	是

返回数据说明

{ "errcode":0, "errmsg":"ok"， "count":123 }

字段说明

字段	说明
errcode	错误码，0为正常。
errmsg	错误信息。
count	已经成功存入的code数目。

4.1.4 核查code接口

为了避免出现导入差错，强烈建议开发者在查询完code数目的时候核查code接口校验code导入微信后台的情况。

接口说明

支持开发者调用该接口查询code导入微信后台的情况。

接口调用请求说明

HTTP请求方式: POST URL:http://api.weixin.qq.com/card/code/checkcode?access_token=ACCESS_TOKEN

请求参数说明

参数	是否必须	说明
access_token	是	调用接口凭证

POST数据

{ "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA", "code": [ "11111", "22222", "33333", "44444", "55555" ] }

字段说明

字段	说明	是否必填
card_id	进行导入code的卡券ID。	是
code	已经微信卡券后台的自定义code，上限为100个。	是

返回数据说明

{ "errcode":0, "errmsg":"ok" "exist_code":["11111","22222","33333"], "not_exist_code":["44444","55555"] }

字段说明

字段	说明
errcode	错误码，0为正常；40109：code数量超过100个
errmsg	错误信息。
exist_code	已经成功存入的code。
not_exist_code	没有存入的code。

4.2 图文消息群发卡券

支持开发者调用该接口获取卡券嵌入图文消息的标准格式代码，将返回代码填入上传图文素材接口中content字段，即可获取嵌入卡券的图文消息素材。

特别注意：目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

接口调用请求说明

HTTP请求方式: POST URL:https://api.weixin.qq.com/card/mpnews/gethtml?access_token=TOKEN

参数说明

参数	是否必须	说明
POST数据	是	Json数据
access_token	是	调用接口凭证

POST数据

{ "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI" }

参数名	必填	类型	示例值	描述
card_id	否	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	卡券ID。

返回数据

{ "errcode":0, "errmsg":"ok", "content":"" }

参数名	描述
errcode	错误码
errmsg	错误信息
content	返回一段html代码，可以直接嵌入到图文消息的正文里。即可以把这段代码嵌入到上传图文消息素材接口中的content字段里。

4.3 根据分组群发卡券消息

支持调用该接口向指定分组的用户群发卡券消息。详情见根据分组进行群发接口

目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

4.4 根据OpenID列表群发卡券消息

支持根据OpenID群发原生卡券。订阅号不可用，服务号认证后具备接口权限。详情见根据OpenID列表群发接口

目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

4.5 客服消息下发卡券

支持开发者调用该接口下发卡券。订阅号不可用，服务号认证后可用。详情见客服接口-发消息

目前该接口仅支持填入非自定义code的卡券,自定义code的卡券需先进行code导入后调用。

4.6 预览接口

支持开发者调用该接口下发卡券。订阅号不可用，服务号认证后可用。详情见预览接口

5 投放渠道数据统计

为方便开发者统计各渠道的卡券投放数据，新增字段outer_str（原outer_id）。将不同设值的outer_str（原outer_id）填入card_ext的json结构中，当用户领取卡券时会将相应设值的outer_id带入领取事件中，推送至开发者服务器。

示例： 在二维码投放方式中设置outer_str为12b

{ "action_name": "QR_CARD", "action_info": { "card": { "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc", "code": "198374613512", "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA", "expire_seconds": "1800"， "is_unique_code": false , "outer_str" : "12b" } } }

领取事件XML文件

    123456789    1  12b 

6 设置测试白名单

接口说明

由于卡券有审核要求，为方便公众号调试，可以设置一些测试帐号，这些帐号可领取未通过审核的卡券，体验整个流程。

开发者注意事项

1.同时支持“openid”、“username”两种字段设置白名单，总数上限为10个。

2.设置测试白名单接口为全量设置，即测试名单发生变化时需调用该接口重新传入所有测试人员的ID.

3.白名单用户领取该卡券时将无视卡券失效状态，请开发者注意。

接口调用请求说明

HTTP请求方式: POST URL:https://api.weixin.qq.com/card/testwhitelist/set?access_token=TOKEN

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	Json数据

POST数据

{ "openid": [ "o1Pj9jmZvwSyyyyyyBa4aULW2mA", "o1Pj9jmZvxxxxxxxxxULW2mA" ], "username": [ "afdvvf", "abcd" ] }

参数说明

参数名	必填	类型	示例值	描述
openid	否	string(20)	o1Pj9jmZvwSyyyyyyBa4aULW2mA	测试的openid列表。
username	否	string（32）	eddy	测试的微信号列表。

返回说明

{ "errcode":0, "errmsg":"ok" }

参数名	描述
errcode	错误码，0为正常。
errmsg	错误信息。