开通VIP，畅享免费电子书等14项超值服
首页
好书
留言交流
下载APP
联系客服
2021.06.23
以下是卡券开发过程中需要了解的关键概念：
申请一个公众平台账号
公众号开发信息配置
填写服务器配置并验证有效性
下面详细介绍这3个步骤。
账号申请完成后，我们进入公众平台官网的开发-基本配置页面，首先完成公众号开发信息配置，包括启用开发者密码(AppSecret)和配置IP白名单
然后，继续下面的服务器配置点击修改配置按钮，填写服务器地址（URL）、Token和EncodingAESKey，其中
Token可由开发者可以任意填写，用作生成签名
该Token会和接口URL中包含的Token进行比对，因此填写的url地址内需要实现返回业务逻辑，下面会有代码示例，从而验证安全性）。
EncodingAESKey由开发者手动填写或随机生成，将用作消息体加解密密钥。
同时，开发者可选择消息加解密方式：
将token、timestamp、nonce三个参数进行字典序排序
将三个参数字符串拼接成一个字符串进行sha1加密
检验signature的PHP示例代码：
注意
配置好商户开发信息后，商户开发者可依据接口文档实现业务逻辑。
普通卡券包含：代金券、团购券、优惠券、折扣券、兑换券
普通卡券特点
注：以下示例针对普通卡券操作
access_token是公众号的全局唯一接口调用凭据，公众号调用各接口时都需使用access_token。开发者需要进行妥善保存。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的access_token失效。
接口调用
请求参数
响应参数
{'access_token':'ACCESS_TOKEN','expires_in':7200}112.上传卡券Logo接口调用
HTTP请求方式:POST/FROM（表单形式提交Logo图片）
响应报文
适用场景
选择卡券背景适用色值
在创建卡券接口中将颜色名（如Color010）填入color字段。
经过上述步骤之后，我们可调用创建卡券接口来创建一类新的卡券，获取card_id。创建卡券成功并通过审核后，商家可以通过文档提供的其他接口将卡券下发给用户，每次成功领取，库存数量相应扣除。
HTTP请求方式:POST
请求参数说明
POST数据示例请参考扩展《卡券创建接口POST报文示例》
普通卡券字段示例会员卡字段示例POST数据格式如下
团购券
{'card':{'card_type':'GROUPON','groupon':{'base_info':{················},'advanced_info':{················},'deal_detail':'示例'}}}12345678910111213141234567891011121314参数名必填类型示例值描述card_type是string(24)GROUPON团购券类型。base_info是JSON结构见扩展《卡券创建接口POST报文示例》基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。advanced_info否JSON结构见扩展《卡券创建接口POST报文示例》卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。deal_detail是string(3072)双人套餐\n-进口红酒一支。\n孜然牛肉一份。团购券专用，团购详情。代金券
折扣券
{'card':{'card_type':'DISCOUNT','discount':{'base_info':{················},'advanced_info':{················},'discount':30}}}12345678910111213141234567891011121314参数名必填类型示例值描述card_type是string(24)DISCOUNT折扣券类型。base_info是Json结构见扩展《卡券创建接口POST报文示例》基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。advanced_info否JSON结构见扩展《卡券创建接口POST报文示例》卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。discount是int30折扣券专用，表示打折额度（百分比）。填30就是七折。兑换券
优惠券
{'card':{'card_type':'GENERAL_COUPON','general_coupon':{'base_info':{················},'advanced_info':{················},'default_detail':'优惠券专用，填写优惠详情'}}}12345678910111213141234567891011121314参数名必填类型示例值描述card_type是string(24)GENERAL_COUPON优惠券类型。base_info是Json结构见扩展《卡券创建接口POST报文示例》基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。advanced_info否JSON结构见扩展《卡券创建接口POST报文示例》卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。default_detail是string(3072)音乐木盒。优惠券专用，填写优惠详情。卡券创建返回报文格式
高级字段为商户额外展示信息字段，非必填,但是填入某些结构体后，须填充完整方可显示：如填入text_image_list结构体时，须同时传入image_url和text，否则也会报错；
预存code模式的卡券须设置quantity为0，导入code后方可增加库存；
注意：最新版本卡券API接口已经不允许使用URL替代方案为小程序。
为了满足商户基于卡券本身的扩展诉求，允许卡券内页添加url跳转外链。带有的的字段有encrypt_code、card_id。
卡券投放类型有：二维码投放、JS-SDK投放、卡券货架投放、群发卡券
二维码方式投放，开发者可调用该接口生成一张卡券二维码供用户扫码后添加到卡券卡包。
POST数据示例
投放单张卡券（非自定义卡券code码无需指定code，非指定用户领取无需指定openid）
{'action_name':'QR_CARD','expire_seconds':1800,'action_info':{'card':{'card_id':'pFS7Fjg8kV1IdDz01r4SQwMkuCKc','code':'198374613512',//自定义Code码的卡券单张投放'openid':'oFS7Fjl0WsZ9AMZqrI80nbIq8xrA',//指定用户可领'is_unique_code':false,'outer_str':'12b'}}}1234567891011121312345678910111213投放多张卡券（一次最多填入5个card_id,否则报错）
POST参数说明
返回参数
注意事项
注意：
目前卡券货架仅支持非自定义code卡券，自定义code卡券需先调用导入code接口，将code导入才能正常使用；
由于卡券有审核要求，为方便公众号调试，可以设置一些测试账号，这些账号可领取未通过审核的卡券，体验整个流程。
调用接口
卡券API接口核销类型
线下核销：指用户到店后，出示二维码或者出示串码，由收银员完成核销动作，如扫码核销、机具核销等
1.查询Code接口
开发者在调用核销code接口之前调用查询code接口，并在核销之前对非法状态的code(如转赠中、已删除、已核销等)做出处理。
POST数据
返回数据(这里以check_consume=true为例)
正常状态
{'errcode':0,'errmsg':'ok','card':{'card_id':'pbLatjk4T4Hx-QFQGL4zGQy27_Qg','begin_time':1457452800,'end_time':1463155199},'openid':'obLatjm43RA5C6QfMO5szKYnT3dM','can_consume':true,'user_card_status':'NORMAL'}123456789101112123456789101112异常状态
2.核销Code接口
消耗code接口是核销卡券的唯一接口,开发者可以调用当前接口将用户的优惠券进行核销，该过程不可逆。
非自定义Code卡券POST数据为
{'code':'12312313'}123123自定义Code卡券的POST数据还需要code_id
返回数据
{'errcode':0,'errmsg':'ok','card':{'card_id':'pFS7Fjg8kV1IdDz01r4SQwMkuCKc'},'openid':'oFS7Fjl0WsZ9AMZqrI80nbIq8xrA'}1234567812345678参数名描述errcode错误码。errmsg错误信息。openid用户在该公众号内的唯一身份标识。card_id卡券ID。注意事项
仅支持核销有效状态的卡券，若卡券处于异常状态，均不可核销。（异常状态包括：卡券删除、未生效、过期、转赠中、转赠退回、失效）;
自定义Code码（use_custom_code为true）的优惠券，在code被核销时，必须调用此接口。用于将用户客户端的code状态变更。自定义code的卡券调用接口时，post数据中需包含card_id，否则报invalidserialcode，非自定义code不需上报；
获取api-ticket
由于获取api_ticket的api调用次数非常有限，频繁刷新api_ticket会导致api调用受限，影响自身业务，开发者需在自己的服务存储与更新api_ticket。
数据示例
chooseCard拉取卡券
特别提醒
开发者特别注意：签名错误会导致拉取卡券列表异常为空，请仔细检查参与签名的参数有效性。
2.Code解码接口
Code解码接口支持两种场景：
商家获取choos_card_info后，将card_id和encrypt_code字段通过解码接口，获取真实code；
卡券内跳转外链的签名中会对code进行加密处理，通过调用解码接口获取真实code；
{'errcode':0,'errmsg':'ok','code':'751234212312'}1234512345参数名描述errcode错误码errmsg错误信息code解密后获取的真实Code码注意事项
只能解码本公众号卡券获取的加密code。
开发者若从url上获取到加密code,请注意先进行urldecode，否则报错。
encrypt_code是卡券的code码经过加密处理得到的加密code码，与code一一对应。
开发者只能解密本公众号的加密code，否则报错。
3.查询Code接口
参考上面线下核销—查询Code接口
4.核销Code接口
参考上面线下核销—核销Code接口
查询code接口，可以查询当前code是否可以被核销，并检查code状态。
当前可以被定位状态有：正常、已核销、转赠中、已删除、已失效、无效code
用于获取用户卡包里的，属于该appid下所有可用卡券，包括正常状态和异常状态。
注：
查询用户已领取的卡券需要用户在该商户公众平台的openId，不支持小程序的openId。
如何在小程序查看用户已领取的卡券？
用户在商户小程序内领取卡券，记录用户小程序的openId、领取卡券的card_id和code落地服务端；
通过card_id和code来关联对应用户的公众号的openId和小程序的openId；
删除卡券接口允许商户删除任意一类卡券。删除卡券后，该卡券对应已生成的领取用二维码、添加到卡包JSAPI均会失效。
卡券快速买单优点
可以通过手机公众号、电脑商户后台，轻松操作收款并查看核销记录，交易对账，并支持离线下载。
支持会员营销，二次营销，如会员卡交易送积分，抵扣积分，买单后赠券等。
该接口支持更新所有卡券类型的部分通用字段及特殊卡券（会员卡、飞机票、电影票、会议门票）中特定字段信息
调用该接口增减某张卡券的库存。
为了满足改票、退款等异常情况，可调用卡券失效接口将用户的卡券设置为失效状态。
开发者可调用该接口，查询某个card_id的创建信息，审核状态以及库存数量。
开发者可批量查询指定状态的卡券列表；
开发者准备一个具备卡券权限的公众号和认证后的小程序账号；
通过公众平台或者卡券API接口创建卡券，获取card_id
小程序内记录用户openid，用户领取的code以及card_id;
处理卡券领取事件，记录用户在公众号内的openId，以及用户领取的code及card_id;
步骤
注意：需要改用户所在商户公众平台的openId，不支持小程序openId，具体步骤可参考《如何在小程序内查看已领取卡券列表》
将返回的数据卡券列表，调用wx.openCard()打开某张/多张卡券查看和使用；
JS-SDK使用步骤
绑定域名
登陆公众平台，进入公众号设置—>功能设置填写JS接口安全域名（以便该域名内部有权限访问JSSDK接口）
引入JS文件在需要调用JS接口的页面，引入如下JS文件：
通过config接口注入权限验证配置
通过ready接口处理成功验证
通过error接口处理失败验证
将所有参数字符串拼接成一个字符串进行sha1加密，得到cardSign
cardExt本身是一个JSON字符串，是商户为该张卡券分配的唯一性信息，包含以下字段：