微信小店
微信门店
微信智能接口
微信设备功能

核销卡券

出自微信公众平台开发者文档
跳转到: 导航, 搜索

目录

更新日志

版本号 更新内容 更新时间
V1.0 1.规范核销引导流程,建议开发者调用核销接口之前先调用查询code接口查看code状态

2.优化查询code接口,便于开发者使用,同时兼容旧接口

2015-8-31

核销卡券

线下核销

步骤一:查询Code接口

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

接口调用请求说明

http请求方式: POST
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) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID代表一类卡券。自定义code卡券必填。
check_consume bool true 是否校验code核销状态,填入true和false时的code异常状态返回数据不同。


当check_consume为true时返回数据

卡券状态正常:

 {
"errcode":0,
"errmsg":"ok",
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"card":{
"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
"begin_time": 1404205036,
"end_time": 1404205036,
"user_card_status": "NORMAL",
"can_consume":"true"
  }
}

卡券状态异常:

{
 "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",
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"card":{
"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
"begin_time": 1404205036,
"end_time": 1404205036
"can_consume":"true"
  }
}

卡券状态异常:

 {
"errcode":0,
"errmsg":"ok",
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"card":{
"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
"begin_time": 1404205036,
"end_time": 1404205036,
"user_card_status": "GIFTING",
"can_consume":"false"
  }
}


参数名 描述
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

步骤二:核销Code接口

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

自定义Code码(use_custom_code为true)的优惠券,在code被核销时,必须调用此接口。用于将用户客户端的code状态变更。自定义code的卡券调用接口时, post数据中需包含card_id,非自定义code不需上报。

接口调用请求说明

http请求方式: POST
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) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券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。

线上核销接口

步骤一:拉取卡券列表接口

微信 JS-SDK 只能在微信内置浏览器中使用,其他浏览器调用无效。微信提供chooseCard接口供商户前端网页调用,用于拉起用户名下该商家筛选条件的卡券内容。 点击查看 调起适用于门店的卡券列表并获取用户选择列表JS-SDK

拉取JS API.png

步骤二:Code解码接口

code解码接口支持两种场景: 1.商家获取choos_card_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码

步骤三:查询Code接口

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

详情请见线下核销:查询code接口

步骤四:核销Code接口

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

自定义Code码(use_custom_code为true)的优惠券,在code被核销时,必须调用此接口。用于将用户客户端的code状态变更。自定义code的卡券调用接口时, post数据中需包含card_id,非自定义code不需上报。

接口调用请求说明

http请求方式: POST
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) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券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。