核销微信平台的卡券

由 如此轻盈 创建，Carrie 最后一次修改 2016-09-27 核销卡券更新日志版本号更新内容更新时间V1.01.规范核销引导流程，建议开发者调用核销接口之前先调用查询code接口查看code状态2.优化查询code接口，便于开发者使用，同时兼容旧接口2015-8-31该部分主要介绍开发者如何在用户使用券之后让卡券从用户的微信客户端消失的过程，这个步骤称为核销。核销目前分为线上核销和线下核销两种类型。线上核销指用户从券面进入一个HTML5网页后主动销券的过程，如微信商城用券、自助核销等；线下核销指用户到店后，出示二维码或者出示串码，由收银员完成核销动作，如扫码核销、机具核销等。1线下核销  1.1 查询Code接口我们强烈建议开发者在调用核销code接口之前调用查询code接口，并在核销之前对非法状态的code(如转赠中、已删除、已核销等)做出处理。接口调用请求说明HTTP请求方式: POSTURL: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否booltrue是否校验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用户openidcard_id卡券IDbegin_time起始使用时间end_time结束时间user_card_status当前code对应卡券的状态NORMAL          正常 CONSUMED     已核销 EXPIRE              已过期 GIFTING            转赠中GIFT_TIMEOUT  转赠超时 DELETE              已删除UNAVAILABLE   已失效 code未被添加或被转赠领取的情况则统一报错：invalid serial codecan_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请求方式: POSTURL: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。注意事项：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-SDK2.2 Code解码接口code解码接口支持两种场景： 1.商家获取choos_card_info后，将card_id和encrypt_code字段通过解码接口，获取真实code。 2.卡券内跳转外链的签名中会对code进行加密处理，通过调用解码接口获取真实code。接口调用请求说明HTTP请求方式: POSTURL: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码   注意事项1.只能解码本公众号卡券获取的加密code。 2.开发者若从url上获取到加密code,请注意先进行urldecode，否则报错。3.encrypt_code是卡券的code码经过加密处理得到的加密code码，与code一一对应。4.开发者只能解密本公众号的加密code，否则报错。2.3 查询Code接口我们强烈建议开发者在调用核销code接口之前调用查询code接口，并在核销之前对非法状态的code(如转赠中、已删除、已核销等)做出处理。2.4 核销Code接口线上核销普通券的接口同线下核销普通券的接口一致。