核销微信平台的卡券

更新日志

该部分主要介绍开发者如何在用户使用券之后让卡券从用户的微信客户端消失的过程，这个步骤称为核销。

核销目前分为线上核销和线下核销两种类型。

线上核销指用户从券面进入一个HTML5网页后主动销券的过程，如微信商城用券、自助核销等；

线下核销指用户到店后，出示二维码或者出示串码，由收银员完成核销动作，如扫码核销、机具核销等。

1线下核销

  1.1 查询Code接口

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

接口调用请求说明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/code/get?access_token=TOKEN

参数说明

POST数据

{
   "card_id" : "card_id_123+",
   "code" : "123456789",
   "check_consume" : 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"
}

卡券状态异常：

{
 "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"
}

注意事项：

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数据

非自定义Code卡券的请求
{
  "code": "12312313"
}
或自定义Code卡券的请求
{
  "code": "12312313",
  "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
}

返回数据 

 {
"errcode":0,
"errmsg":"ok",
"card":{"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"},
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}

注意事项：

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数据

{
  "encrypt_code":"XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"
}

  参数说明

返回数据

 {
  "errcode":0,
  "errmsg":"ok",
  "code":"751234212312"
  }

   参数说明

   注意事项

1.只能解码本公众号卡券获取的加密code。 

2.开发者若从url上获取到加密code,请注意先进行urldecode，否则报错。

3.encrypt_code是卡券的code码经过加密处理得到的加密code码，与code一一对应。

4.开发者只能解密本公众号的加密code，否则报错。

2.3 查询Code接口

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

2.4 核销Code接口

线上核销普通券的接口同线下核销普通券的接口一致。