管理卡券

柔光的暖阳◎ 2022-06-08 10:57 269阅读 0赞

目录  
1 查询Code接口  
2 获取用户已领取卡券接口  
3 查看卡券详情  
4 批量查询卡券列表  
5 更改卡券信息接口  
6 修改库存接口  
7 更改Code接口  
8 删除卡券接口  
9 设置卡券失效接口  
10 统计卡券数据  
10.1 拉取卡券概况数据接口  
10.2 获取免费券数据接口  
10.3 拉取会员卡概况数据接口  
10.4 拉取单张会员卡数据接口

查询Code接口  
查询code接口可以查询当前code是否可以被核销并检查code状态。当前可以被定位的状态为正常、已核销、转赠中、已删除、已失效和无效code。  
接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/code/get?access\_token=TOKEN][https_api.weixin.qq.com_card_code_get_access_token_TOKEN]

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

POST数据  
\{  
“card\_id” : “card\_id\_123+”,  
“code” : “123456789”,  
“check\_consume” : true  
\}

参数说明  
参数名 必填 类型 示例值 描述  
code 是 string(20) 110201201245 单张卡券的唯一标准。  
card\_id 否 string(32)  
pFS7Fjg8kV1I  
dDz01r4SQwMkuCKc  
卡券ID代表一类卡券。自定义code卡券必填。  
check\_consume 否 bool true 是否校验code核销状态，填入true和false时的code异常状态返回数据不同。

当check\_consume为true时返回数据  
卡券状态正常：  
\{  
“errcode”: 0,  
“errmsg”: “ok”,  
“card”: \{  
“card\_id”: “pbLatjk4T4Hx-QFQGL4zGQy27\_Qg”,  
“begin\_time”: 1457452800,  
“end\_time”: 1463155199  
\},  
“openid”: “obLatjm43RA5C6QfMO5szKYnT3dM”,  
“can\_consume”: true,  
“outer\_str”: “12b”,  
“user\_card\_status”: “NORMAL”  
\}  
卡券状态异常：  
\{  
“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”: “pbLatjk4T4Hx-QFQGL4zGQy27\_Qg”,  
“begin\_time”: 1457452800,  
“end\_time”: 1463155199  
\},  
“openid”: “obLatjm43RA5C6QfMO5szKYnT3dM”,  
“can\_consume”: true,  
“outer\_str”: “12b”,  
“user\_card\_status”: “NORMAL”  
\}  
卡券状态异常：  
\{  
“errcode”: 0,  
“errmsg”: “ok”,  
“card”: \{  
“card\_id”: “pbLatjnK8NLbWgwMgfMtnj3gaglw”,  
“begin\_time”: 1457625600,  
“end\_time”: 1460217599  
\},  
“openid”: “obLatjm43RA5C6QfMO5szKYnT3dM”,  
“can\_consume”: false,  
“outer\_str”: “12b”,  
“user\_card\_status”: “GIFTING”  
\}

参数名 描述  
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  
outer\_str 卡券领取时商户传入的渠道值  
can\_consume 是否可以核销，true为可以核销，false为不可核销

注意事项：  
1.固定时长有效期会根据用户实际领取时间转换，如用户2013年10月1日领取，固定时长有效期为90天，即有效时间为2013年10月1日-12月29日有效。  
2.无论check\_consume填写的是true还是false,当code未被添加或者code被转赠领取是统一报错：invalid serial code

获取用户已领取卡券接口  
用于获取用户卡包里的，属于该appid下所有可用卡券，包括正常状态和异常状态。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/user/getcardlist?access\_token=TOKEN][https_api.weixin.qq.com_card_user_getcardlist_access_token_TOKEN]

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

POST数据  
\{  
“openid”: “12312313”,  
“card\_id”: “xxxxxxxxxx”  
\}

参数说明  
参数名 必填 类型 示例值 描述  
openid 是 string(64) 1231231 需要查询的用户openid  
card\_id 否 string(32) pFS7Fjg8kV1IdDz01xxxxx 卡券ID。不填写时默认查询当前appid下的卡券。

返回数据  
\{  
“errcode”:0,  
“errmsg”:”ok”,  
“card\_list”: \[  
\{“code”: “xxx1434079154”, “card\_id”: “xxxxxxxxxx”\},  
\{“code”: “xxx1434079155”, “card\_id”: “xxxxxxxxxx”\}  
\]，  
“has\_share\_card”: true  
\}

参数说明

参数名 描述  
errcode 错误码  
errmsg 错误信息  
card\_list 卡券列表  
has\_share\_card 是否有可用的朋友的券

查看卡券详情  
开发者可以调用该接口查询某个card\_id的创建信息、审核状态以及库存数量。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/get?access\_token=TOKEN][https_api.weixin.qq.com_card_get_access_token_TOKEN]

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

POST数据  
\{  
“card\_id”:”pFS7Fjg8kV1IdDz01r4SQwMkuCKc”  
\}  
参数名 必填 类型 示例值 描述  
card\_id 是 string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID。

返回数据  
\{  
“errcode”: 0,  
“errmsg”: “ok”,  
“card”: \{  
“card\_type”: “DISCOUNT”,  
“discount”: \{  
“base\_info”: \{  
“id”: “pbLatjnP97\_F9PudzBARQhn7xR7A”,  
“logo\_url”: “[http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafmY25YclQ7vw5noBxeVH3DG5AKFR1ZsRgMgsvjll7EkUsZib00J964AEpTjkNXF2HorJHt5mtt45Q/0?wx\_fmt=png][http_mmbiz.qpic.cn_mmbiz_p98FjXy8LafmY25YclQ7vw5noBxeVH3DG5AKFR1ZsRgMgsvjll7EkUsZib00J964AEpTjkNXF2HorJHt5mtt45Q_0_wx_fmt_png]“,  
“code\_type”: “CODE\_TYPE\_NONE”,  
“brand\_name”: “微信餐厅”,  
“title”: “9折优惠券”,  
“date\_info”: \{  
“type”: “DATE\_TYPE\_FIX\_TERM”,  
“fixed\_term”: 30,  
“fixed\_begin\_term”: 0  
\},  
“color”: “\#10AD61”,  
“notice”: “到店使用”,  
“description”: “”,  
“location\_id\_list”: \[  
218384742,  
402521653,  
402521608  
\],  
“get\_limit”: 3,  
“can\_share”: true,  
“can\_give\_friend”: true,  
“status”: “CARD\_STATUS\_VERIFY\_OK”,  
“sku”: \{  
“quantity”: 100096,  
“total\_quantity”: 100100  
\},  
“create\_time”: 1457525546,  
“update\_time”: 1457526240,  
“area\_code\_list”: \[\]  
\},  
“discount”: 10,  
“advanced\_info”: \{  
“time\_limit”: \[  
\{  
“type”: “MONDAY”  
\},  
\{  
“type”: “TUESDAY”  
\}  
\],  
“text\_image\_list”: \[\],  
“business\_service”: \[\],  
“consume\_share\_card\_list”: \[\],  
“abstract”: \{  
“abstract”: “点击了解更多”,  
“icon\_url\_list”: \[  
“[http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ/0?wx\_fmt=jpeg][http_mmbiz.qpic.cn_mmbiz_p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ_0_wx_fmt_jpeg]”  
\]  
\},  
“share\_friends”: false  
\}  
\}  
\}  
\}  
参数名 描述  
card\_type 卡券类型。  
团购券：GROUPON; 折扣券：DISCOUNT; 礼品券：GIFT;  
代金券：CASH; 通用券：GENERAL\_COUPON;  
会员卡：MEMBER\_CARD; 景点门票：SCENIC\_TICKET；  
电影票：MOVIE\_TICKET； 飞机票：BOARDING\_PASS；  
会议门票：MEETING\_TICKET； 汽车票：BUS\_TICKET;  
base\_info 基本的卡券数据，见下表，所有卡券通用。  
deal\_detail 团购券专用字段，团购详情。  
gift 礼品券专用，表示礼品名字。  
least\_cost least\_cost字段为代金券专用，表示起用金额（单位为分）。  
reduce\_cost 代金券专用，表示减免金额（单位为分）  
discount 折扣券专用字段，表示打折额度（百分比），例：填30为七折团购详情。  
supply\_balance 会员卡专属字段，表示是否支持积分，填写true或false，如填写true，积分相关字段均为必填，会员卡专用。  
supply\_bonus 会员卡专属字段，表示否支持储值，填写true或false，如填写true，储值相关字段均为必填，会员卡专用。  
bonus\_cleared 积分清零规则，会员卡专用。  
bonus\_rules 积分规则，会员卡专用。  
balance\_rules 储值规则，会员卡专用。  
prerogative 会员卡专属字段，表示特权说明，会员卡专用。  
bind\_old\_card\_url 绑定旧卡的url，会员卡专用。  
activate\_url 激活会员卡，会员卡专用。  
need\_push\_on\_view 进入会员卡时是否推送事件，填写true或false，会员卡专用。  
from 飞机票的起点，上限为18个汉字，机票专用。  
to 飞机票的终点，上限为18个汉字，机票专用。  
flight 航班，机票专用。  
departure\_time 起飞时间，机票专用。（Unix时间戳格式）  
landing\_time 降落时间，机票专用。（Unix时间戳格式）  
check\_in\_url 在线值机的链接，机票专用。  
gate 登机口。如发生登机口变更，建议商家实时调用该接口变更，机票专用。  
boarding\_time 登机时间，只显示“时分”不显示日期，机票专用。（Unix时间戳格式）  
meeting\_detail 会议详情，会议门票专用。  
map\_url 会场导览图，会议门票专用。

base\_info字段：

参数名 描述  
logo\_url 卡券的商户logo，建议像素为300\*300。  
code\_type  
“CODE\_TYPE\_TEXT”，文本；  
“CODE\_TYPE\_BARCODE”，一维码 ；  
“CODE\_TYPE\_QRCODE”，二维码；  
“CODE\_TYPE\_ONLY\_QRCODE”,二维码无code显示；  
“CODE\_TYPE\_ONLY\_BARCODE”,一维码无code显示；  
brand\_name  
商户名字（填写直接提供服务的商户名  
，第三方商户名填写在source字段）。  
title 卡券名。  
color 卡券的背景颜色。  
notice 使用提醒，字数上限为16个汉字。  
description 使用说明。长文本描述。  
date\_info 使用日期，有效期的信息。  
type  
使用时间的类型  
DATE\_TYPE\_FIX\_TIME\_RANGE 表示固定日期区间，DATE\_TYPE\_FIX\_TERM表示固定时长（自领取后按天算），DATE\_TYPE\_PERMANENT 表示永久有效（会员卡类型专用）。  
begin\_timestamp  
type为DATE\_TYPE\_FIX\_TIME\_RANGE时专用  
，表示起用时间。从1970年1月1日00:00:00至起用时间的秒数，最终需转换为字符串形态传入，下同。（单位为秒）  
end\_timestamp  
type为DATE\_TYPE\_FIX\_TIME\_RANGE时专用  
，表示结束时间。（单位为秒）  
fixed\_term  
type为DATE\_TYPE\_FIX\_TERM时专用  
，表示自领取后多少天内有效，领取后当天有效填写0。  
（单位为天）  
fixed\_begin\_term  
type为DATE\_TYPE\_FIX\_TERM时专用  
，表示自领取后多少天开始生效。（单位为天）  
sku 商品信息  
quantity 卡券现有库存的数量  
total\_quantity 卡券全部库存的数量，上限为100000000。  
location\_id\_list 门店位置ID。  
use\_all\_locations  
支持全部门店，填写true或false，与location\_id\_list互斥  
use\_custom\_code 是否自定义Code码。填写true或false，默认为false。  
bind\_openid 是否指定用户领取，填写true或false。默认为否。  
can\_share  
卡券是否可转赠，填写true或false,true代表可转赠  
默认为true。  
service\_phone 客服电话。  
source 第三方来源名，例如同程旅游、大众点评。  
custom\_url\_name 商户自定义入口名称。  
custom\_url 商户自定义入口跳转外链的地址链接,跳转页面内容需与自定义cell名称保持匹配。  
custom\_url\_sub\_title 显示在入口右侧的tips，长度限制在6个汉字内。  
promotion\_url\_name 营销场景的自定义入口。  
promotion\_url 入口跳转外链的地址链接。  
promotion\_url\_sub\_title 显示在营销入口右侧的提示语。  
custom\_url\_name 商户自定义入口名称。  
status  
“CARD\_STATUS\_NOT\_VERIFY”,待审核；  
“CARD\_STATUS\_VERIFY\_FAIL”,审核失败；  
“CARD\_STATUS\_VERIFY\_OK”，通过审核；  
“CARD\_STATUS\_DELETE”，卡券被商户删除；  
“CARD\_STATUS\_DISPATCH”，在公众平台投放过的卡券；

开发者注意事项  
1.对于部分有特殊权限的商家，查询卡券详情得到的返回可能含特殊接口的字段。  
2.由于卡券字段会持续更新，实际返回字段包含但不限于文档中的字段，建议开发者开发时对于不理解的字段不做处理，以免出错。

批量查询卡券列表  
接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/batchget?access\_token=TOKEN][https_api.weixin.qq.com_card_batchget_access_token_TOKEN]

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

POST数据  
\{  
“offset”: 0,  
“count”: 10,  
“status\_list”: \[“CARD\_STATUS\_VERIFY\_OK”, “CARD\_STATUS\_DISPATCH”\]  
\}

参数名 必填 类型 示例值 描述  
offset 是 int 0 查询卡列表的起始偏移量，从0开始，即offset: 5是指从从列表里的第六个开始读取。  
count 是 int 10 需要查询的卡片的数量（数量最大50）。  
status\_list 否 string(32)  
CARD\_STATU  
S\_VERIFY\_OK  
支持开发者拉出指定状态的卡券列表  
“CARD\_STATUS\_NOT\_VERIFY”,  
待审核；  
“CARD\_STATUS\_VERIFY\_FAIL”,  
审核失败；  
“CARD\_STATUS\_VERIFY\_OK”，  
通过审核；  
“CARD\_STATUS\_DELETE”，  
卡券被商户删除；  
“CARD\_STATUS\_DISPATCH”，  
在公众平台投放过的卡券；

返回数据

\{  
“errcode”:0,  
“errmsg”:”ok”,  
“card\_id\_list”:\[“ph\_gmt7cUVrlRk8swPwx7aDyF-pg”\],  
“total\_num”:1  
\}

参数名 描述  
errcode 错误码，0为正常。  
errmsg 错误信息。  
card\_id\_list 卡券ID列表。  
total\_num 该商户名下卡券ID总数。

注意事项：  
1.未传入筛选条件时，该接口默认传回该商户名下所有状态的卡券；  
2.开发者可以请求之后调用查看卡券详情接口确定卡券状态；

更改卡券信息接口

接口说明  
支持更新所有卡券类型的部分通用字段及特殊卡券（会员卡、飞机票、电影票、会议门票）中特定字段的信息。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/update?access\_token=TOKEN][https_api.weixin.qq.com_card_update_access_token_TOKEN]

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

POST数据  
\{  
“card\_id”:”ph\_gmt7cUVrlRk8swPwx7aDyF-pg”,  
“member\_card”: \{ //填写该cardid相应的卡券类型（小写）。  
“base\_info”: \{  
“logo\_url”: “http:\\/\\/www.supadmin.cn\\/uploads\\/allimg\\/120216\\/1\_120216214725\_1.jpg”,  
“color”: “Color010”,  
“notice”: “使用时向服务员出示此券”,  
“service\_phone”: “020-88888888”,  
“description”: “不可与其他优惠同享\\n如需团购券发票，请在消费时向商户提出\\n店内均可使用，  
仅限堂食\\n餐前不可打包，餐后未吃完，可打包\\n本团购券不限人数，建议2人使用，  
超过建议人数须另收酱料费5元/位\\n本单谢绝自带酒水饮料”  
“location\_id\_list” : \[123, 12321, 345345\]  
\},  
“bonus\_cleared”: “aaaaaaaaaaaaaa”,  
“bonus\_rules”: “aaaaaaaaaaaaaa”,  
“prerogative”: “”  
\}  
\}

通用字段修改：

参数名 是否提审 类型 示例值 描述  
base\_info - JSON接口 见上述示例 卡券基础信息字段。  
logo\_url 是 string(128) mmbiz.qpic.cn/ 卡券的商户logo，建议像素为300\*300。  
notice 是 string（48） 请出示二维码核销卡券。 使用提醒，字数上限为16个汉字。  
description 是 string（3072） 不可与其他优惠同享 使用说明。  
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.xxx.com 顶部居中的自定义cell的跳转链接。  
location\_id\_list 否 string（3072） 1234,2314  
支持更新适用门店列表  
，清空门店更新时传“0”  
custom\_url\_name 否 string（16） 立即使用 自定义跳转入口的名字。  
custom\_url 否 string（128） “xxxx.com”。 自定义跳转的URL。  
custom\_url\_sub\_title 否 string（18） 更多惊喜 显示在入口右侧的提示语。  
promotion\_url\_name 否 string（16） 产品介绍。 营销场景的自定义入口名称。  
promotion\_url 否 string（128） XXXX.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显示；  
get\_limit 否 int 1 每人可领券的数量限制。  
can\_share 否 bool false 卡券原生领取页面是否可分享。  
can\_give\_friend 否 bool false 卡券是否可转赠。  
date\_info 否 Json结构 见上述示例 使用日期，有效期的信息，有效期时间修改仅支持有效区间的扩大。  
type 否 string  
DATE\_TYPE\_FI  
X\_TIME\_RANGE  
有效期类型，仅支持更改type为DATE\_TYPE\_FIX\_TIME\_RANGE 的时间戳，不支持填入DATE\_TYPE\_FIX\_TERM。  
begin\_timestamp 否 unsigned int 14300000 固定日期区间专用，表示起用时间。（单位为秒）  
end\_timestamp 否 unsigned int 15300000 固定日期区间专用，表示结束时间。结束时间仅支持往后延长。

不同类型卡券专属字段修改：  
特别注意，以下支持更新的字段不在基本信息base\_info的结构中。

参数名 是否提审 类型 示例值 描述  
bonus\_cleared 是 string(3072) 每年12月30号积分清0。 积分清零规则，会员卡专用。  
bonus\_rules 是 string(3072) 每消费1元增加1积分。 积分规则，会员卡专用。  
balance\_rules 是 string(3072) 支持在线充入余额。 储值说明，会员卡专用。  
prerogative 是 string(3072) XX会员可享有全场商品8折优惠。 特权说明，会员卡专用。  
custom\_field1 否 JSON结构 见创建会员卡示例。 自定义会员信息类目，会员卡激活后显示，会员卡专用。  
custom\_field2 否 JSON结构 见创建会员卡示例。 自定义会员信息类目，会员卡激活后显示，会员卡专用。  
custom\_field3 否 JSON结构 见创建会员卡示例。 自定义会员信息类目，会员卡激活后显示，会员卡专用。  
name\_type 否 string(24)  
FIELD\_NAME  
\_TYPE\_LEVEL  
会员信息类目名称。FIELD\_NAME\_TYPE\_LEVEL等级；FIELD\_NAME\_TYPE\_COUPON优惠券；FIELD\_NAME\_TYPE\_STAMP印花；FIELD\_NAME\_TYPE\_DISCOUNT折扣；FIELD\_NAME\_TYPE\_ACHIEVEMEN成就；FIELD\_NAME\_TYPE\_MILEAGE里程。  
url 否 string（128） xxx.com 点击类目跳转外链url  
custom\_cell1 否 JSON结构 见上述示例。 自定义会员信息类目，会员卡激活后显示。  
detail 是 string(3072) 电影名：复仇者联盟2。/n放映时间：2015年5月12日23:00。/n票类型：3D。 电影票详情。  
departure\_time 否 unsigned int 1431271351 起飞时间。  
landing\_time 否 unsigned int 1441271351 降落时间。  
gate 否 string(12) 3号 登机口。如发生登机口变更，建议商家实时调用该接口变更。  
boarding\_time 否 unsigned int 1431271351 登机时间，只显示“时分”不显示日期，按Unix时间戳格式填写。如发生登机时间变更，建议商家实时调用该接口变更。  
guide\_url 否 string(128) www.qq.com 景区门票的导览图URL。  
map\_url 否 string(128) xxx.com。 会场导览图。

返回数据说明  
\{  
“errcode”:0,  
“errmsg”:”ok”,  
“send\_check”:false  
\}

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

开发者注意事项注  
1. 请开发者注意需要重新提审的字段，开发者调用更新接口时，若传入了提审字段则卡券需要重新进入审核状态；  
2. 接口更新方式为覆盖更新：即开发者只需传入需要更改的字段，其他字段无需填入，否则可能导致卡券重新提审；  
3. 若开发者置空某些字段，可直接在更新时传“”（空）；  
4. 调用该接口后更改卡券信息后，请务必调用查看卡券详情接口验证是否已成功更改，  
5.未列出的字段不支持修改更新。

修改库存接口  
调用修改库存接口增减某张卡券的库存。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/modifystock?access\_token=TOKEN][https_api.weixin.qq.com_card_modifystock_access_token_TOKEN]

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

POST数据  
\{  
“card\_id”: “pFS7Fjg8kV1IdDz01r4SQwMkuCKc”,  
“increase\_stock\_value”: 1231231,  
“reduce\_stock\_value”: 1231231  
\}

参数名 必填 类型 示例值 描述  
card\_id 是 string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID。  
increase\_stock\_value 否 int 1231231 增加多少库存，支持不填或填0。  
reduce\_stock\_value 否 int 1231231 减少多少库存，可以不填或填0。

返回数据  
\{  
“errcode”:0,  
“errmsg”:”ok”  
\}

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

更改Code接口

为确保转赠后的安全性，微信允许自定义Code的商户对已下发的code进行更改。 注：为避免用户疑惑，建议仅在发生转赠行为后（发生转赠后，微信会通过事件推送的方式告知商户被转赠的卡券Code）对用户的Code进行更改。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/code/update?access\_token=TOKEN][https_api.weixin.qq.com_card_code_update_access_token_TOKEN]

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

POST数据  
\{  
“code”: “12345678”,  
“card\_id”: “pFS7Fjg8kV1IdDz01r4SQwMkuCKc”,  
“new\_code”: “3495739475”  
\}  
参数名 必填 类型 示例值 描述  
card\_id 否 string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID。自定义Code码卡券为必填。  
code 是 string(16) 110201201245 需变更的Code码。  
new\_code 是 string(64) 1231231 变更后的有效Code码。

返回数据  
\{  
“errcode”:0,  
“errmsg”:”ok”,  
\}

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

删除卡券接口  
删除卡券接口允许商户删除任意一类卡券。删除卡券后，该卡券对应已生成的领取用二维码、添加到卡包JS API均会失效。 注意：如用户在商家删除卡券前已领取一张或多张该卡券依旧有效。即删除卡券不能删除已被用户领取，保存在微信客户端中的卡券。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/delete?access\_token=TOKEN][https_api.weixin.qq.com_card_delete_access_token_TOKEN]

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

POST数据  
\{  
“card\_id”: “pFS7Fjg8kV1IdDz01r4SQwMkuCKc”  
\}  
参数名 必填 类型 示例值 描述  
card\_id 是 string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID。

返回数据  
\{  
“errcode”:0,  
“errmsg”:”ok”  
\}

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

设置卡券失效接口

为满足改票、退款等异常情况，可调用卡券失效接口将用户的卡券设置为失效状态。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/card/code/unavailable?access\_token=TOKEN][https_api.weixin.qq.com_card_code_unavailable_access_token_TOKEN]

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

POST数据  
非自定义卡券的请求  
\{  
“code”: “12312313”,  
“reason”:”退款”  
\}  
或自定义code卡券的请求。  
\{  
“code”: “12312313”,  
“card\_id”: “pFS7Fjg8kV1IdDz01r4SQwMkuCKc”  
\}  
参数名 必填 类型 示例值 描述  
card\_id 是 string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID。  
code 是 string(20) 1231231 设置失效的Code码。  
reason 否 string(64) 用户发生退款 失效理由

返回数据  
\{  
“errcode”:0,  
“errmsg”:”ok”,  
\}

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

注意事项：

1.设置卡券失效的操作不可逆，即无法将设置为失效的卡券调回有效状态，商家须慎重调用该接口。  
2.商户调用失效接口前须与顾客事先告知并取得同意，否则因此带来的顾客投诉，微信将会按照《微信运营处罚规则》进行处罚。

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

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

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/datacube/getcardbizuininfo?access\_token=ACCESS\_TOKEN][https_api.weixin.qq.com_datacube_getcardbizuininfo_access_token_ACCESS_TOKEN]  
请求参数说明  
参数 是否必须 说明  
access\_token 是 调用接口凭证  
POST数据 是 Json数据

POST数据  
｛  
“begin\_date”:”2015-06-15”, //请开发者按示例格式填写日期，否则会报错date format error  
“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”\}  
3. 该接口只能拉取非当天的数据，不能拉取当天的卡券数据，否则报错。

获取免费券数据接口  
接口说明  
支持开发者调用该接口拉取免费券（优惠券、团购券、折扣券、礼品券）在固定时间区间内的相关数据。

接口调用请求说明  
http请求方式: POSThttps://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. 该接口目前仅支持拉取免费券（优惠券、团购券、折扣券、礼品券）的卡券相关数据，暂不支持特殊票券（电影票、会议门票、景区门票、飞机票）数据。  
2. 查询时间区间需<=62天，否则报错\{“errcode:” 61501，errmsg: “date range error”\}；  
3. 传入时间格式需严格参照示例填写如”2015-06-15”，否则报错｛”errcode”:”date format error”｝  
4. 该接口只能拉取非当天的数据，不能拉取当天的卡券数据，否则报错。

拉取会员卡概况数据接口  
接口说明  
支持开发者调用该接口拉取公众平台创建的会员卡相关数据。

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/datacube/getcardmembercardinfo?access\_token=ACCESS\_TOKEN][https_api.weixin.qq.com_datacube_getcardmembercardinfo_access_token_ACCESS_TOKEN]

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

POST数据  
｛  
“begin\_date”:”2015-06-15”,  
“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”: 0,  
“view\_user”: 0,  
“receive\_cnt”: 0,  
“receive\_user”: 0,  
“active\_user”: 0,  
“verify\_cnt”: 0,  
“verify\_user”: 0,  
“total\_user”: 86,  
“total\_receive\_user”: 95  
\]  
\}

字段说明：

字段 说明  
ref\_date 日期信息  
view\_cnt 浏览次数  
view\_user 浏览人数  
receive\_cnt 领取次数  
receive\_user 领取人数  
verify\_cnt 使用次数  
verify\_user 使用人数  
active\_user 激活人数  
total\_user 有效会员总人数  
total\_receive\_user 历史领取会员卡总人数

拉取单张会员卡数据接口  
接口说明  
支持开发者调用该接口拉取API创建的会员卡数据情况

接口调用请求说明  
HTTP请求方式: POST  
URL:[https://api.weixin.qq.com/datacube/getcardmembercarddetail?access\_token=ACCESS\_TOKEN][https_api.weixin.qq.com_datacube_getcardmembercarddetail_access_token_ACCESS_TOKEN]

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

POST数据  
｛  
“begin\_date”:”2015-06-15”,  
“end\_date”:”2015-06-30”,  
“card\_id”:”xxxxxxxxxxxxxxxx”  
｝

参数说明：

字段 说明 是否必填 类型 示例值  
begin\_date 查询数据的起始时间。 是 string(16) 2015-06-15  
end\_date 查询数据的截至时间。 是 string(16) 2015-06-30  
card\_id 卡券id 是 string(32)  
p4WkzwieuDBzzn7Jed6SBO0-ZgaU

返回数据说明 ：  
\{  
“list”: \[  
\{  
“ref\_date”: “2016-07-06”,  
“merchanttype”: 2,  
“cardid”: “p4WkzwieuDBzzn7Jed6SBO0-ZgaU”,  
“submerchantid”: 0,  
“view\_cnt”: 2,  
“view\_user”: 1,  
“receive\_cnt”: 1,  
“receive\_user”: 1,  
“verify\_cnt”: 0,  
“verify\_user”: 0,  
“active\_cnt”: 1,  
“active\_user”: 1,  
“total\_user”: 249,  
“new\_user”: 0,  
“payOriginalFee”: 0,  
“fee”: 0  
\}  
\]  
\}  
字段说明：

字段 说明  
ref\_date 日期信息  
merchanttype 子商户类型  
submerchantid 子商户ID  
view\_cnt 浏览次数  
view\_user 浏览人数  
receive\_cnt 领取次数  
receive\_user 领取人数  
verify\_cnt 使用次数  
verify\_user 使用人数  
active\_user 激活人数  
total\_user 有效会员总人数  
total\_receive\_user 历史领取会员卡总人数  
new\_user 新用户数  
payOriginalFee 应收金额（仅限使用快速买单的会员卡）  
fee 实收金额（仅限使用快速买单的会员卡）

[https_api.weixin.qq.com_card_code_get_access_token_TOKEN]: https://api.weixin.qq.com/card/code/get?access_token=TOKEN
[https_api.weixin.qq.com_card_user_getcardlist_access_token_TOKEN]: https://api.weixin.qq.com/card/user/getcardlist?access_token=TOKEN
[https_api.weixin.qq.com_card_get_access_token_TOKEN]: https://api.weixin.qq.com/card/get?access_token=TOKEN
[http_mmbiz.qpic.cn_mmbiz_p98FjXy8LafmY25YclQ7vw5noBxeVH3DG5AKFR1ZsRgMgsvjll7EkUsZib00J964AEpTjkNXF2HorJHt5mtt45Q_0_wx_fmt_png]: http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafmY25YclQ7vw5noBxeVH3DG5AKFR1ZsRgMgsvjll7EkUsZib00J964AEpTjkNXF2HorJHt5mtt45Q/0?wx_fmt=png
[http_mmbiz.qpic.cn_mmbiz_p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ_0_wx_fmt_jpeg]: http://mmbiz.qpic.cn/mmbiz/p98FjXy8LafiawSeJeqBzk8qC40iaKIwUPm4TSCelulzEbAywKr7tWjkd5vRjbmFloUFeThfwhwMUZIXmsCtJpyQ/0?wx_fmt=jpeg
[https_api.weixin.qq.com_card_batchget_access_token_TOKEN]: https://api.weixin.qq.com/card/batchget?access_token=TOKEN
[https_api.weixin.qq.com_card_update_access_token_TOKEN]: https://api.weixin.qq.com/card/update?access_token=TOKEN
[https_api.weixin.qq.com_card_modifystock_access_token_TOKEN]: https://api.weixin.qq.com/card/modifystock?access_token=TOKEN
[https_api.weixin.qq.com_card_code_update_access_token_TOKEN]: https://api.weixin.qq.com/card/code/update?access_token=TOKEN
[https_api.weixin.qq.com_card_delete_access_token_TOKEN]: https://api.weixin.qq.com/card/delete?access_token=TOKEN
[https_api.weixin.qq.com_card_code_unavailable_access_token_TOKEN]: https://api.weixin.qq.com/card/code/unavailable?access_token=TOKEN
[https_api.weixin.qq.com_datacube_getcardbizuininfo_access_token_ACCESS_TOKEN]: https://api.weixin.qq.com/datacube/getcardbizuininfo?access_token=ACCESS_TOKEN
[https_api.weixin.qq.com_datacube_getcardmembercardinfo_access_token_ACCESS_TOKEN]: https://api.weixin.qq.com/datacube/getcardmembercardinfo?access_token=ACCESS_TOKEN
[https_api.weixin.qq.com_datacube_getcardmembercarddetail_access_token_ACCESS_TOKEN]: https://api.weixin.qq.com/datacube/getcardmembercarddetail?access_token=ACCESS_TOKEN