微信公众平台卡券API接口开发指南

victor8885 2021-06-23

展开全文

文章目录

说明

《微信公众平台卡劵功能接入指南》介绍微信公众平台提供卡券的创建、投放、核销整套的流程，为什么还提供API接口操作方式？卡券API接口提供更加丰富的卡券功能（公众平台不具备的），我们可通过API接口形式来创建更加多样化的卡券（例如：设置卡券关联小程序、会员卡的储值功能、以及卡券的自助买单等等）。

注：该文档后面所涉及的卡券操作都是基于API接口方式，如果商户想免开发使用卡券，可使用公众平台提供的卡券创建、投放、核销相关功能。

卡券术语介绍

以下是卡券开发过程中需要了解的关键概念：

参数名	描述
card_id	卡券ID。一个卡券ID对应一类卡券，包含了相应库存数量的Code码。
code	卡券Code码。一张卡券的唯一标识，核销卡券时使用此串码，支持商户自定义。
openid	用户在该公众号下的唯一身份。
access_token	调用接口的凭证，有效时间为7200s，每次请求刷新，通过获取access_token接口获取,开发者需妥善保存并建立缓存机制。
jsapi_ticket	调用微信内网页调用微信原生功能的JS-SDK接口须使用的签名票据，详情见: JS-SDK部分
api_ticket	调用微信卡券接口时签名的临时票据，有效时间为7200s， 7200s内重复请求保持不变，通过获取api_ticket接口获取。
card_ext	可扩展的卡券的附加信息，用于投放卡券时附带卡券基本信息。
outer_str	领券渠道的场景值。支持商户自定义场景值填入card_ext进行卡券投放，当用户领取时会将相应场景值通过事件通知商户。
事件推送	在卡券通过审核、卡券被领取、卡券被删除、卡券被核销时，均会推送事件通知开发者，接收地址为公众平台开发者中心填写的服务器URL。
自定义入口	通过API创建卡券支持商户自定义卡券详情页跳转外链的单元,用户跳转至该链接时会在链接后缀有卡券的card_id和加密的code。

卡券生命周期流程图

在这里插入图片描述

准备

申请开发账号

申请一个公众平台账号

公众平台开发配置

申请微信公众平台开发者账号后，开发者需要按照如下步骤完成：

公众号开发信息配置

填写服务器配置并验证有效性

申请微信认证及开通微信卡券功能

下面详细介绍这3个步骤。

公众号开发信息配置

账号申请完成后，我们进入公众平台官网的开发-基本配置页面，首先完成公众号开发信息配置，包括启用开发者密码(AppSecret)和配置IP白名单
在这里插入图片描述

填写服务器配置并验证有效性

然后，继续下面的服务器配置点击修改配置按钮，填写服务器地址（URL）、Token和EncodingAESKey，其中

URL是开发者用来接收微信消息和事件的接口URL

用户每次向公众号发送消息、或者产生自定义菜单、或产生微信支付订单等情况时，开发者填写的服务器配置URL将得到微信服务器推送过来的消息和事件，开发者可以依据自身业务逻辑进行响应，如回复消息）。
Token可由开发者可以任意填写，用作生成签名

该Token会和接口URL中包含的Token进行比对，因此填写的url地址内需要实现返回业务逻辑，下面会有代码示例，从而验证安全性）。
EncodingAESKey由开发者手动填写或随机生成，将用作消息体加解密密钥。

同时，开发者可选择消息加解密方式：

明文模式
兼容模式
安全模式

模式的选择与服务器配置在提交后都会立即生效，请开发者谨慎填写及选择。加解密方式的默认状态为明文模式，选择兼容模式和安全模式需要提前配置好相关加解密代码，详情请参考消息体签名及加解密部分的文档。
在这里插入图片描述

填写好以后提交，微信服务器将发送GET请求到您填写的服务器地址URL上，GET请求携带参数如下表所示：

参数	描述
signature	微信加密签名，signature结合了开发者填写的token参数和请求中的timestamp参数、nonce参数。
timestamp	时间戳
nonce	随机数
echostr	随机字符串

开发者通过检验signature对请求进行校验（下面有校验方式）。若确认此次GET请求来自微信服务器，请原样返回echostr参数内容，则接入生效，成为开发者成功，否则接入失败。加密/校验流程如下：

将token、timestamp、nonce三个参数进行字典序排序
将三个参数字符串拼接成一个字符串进行sha1加密
开发者获得加密后的字符串可与signature对比，标识该请求来源于微信

检验signature的PHP示例代码：

private function checkSignature()
{
    $signature = $_GET['signature'];
    $timestamp = $_GET['timestamp'];
    $nonce = $_GET['nonce'];

    $token = TOKEN;
    $tmpArr = array($token, $timestamp, $nonce);
    sort($tmpArr, SORT_STRING);
    $tmpStr = implode( $tmpArr );
    $tmpStr = sha1( $tmpStr );
    
    if( $tmpStr == $signature ){
        return true;
    }else{
        return false;
    }
}

PHP示例代码下载：下载

申请微信认证及开通微信卡券功能

在进行公众平台开发配置后，成为开发者。此时您仅具备较少的接口权限，商户如需进行卡券开发，需要在公众平台网站中申请微信认证并开通微信卡券功能，认证成功后，将获得更多接口权限，满足更多业务需求。

您也可以利用微信公众账号测试号申请系统来申请一个测试的公众平台开发账号（免去认证复杂流程）

注意

微信公众平台开发是指为微信公众号进行业务开发，为移动应用、PC端网站、公众号第三方平台（为各行各业公众号运营者提供服务）的开发，请前往微信开放平台接入。
在申请到认证公众号之前，你可以先通过测试号申请系统，快速申请一个接口测试号，立即开始接口测试开发。
在开发过程中，可以使用接口调试工具来在线调试某些接口。
每个接口都有每日接口调用频次限制，可以在公众平台官网-开发者中心处查看具体频次。
在开发出现问题时，可以通过接口调用的返回码，以及报警排查指引（在公众平台官网-开发者中心处可以设置接口报警），来发现和解决问题。
公众平台以access_token为接口调用凭据，来调用接口，所有接口的调用需要先获取access_token，access_token在2小时内有效，过期需要重新获取，但1天内获取次数有限，开发者需自行存储，详见获取接口调用凭据（access_token）文档。
微信公众号接口必须以http://或https://开头，分别支持80端口和443端口。

配置好商户开发信息后，商户开发者可依据接口文档实现业务逻辑。

卡券分类

普通卡券

普通卡券包含：代金券、团购券、优惠券、折扣券、兑换券

普通卡券特点

折扣券：为用户提供消费折扣。
代金券：可为用户提供现金减免服务。
礼品券：可为用户提供消费赠品服务。
团购券：可为用户提供团购套餐服务。
优惠券：即通用券，商户可自定义服务内容程度较高。

会员卡券

会员卡具体介绍及相关接口参考《创建会员卡》

朋友的券

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

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

注意

目前，仅支持商户创建代金券（可通过公众平台和接口创建）和兑换券（仅支持通过接口创建）两种类型的券。
朋友的券仅针对部分类目商户开放（可参考《朋友共享的优惠券使用规则》—开放范围），凡是符合本次开放类目商户均可看到朋友的券入口。

特殊票券

微信卡券特殊的券包含：会议/演出门票、景区门票、电影票、飞机票。具体相关API接口操作可参考《特殊票券》

接口开发

注：以下示例针对普通卡券操作

当具备微信公众平台合法账号，且经过微信认证具备相应权限后，我们可使用AppID和appsecret来进行微信相关接口调试，我们可使用微信公众平台接口调试工具选择合适的接口，系统会生成该接口的参数表，您可以直接在文本框内填入对应的参数值。（红色星号表示该字段必填）点击检查问题按钮，即可得到相应的调试信息。（以下是使用测试账号的进行调试）

创建卡券

1. 获取access_token接口

access_token是公众号的全局唯一接口调用凭据，公众号调用各接口时都需使用access_token。开发者需要进行妥善保存。access_token的存储至少要保留512个字符空间。access_token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的access_token失效。

另外该接口调用需要配置IP白名单，更多注意事项可阅读《获取Access token》

接口调用

http请求方式: GET

URL：https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

请求参数

grant_type	是	获取access_token填写client_credential
appid	是	第三方用户唯一凭证
secret	是	第三方用户唯一凭证密钥，即appsecret

响应参数

access_token	获取到的凭证
expires_in	凭证有效时间，单位：秒

正常情况下，微信会返回下述JSON数据包给公众号：

{'access_token':'ACCESS_TOKEN','expires_in':7200}
1
1

2. 上传卡券Logo

接口调用

HTTP请求方式: POST/FROM（表单形式提交Logo图片）

URL：https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN

响应报文

{
  'url':'http://mmbiz./mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0'
}

3. 设置卡券适用门店（可选）

适用场景

拥有线下门店的商户，使用前商户需调用微信门店接口，设置门店。详情参考《微信门店接口》

4. 选取卡券背景颜色

选择卡券背景适用色值

在创建卡券接口中将颜色名（如Color010）填入color字段。

目前微信提供以下十四种色值供开发者使用。

背景颜色名称	色值	颜色
Color010	#63b359
Color020	#2c9f67
Color030	#509fc9
Color040	#5885cf
Color050	#9062c0
Color060	#d09a45
Color070	#e4b138
Color080	#ee903c
Color081	#f08500
Color082	#a9d92d
Color090	#dd6549
Color0100	#cc463d
Color0101	#cf3e36
Color0102	#5E6671

5. 创建卡券（这里以团购券为例）

经过上述步骤之后，我们可调用创建卡券接口来创建一类新的卡券，获取card_id。创建卡券成功并通过审核后，商家可以通过文档提供的其他接口将卡券下发给用户，每次成功领取，库存数量相应扣除。

注意：微信卡券不再支持配置网页链接跳转，请选择小程序替代

接口调用

HTTP请求方式: POST

URL：https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN

请求参数说明

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

POST数据示例请参考扩展《卡券创建接口POST报文示例》

普通卡券字段示例
在这里插入图片描述
会员卡字段示例

POST数据格式如下

团购券

{
 'card': {
     'card_type': 'GROUPON',
     'groupon': {
         'base_info': {
         ················
         },
          'advanced_info': {
         ················
          },
         'deal_detail': '示例'
     }
 }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
1
2
3
4
5
6
7
8
9
10
11
12
13
14

参数名	必填	类型	示例值	描述
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': 'CASH',
     'cash': {
         'base_info': {
         ················
         },
          'advanced_info': {
         ················
          },
         'least_cost': 1000,
         'reduce_cost': 100,
     }
 }
}

参数名	必填	类型	示例值	描述
card_type	是	string(24)	CASH	代金券类型。
base_info	是	JSON结构	见扩展《卡券创建接口POST报文示例》	基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。
advanced_info	否	JSON结构	见扩展《卡券创建接口POST报文示例》	卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。
least_cost	是	int	10000	代金券专用，表示起用金额（单位为分）,如果无起用门槛则填0。`注意：该字段移动到advanced_info内了`。
reduce_cost	是	int	10000	代金券专用，表示减免金额。（单位为分）

折扣券

{
 'card': {
     'card_type': 'DISCOUNT',
     'discount': {
         'base_info': {
         ················
         },
          'advanced_info': {
         ················
          },
         'discount': 30
     }
   }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
1
2
3
4
5
6
7
8
9
10
11
12
13
14

参数名	必填	类型	示例值	描述
card_type	是	string(24)	DISCOUNT	折扣券类型。
base_info	是	Json结构	见扩展《卡券创建接口POST报文示例》	基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。
advanced_info	否	JSON结构	见扩展《卡券创建接口POST报文示例》	卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。
discount	是	int	30	折扣券专用，表示打折额度（百分比）。填30就是七折。

兑换券

{
'card': {
    'card_type': 'GIFT',
    'gift': {
        'base_info': {
        ················
        },
         'advanced_info': {
        ················
         },
        'gift':'可兑换音乐木盒一个'
    }
  }
}

参数名	必填	类型	示例值	描述
card_type	是	string(24)	GIFT	兑换券类型。
base_info	是	Json结构	见扩展《卡券创建接口POST报文示例》	基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。
advanced_info	否	JSON结构	见扩展《卡券创建接口POST报文示例》	卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。
gift	是	string(3072)	可兑换音乐木盒一个。	兑换券专用，填写兑换内容的名称。

优惠券

{
'card': {
    'card_type': 'GENERAL_COUPON',
    'general_coupon': {
        'base_info': {
        ················
        },
         'advanced_info': {
        ················
         },
        'default_detail':'优惠券专用，填写优惠详情'
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
1
2
3
4
5
6
7
8
9
10
11
12
13
14

参数名	必填	类型	示例值	描述
card_type	是	string(24)	GENERAL_COUPON	优惠券类型。
base_info	是	Json结构	见扩展《卡券创建接口POST报文示例》	基本的卡券数据，见扩展《卡券基础信息base_info字段》，所有卡券类型通用。
advanced_info	否	JSON结构	见扩展《卡券创建接口POST报文示例》	卡券高级信息字段，见扩展《卡券高级信息advanced_info》，所有卡券类型通用。
default_detail	是	string(3072)	音乐木盒。	优惠券专用，填写优惠详情。

卡券创建返回报文格式

{'errcode':0,'errmsg':'ok','card_id':'p1Pj9jr90_SQRaVqYI239Ka1erkI'}

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

注意事项

高级字段为商户额外展示信息字段，非必填,但是填入某些结构体后，须填充完整方可显示：如填入text_image_list结构体时，须同时传入image_url和text，否则也会报错；

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

创建卡券时，开发者填入的时间戳须注意时间戳溢出时间，设置的时间戳须早于2038年1月19日；

预存code模式的卡券须设置quantity为0，导入code后方可增加库存；

卡券自定义cell跳转小程序支持的最低微信客户端版本为6.5.8，低版本用户仍然会跳转url，高版本会跳转小程序；

如需卡券跳转到小程序，开发者须将小程序绑定在公众号下，绑定说明请见绑定公众号与小程序

跳转外链带参数说明

注意：最新版本卡券API接口已经不允许使用URL替代方案为小程序。

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

encrypt_code为加密码码，需调用解码接口获取真实Code码。假如指定的url为http://www.qq.com，用户点击时，跳转的url则为： http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID

投放卡券

卡券投放类型有：二维码投放、JS-SDK投放、卡券货架投放、群发卡券

二维码投放

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

接口调用

HTTP请求方式: POST

URL：https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

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

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'
  }
 }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
1
2
3
4
5
6
7
8
9
10
11
12
13

投放多张卡券（一次最多填入5个card_id,否则报错）

{
'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'
}
]
}
}
}

POST参数说明

参数名	必填	类型	示例值	描述
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':  'gQHB8Do...AA==',  //获取ticket后需调用换取二维码接口获取二维码图片，详情见字段说明。
  'expire_seconds': 1800,
  'url': 'http://weixin.qq.com/q/BHWya_zlfioH6fXeL16o ',
  'show_qrcode_url': ' https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQH98DVk...'
 }
1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8

参数名	描述
errcode	错误码
errmsg	错误信息
ticket	获取的二维码ticket，凭借此ticket调用通过ticket换取二维码接口可以在有效时间内换取二维码。使用该接口可获得多个带不同场景值的二维码（用于用户渠道推广分析和用户账号绑定等场景），用户扫描后，公众号可以接收到事件推送。详情使用情参考《生成带参数的二维码》
url	二维码图片解析后的地址，开发者可根据该地址自行生成需要的二维码图片
show_qrcode_url	二维码显示地址，点击后跳转二维码页面

我们将返回的url利用草料二维码生成对应的二维码图片或直接访问show_qrcode_url，使用微信扫一扫，卡跳转到对应的卡券页面（我这里没有添加测试账号，显示未审核无法领取，后面有通过接口添加测试白名单进行测试）
在这里插入图片描述

注意事项

自定义Code码的卡券调用接口时，POST数据中需要指定code字段，且生成的二维码每次只能领取一次，若开发者想要使用自己的串码系统并且想要用微信二维码投放，必须先将自定义的code码导入。非自定义的卡券Code不需要指定；
如果卡券二维码只能被指定的用户扫码领取，则需要设置openid字段，否则无需设置；
领取多张的二维码一次最多填入5个card_id，否则报错。

JS-SDK投放

通过使用JS-SDK(微信 JS-SDK 仅支持在微信内置浏览器中使用,其他浏览器调用无效)，开发者可通过网页在微信内浏览器中，直接使用卡券能力。JS-SDK使用步骤见扩展《JS-SDK使用步骤》

JSSDK中卡券相关接口

addCard：批量添加卡券到微信卡券包
openCard：查看微信卡包中的卡券
choseCard：拉取用户指定条件的卡券列表，并返回用户选中的卡券列表信息（不支持小程序）

具体相关接口操作步骤可参照《小程序内添加和查看卡券》

注意：

微信卡券接口中使用的签名凭证是api_ticket，因此在使用JS-SDK内卡券相关接口，首先要获取**api-ticket**。

微信卡券货架投放

微信卡券货架支持开发者通过调用该接口生成一个卡券领取的H5页面，并返回给开发者页面链接，进行卡券投放。

注意：

目前卡券货架仅支持非自定义code卡券，自定义code卡券需先调用导入code接口，将code导入才能正常使用；

公众号下发消息投放

参考链接

添加测试白名单账号

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

注意

同时支持openid、username两种字段设置白名单，总数上限为10个。
设置测试白名单接口为全量设置，即测试名单发生变化时需调用该接口重新传入所有测试人员的ID.
白名单用户领取该卡券时将无视卡券失效状态，请开发者注意

调用接口

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'}
1
1

添加卡券测试白名单成功之后，我们在用测试账号扫码领券,微信会自动添加到卡包。
在这里插入图片描述

核销卡券

微信公众平台提供了很方便的卡券核销功能，商户可通过手机核销、网页核销、自助核销方式进行卡券的核销，接下来我们利用API接口方式实现对卡券的核销。

注意：微信公众平台提供的自助核销功能，仅限线下券使用，卡券必须设置门店方可使用自助核销功能。

卡券API接口核销类型

线上核销：指用户从券面进入一个HTML5网页后主动销券的过程，如微信商城用券、自助核销等；
线下核销：指用户到店后，出示二维码或者出示串码，由收银员完成核销动作，如扫码核销、机具核销等

线下核销

1. 查询Code接口

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

接口调用

HTTP请求方式: POST

URL：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接口异常状态返回数据不同，正常状态返回数据一致。(建议设置为true)。

返回数据(这里以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'
}
1
2
3
4
5
6
7
8
9
10
11
12
1
2
3
4
5
6
7
8
9
10
11
12

异常状态

{
  'errcode': 0,
  'errmsg': 'ok',
  'card': {
    'card_id': 'pbLatjnK8NLbWgwMgfMtnj3gaglw',
    'begin_time': 1457625600,
    'end_time': 1460217599
  },
  'openid': 'obLatjm43RA5C6QfMO5szKYnT3dM',
  'can_consume': false,
  '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
can_consume	是否可以核销，true为可以核销，false为不可核销

2. 核销Code接口

消耗code接口是核销卡券的唯一接口,开发者可以调用当前接口将用户的优惠券进行核销，该过程不可逆。

接口调用

HTTP请求方式: POST

URL：https://api.weixin.qq.com/card/code/consume?access_token=TOKEN

请求参数

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

POST数据

非自定义Code卡券POST数据为

{ 
  'code': '12312313'
}
1
2
3
1
2
3

自定义Code卡券的POST数据还需要code_id

{ 
  'code': '12312313', 
  'card_id': 'pFS7Fjg8kV1IdDz01r4SQwMkuCKc'
}

参数名	必填	类型	示例值	描述
card_id	否	string(32)	pFS7Fjg8kV1Id Dz01r4SQwMkuCKc	卡券ID。创建卡券时use_custom_code填写true时必填（自定义卡券Code）。非自定义Code不必填写。
code	是	string(20)	1231231	需核销的Code码。

返回数据

{
'errcode':0,
'errmsg':'ok',
'card':{
'card_id':'pFS7Fjg8kV1IdDz01r4SQwMkuCKc'
},
'openid':'oFS7Fjl0WsZ9AMZqrI80nbIq8xrA'
}
1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8

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

注意事项
1. 仅支持核销有效状态的卡券，若卡券处于异常状态，均不可核销。（异常状态包括：卡券删除、未生效、过期、转赠中、转赠退回、失效）;
2. 自定义Code码（use_custom_code为true）的优惠券，在code被核销时，必须调用此接口。用于将用户客户端的code状态变更。自定义code的卡券调用接口时， post数据中需包含card_id，否则报invalid serial code，非自定义code不需上报；

线上核销

微信 JS-SDK 只能在微信内置浏览器中使用,其他浏览器调用无效。通过微信JSSDK提供chooseCard接口供商户前端网页调用,用于拉起用户名下该商家筛选条件的卡券内容，并返回用户选择的卡券信息；然后通过微信卡券Code解码接口，解析用户选择的卡券码，获取真实code；然后再跳用查询卡券Code接口，验证卡券是否可核销，最后调用卡券核销接口，详细流程如下：

1. 拉取卡券列表接口（JS-SDK—chooseCard）

微信卡券接口中使用的签名凭证是api_ticket，因此在使用JS-SDK内卡券相关接口，首先要获取api-ticket

获取api-ticket

api_ticket 是用于调用微信卡券JS API的临时票据，有效期为7200 秒，通过access_token 来获取。

由于获取api_ticket 的api 调用次数非常有限，频繁刷新api_ticket 会导致api调用受限，影响自身业务，开发者需在自己的服务存储与更新api_ticket。

接口调用

http请求方式: GET

URL： https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card

请求参数

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

参数名描述
errcode 错误码
errmsg 错误信息
ticket api_ticket，卡券接口中签名所需凭证
expires_in 有效时间
数据示例
{ 'errcode':0, 'errmsg':'ok', 'ticket':'bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA', 'expires_in':7200 }
- 1
- 2
- 3
- 4
- 5
- 6
- 1
- 2
- 3
- 4
- 5
- 6

chooseCard拉取卡券

接口调用

wx.chooseCard({
  shopId: '',    // 门店Id
  cardType: '',  // 卡券类型
  cardId: '',    // 卡券Id
  timestamp: 0,  // 卡券签名时间戳
  nonceStr: '',  // 卡券签名随机串
  signType: '',  // 签名方式，默认'SHA1'
  cardSign: '',  // 卡券签名
  success: function (res) {
    var cardList= res.cardList; // 用户选中的卡券列表信息
  }
});
1
2
3
4
5
6
7
8
9
10
11
12
1
2
3
4
5
6
7
8
9
10
11
12

参数名	必填	类型	示例值	描述
shopId	否	string(24)	1234	门店ID。shopID用于筛选出拉起带有指定location_list(shopID)的卡券列表，非必填。
cardType	否	string(24)	GROUPON	卡券类型，用于拉起指定卡券类型的卡券列表。当cardType为空时，默认拉起所有卡券的列表，非必填。
cardId	否	string(32)	p1Pj9jr90_SQRaVqYI239Ka1erk	卡券ID，用于拉起指定cardId的卡券列表，当cardId为空时，默认拉起所有卡券的列表，非必填。
timestamp	是	string(32)	14300000000	时间戳。
nonceStr	是	string(32)	sduhi123	随机字符串。
signType	是	string(32)	SHA1	签名方式，目前仅支持SHA1
cardSign	是	string(64)	abcsdijcous123	签名。

在这里插入图片描述

cardSign签名，可参见扩展《微信卡券签名cardSign说明》

特别提醒

开发者特别注意：签名错误会导致拉取卡券列表异常为空，请仔细检查参与签名的参数有效性。

拉取列表仅与用户本地卡券有关，拉起列表异常为空的情况通常有三种：签名错误、时间戳无效、筛选机制有误。请开发者依次排查定位原因。

2. Code解码接口

Code解码接口支持两种场景：

商家获取choos_card_info后，将card_id和encrypt_code字段通过解码接口，获取真实code；
卡券内跳转外链的签名中会对code进行加密处理，通过调用解码接口获取真实code；

通过微信JSSDK提供chooseCard接口供商户前端网页（JSSDK使用必须在微信内置浏览器中）调用,用于拉起用户名下该商家筛选条件的卡券内容

接口调用

HTTP请求方式: POST

URL：https://api.weixin.qq.com/card/code/decrypt?access_token=TOKEN
请求参数

参数是否必须说明
POST数据是 Json数据
access_token 是调用接口凭证
POST数据示例
{ 'encrypt_code':'XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE' }
- 1
- 2
- 3
- 1
- 2
- 3
参数名必填类型示例值描述
encrypt_code 是 string(128) XXIzTtMqCxwOaawoE91+VJdsFmv7b 8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE 经过加密的Code码
返回数据
```
{
  'errcode':0,
  'errmsg':'ok',
  'code':'751234212312'
}
1
2
3
4
5
1
2
3
4
5
```
参数名描述
errcode 错误码
errmsg 错误信息
code 解密后获取的真实Code码
注意事项
1. 只能解码本公众号卡券获取的加密code。
2. 开发者若从url上获取到加密code,请注意先进行urldecode，否则报错。
3. encrypt_code是卡券的code码经过加密处理得到的加密code码，与code一一对应。
4. 开发者只能解密本公众号的加密code，否则报错。

3. 查询Code接口

参考上面线下核销—查询Code接口

4. 核销Code接口

参考上面线下核销—核销Code接口

管理卡券

查询Code状态接口

查询code接口，可以查询当前code是否可以被核销，并检查code状态。

当前可以被定位状态有：正常、已核销、转赠中、已删除、已失效、无效code

获取用户已领取卡券接口

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

注：

查询用户已领取的卡券需要用户在该商户公众平台的openId，不支持小程序的openId。

如何在小程序查看用户已领取的卡券？

用户在商户小程序内领取卡券，记录用户小程序的openId、领取卡券的card_id和code落地服务端；

通过商户后台服务接收微信卡券领取事件，获取用户对应的公众平台openId、领取卡券的card_id和code；

通过card_id和code来关联对应用户的公众号的openId和小程序的openId；

用户通过小程序的openId向服务端发起查询领取卡券请求，服务端根据用户小程序openId获取对应的公众平台openId，然后调用微信查询接口，获取该用户已领取的卡券列表即可。

删除卡券接口

删除卡券接口允许商户删除任意一类卡券。删除卡券后，该卡券对应已生成的领取用二维码、添加到卡包JS API均会失效。

注：

如用户在商家删除卡券前已领取一张或多张该卡券依旧有效。即删除卡券不能删除已被用户领取，保存在微信客户端中的卡券。

设置卡券快速买单

微信卡券买单功能是微信卡券的一项新的能力，可以方便消费者买单时，直接录入消费金额，自动使用领到的优惠（券或卡）抵扣，并拉起微信支付快速完成付款。

卡券快速买单优点

无需商户具备微信支付开发能力，即可完成订单生成，与微信支付打通。

可以通过手机公众号、电脑商户后台，轻松操作收款并查看核销记录，交易对账，并支持离线下载。

支持会员营销，二次营销，如会员卡交易送积分，抵扣积分，买单后赠券等。

注：

设置快速买单的卡券须支持至少一家有核销员门店，否则无法设置成功；
若该卡券设置了center_url（居中使用跳转链接）,须先将该设置更新为空后再设置自快速买单方可生效。

设置自助核销接口

创建卡券之后，开发者可以通过设置微信买单接口设置该card_id支持自助核销功能。

注：

设置自助核销的卡券须支持至少一家门店，否则无法设置成功；
若该卡券设置了center_url（居中使用跳转链接）,须先将该设置更新为空后再设置自助核销功能方可生效。

更新卡券信息接口

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

修改库存接口

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

更改code接口

为了确保卡券转增后的安全性，微信允许自定义code的商户对已下发的code进行更改。

注：

为了避免用户疑惑，建议仅在发生转增行为后(发生转增后，微信会通过事件推送方式告知商户被转增卡券的code)对用户的Code进行更改。

设置卡券失效接口

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

查看卡券详情

开发者可调用该接口，查询某个card_id的创建信息，审核状态以及库存数量。

注：

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

批量查询卡券列表

开发者可批量查询指定状态的卡券列表；

注：

未传入筛选条件时，该接口默认查询该商户名下所有状态卡券；
开发者可以请求后，然后调用查看卡券详情接口确定卡券状态；

小程序接入微信卡券

开发准备

开发者准备一个具备卡券权限的公众号和认证后的小程序账号；
开发者准备一个认证后的微信开放平台账号,并将小程序和公众号绑定在同一个开放平台账号下
通过公众平台或者卡券API接口创建卡券，获取card_id
在小程序内调用wx.addcard接口（将卡券添加到微信卡包）并处理领取成功回调；
第四步在用户领取卡券回调结果中，获取到code(加密后的code)，调用解码code接口获取真实的code；
小程序内记录用户openid，用户领取的code以及card_id;
处理卡券领取事件，记录用户在公众号内的openId，以及用户领取的code及card_id;

接口说明

获取api_ticket

api_ticket 是用于调用微信卡券JS API的临时票据，有效期为7200 秒，通过access_token 来获取。

由于获取api_ticket 的api 调用次数非常有限，频繁刷新api_ticket 会导致api调用受限，影响自身业务，开发者需在自己的服务存储与更新api_ticket。

添加卡券(wx.addcard)

将卡券/卡券列表添加到微信卡包，接口详细参见《批量添加卡券接口》

注意

wx.addcard接口中涉及的签名中的api_ticket必须传入创建该卡券的公众号获取到的ticket
用户领取卡券后，会有领取卡券事件推送至开发者服务器，开发者须进行处理，详细请见卡券事件通知；
开发者可以通过推送事件内的outer_str判断用户领券来源；
该功能仅支持1.1.0版本及以上的基础库版本，小程序内须做版本判断并对低版本进行兼容

查看卡券(wx.openCard)

在小程序内查看、出示自己的微信卡券

步骤

开发者须在用户进入小程序时，请求开发者服务器调用获取用户已领取卡券接口取获取用户已经领取到的卡券的card_id和code(真实)；

注意：需要改用户所在商户公众平台的openId，不支持小程序openId，具体步骤可参考《如何在小程序内查看已领取卡券列表》

将返回的数据卡券列表，调用wx.openCard()打开某张/多张卡券查看和使用；

扩展

微信公众账号测试号申请系统

微信公众平台接口调试工具

微信公众平台开发者文档

微信JS-SDK说明文档

JS-SDK使用步骤

绑定域名

登陆公众平台，进入公众号设置—>功能设置填写JS接口安全域名（以便该域名内部有权限访问JSSDK接口）
引入JS文件
在需要调用JS接口的页面，引入如下JS文件：
http://res.wx.qq.com/open/js/jweixin-1.6.0.js （支持https） //或 http://res2.wx.qq.com/open/js/jweixin-1.6.0.js （支持https）
- 1
- 2
- 3
- 1
- 2
- 3

通过config接口注入权限验证配置

所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用（同一个url仅需调用一次，对于变化url的SPA的web app可在每次url变化时进行调用,目前Android微信客户端不支持pushState的H5新特性，所以使用pushState来实现web app的页面会导致签名失败，此问题会在Android6.2中修复）。

wx.config({
  debug: true, //开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
  appId: '', // 必填，公众号的唯一标识
  timestamp: , // 必填，生成签名的时间戳
  nonceStr: '', // 必填，生成签名的随机串
  signature: '',// 必填，签名
  jsApiList: [] // 必填，需要使用的JS接口列表
});
1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8

签名算法见附录1，所有JS接口列表见附录2

通过ready接口处理成功验证
wx.ready(function(){ // config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。 });
- 1
- 2
- 3
- 1
- 2
- 3

通过error接口处理失败验证

wx.error(function(res){
  // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。
});
1
2
3
1
2
3

微信卡券接口说明

微信卡券扩展字段及签名生成算法

卡券签名cardSign说明

将 api_ticket、appid、location_id、timestamp、nonce_str、card_id、card_type的value值进行字符串的字典序排序。

将所有参数字符串拼接成一个字符串进行sha1加密，得到cardSign

卡券扩展字段cardExt说明

cardExt本身是一个JSON字符串，是商户为该张卡券分配的唯一性信息，包含以下字段：

字段	是否必填	是否参与签名	说明
code	否	是	指定的卡券code码，只能被领一次。自定义code模式的卡券必须填写，非自定义code和预存code模式的卡券不必填写。详情见：是否自定义code码
openid	否	是	指定领取者的openid，只有该用户能领取。bind_openid字段为true的卡券必须填写，bind_openid字段为false不必填写。
timestamp	是	是	时间戳，商户生成从1970年1月1日00:00:00至今的秒数,即当前的时间,且最终需要转换为字符串形式;由商户生成后传入,不同添加请求的时间戳须动态生成，若重复将会导致领取失败！。
nonce_str	否	是	随机字符串，由开发者设置传入，加强安全性（若不填写可能被重放请求）。随机字符串，不长于32位。推荐使用大小写字母和数字，不同添加请求的nonce须动态生成，若重复将会导致领取失败。
fixed_begintimestamp	否	否	卡券在第三方系统的实际领取时间，为东八区时间戳（UTC+8,精确到秒）。当卡券的有效期类型为 DAT E_TYPE_FIX_TERM时专用，标识卡券的实际生效时间，用于解决商户系统内起始时间和领取时间不同步的问题。
outer_str	否	否	领取渠道参数，用于标识本次领取的渠道值。
signature	是	-	签名，商户将接口列表中的参数按照指定方式进行签名,签名方式使用SHA1,具体签名方案参见下文;由商户按照规范签名后传入。

签名说明

将 api_ticket、timestamp、card_id、code、openid、nonce_str的value值进行字符串的字典序排序。
将所有参数字符串拼接成一个字符串进行sha1加密，得到signature。
signature中的timestamp，nonce字段和card_ext中的timestamp，nonce_str字段必须保持一致。
code=1434008071，timestamp=1404896688，card_id=pjZ8Yt1XGILfi-FUsewpnnolGgZk， api_ticket=ojZ8YtyVyr30HheH3CM73y7h4jJE ，nonce_str=123 则signature=sha1(12314048966881434008071ojZ8YtyVyr30HheH3CM73y7h4jJEpjZ8Yt1XGILfi-FUsewpnnolGgZk)=f137ab68b7f8112d20ee528ab6074564e2796250。

强烈建议开发者使用卡券资料包中的签名工具SDK进行签名或使用微信卡券JSAPI签名校验工具进行校验

微信卡券创建接口字段

卡券创建接口POST报文示例

{
  'card': {
      'card_type': 'GROUPON',
      'groupon': {
          'base_info': {
              'logo_url': 'http://mmbiz./mmbiz/iaLb7g/0',
              'brand_name': '微信餐厅',
              'code_type': 'CODE_TYPE_TEXT',
              'title': '132元双人火锅套餐',
              'color': 'Color010',
              'notice': '使用时向服务员出示此券',
              'service_phone': '020-88888888',
              'description': '不可与其他优惠同享\n如需团购券发票，请在消费时向商户提出',
              'date_info': {
                  'type': 'DATE_TYPE_FIX_TIME_RANGE',
                  'begin_timestamp': 1397577600,
                  'end_timestamp': 1472724261
              },
              'sku': {
                  'quantity': 500000
              },
              'use_limit':100,
              'get_limit': 3,
              'use_custom_code': false,
              'bind_openid': false,
              'can_share': true,
              'can_give_friend': true,
              'location_id_list': [
                  123,
                  12321,
                  345345
              ],
              'center_title': '顶部居中按钮',
              'center_sub_title': '按钮下方的wording',
              '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',
              'source': '大众点评'
          },
           'advanced_info': {
               'use_condition': {
                   'accept_category': '鞋类',
                   'reject_category': '阿迪达斯',
                   'can_use_with_other_discount': true
               },
               'abstract': {
                   'abstract': '微信餐厅推出多种新季菜品，期待您的光临',
                   'icon_url_list': [
                       'http://mmbiz./mmbiz/p98sfw/0'
                   ]
               },
               'text_image_list': [
                   {
                       'image_url': 'http://mmbiz./mmbiz/p9sfw/0',
                       'text': '此菜品精选食材，以独特的烹饪方法，最大程度地刺激食 客的味蕾'
                   },
                   {
                       'image_url': 'http://mmbiz./mmbiz/p98FjXy8nDsfw/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'
               ]
           },
          'deal_detail': '以下锅底2选1（有菌王锅、酸菜鱼锅可选）：\n大锅1份 12元\n小锅2份 16元 '
      }
  }}

卡券基础信息base_info字段

必填字段

参数名	必填	类型	示例值	描述
logo_url	是	strin g(128)	http://mmbiz./	卡券的商户logo，建议像素为300*300。
code_type	是	string(16)	CODE_TYPE_TEXT	码型： '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	是	string（36）	海底捞	商户名字,字数上限为12个汉字。
title	是	string（27）	双人套餐100元兑换券	卡券名，字数上限为9个汉字。(建议涵盖卡券属性、服务及金额)。
color	是	string（16）	Color010	券颜色。按色彩规范标注填写Color010-Color100。
notice	是	string（48）	请出示二维码	卡券使用提醒，字数上限为16个汉字。
description	是	strin g （3072）	不可与其他优惠同享	卡券使用说明，字数上限为1024个汉字。
sku	是	JSON结构	见上述示例。	商品信息。
quantity	是	int	100000	卡券库存的数量，上限为100000000。
date_info	是	JSON结构	见上述示例。	使用日期，有效期的信息。
type	是	string	DATE_TYPE_FIX TIME_RANGE 表示固定日期区间，DATE_TYPE FIX_TERM 表示固定时长（自领取后按天算。	使用时间的类型，旧文档采用的1和2依然生效。
begin_time stamp	是	unsigned int	14300000	type为DATE_TYPE_FIX_TIME_RANGE时专用，表示起用时间。从1970年1月1日00:00:00至起用时间的秒数，最终需转换为字符串形态传入。（东八区时间,UTC+8，单位为秒）
end_time stamp	是	unsigned int	15300000	表示结束时间，建议设置为截止日期的23:59:59过期。（东八区时间,UTC+8，单位为秒）
fixed_term	是	int	15	type为DATE_TYPE_FIX_TERM时专用，表示自领取后多少天内有效，不支持填写0。
fixed_begin _term	是	int	0	type为DATE_TYPE_FIX_TERM时专用，表示自领取后多少天开始生效，领取后当天生效填写0。（单位为天）
end_time s tamp	是	unsigned int	15300000	可用于DATE_TYPE_FIX_TERM时间类型，表示卡券统一过期时间，建议设置为截止日期的23:59:59过期。（东八区时间,UTC+8，单位为秒），设置了fixed_term卡券，当时间达到end_timestamp时卡券统一过期

非必填字段

参数名	必填	类型	示例值	描述
use_custom_code	否	bool	true	是否自定义Code码。填写true或false，默认为false。通常自有优惠码系统的开发者选择自定义Code码，并在卡券投放时带入 Code码，详情见是否自定义Code码。
get_custom_code_mode	否	string(32)	GET_CUSTOM_COD E_MODE_DEPOSIT	填入 GET_CUSTOM_CODE_MODE_DEPOSIT 表示该卡券为预存code模式卡券，须导入超过库存数目的自定义code后方可投放，填入该字段后，quantity字段须为0,须导入code 后再增加库存
bind_openid	否	bool	true	是否指定用户领取，填写true或false 。默认为false。通常指定特殊用户群体投放卡券或防止刷券时选择指定用户领取。
service_phone	否	string（24）	40012234	客服电话。
location_id_list	否	array	1234，2312	门店位置poiid。调用 POI门店管理接口获取门店位置poiid。具备线下门店的商户为必填。
use_all_locations	否	bool	true	设置本卡券支持全部门店，与location_id_list互斥
center_title	否	string（18）	立即使用	卡券顶部居中的按钮，仅在卡券状态正常(可以核销)时显示
center_sub_title	否	string（24）	立即享受优惠	卡券顶部居中按钮下方的提示语，仅在卡券状态正常(可以核销)时显示。
center_url	否	string（128）	www.qq.com	卡券顶部居中按钮入口跳转的url ，仅在卡券状态正常(可以核销)时显示。`注意：微信卡券不再支持配置网页链接跳转，请选择小程序替代`
center_app_brand_user_name	否	string（128）	gh_86a091e50ad4@app	卡券顶部居中按钮入口跳转的小程序的user_name，`仅可跳转该公众号绑定的小程序`。
center_app_brand_pass	否	string（128）	API/cardPage	卡券顶部居中按钮入口跳转的小程序的path
custom_url_name	否	string（15）	立即使用	自定义跳转外链的入口名字。
custom_url	否	string（128）	www.qq.com	自定义跳转的URL。`注意：微信卡券不再支持配置网页链接跳转，请选择小程序替代`
custom_url_sub_title	否	string（18）	更多惊喜	显示在入口右侧的提示语。
custom _app_brand_user_name	否	string（128）	gh_86a091e50ad4@app	自定义使用入口跳转小程序的user_name，`仅可跳转该公众号绑定的小程序`。
custom _app_brand_pass	否	string（128）	API/cardPage	自定义使用入口跳转的小程序的path
promotion_url_name	否	string（15）	产品介绍	自定义营销场景的Cell入口名称。
promotion_url	否	string（128）	www.qq.com	自定义营销场景入口跳转外链的地址链接。`注意：微信卡券不再支持配置网页链接跳转，请选择小程序替代`
promotion_url_sub_title	否	string（18）	卖场大优惠。	自定义营销场景入口右侧的提示语。
promotion _app_brand_user_name	否	string（128）	gh_86a091e50ad4@app	自定义营销入口跳转的小程序的user_name，`仅可跳转该公众号绑定的小程序`。
promotion _app_brand_pass	否	string（128）	API/cardPage	自定义营销入口跳转的小程序的path
get_limit	否	int	1	每人可领券的数量限制,不填写默认为50。
use_limit	否	int	100	每人可核销的数量限制,不填写默认为50。
can_share	否	bool	false	卡券领取页面是否可分享。
can_give_friend	否	bool	false	卡券是否可转赠。

卡券高级信息advanced_info字段

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