核销卡券
核销卡券
更新日志
| 版本号 | 更新内容 | 更新时间 |
|---|---|---|
| V1.0 | 1.规范核销引导流程，建议开发者调用核销接口之前先调用查询code接口查看code状态 2.优化查询code接口，便于开发者使用，同时兼容旧接口 | 2015-8-31 |
该部分主要介绍开发者如何在用户使用券之后让卡券从用户的微信客户端消失的过程，这个步骤称为核销。
核销目前分为线上核销和线下核销两种类型。
线上核销指用户从券面进入一个HTML5网页后主动销券的过程，如微信商城用券、自助核销等；
线下核销指用户到店后，出示二维码或者出示串码，由收银员完成核销动作，如扫码核销、机具核销等。
1线下核销
1.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异常状态返回数据不同。 |
当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"
}卡券状态异常：
{
"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,
"user_card_status": "NORMAL"
}卡券状态异常：
{
"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为不可核销 |
注意事项：
1.固定时长有效期会根据用户实际领取时间转换，如用户2013年10月1日领取，固定时长有效期为90天，即有效时间为2013年10月1日-12月29日有效。
2.无论check_consume填写的是true还是false,当code未被添加或者code被转赠领取是统一报错：invalid serial code
1.2 核销Code接口
消耗code接口是核销卡券的唯一接口,开发者可以调用当前接口将用户的优惠券进行核销，该过程不可逆。
接口调用请求说明
HTTP请求方式: POST URL:https://api.weixin.qq.com/card/code/consume?access_token=TOKEN
参数说明
| 参数 | 是否必须 | 说明 |
|---|---|---|
| POST数据 | 是 | Json数据 |
| access_token | 是 | 调用接口凭证 |
POST数据
非自定义Code卡券的请求
{
"code": "12312313"
}
或自定义Code卡券的请求
{
"code": "12312313",
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}| 参数名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|
| card_id | 否 | string(32) | pFS7Fjg8kV1Id Dz01r4SQwMkuCKc | 卡券ID。创建卡券时use_custom_code填写true时必填。非自定义Code不必填写。 |
| code | 是 | string(20) | 1231231 | 需核销的Code码。 |
返回数据
{
"errcode":0,
"errmsg":"ok",
"card":{"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"},
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}| 参数名 | 描述 |
|---|---|
| errcode | 错误码。 |
| errmsg | 错误信息。 |
| openid | 用户在该公众号内的唯一身份标识。 |
| card_id | 卡券ID。 |
注意事项：
1.仅支持核销有效状态的卡券，若卡券处于异常状态，均不可核销。（异常状态包括：卡券删除、未生效、过期、转赠中、转赠退回、失效）
2.自定义Code码（use_custom_code为true）的优惠券，在code被核销时，必须调用此接口。用于将用户客户端的code状态变更。自定义code的卡券调用接口时， post数据中需包含card_id，否则报invalid serial code，非自定义code不需上报。
2 线上核销
2.1 拉取卡券列表接口（JS-SDK）
微信 JS-SDK 只能在微信内置浏览器中使用,其他浏览器调用无效。微信提供chooseCard接口供商户前端网页调用,用于拉起用户名下该商家筛选条件的卡券内容。 点击查看 调起适用于门店的卡券列表并获取用户选择列表JS-SDK
2.2 Code解码接口
code解码接口支持两种场景：
1.商家获取choos_card_info后，将card_id和encrypt_code字段通过解码接口，获取真实code。
2.卡券内跳转外链的签名中会对code进行加密处理，通过调用解码接口获取真实code。
接口调用请求说明
HTTP请求方式: POST URL: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+VJdsFmv7b 8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE | 经过加密的Code码。 |
返回数据
{
"errcode":0,
"errmsg":"ok",
"code":"751234212312"
}
参数说明
| 参数名 | 描述 |
|---|---|
| errcode | 错误码 |
| errmsg | 错误信息 |
| code | 解密后获取的真实Code码 |
注意事项
1.只能解码本公众号卡券获取的加密code。
2.开发者若从url上获取到加密code,请注意先进行urldecode，否则报错。
3.encrypt_code是卡券的code码经过加密处理得到的加密code码，与code一一对应。
4.开发者只能解密本公众号的加密code，否则报错。
2.3 查询Code接口
我们强烈建议开发者在调用核销code接口之前调用查询code接口，并在核销之前对非法状态的code(如转赠中、已删除、已核销等)做出处理。
2.4 核销Code接口
线上核销普通券的接口同线下核销普通券的接口一致。