朋友的券-朋友的券核销


上一篇 : 朋友的券-投放朋友的券 下一篇: 朋友的券-朋友的券管理接口



朋友的券核销

接口说明

此处介绍朋友的券的核销方式,分为线上和线下核销两部分,下面分不同的场景介绍。

案例介绍

线下核销

机具扫码核销

场景介绍

具有机具和开发能力的商户可以通过机具扫码进行卡券核销,开发者可以通过机具扫码获得卡券code之后,调用核销code接口将卡券进行核销,方便快捷。

接口调用流程

0 (4).jpg

网页工具核销

场景介绍

若开发者没有能力进行机具开发,可以开发一个核销员端使用的网页进行朋友的券的核销,当用户出示二维码时。

接口调用流程

0 (5).jpg

卡券商户助手核销

场景介绍

手机核销助手是基于“卡券商户助手“公众号的官方卡券核销工具,同样支持朋友的券的核销。

快速体验

步骤一:关注“微信卡券商户助手”

0 (3).jpg

步骤二:进入【微信公众号后台】-【卡券功能】-【卡券核销】-【添加核销员】,为自己的微信号设置核销员权限,并选择已有的门店。

步骤三:用另一台手机领取自己创建的朋友的券,展开二维码并用已设置为核销员的手机扫码或者输码核销卡券。

公众号商户后台核销

商户可以在电脑登录公众号商户后要,【卡券功能】-【卡券核销】-【网页核销】直接核销核销卡券。

线上核销

线上核销涉及的接口与线下核销接口略有不同,线上核销接口需要消费者跳转至H5网页,所以可能会出现两个用户同时使用同一张卡券的情况,我们约定,对于没有点击卡券上的“出示使用”的核销,开发者先调用占用(mark)接口,将一个code(卡券串码)与一个openid(用户身份识别码)关联,保证该code不被另外的人使用。

网页快速核销

场景介绍

若开发者没有办法配置核销员或者商户没办法,可以自定义一个H5核销界面,用户在券面发起核销并在开发者自定义的H5网页内完成核销和裂变送券的过程。

值得开发者注意的是,对于自助核销的卡券,开发者在创建/更新卡券是可以将code_type字段设置为CODE_TYPE_NONE,这样可以隐藏掉卡券上使用二维码的入口(如下图),同时将核销的url通过创建接口中的center_title center_sub_title,center_url写入,那么此自定义入口会指定居中(如下图)

详情请见创建朋友的券接口

0 (2).jpg

接口调用流程

0.png

API详情

查询Code接口

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

接口调用请求说明

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

参数说明

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

POST数据

{
   "card_id": "pbLatjorLTVl-tdvZ6zQRIc-Fn6Y",
    "code": "245645675434",
    "check_consume": true
}
参数名 必填 类型 示例值 描述
code string(20) 110201201245 单张卡券的唯一标准。
card_id string(32) pFS7Fjg8kV1IdDz01r4SQwMkuCKc 卡券ID代表一类卡券。
check_consume bool true 是否校验code核销状态,填入true和false时的code异常状态返回数据不同。

当check_consume为true时返回数据

卡券状态正常:

{
   "errcode": 0,
   "errmsg": "ok",
   "card": {
       "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk",
       "begin_time": 1447397802,
       "end_time": 1452893532
   },
   "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
   "can_consume": true,
   "user_card_status": "NORMAL",
   "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
   "use_count": 1
}

卡券状态异常:

{
   "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": "pbLatjhCp8_HXAq84nHritGPqnjk",
       "begin_time": 1447397802,
       "end_time": 1452893532
   },
   "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
   "can_consume": true,
   "user_card_status": "NORMAL",
   "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
   "use_count": 1
}

卡券状态异常:

{
   "errcode": 0,
   "errmsg": "ok",
   "card": {
       "card_id": "pbLatjhCp8_HXAq84nHritGPqnjk",
       "begin_time": 1447397802,
       "end_time": 1452893532
   },
   "openid": "obLatjm43RA5C6QfMO5szKYnT3dM",
   "can_consume": false,
   "user_card_status": "DELETE",
   "mark_openid": "obLatjjwDolFjRRd3doGIdwNqRXw",
   "use_count": 1
}
参数名 描述
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为不可核销
mark_openid 当前占用此卡券的顾客的openid,核销时仅限该openid的用户可以核销该卡券
use_count 当前占用这个卡券的人已经使用该card_id的次数

注意事项:

1.固定时长有效期会根据用户实际领取时间转换,如用户2013年10月1日领取,固定时长有效期为90天,即有效时间为2013年10月1日-12月29日有效。

2.无论check_consume填写的是true还是false,当code未被添加或者code被转赠领取是统一报错:invalid serial code

拉取卡券列表(ChooseCard)接口

微信 JS SDK 只能在微信内置浏览器中使用,其他浏览器调用无效。微信提供chooseCard接口供商户前端网页调用,用于拉起用户名下该商家筛选条件的卡券内容。

点击查看调起适用于门店的卡券列表并获取用户选择列表JS SDK

0 (1).jpg

获取自定义外链参数

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

假如指定的url为http://www.qq.com,用户点击时,跳转的url则为:http://www.qq.com?card_id=pWXUrtw4ehIUwDTXxkvCC6THenb8&encrypt_code= LPmXP%2BZFM9bdEQPSqcA8%2F%2F6pefbsKaRxnNUMHh5%2Fq6Q%3D &openid=oWXUrt8i3***ymgmPcHKlo0TdgHw

注意:

1.encrypt_code为加密码码,需调用解码接口获取真实Code码。

2.从url中取出的参数须经过urlencode方可用于post请求。

Code解码接口

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

Mark(占用)Code接口

朋友的券由于共享的特性,会出现多个消费者同时进入某一个卡券的自定义H5网页的情况,若该网页涉及线上下单、核销、支付等行为,会造成两个消费者同时使用同一张券,会有一个消费者使用失败的情况,为此我们设计了mark(占用)code接口。

对于出示核销(消费者点击“出示使用”按钮)的场景,开发者直接调用核销接口,无需考虑mark逻辑,此时由客户端代为完成。

对于消费者进入H5网页核销的情况,我们约定,开发者在帮助消费者核销卡券之前,必须帮助先将此code(卡券串码)与一个openid绑定(即mark住),才能进一步调用核销接口,否则报错。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/mark?access_token=TOKEN

参数说明

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

POST数据

{
   "code": "114567897765",
   "card_id": "pbxxxxxxxxhjahkdjad",
   "openid": "obcdkalgsdklkdooooooo",
   "is_mark": true
}
参数名 必填 描述
code 卡券的code码。
card_id 卡券的ID。
openid 用券用户的openid。
is_mark 是否要mark(占用)这个code,填写true或者false,表示占用或解除占用。

返回数据

数据示例:

 {"errcode":0, "errmsg":"ok"}
参数名 描述
errcode 错误码
errmsg 错误信息

注意:

  1. 接口只支持未使用、正常状态的朋友的券,开发者调用前须查询code。

  2. is_mark不填默认为true。

  3. 重复用同一个openid mark,都返回成功。

  4. 用openid_a mark后,用openid_b mark会报错40146

  5. is_mark为false时取消mark,要求传入的openid和mark时一致,否则报错40416。

  6. 不调用接口解除mark的话,5分钟后自动解除。(时间可能根据产品策略调整)

线下核销Code接口

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

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/consume?access_token=TOKEN

参数说明

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

POST数据

非自定义Code卡券的请求 {"code": "12312313"}
参数名 必填 类型 示例值 描述
code string(20) 1231231 需核销的Code码。

返回数据

数据示例:

{
   "errcode": 0,
   "errmsg": "ok",
   "card": {
       "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
   },
   "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}
参数名 描述
errcode 错误码。
errmsg 错误信息。
openid 用户在该公众号内的唯一身份标识。
card_id 卡券ID。

线上核销Code接口

线上核销code接口与普通的核销code接口不同,开发者须传入当前使用该卡券顾客的openid才可以核销。

接口调用请求说明

http请求方式: POST https://api.weixin.qq.com/card/code/consume?access_token=TOKEN

参数说明

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

POST数据

{"code": "12312313", "openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA" }
参数名 必填 类型 示例值 描述
code string(20) 1231231 需核销的Code码。
openid string(20) oFS7Fjl0WsZ9AMZqrI80nbIq8xrA 当前卡券使用者的openid,通常通过网页授权登录或自定义url跳转参数获得。

返回数据

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

注意:

1.只有在线上核销的场景时,调用核销接口才需要传openid参数;

2.线下核销的场景下,核销接口传递的参数仅为code,无需openid。

核销事件推送

卡券被核销时,微信会把这个事件推送到开发者填写的URL。 点击查看卡券核销事件推送

当用户使用优惠券后,商家可通过JS SDK再次赠送一张卡券。核销后再次赠送卡券接口(JS SDK)

0.jpg

该接口仅限6.3.6以上版本客户端使用,且须配置1.1.0的js文件https://res.wx.qq.com/open/js/jweixin-1.1.0.js

详情请见核销后再次赠送卡券接口

帮助

错误码

错误码 说明 排错指引
40003 Invalid opened,缺少openid 核销时用户的卡券未处于展示(mark)状态,朋友的券规定,券必须处于展示(mark)状态时,才允许被核销
40056 无效code Code尚未被领取
40075 错误的encrypt码 请检查加密码是否拼写正确,请检查在url中取出encrypt_code(加密code)在post之前是否做过urlencode
40078 该Code已经被删除或者转赠中 建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销
40079 卡券过期 建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销
40099 Code已经被核销 建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销
40127 该Code已经被删除、置为失效或者转赠成功 建议开发者在调用核销接口之前先调用【查询code接口】确认code有效后再发起核销

常见问题

1、为什么JSSDK拉起卡券列表中没有卡券?

A:JSSDK拉不起卡券一般为签名错误和筛选条件错误,两种情况。 签名错误是指卡券签名错误,建议用http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=cardsign调试筛选条件错误是指shopid/cardid/和cardtype传参有误,比如传入了cash类型的cardtype,但是实际上用户卡包中无此类型卡券。‘

2、为什么要调用mark住接口?

A:由于朋友的券会出现在不同的用户列表中,所以在同一时刻可能有多个用户同时进入开发者开发的核销页面或者下单、支付页面,会出现用户付款但是没有成功核销卡券的情况,所以我们约定必须在卡券核销之前调用mark住接口将code与当前的openid锁定。 其本质是将code与当前使用者锁定的一个锁、 比如快速买单和商城下单的场景可以在支付前调用mark接口,如果mark失败则停止支付,而开发了自主核销页面的开发者可以选择在核销之前mark住code,从而避免冲突的发生。


上一篇 : 朋友的券-投放朋友的券 下一篇: 朋友的券-朋友的券管理接口