更新日志

版本号	更新内容	更新时间
V1.1	1.限制共享券代金券类型标题传入，统一命名为xxx元代金券，xxx为减免金额字段； 2.礼品券更名为兑换券，限制标题传入，统一命名为：洗手液(商品名)+1(数量)+瓶（数量单位），对应gift_name,gift_num,和gift_unit字段。	2015-12-2
V1.2	1.新增朋友的券白名单接口，支持领取共享未通过审核的共享券，仅限白名单list内用户可见。 2.新增朋友的券测试沙箱机制，未在开放类目内的开发者可以通过沙箱测试号测试创建、领取共享券 3.新增接口充值库存、券点系列接口，开发者可以通过接口完成库存、券点的充值和管理。 4.支持接口创建有门槛朋友的券，目前支持“满减券”、“指定品类券”和“不与其他优惠共享”类型门槛。	2015-12-27
V1.3	1.根据开发者填入的不同门槛，卡券标题拼接方案变更； 2.支持开发者填入使用时段限制，比如：周一 10：00-20:59可用；周一至周五 10：00-20:59可用	2016-2-16
V1.4	新创建的朋友的券只能在生效前提前5天投放，否则不可领取	2016-4-12

朋友的券简介

“朋友共享的优惠券”（以下简称“朋友的券”），是基于微信优惠券推出的新功能，实现“一人领取多人共享”的快速社交传播和转化的效果。

领取并与朋友共享此券，券会自动展示在领取人及其朋友的优惠券列表中，领取人及其朋友均可使用此券。商户可选择赠送配置：当朋友的券被使用后,根据商户配置的赠送量,使用者将立即获赠一张朋友的券,继续与朋友共享此券。

朋友的券的优势

1、高曝光量：朋友的券被领取后，将自动展示在领取者及其朋友的微信优惠券里，曝光量得到大幅提升。

2、高转化率：一张优惠券，传统玩法下只曝光至一个用户，朋友的券新玩法下可以曝光至领取者及其朋友们；同样的预算成本，得到更大量的曝光，转化率、收益也会得到有效提升。

3、朋友推荐： 优惠经过领取者认可后才会被共享给朋友们，该朋友的券的价值有领取者的背书，更值得信赖；同时微信朋友间的相似喜好，可以进一步提高朋友的券的转化率。

4、裂变：朋友的券被用户或其朋友核销后，商家可以立即再次赠送优惠券供使用者领取共享，且赠券仍为朋友的券。这让商家的优惠在用户中得到持续的曝光。

开放对象

朋友的券将按照卡券商户的类目逐步开放，首批开放朋友的券功能的商户类目如下。后续将向更多类目商户逐步开放，请关注微信公众平台公告。

一级类目	二级内容
美食	粤菜、茶餐厅、川菜、湘菜、东北菜、西北菜、火锅、自助餐、小吃、快餐、日本料理、韩国料理、东南亚菜、西餐、面包甜点、咖啡厅、江浙菜、其它美食、外卖
休闲娱乐	展览展出、温泉洗浴、足疗按摩、运动健身、棋牌室、KTV、酒吧/俱乐部、艺术写真、宠物美容、美容美发、美甲
生活服务	快递、宠物医疗、物业管理、家政服务、养生养护
电影票	电影票
酒店	快捷酒店、度假村、星级酒店
购物	母婴用品、普通食品、鲜花礼品、家纺家装、钟表眼镜、日护用品、化妆品、运动户外、鞋类箱包、服饰、副食品门市、超市/便利店、购物中心/购物街、百货商场
生活服务	婚庆服务、加油站、汽车维修、汽车驾校
旅游	景点门票
购物	便利店、珠宝配饰、家居、建材五金/机械仪表、乐器、酒类、药房/药店、图书报刊杂志、数码家电
运输票务	机票、船票、车票

若开发者的公众号未在开放类目内，开发者可以申请沙箱测试号进行创建、领取、投放、核销等流程，沙箱测试号具有朋友的券创建权限，创建的卡券不会被审核通过，开发者可以通过设置接口白名单领取未审核通过的券，共享后仅白名单list内的好友可见。

特别说明

优惠券共享的玩法，将极大地提升优惠券的曝光量和使用率。优惠券使用后，会引入好友互动，增加社交趣味性。特别地，朋友共享的优惠券，需要满足以下要求
1、选择起用金额为0元的无门槛代金券或无门槛兑换券，或选择指定门槛类型的代金券或者兑换券，目前支持的门槛类型为：满减门槛（满xxx可用）、指定品类门槛（指定xxx可用/不可用）以及不与其他优惠共享门槛，详情请见选择朋友的券门槛；
2、需要设置图文介绍的优惠详情（advanced_info字段）；
3、可选择每核销使用1张优惠券，再送用户1张；
4、暂不支持商家自定义Code码；

开发者注意事项

1、登录【微信公众平台后台】，点击【卡券功能】或者调用开通券点账户接口开通朋友的券券点账户，目前商户后台该开通入口仅针对指定类目商户开放，如还没发现入口开发者可以先耐心等待，后续会逐步放开；
2、创建优惠券：其中先准备好LOGO、门店、色值等内容，然后使用创建接口，创建起用金额为0元的代金券，并填入图文介绍，设置每核销1张，再赠送用户1张，得到card_id。
3、调用兑换库存、充值券点系列接口为优惠券配置库存，为账号充值券点。
4、投放朋友的券：设置库存后，开发者可以取card_id通过生成二维码或者扫码打开的H5投放，同时也可以通过微信摇一摇或者微信WIFI渠道打开的H5投放卡券，用户扫码即可共享此券。
若卡券未通过审核，开发者可以通过设置白名单接口设置接口白名单领取未审核通过的优惠券并共享，共享后仅接口白名单内的好友可见。
5、核销朋友的券：共享的用户及其好友，可以看到此券，到店出示享受优惠，使用后再获得赠送的卡券继续和好友共享，此部分开发者须使用核销助手或开发核销工具帮助商户核销。
6、管理朋友的券：开发者在卡券投放发布后可对卡券信息进行修改或统计卡券数据。

创建朋友的券

朋友的券样式

朋友的券较之前的样式有较大改变，卡券背景色更加突出，强调券的整洁和美观的同时将商户元素更加有强调性地展示，同时支持图文介绍传入，给了商户更大的曝光空间。

接口调用说明

创建卡券是卡券开发的第一步，开发者需要传入优惠内容生成一个card_id，并在通过审核后进行投放、核销等动作。在进行卡券创建前，请开发者根据自身业务场景确定以下几点

选择合适的门槛类型

目前朋友的券支持无门槛类型以及指定门槛类型的代金券、兑换券，微信后台会根据商户填写的门槛类型自动拼接卡券的详情摘要字段和卡券标题字段，开发者可以根据需求选择合适的门槛类型组合，获得最佳的发券效果。

商户按照指定字段填写门槛有利于优惠券审核快速通过，若商户填写了非以下类型的门槛，优惠券将不会被审核通过。

同时，微信后台会根据卡券选择的门槛不同而设置不同的库存价格，目前定价标准为：

1）无门槛类型，保持0.2券点/张； 2）指定品类可用/不可用门槛，0.4券点/张； 3）满减/买xx可用门槛，0.6券点/张；

不同门槛类型的字段以及展现

微信后台会根据开发者填入不同的门槛字段决定券的样式和展现，下面以一张50元代金券和兑换蛋挞一个的兑换券说明不同门槛带来的 展现逻辑变化。

门槛类型	适用券种	设置条件	详情摘要	标题
无门槛	代金券/兑换券	不填入任何门槛字段	无起用金额限制，全场通用，不限品类	50元代金券/苹果一个
指定品类可用/不可用门槛	代金券	填入accept_category（蛋挞）和reject_category（蛋糕）字段	适用于蛋挞，不适用于蛋糕	蛋挞减50元（填入的accept_catagory小于等于5个汉字）；50元代金券（填入的accept_catagory大于5个汉字）
满减门槛	代金券/兑换券	填入least_cost（500）字段	消费满500元可用	全场满500减50
买送门槛（限兑换券）	兑换券	填入object_use_for字段	购买蛋糕可用	买蛋糕送蛋挞
不与其他优惠共享门槛	代金券/兑换券	填入can_use_with_other_discount （false）字段	不与其他优惠共享	50元代金券

注意：

1.门槛字段用于拼接标题以及优惠说明，会影响商户卡券库存定价，请开发者务必按照要求填写，并提前预览生成的卡券；
2.门槛字段一旦设定即不可更改，请开发者慎重填写，及时预览。
3.当开发者同时填入满减字段和指定品类可用字段，则会拼接为"羽绒服（accept_catagory字段小于等于5个字）满500减50"，"满500减50"（accept_catagory字段大于5个字）

选择合适的code显示类型

目前卡券支持五种code显示类型：即二维码显示code、二维码不显示code、一维码显示code、仅code类型和无code类型（仅限支持券）。

对于不同的code类型，需要的核销方式也不同，对于显示二维码和一维码的卡券可以采用扫码核销的方式，对于只显示code类型的卡券适合用输码核销的方式，而无code类型的优惠券，则仅适合用于线上券使用，并且商户需开发自定义页面供用户核销卡券。

不同的code类型，开发者在创建券时须传入不同的code_type参数。

类别	字段名	适用核销方式
二维码/一维码显示code	CODE_TYPE_QRCODE/CODE_TYPE_BARCODE	适用于扫码/输码核销
二维码不显示code	CODE_TYPE_ONLY_QRCODE	仅适用于扫码核销
仅code类型	CODE_TYPE_TEXT	仅适用于输码核销
无code类型	CODE_TYPE_NONE	仅适用于线上核销，在券面不出现二维码展开入口

记录用户领券行为

记录用户领券行为有多种方式：

1. 用户领取卡券后会推送事件通知开发者，领取卡券事件中包含卡券ID、Code码、领取人OpenID。卡券被核销时同样会推送事件。

2. 调用查询Code接口获取该Code码的状态（是否被领取、核销、删除），若Code码被用户领取且处于有效状态，可获取领券人OpenID。

3. 从卡券详情页跳转外部链接时，微信后台会自动带上卡券ID、Code码等信息。

活用自定义入口

为满足商户功能扩展的需求，新增可自定义三个卡券内的入口，支持跳转到商户自定义url链接。

两个自定义入口基于不同的场景定位设置，区别如下：

类别	示例	字段	显示逻辑
使用场景入口	立即使用	center_title、center_sub_title、center_url	传入后将覆盖二维码展开按钮，未到有效期时按钮置灰
服务场景入口	在线商城	custom_url_name、custom_url_sub_title、custom_url	仅卡券被用户领取且处于有效状态时显示（转赠中、核销后不显示）。
营销场景入口	再次购买	promotion_url_name、promotion_url_sub_title、promotion_url	卡券处于正常状态、转赠中、核销后等异常状态均显示该入口。

接口调用流程

创建朋友的券请严格按照以下接口调用流程调用接口。

开发者须按照以上流程调用接口，接口列表如下表。

API列表

步骤	API名称	用途	API属性
1	上传图片接口	上传卡券logo和卡券图片，获得url	基础接口
2	选取卡券背景色	获取卡券背景颜色色值colorid	创建卡券
3	微信门店接口	设置卡券门店并通过审核获得poiid，用于创建时填入location_list字段	创建卡券
4	创建朋友的券接口	创建卡券获得card_id用于增加库存、投放等动作	创建卡券
5	审核事件推送	获得审核结果	卡券事件推送

API详情

上传图片接口

请点击查看上传图片接口，开发者需调用接口上传商家图标LOGO至微信服务器，获取相应logo_url，用于卡券创建。

注意事项：

1.上传的图片限制文件大小限制1MB，支持JPG 格式。

2.调用接口获取的url 仅支持在微信相关业务下使用，否则会做相应处理。

3.此处必须上传微信服务器返回的图片链接，否则报错；

微信门店接口

请点击查看微信门店接口文档，获取门店 ID 后填入创建卡券接口中的相应字段 location_id_list，即可设置该卡券的适用门店。

选取卡券背景色

请点击查看 选取卡券背景颜色接口文档，选择适用色值，让优惠券变得更加个性，在步骤四创建卡券中将颜色名（如Color010）填入color字段。

创建朋友的券接口

创建朋友的券接口是创建系列接口最重要的一环。

朋友的券是在原有卡券的基础上衍生出的一种高级券的类型，比起普通卡券，朋友的券可以展示有图文介绍的优惠详情（通过advanced_info字段定义），突出服务和商品摘要信息。

接口说明

开发者需调用该接口创建朋友的券，填入商家信息、LOGO、门店以及相关的优惠和使用字段。创建成功后，会获得Card_id，用于下一步的投放。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

参数说明

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

代金券POST示例

{ "card": { "card_type": "CASH", "cash": { "base_info": { "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0", "brand_name": "微信餐厅", "code_type": "CODE_TYPE_TEXT", "color": "Color010", "service_phone": "020-88888888", "description": "不可与其他优惠同享如需团购券发票，请在消费时向商户 提出", "date_info": { "type": "DATE_TYPE_FIX_TIME_RANGE", "begin_timestamp": 1447397802, "end_timestamp": 1449893532 }, "can_share": false, "can_give_friend": false, "location_id_list": [ 272981040, 400183234 ], "get_limit": 3, "center_title": "快速核销", "center_sub_title": "", "center_url": "www.qq.com", "custom_url_name": "立即使用", "custom_url": "http://www.qq.com", "custom_url_sub_title": "6个汉字tips", "promotion_url_name": "更多优惠", "promotion_url": "http://www.qq.com" }, "advanced_info": { "use_condition": { "accept_category": "鞋类", "reject_category": "阿迪达斯", "can_use_with_other_discount": true }, "abstract": { "abstract": "微信餐厅推出多种新季菜品，期待您的光临", "icon_url_list": [ "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0" ] }, "text_image_list": [ { "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0", "text": "此菜品精选食材，以独特的烹饪方法，最大程度地刺激食 客的味蕾" }, { "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0", "text": "此菜品迎合大众口味，老少皆宜，营养均衡" } ], "time_limit": [ { "type": "MONDAY", "begin_hour": 0, "end_hour": 10, "begin_minute": 10, "end_minute": 59 }, { "type": "HOLIDAY" } ], "business_service": [ "BIZ_SERVICE_FREE_WIFI", "BIZ_SERVICE_WITH_PET", "BIZ_SERVICE_FREE_PARK", "BIZ_SERVICE_DELIVER" ], "consume_share_self_num": 1, "consume_share_card_list": [], "share_friends": true }, "reduce_cost": 10 } } }

兑换券POST示例

{ "card": { "card_type": "GIFT", "gift": { "base_info": { ... }, "advanced_info": { ... }, "gift_name": "苹果", "gift_num": 1, "gift_unit": "个""gift": "送苹果一个" } } }

朋友的券JSON结构解析

在以上字段中除卡券基本信息之外，代金券与兑换券均相同，故兑换券JSON不作展示。

卡券信息字段

字段	说明	是否必填
card_type	卡券类型，现仅支持代金券类型和兑换券类型，填写CASH或者GIFT	是
cash	代金券类型json结构函数名	是
reduce_cost	代金券专用，表示减免金额（单位为分），不可填0。	是
gift	兑换券券类型json结构函数名	是
gift_name	兑换券兑换商品名字，限6个汉字	是
gift_num	兑换券兑换商品数目，限三位数字	否
gift_unit	兑换券兑换商品的数量单位，限两个汉字	否
gift	兑换券类型时显示的礼品详情	是

Base_info（卡券基础信息）字段

字段	说明	是否必填
base_info	基本卡券数据，对于任何卡券类型base_info字段相同	是
logo_url	卡券商家LOGO，请使用调用上传图片接口获得的url	是
code_type	卡券的code类型 "CODE_TYPE_TEXT"，文本； "CODE_TYPE_BARCODE"，一维码； "CODE_TYPE_QRCODE"，二维码； "CODE_TYPE_ONLY_QRCODE",二维码无code显示； "CODE_TYPE_ONLY_BARCODE",一维码无code显示； "CODE_TYPE_NONE"无code类型	是
brand_name	商家名字,上限为12个汉字	是
color	券颜色，请参考 选取卡券背景颜色接口文档	是
notice	使用提醒，上限为12个汉字（一句话描述，展示在首页，示例：请出示二维码核销卡券）	是
description	使用说明。长文本描述，可以分行，上限为1000个汉字	是
date_info	使用日期，有效期的信息，仅支持DATE_TYPE_FIX_TIME_RANGE	是
begin_timestamp	DATE_TYPE_FIX_TIME_RANGE时专用，表示起用时间。从1970年1月1日00:00:00至起用时间的秒数，最终需转换为字符串形态传入，下同。（单位为秒）	是
end_timestamp	DATE_TYPE_FIX_TIME_RANGE表示结束时间。从1970年1月1日00:00:00至起用时间的秒数，最终需转换为字符串形态传入。（单位为秒）	是
location_id_list	门店位置ID，请参考微信门店接口文档，朋友的券须至少传入一个可用poi_id,否则报错	是
can_share	是否支持分享到对话、朋友圈，与share_friends字段互斥，若创建朋友共享券此处应填入false,不可为空	是
can_give_friend	是否支持赠送，与share_friends字段互斥，若创建朋友共享券此处应填入false,不可为空	是
service_phone	客服电话	否
get_limit	领取限制，限制用户扫码或点击H5领取的次数	否
center_title	居中置顶的url标题，一般为快速核销或者快速买单，用于跳转商户自己开发的核销或者买单页面，9个中文字符以内。该cell仅限卡券状态正常，且处于有效期内的时候显示。	否
center_sub_title	居中置顶的url副标题，显示在标题下方，12个中文字符以内。该标题仅限卡券状态正常，且处于有效期内的时候显示。	否
center_url	居中置顶的url，该url仅限卡券状态正常，且处于有效期内的时候显示。	否
custom_url_name	商家自定义入口名称，与custom_url字段共同使用，长度限制在5个汉字内	否
custom_url	商家自定义入口跳转外链的地址链接,跳转页面内容需与自定义cell名称保持匹配	否
custom_url_sub_title	显示在入口右侧的tips，长度限制在6个汉字内	否
promotion_url_name	营销场景的自定义入口	否
promotion_url	入口跳转外链的地址链接。	否
promotion_url_sub_title	显示在入口右侧的tips，长度限制在6个汉字内	否

Advanced_info（卡券高级信息）字段

新增门槛字段，代金券类型（CASH）的卡券可以与满减门槛（least_cost字段）、指定品类可用/不可用门槛（accept_category/reject_category）不与其他优惠共享门槛组合使用。

兑换券类型（GIFT）的卡券可以与满减门槛（least_cost字段）、买送门槛（object_use_for字段）和不与其他优惠共享门槛组合使用。

字段	说明	是否必填
advanced_info	创建优惠券特有的高级字段	是
use_condition	使用门槛（条件）字段	否
accept_category	指定可用的商品类目，仅用于代金券类型，填入后将在券面拼写适用于xxx，标题自动拼为xxx减50元（若仅填入5个字），50元代金券（填入5个字以上）。	否
reject_category	指定不可用的商品类目，仅用于代金券类型，填入后将在券面拼写不适用于xxx。	否
least_cost	满减门槛字段，可用于兑换券和代金券，填入后将在全面拼写消费满xx元可用，标题自动拼为满xx减xx/满xx送xx(gift_name)	否
object_use_for	购买xx可用类型门槛，仅用于兑换，填入后自动拼写购买xxx可用，标题自动拼为买xx送xx(gift_name)	否
can_use_with_other_discount	不可以与其他类型共享门槛，填写false时系统将在使用须知里拼写不可与其他优惠共享，默认为true	否
abstract	封面摘要结构体名称	是
abstract	封面摘要简介。	是
icon_url_list	封面图片列表，仅支持填入一个封面图片链接，上传图片接口上传获取图片获得链接，填写非CDN链接会报错，并在此填入。建议图片尺寸像素850*350	是
text_image_list	图文列表，显示在详情内页，优惠券券开发者须至少传入一组图文列表	是
image_url	图片链接，必须调用上传图片接口上传图片获得链接，并在此填入，否则报错	是
text	图文描述，5000字以内	是
business_service	商家服务类型： BIZ_SERVICE_DELIVER 外卖服务；BIZ_SERVICE_FREE_PARK 停车位；BIZ_SERVICE_WITH_PET 可带宠物；BIZ_SERVICE_FREE_WIFI 免费wifi，可多选	否
time_limit	使用时段限制	否
type	限制类型枚举值：支持填入 MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 HOLIDAY 假期通用 此处只控制显示，不控制实际使用逻辑，不填默认不显示	否
begin_hour	当前type类型下的起始时间（小时），如当前结构体内填写了MONDAY，此处填写了10，则此处表示周一 10:00可用	否
begin_minute	当前type类型下的起始时间（分钟），如当前结构体内填写了MONDAY，begin_hour填写10，此处填写了59，则此处表示周一 10:59可用	否
end_hour	当前type类型下的结束时间（小时），如当前结构体内填写了MONDAY，此处填写了20，则此处表示周一 10:00-20:00可用	否
end_minute	当前type类型下的结束时间（分钟），如当前结构体内填写了MONDAY，begin_hour填写10，此处填写了59，则此处表示周一 10:59-00:59可用	否
consume_share_self_num	核销后送券的数量，可设置核销后送本卡券的数量，限制传入1张，与consume_share_card_list字段互斥	否
consume_share_card_list	核销后赠送其他卡券的列表，与consume_share_self_num字段互斥	否
card_id	核销后赠送的其他卡券card_id，目前仅支持填入一个共享券card_id，此处必须填入共享券	否
num	核销后赠送的该card_id数目，目前仅支持填1	否
share_friends	是否支持分享给朋友使用，填写true优惠券才可被共享	是

注意事项：

1.门槛字段用于拼接标题以及券面的优惠说明，请开发者务必按照要求选择填写，以免造成不必要的麻烦。

2.填入时间限制字段（time_limit）,只控制显示，不控制实际使用逻辑，不填默认不显示。

返回数据

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

字段说明

字段名	说明
错误码	错误码，0为正常，40071为格式错误，请对比JSON示例排查错误
errmsg	错误信息
card_id	卡券id

审核事件推送

生成的卡券通过审核时，微信会把这个事件推送到开发者填写的URL。 点击查看卡券事件推送机制

朋友的券支持买单

同普通卡券一样，朋友的券一样支持微信快速买单，开通了微信支付的商户可以为朋友的券开通买单，便捷收银。

帮助

错误码

错误码	说明	排错指引
40079	有效期错误	须将有效期设置为90天以内
40141	图片url错误	须使用将图片上传至CDN后获得的url
41025	缺少location_list	创建的JSON中须填入location_list(即poi_id，门店id)
42001	token过期	重新获取最新的token调用接口，若有多个调用源，需要统一管理token
47001	创建JSON结构错误	针对报错信息提示的位置对比示例排查

更多错误码，请见卡券全局错误码

常见问题

1.为什么朋友的券不能在创建的时候填入库存？

朋友的券库存机制与普通券不同，开发者须先创建卡券后，到MP（商户后台）用券点充值库存，不支持在创建的时候填入库存。

2.为什么朋友的券只能创建三个月时长的卡券？

朋友的券不同于普通卡券，有很强的时效性和活动性，为了保证用户的券列表能常来常新，我们约定，每个商户最多只能创建时长不超过三个月（90天)的卡券。

3.卡券过期了券点会退吗？

若卡券过期时，card_id内尚有库存，我们会将库存折合券点退回商户的账户，周期为T+1（隔日退回）。

配置库存、充值券点

该部分介绍开发者怎样为card_id配置库存以及充值、管理账号的券点。

接口说明

创建朋友的券成功后，开发者可以通过接口为card_id配置库存，不同于普通券的是，朋友的券库存须使用券点（什么是券点？）兑换，券点分为免费券点和付费券点，免费券点由微信平台赠送产生，而付费券点由开发者充值产生。

接口调用流程

API列表

步骤	API名称	用途	API属性
1	开通券点账户接口	开通券点账户	库存接口
2	对优惠券批价接口	获取对当前card_id充值一定量的库存所耗费的券点总额	库存接口
3	查询券点余额接口	查询账户内券点是否可以支付本次批价的库存充值	库存接口
4	确认兑换库存接口	确认充值库存	库存接口
5	充值券点接口	使用微信支付充值账户内的券点	充值接口
6	查询订单详情接口	查询某次充值订单的状态	充值接口
6	查询流水详情接口	查询库存、券点订单的状态	管理接口

API详情

该部分主要介绍库存、券点接口的调用方法和传递参数。

开通券点账户接口

本接口用于开发者为当前appid开通券点账户并获得免费券点奖励

接口调用请求说明

HTTP请求方式: GET https://api.weixin.qq.com/card/pay/activate?access_token=ACCESS_TOKEN

返回数据示例

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

返回数据示例

参数名	描述
errcode	错误码
errmsg	错误信息
reward	奖励券点数量，以元为单位，微信卡券对每一个新开通券点账户的商户奖励200个券点，点击查看券点规则什么是券点？

对优惠券批价

本接口用于提前查询本次新增库存需要多少券点

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/getpayprice?access_token=ACCESS_TOKEN

参数说明

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

POST数据

{"card_id": "pbLatjpQxxxxxxxxCEV_cLTwoB7yU", "quantity": "1"}

请求参数说明

参数名	必填	类型	示例值	描述
card_id	是	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	需要来配置库存的card_id
quantity	是	int	100	本次需要兑换的库存数目

返回数据示例

{ "errcode": 0, "errmsg": "ok", "order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIf7Ag5Ww-YdxP-KeT6LeJBttb1xpY0Uf7g8DNHrbUyHopolqfUqPBBLDEmB7Z-91I8", "price": "0.2", "free_coin": "0.2", "pay_coin": "0" }

参数名	描述
errcode	错误码
errmsg	错误信息
order_id	本次批价的订单号，用于下面的确认充值库存接口，仅对当前订单有效且仅可以使用一次，60s内可用于兑换库存。
price	本次需要支付的券点总额度
free_coin	本次需要支付的免费券点额度
pay_coin	本次需要支付的付费券点额度

查询券点余额接口

本接口用于开发者查询当前券点账户中的免费券点/付费券点数目以及总额。

接口调用请求说明

HTTP请求方式: GET https://api.weixin.qq.com/card/pay/getcoinsinfo?access_token=ACCESS_TOKEN

返回数据示例

{"errcode": 0, "errmsg": "ok", "free_coin": 200 "pay_coin": 1 "total_coin": 201}

返回参数说明

参数名	描述
errcode	错误码
errmsg	错误信息
free_coin	免费券点数目
pay_coin	免费券点数目
total_coin	全部券点数目

确认兑换库存接口

本接口用于确认兑换库存，确认后券点兑换为库存，过程不可逆。

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/confirm?access_token=ACCESS_TOKEN

参数说明

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

POST数据

{ "card_id": "pbLatjpxxxxlCEV_cLTwoB7yU", "order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIfkbR7Ag5WwYdxP-KeT6LeJBttb1xpYxxxxxxxxxxxxHrbUyHopolqfUqPBBLDEmB7Z-91I8", "quantity": "1" }

请求参数说明

参数名	必填	类型	示例值	描述
card_id	是	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	需要来兑换库存的card_id
quantity	是	int	100	本次需要兑换的库存数目
order_id	是	string	P9zzllX2VJ5NgiF9kFVarX7bc8r	仅可以使用上面得到的订单号，保证批价有效性

返回数据示例

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

参数说明

参数名	描述
errcode	错误码
errmsg	错误信息

特别注意：

上一步获得的order_id须在60s内使用，否则确认兑换库存接口将会失效

充值券点接口

开发者可以通过此接口为券点账户充值券点，1元等于1点。开发者调用接口后可以获得一个微信支付的支付二维码链接， 开发者可以将链接转化为二维码扫码支付。

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/recharge?access_token=ACCESS_TOKEN

参数说明

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

POST数据

{"coin_count": 100}

请求参数说明

参数名	必填	类型	示例值	描述
coin_count	是	int	10000	需要充值的券点数目，1点=1元

返回数据示例

{ "errcode": 0, "errmsg": "ok", "order_id": "100005790120***221401000171", "qrcode_url": "weixin://wxpay/bizpayurl?pr=xxxxxxxxx", "qrcode_buffer": "pwxs*************xxxxxxxxxx" }

参数名	描述
errcode	错误码
errmsg	错误信息
order_id	本次支付的订单号，用于查询订单状态
qrcode_url	支付二维码的的链接，开发者可以调用二维码生成的公开库转化为二维码显示在网页上，微信扫码支付
qrcode_buffer	二维码的数据流，开发者可以使用写入一个文件的方法显示该二维码

注意：

开发者可以参考以下方法将buffer显示二维码

查询订单详情接口

本接口用于查询充值订单的状态

接口调用请求说明

HTTP请求方式: POST https://api.weixin.qq.com/card/pay/getorder?access_token=ACCESS_TOKEN

参数说明

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

POST数据

{"order_id": "100005790********401000171"}

请求参数说明

参数名	必填	类型	示例值	描述
order_id	是	int	10000	上一步中获得的订单号，作为一次交易的唯一凭证

返回数据示例

{ "errcode": 0, "errmsg": "ok", "order_info": { "order_id": "100005790120151221401000171", "status": "ORDER_STATUS_FINANCE_SUCC", "create_time": 1450712798, "pay_finish_time": 1450712905, "desc": "微信支付充值", "free_coin_count": "0", "pay_coin_count": "1", "refund_free_coin_count": "0", "refund_pay_coin_count": "0", "openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY", "order_type": "ORDER_TYPE_WXPAY" } }

返回数据说明

参数名	描述
errcode	错误码
errmsg	错误信息
order_info	订单信息结构体
order_id	订单号
status	订单状态， ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票
create_time	订单创建时间
pay_finish_time	支付完成时间
desc	支付描述，一般为微信支付充值
free_coin_count	本次充值的付费券点数量，以元为单位
pay_coin_count	二维码的数据流，开发者可以使用写入一个文件的方法显示该二维码
refund_free_coin_count	回退的免费券点
refund_pay_coin_count	回退的付费券点
openid	支付人的openid
order_tpye	订单类型，ORDER_TYPE_WXPAY为充值

查询券点流水详情接口

本接口用于查询券点的流水详情。

接口调用请求说明

HTTP请求方式: POSThttps://api.weixin.qq.com/card/pay/getorderlist?access_token=ACCESS_TOKEN

参数说明

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

POST数据

{ "offset": 0, "count": 5, "order_type": "ORDER_TYPE_WXPAY", "nor_filter": { "status": "ORDER_STATUS_SUCC" }, "sort_info": { "sort_key": "SORT_BY_TIME", "sort_type": "SORT_DESC" }, "begin_time": "1440420538", "end_time": "1450713203" }

请求参数说明

参数名	必填	类型	示例值	描述
offset	否	int	0	分批查询的起点，默认为0
count	否	int	50	分批查询的数量
begin_time	否	int	14552146398	批量查询订单的起始事件，为时间戳，默认1周前
end_time	否	int	14552146398	批量查询订单的结束事件，为时间戳，默认为当前时间
order_type	否	string	ORDER_TYPE_WXPAY	所要拉取的订单类型 ORDER_TYPE_SYS_ADD 平台赠送 ORDER_TYPE_WXPAY 充值 ORDER_TYPE_REFUND 库存回退券点 ORDER_TYPE_REDUCE 券点兑换库存 ORDER_TYPE_SYS_REDUCE 平台扣减
nor_filter	否	JSON结构	ORDER_STATUS_QUANTITY_SUCC	反选，不要拉取的订单
status	否	string	ORDER_STATUS_REFUND_WAITING	不要拉取的订单状态 订单状态包括： ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票
sort_info	否	JSON结构		对结果排序
sort_key	否	string	SORT_BY_TIME	排序依据，SORT_BY_TIME 以订单时间排序
sort_type	否	string	SORT_DESC	排序规则，SORT_ASC 升序 SORT_DESC 降序

返回数据示例

{ "errcode": 0, "errmsg": "ok", "total_num": 1, "order_list": [ { "order_id": "100005790120151221401000171", "status": "ORDER_STATUS_FINANCE_SUCC", "create_time": 1450712798, "pay_finish_time": 1450712905, "desc": "微信支付充值", "free_coin_count": "0", "pay_coin_count": "1", "refund_free_coin_count": "0", "refund_pay_coin_count": "0", "openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY", "order_type": "ORDER_TYPE_WXPAY" } ] }

返回数据说明

参数名	描述
errcode	错误码
errmsg	错误信息
total_num	符合条件的订单总数量
order_list	显示的订单详情列表，根据offset和count来显示
order_id	订单号
status	订单状态， ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代币成功 ORDER_STATUS_QUANTITY_SUCC 加库存成功 ORDER_STATUS_HAS_REFUND 已退币 ORDER_STATUS_REFUND_WAITING 等待退币确认 ORDER_STATUS_ROLLBACK 已回退,系统失败 ORDER_STATUS_HAS_RECEIPT 已开发票
create_time	订单创建时间
pay_finish_time	支付完成时间
desc	支付描述，一般为微信支付充值
free_coin_count	本次充值的付费券点数量，以元为单位
pay_coin_count	二维码的数据流，开发者可以使用写入一个文件的方法显示该二维码
refund_free_coin_count	回退的免费券点
refund_pay_coin_count	回退的付费券点
openid	支付人的openid
order_tpye	订单类型，ORDER_TYPE_WXPAY为充值

券点流水详情事件推送

当券点发生变动时，微信服务器会将本次变动的类型、券点数额以及时间等信息推送给开发者服务器。

朋友的券投放

接口说明

该部分主要讲述微信卡券不同的投放渠道和投放方式，建议开发者仔细阅读本部分文档，避免在投放过程中出现消费者无法共享的情况。

开发者注意事项

共享券投放与普通券投放略有不同。现共享券仅支持线下二维码扫码投放（不包含长按二维码识别）、摇一摇Beacon投放的H5以及WIFI环境H5投放场景，共享券同时支持扫码跳转H5后领券，其他投放渠道暂不支持。

案例介绍

卡券二维码投放

场景介绍

二维码一般用于商户卡券的店内投放、海报投放和传单投放，商户通过接口生成二维码之后，可以将二维码贴在收银台、海报、传单等宣传物料上。用户扫码后可以将卡券共享至共享券列表，供自己和朋友们使用。

使用流程

完成以上流程，开发者需要：

1.创建朋友的券并再通过审核之后在【微信公众平台商户后台】增加库存；

2.调用创建二维码接口生成领券二维码；

3.监听领取时间推送，记录卡券发放量并做数据统计；

API列表

步骤	API名称	用途	API属性
1	生成二维码接口	创建二维码得到二维码的展示url	投放接口
2	卡券领取事件推送	用户领取卡券后，获得用户的openid、code和card_id等信息	事件推送

H5网页投放

场景介绍

开发者可以开发领券H5网页，并将url转化成二维码或者配置在微信摇一摇或者微信Wi-Fi投放。 该渠道适用于对领取页面有要求的商户，可以自定义页面样式体现品牌价值或者自定义领取流程（如加入游戏环节）等。

注意：

1.目前仅支持线下场景投放，如卡券二维码、从扫码进入H5网页扫码或者从Wi-Fi或者iBeacon进入的网页领券。其他渠道暂不支持。

2.点击此处了解Wi-Fi和微信摇一摇摇一摇周边（iBeacon）

接口调用流程

API列表

步骤	API名称	用途	API属性
1	获取JSAPI_TICKET接口	获取到JSAPI_TICKET用于参与JS SDK config	基础接口
2	获取卡券API_TICKET接口	获取到卡券API_TICKET用于cardext内signarue签名	投放接口
3	批量添加卡券接口	将共享券添加到用户的券列表	投放接口
4	卡券领取事件推送	用户领取卡券后，获得用户的openid、code和card_id等信息	事件推送

API详情

设置测试白名单接口

当朋友的券审核未通过时，开发者可以通过设置白名单的方式领取朋友的券并共享。 共享的未审核状态的券仅白名单列表内可见。

生成二维码接口

接口调用请求说明

http请求方式: POST 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_id": 1 } } }

参数名	必填	类型	示例值	描述
code	是	string(20)	110201201245	卡券Code码,use_custom_code字段为true的卡券必须填写，非自定义code不必填写。。
card_id	否	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	卡券ID。
openid	否	string(32)	oXch-jkrxp42VQu8ldweCwDt97qo	指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，非指定openid不必填写。
expire_seconds	否	unsigned int	60	指定二维码的有效时间，范围是60 ~ 1800秒。不填默认为永久有效。
is_unique_code	否	bool	false	指定下发二维码，生成的二维码随机分配一个code，领取后不可再次扫描。填写true或false。默认false。
outer_id	否	int	12	领取场景值，用于领取渠道的数据统计，默认值为0，字段类型为整型，长度限制为60位数字。用户领取卡券后触发的事件推送中会带上此自定义场景值。

注意事项：

1.若开发者填写了is_unique_code为true，需要保证卡券已审核通过并有库存，否则会报错。

返回数据

数据示例：

{ "errcode": 0, "errmsg": "ok", "ticket": "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==", "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	二维码显示地址，点击后跳转二维码页面

获取JSAPI_TICKET接口

接口调用请求说明

http请求方式: GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi

返回数据

{ "errcode": 0, "errmsg": "ok", "ticket": "bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA", "expires_in": 7200 }

参数名	描述
errcode	错误码
errmsg	错误信息
ticket	获取的JSAPI_TICKET
expires_in	有效时间，ticket有效时间为2小时，2小时内不变

获取卡券API_TICKET接口

接口调用请求说明

http请求方式: GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card

返回数据

{ "errcode": 0, "errmsg": "ok", "ticket": "bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA", "expires_in": 7200 }

参数名	描述
errcode	错误码
errmsg	错误信息
ticket	获取的卡券API_TICKET
expires_in	有效时间，ticket有效时间为2小时，2小时内不变

批量添加卡券（addcard）接口

朋友的券领取须指引用户升级到最新的微信客户端版本，最低版本要求为：iOS微信版本为6.3.6及以上，Android微信版本为6.3.7及以上。 开发者可以判断用户版本后调用addcard接口，请点击查看判断用户客户端版本、批量添加卡券接口。

卡券领取事件

用户领取朋友的券后，会有事件推送到开发者服务器。

帮助

错误码

错误码	说明	排错指引
40053	JSON结构错误	card_id或者参数名有误，请对比示例排查
43008	当前账号未开通支付权限或未开通支付后送券接口权限，无法设置支付后送朋友的券功能	前往开通微信支付
45021	赠券规则列表长度高于10个	减少赠券规则列表的个数
47001	创建JSON结构错误	针对报错信息提示的位置对比示例排查

更多错误码，请见卡券全局错误码

常见问题

1.如何区分领取渠道？

开发者可以在生成二维码或者H5添加卡券时，填入outer_id(自定义渠道值),这个数值会随领取事件推送至开发者服务器，从而使得开发者可以区分每一个code（卡券串码）的投放渠道。

2.为什么长按二维码不能领取卡券？

目前朋友的券仅支持线下渠道投放，对于线上的场景（如长按二维码领取、公众号群发）等做了限制。

朋友的券核销

接口说明

此处介绍朋友的券的核销方式，分为线上和线下核销两部分，下面分不同的场景介绍。

案例介绍

线下核销

机具扫码核销

场景介绍

具有机具和开发能力的商户可以通过机具扫码进行卡券核销，开发者可以通过机具扫码获得卡券code之后，调用核销code接口将卡券进行核销，方便快捷。

接口调用流程

API列表

步骤	API名称	用途	API属性
1	查询code接口	查询code状态，获知当前卡券是否可以核销	管理卡券
2	线下核销code接口	设置卡券门店并通过审核获得poiid，用于创建时填入location_list字段	核销卡券
3	卡券核销事件	获得当前卡券的使用人、code和card_id等信息	事件推送

网页工具核销

场景介绍

若开发者没有能力进行机具开发，可以开发一个核销员端使用的网页进行朋友的券的核销，当用户出示二维码时。

接口调用流程

API列表

步骤	API名称	用途	API属性
1	查询code接口	查询code状态，获知当前卡券是否可以核销	管理卡券
2	线下核销code接口	设置卡券门店并通过审核获得poiid，用于创建时填入location_list字段	核销卡券
3	卡券核销事件	获得当前卡券的使用人、code和card_id等信息	事件推送

卡券商户助手核销

场景介绍

手机核销助手是基于“卡券商户助手“公众号的官方卡券核销工具，同样支持朋友的券的核销。

快速体验

步骤一：关注“微信卡券商户助手”

步骤二：进入【微信公众号后台】-【卡券功能】-【卡券核销】-【添加核销员】，为自己的微信号设置核销员权限，并选择已有的门店。

步骤三：用另一台手机领取自己创建的朋友的券，展开二维码并用已设置为核销员的手机扫码或者输码核销卡券。

公众号商户后台核销

商户可以在电脑登录公众号商户后要，【卡券功能】-【卡券核销】-【网页核销】直接核销核销卡券。

线上核销

线上核销涉及的接口与线下核销接口略有不同，线上核销接口需要消费者跳转至H5网页，所以可能会出现两个用户同时使用同一张卡券的情况，我们约定，对于没有点击卡券上的“出示使用”的核销，开发者先调用占用（mark）接口，将一个code(卡券串码)与一个openid（用户身份识别码）关联，保证该code不被另外的人使用。

网页快速核销

场景介绍

若开发者没有办法配置核销员或者商户没办法，可以自定义一个H5核销界面，用户在券面发起核销并在开发者自定义的H5网页内完成核销和裂变送券的过程。

值得开发者注意的是，对于自助核销的卡券，开发者在创建/更新卡券是可以将code_type字段设置为CODE_TYPE_NONE,这样可以隐藏掉卡券上使用二维码的入口（如下图），同时将核销的url通过创建接口中的center_title center_sub_title，center_url写入，那么此自定义入口会指定居中（如下图）

接口调用流程

API列表

步骤	API名称	用途	API属性
1	获取自定义跳转链接参数	获取加密code（encrypt_code）、card_id和openid	创建卡券
2	code解码接口	通过加密code获得真实的code	核销卡券
3	查询code接口	查看code状态是否可以核销	管理卡券
4	Mark(占用)code接口	在核销之前将code锁住，防止出现两个人同时核销券的情况	核销卡券
5	线上核销code接口	将卡券核销掉，须传入openid和code	核销接口
6	卡券核销事件	获得当前卡券的使用人、code和card_id等信息	事件推送
7	核销裂赠券接口（JSSDK）	拉起裂变领取页供用户领取	核销接口

API详情

查询Code接口

我们强烈建议开发者在调用核销code接口之前调用查询code接口，并在核销之前对非法状态的code(如转赠中、已删除、已核销等)做出处理。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/get?access_token=TOKEN

参数说明

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

POST数据

{ "card_id": "pbLatjorLTVl-tdvZ6zQRIc-Fn6Y", "code": "245645675434", "check_consume": true}

参数名	必填	类型	示例值	描述
code	是	string(20)	110201201245	单张卡券的唯一标准。
card_id	否	string(32)	pFS7Fjg8kV1IdDz01r4SQwMkuCKc	卡券ID代表一类卡券。
check_consume	否	bool	true	是否校验code核销状态，填入true和false时的code异常状态返回数据不同。

当check_consume为true时返回数据

卡券状态正常：

{ "errcode": 0, "errmsg": "ok", "card": { "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk", "begin_time": 1447397802, "end_time": 1452893532 }, "openid": "obLatjm43RA5C6QfMO5szKYnT3dM", "can_consume": true, "user_card_status": "NORMAL", "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw", "use_count": 1 }

卡券状态异常：

{ "errcode": 40127, "errmsg": "invalid user-card status! Hint: the card was given to user, but may be deleted or set unavailable ! hint: [iHBD40040ent3]" }

当check_consume为false时返回数据

卡券状态正常：

{ "errcode": 0, "errmsg": "ok", "card": { "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk", "begin_time": 1447397802, "end_time": 1452893532 }, "openid": "obLatjm43RA5C6QfMO5szKYnT3dM", "can_consume": true, "user_card_status": "NORMAL", "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw", "use_count": 1 }

卡券状态异常：

{ "errcode": 0, "errmsg": "ok", "card": { "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk", "begin_time": 1447397802, "end_time": 1452893532 }, "openid": "obLatjm43RA5C6QfMO5szKYnT3dM", "can_consume": false, "user_card_status": "DELETE", "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw", "use_count": 1 }

参数名	描述
errcode	错误码
errmsg	错误信息
openid	领取该卡券用户的openid
card_id	卡券ID
begin_time	起始使用时间
end_time	结束时间
user_card_status	当前code对应卡券的状态， NORMAL 正常 CONSUMED 已核销 EXPIRE 已过期 GIFTING 转赠中 GIFT_TIMEOUT 转赠超时 DELETE 已删除，UNAVAILABLE 已失效； code未被添加或被转赠领取的情况则统一报错：invalid serial code
can_consume	是否可以核销，true为可以核销，false为不可核销
mark_openid	当前占用此卡券的顾客的openid，核销时仅限该openid的用户可以核销该卡券
use_count	当前占用这个卡券的人已经使用该card_id的次数

注：

1.固定时长有效期会根据用户实际领取时间转换，如用户2013年10月1日领取，固定时长有效期为90天，即有效时间为2013年10月1日-12月29日有效。

2.无论check_consume填写的是true还是false,当code未被添加或者code被转赠领取是统一报错：invalid serial code

拉取卡券列表(ChooseCard)接口

微信 JS SDK 只能在微信内置浏览器中使用,其他浏览器调用无效。微信提供chooseCard接口供商户前端网页调用,用于拉起用户名下该商家筛选条件的卡券内容。

点击查看 调起适用于门店的卡券列表并获取用户选择列表JS SDK

获取自定义外链参数

为了满足商户基于卡券本身的扩展诉求，允许卡券内页添加url跳转外链。带有的的字段有openid、encrypt_code、card_id。

假如指定的url为http://www.qq.com，用户点击时，跳转的url则为：http://www.qq.com?card_id=pWXUrtw4ehIUwDTXxkvCC6THenb8&encrypt_code= LPmXP%2BZFM9bdEQPSqcA8%2F%2F6pefbsKaRxnNUMHh5%2Fq6Q%3D &openid=oWXUrt8i3***ymgmPcHKlo0TdgHw

注意：

1.encrypt_code为加密码码，需调用解码接口获取真实Code码。

2.从url中取出的参数须经过urlencode方可用于post请求。

Code解码接口

code解码接口支持两种场景： 1.商家获取choosecard_info后，将card_id和encrypt_code字段通过解码接口，获取真实code。 2.卡券内跳转外链的签名中会对code进行加密处理，通过调用解码接口获取真实code。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/decrypt?access_token=TOKEN

参数说明

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

POST数据

{"encrypt_code": "XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"}

参数名	必填	类型	示例值	描述
encrypt_code	是	string(128)	XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE	经过加密的Code码。

返回数据

数据示例：

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

参数名	描述
errcode	错误码
errmsg	错误信息
code	解密后获取的真实Code码

Mark(占用)Code接口

朋友的券由于共享的特性，会出现多个消费者同时进入某一个卡券的自定义H5网页的情况，若该网页涉及线上下单、核销、支付等行为，会造成两个消费者同时使用同一张券，会有一个消费者使用失败的情况，为此我们设计了mark（占用）code接口。

对于出示核销（消费者点击“出示使用”按钮）的场景，开发者直接调用核销接口，无需考虑mark逻辑，此时由客户端代为完成。

对于消费者进入H5网页核销的情况，我们约定，开发者在帮助消费者核销卡券之前，必须帮助先将此code（卡券串码）与一个openid绑定（即mark住），才能进一步调用核销接口，否则报错。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/mark?access_token=TOKEN

参数说明

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

POST数据

{ "code": "114567897765", "card_id": "pbxxxxxxxxhjahkdjad", "openid": "obcdkalgsdklkdooooooo", "is_mark": true }

参数名	必填	描述
code	是	卡券的code码。
card_id	是	卡券的ID。
openid	是	用券用户的openid。
is_mark	是	是否要mark（占用）这个code，填写true或者false，表示占用或解除占用。

返回数据

数据示例：

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

参数名	描述
errcode	错误码
errmsg	错误信息

注意：

1. 接口只支持未使用、正常状态的朋友的券，开发者调用前须查询code。

2. is_mark不填默认为true。

3. 重复用同一个openid mark，都返回成功。

4. 用openid_a mark后，用openid_b mark会报错40146

5. is_mark为false时取消mark，要求传入的openid和mark时一致，否则报错40416。

6. 不调用接口解除mark的话，5分钟后自动解除。（时间可能根据产品策略调整）

线下核销Code接口

消耗code接口是核销卡券的唯一接口，仅支持核销有效期内的卡券，否则会返回错误码invalid time。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/consume?access_token=TOKEN

参数说明

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

POST数据

非自定义Code卡券的请求 {"code": "12312313"}

参数名	必填	类型	示例值	描述
code	是	string(20)	1231231	需核销的Code码。

返回数据

数据示例：

{ "errcode": 0, "errmsg": "ok", "card": { "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc" }, "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA" }

参数名	描述
errcode	错误码。
errmsg	错误信息。
openid	用户在该公众号内的唯一身份标识。
card_id	卡券ID。

线上核销Code接口

线上核销code接口与普通的核销code接口不同，开发者须传入当前使用该卡券顾客的openid才可以核销。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/consume?access_token=TOKEN

参数说明

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

POST数据

{"code": "12312313", "openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA" }

参数名	必填	类型	示例值	描述
code	是	string(20)	1231231	需核销的Code码。
openid	是	string(20)	oFS7Fjl0WsZ9AMZqrI80nbIq8xrA	当前卡券使用者的openid，通常通过网页授权登录或自定义url跳转参数获得。

返回数据

数据示例：

{ "errcode":0, "errmsg":"ok", "card":{"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"}, "openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA" }

参数名	描述
errcode	错误码。
errmsg	错误信息。
openid	用户在该公众号内的唯一身份标识。
card_id	卡券ID。

注意：

1.只有在线上核销的场景时，调用核销接口才需要传openid参数； 2.线下核销的场景下，核销接口传递的参数仅为code，无需openid；

核销事件推送

卡券被核销时，微信会把这个事件推送到开发者填写的URL。 点击查看卡券核销事件推送

当用户使用优惠券后，商家可通过JS SDK再次赠送一张卡券。核销后再次赠送卡券接口（JS SDK）

该接口仅限6.3.6以上版本客户端使用，且须配置1.1.0的js文件https://res.wx.qq.com/open/js/jweixin-1.1.0.js

详情请见核销后再次赠送卡券接口

帮助

错误码

错误码	说明	排错指引
40003	Invalid opened，缺少openid	核销时用户的卡券未处于展示（mark）状态，朋友的券规定，券必须处于展示（mark）状态时，才允许被核销
40056	无效code	Code尚未被领取
40075	错误的encrypt码	请检查加密码是否拼写正确，请检查在url中取出encrypt_code（加密code）在post之前是否做过urlencode
40078	该Code已经被删除或者转赠中	建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销
40079	卡券过期	建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销
40099	Code已经被核销	建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销
40127	该Code已经被删除、置为失效或者转赠成功	建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销

更多错误码，请见卡券全局错误码

常见问题

1、为什么JSSDK拉起卡券列表中没有卡券？

A:JSSDK拉不起卡券一般为签名错误和筛选条件错误，两种情况。 签名错误是指卡券签名错误，建议用http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=cardsign调试筛选条件错误是指shopid/cardid/和cardtype传参有误，比如传入了cash类型的cardtype,但是实际上用户卡包中无此类型卡券。

2、为什么要调用mark住接口？

A：由于朋友的券会出现在不同的用户列表中，所以在同一时刻可能有多个用户同时进入开发者开发的核销页面或者下单、支付页面，会出现用户付款但是没有成功核销卡券的情况，所以我们约定必须在卡券核销之前调用mark住接口将code与当前的openid锁定。 其本质是将code与当前使用者锁定的一个锁、 比如快速买单和商城下单的场景可以在支付前调用mark接口，如果mark失败则停止支付，而开发了自主核销页面的开发者可以选择在核销之前mark住code，从而避免冲突的发生。

朋友的券管理接口

更新朋友的券信息接口

接口说明

创建朋友的券成功之后开发者可调用该接口更改卡券信息，某些需要修改后送审的字段开发者需慎重处理

开发者注意事项

1. 更改卡券的部分字段后会重新提交审核，详情见字段说明，更新成功后可通过调用查看卡券详情接口核查更新结果；

2. 仅填入需要更新的字段，许多开发者在调用该接口时会填入brandname（品牌名称）等不支持修改的字段，导致更新不成功。

3. 调用该接口后更改卡券信息后，请务必调用查看卡券详情接口验证是否已成功更改。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/update?access_token=TOKEN

参数说明

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

POST示例

{ "card_id": "pbLatjgOY1_Cxi3mnWBThtG90HGg", "cash": { "base_info": { "code_type": "CODE_TYPE_TEXT", "color": "Color010", "service_phone": "020-88888888", "description": "不可与其他优惠同享如需团购券发票，请在消费时向商户提出", "can_share": false, "can_give_friend": false, "location_id_list": [ 272981040, 400183234 ], "custom_url_name": "立即使用", "custom_url": "http://www.qq.com ", "custom_url_sub_title": "6个汉字tips", "promotion_url_name": "更多优惠", "promotion_url": "http://www.qq.com" }, "advanced_info": { "time_limit": [ { "type": "MONDAY" }, { "type": "HOLIDAY" } ], "text_image_list": [ { "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0", "text": "此菜品精选食材，以独特的烹饪方法，最大程度地刺激食客的味蕾" }, { "image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0", "text": "此菜品迎合大众口味，老少皆宜，营养均衡" } ], "business_service": [ "BIZ_SERVICE_FREE_WIFI", "BIZ_SERVICE_WITH_PET", "BIZ_SERVICE_FREE_PARK", "BIZ_SERVICE_DELIVER" ], "consume_share_card_list": [ { "card_id": "pbLatjpvp0Xq6jtgRRxCKtudkBz8k", "num": 1 } ], "consume_share_self_num": 0, "abstract": { "abstract": "微信餐厅推出多种新季菜品，期待您的光临", "icon_url_list": [ "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0" ] } } } }

字段说明

Base_info（卡券基础信息）字段修改：

参数名	是否提审	类型	示例值	描述
base_info	-	JSON结构		卡券基础信息字段。
logo_url	是	string(128)	http://mmbiz.qpic.cn/	卡券的商户logo，建议像素为300*300。
notice	是	string（48）	请出示二维码核销卡券。	使用提醒，字数上限为16个汉字。
description	是	string（3072）	不可与其他优惠同享\n如需团购券发票，请在消费时向商户提出\n店内均可使用，仅限堂食。	使用说明。
service_phone	否	string（24）	40012234	客服电话。
color	是	string（3072）	Color010	卡券颜色。
location_id_list	否	string（3072）	1234,2314	支持更新适用门店列表。
center_title	否	string（18）	快速使用	顶部居中的自定义cell。
center_sub_title	否	string（24）	点击快速核销卡券	顶部居中的自定义cell说明。
center_url	否	string（128）	www.qq.com	顶部居中的自定义cell的跳转链接。
location_id_list	否	string（3072）	1234,2314	支持更新适用门店列表。
custom_url_name	否	string（16）	立即使用	自定义跳转入口的名字。
custom_url	否	string（128）	www.qq.com	自定义跳转的URL。
custom_url_sub_title	否	string（18）	更多惊喜	显示在入口右侧的提示语。
promotion_url_name	否	string（16）	产品介绍。	营销场景的自定义入口名称。
promotion_url	否	string（128）	www.qq.com；	入口跳转外链的地址链接。
promotion_url_sub_title	否	string（18）	卖场大优惠。	显示在营销入口右侧的提示语。
code_type	否	string（16）	CODE_TYPE_TEXT。	Code码展示类型，"CODE_TYPE_TEXT"，文本；"CODE_TYPE_BARCODE"，一维码 ；"CODE_TYPE_QRCODE"，二维码；"CODE_TYPE_ONLY_QRCODE",二维码无code显示；"CODE_TYPE_ONLY_BARCODE",一维码无code显示；"CODE_TYPE_NONE"，无code类型
get_limit	否	int	1	每人可领券的数量限制。
can_share	否	bool	false	卡券原生领取页面是否可分享。
can_give_friend	否	bool	false	卡券是否可转赠。
date_info	否	Json结构	见上述示例	使用日期，有效期的信息，有效期时间修改仅支持有效区间的扩大。
type	否	string	DATE_TYPE_FIX_TIME_RANGE	有效期类型，仅支持更改type为DATE_TYPE_FIX_TIME_RANGE 的时间戳。
begin_timestamp	否	unsigned int	14300000	固定日期区间专用，表示起用时间。（单位为秒）
end_timestamp	否	unsigned int	15300000	固定日期区间专用，表示结束时间。最长可将卡券有效期延长至三个月。

Advanced_info（卡券高级信息）字段修改：

特别注意，以下支持更新的字段不在基本信息base_info的结构中。

参数名	是否提审	类型	示例值	描述
advanced_info	是	JSON结构
abstract	否	JSON结构	优惠详情摘要字段。
abstract	否	string(60)	简介。	本券限领一张，不能与其他优惠共同使用。
icon_url_list	否	string(3072)	图片列表，仅支持填入一个封面图片链接，上传图片接口上传获取图片获得链接，填写非CDN链接会报错，并在此填入。建议图片尺寸像素900*375	http://mmbiz.qpic.cn/mmbiz/xxxxx
text_image_list	否	string(3072)	图文列表，显示在详情内页，优惠券券开发者须至少传入一组图文列表
image_url	否	string(3072)	图片链接，必须调用上传图片接口上传图片获得链接，并在此填入，否则报错	http://mmbiz.qpic.cn/mmbiz/xxxxx
text	否	string(3072)	图文描述，5000字以内	一般为商品详情介绍
business_service	否	string(24)	商家服务类型 可多选,此处仅控制展示，不填则不显示	BIZ_SERVICE_DELIVER 外卖服务；BIZ_SERVICE_FREE_PARK 停车位；BIZ_SERVICE_WITH_PET 可带宠物；BIZ_SERVICE_FREE_WIFI 免费Wi-Fi
time_limit	是	string(24)	使用时段限制
type	是	string（24）	MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 HOLIDAY 假期通用	限制类型，可多选,此处仅控制展示，不填则不显示
consume_share_self_num	是	int	核销后送券的数量，可设置核销后送本券的数量，限制传入1张，与consume_share_card_list互斥	1
consume_share_card_list	是	JSON	核销后赠送其他卡券的列表
card_id	是	string（24）	pbLatjhvf1xBtaOIhYOCnp7Wv4DA	核销后赠送的其他卡券card_id，目前仅支持填入一个共享券card_id，注意此处必须填入共享券
num	是	unsigned int	1	核销后赠送的该card_id数目，目前仅支持填1

返回数据说明

数据示例：

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

参数名	描述
errcode	错误码，0为正常。
errmsg	错误信息。
send_check	是否提交审核，false为修改后不会重新提审，true为修改字段后重新提审，该卡券的状态变为审核中。

拉取朋友的券数据接口

接口简介及开发注意事项

为支持开发者调用API查看卡券相关数据，微信卡券团队封装数据接口并面向具备卡券功能权限的开发者开放使用。开发者调用该接口可获取本商户下的所有卡券相关的总数据以及指定卡券的相关数据。

拉取卡券概况数据接口

接口说明

支持调用该接口拉取本商户的总体数据情况，包括时间区间内的各指标总量。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/datacube/getcardbizuininfo?access_token=ACCESS_TOKEN

请求参数说明

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

POST数据

{ "begin_date": "2015-06-15", //请开发者按示例格式填写日期，否则会报错dateformaterror"end_date": "2015-06-30", "cond_source": 0 }

参数说明：

字段	说明	是否必填	类型	示例值
begin_date	查询数据的起始时间。	是	string(16)	2015-06-15
end_date	查询数据的截至时间。	是	string(16)	2015-06-30
cond_source	卡券来源，0为公众平台创建的卡券数据、1是API创建的卡券数据	是	unsigned int	0

返回数据说明数据示例：

{ "list": [ { "ref_date": "2015-06-23", "view_cnt": 1, "view_user": 1, "receive_cnt": 1, "receive_user": 1, "verify_cnt": 0, "verify_user": 0, "given_cnt": 0, "given_user": 0, "expire_cnt": 0, "expire_user": 0 } ] }

字段说明：

字段	说明
ref_date	日期信息
view_cnt	浏览次数
view_user	浏览人数
receive_cnt	领取次数
receive_user	领取人数
verify_cnt	使用次数
verify_user	使用人数
given_cnt	转赠次数
given_user	转赠人数
expire_cnt	过期次数
expire_user	过期人数

注意：

1. 查询时间区间需<=62天，否则报错{errcode: 61501，errmsg: "date range error"}；

2. 传入时间格式需严格参照示例填写”2015-06-15”，否则报错{errcode":61500,"errmsg":"date format error"}

获取朋友的券数据接口

接口说明

支持开发者调用该接口拉取朋友的券在固定时间区间内的相关数据。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/datacube/getcardcardinfo?access_token=ACCESS_TOKEN

请求参数说明

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

POST数据

{ "begin_date": "2015-06-15", "end_date": "2015-06-30", "cond_source": 0, "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE" }

参数说明：

字段	说明	是否必填	类型	示例值
begin_date	查询数据的起始时间。	是	string(16)	2015-06-15
end_date	查询数据的截至时间。	是	string(16)	2015-06-30
cond_source	卡券来源，0为公众平台创建的卡券数据、1是API创建的卡券数据	是	unsigned int	0
card_id	卡券ID。填写后，指定拉出该卡券的相关数据。	否	string(32)	po8pktyDLmakNY2fn2VyhkiEPqGE

返回数据说明数据示例：

{ "list": [ { "ref_date": "2015-06-23", "card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE", "card_type": 3, "view_cnt": 1, "view_user": 1, "receive_cnt": 1, "receive_user": 1, "verify_cnt": 0, "verify_user": 0, "given_cnt": 0, "given_user": 0, "expire_cnt": 0, "expire_user": 0 } ] }

字段说明：

字段	说明
ref_date	日期信息
card_id	卡券ID
card_type	cardtype:0：折扣券，1：代金券，2：礼品券，3：优惠券，4：团购券（暂不支持拉取特殊票券类型数据，电影票、飞机票、会议门票、景区门票）
view_cnt	浏览次数
view_user	浏览人数
receive_cnt	领取次数
receive_user	领取人数
verify_cnt	使用次数
verify_user	使用人数
given_cnt	转赠次数
given_user	转赠人数
expire_cnt	过期次数
expire_user	过期人数

注意：

1. 查询时间区间需<=62天，否则报错{"errcode:" 61501，errmsg: "date range error"}；

2. 传入时间格式需严格参照示例填写如”2015-06-15”，否则报错｛"errcode":"date format error"｝

我是第三方开发者/服务商

朋友的券目前率先开通了MP流程，同样支持接口创建朋友的券。目前第三方/服务商可以利用现有能力帮助没有开发能力的商户创建、投放并核销朋友的券，并管理朋友的券数据。

第三方/服务商可以通过以下流程完成朋友的券基本流程：

1、第三方/服务商须登录微信开放平台申请成为公众号第三方平台，并全网发布。
2、商户通过公众号授权将公众账号的卡券权限集授权给第三方代调用接口。
3、开发者根据垂直行业特点，帮助商户完成创建朋友的券、投放朋友的券、 接口兑换库存、充值券点、核销朋友的券并完成朋友的券数据管理。
4、对于有能力的开发者可以融合第三方授权授权和第三方协助制券等模式搭建自己的 卡券平台供子商户使用。

交流反馈

朋友的券开发者可以加入开发者交流五群、六群（QQ群）：512568283、205482166，若开发过程中遇到问题，也可以发送邮件到weixin_card@foxmail.com 反馈。