回顾
继续介绍NODEJS开发微信卡券功能,昨天简单演示了微信接口的Access Token的原理和用法,还有门店的添加和查询,今天我们将介绍卡券的创建以及核销的最基本的流程。
本文将使用NodeJS作为开发语言,以wechat-card,和官方文档为主进行演示。
创建卡券
昨天我们已经添加完成门店,接下来我们将要创建卡券。微信的API接口为:
https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN
使用wechat-card module可以按照以下操作:
var card = {
card_type: "DISCOUNT",
base_info: {
// ...
},
special_info: {
// ...
}
};
wxCard.card.createCard(card, function(err, cardId) {
// 创建成功后,返回卡券的ID
});
这里有需要特别说明的,card_type为卡券的类型,wechat-card module目前只支持DISCOUNT(折扣券), CASH(现金券), GENERAL_COUPON(普通优惠券), GIFT(礼品券), GROUPON(团购券), LUCK_MONEY(红包),其他类型的大家可以按照官方文档进行操作。
卡券的配置参数中,可以分为三个类型的参数,一是card_type,即卡券类型;二是base_info,即基本信息,所有类型的卡券都会包含这部分参数,具体的参数请参见wechat-card文档或者官方文档;三是每种类型的卡券特有的参数,wechat-card中将这类参数归为special_info。
在base_info中,分为必须参数和可选参数,具体参见文档,这里有几个要特别说明的配置字段:
1. color: 这个字段来设置卡券的背景颜色,我们要特别说明这个字段的原因是,这里的颜色不是我们可以随意设置的,微信提供了一组颜色代码,我们必须从中选择一个。我们可以通过接口来获取到微信提供的颜色列表:
// 微信提供的接口为:https://api.weixin.qq.com/card/getcolors?access_token=TOKEN
wxCard.basic.getColorList(function(err, colors) {
// colors 的格式: [{name: 'Color010', value: '#55bd47' }, ...]
});
2. use_custom_code: 这个字段用来标明该卡券是否使用自定义CODE。这里我们先提前介绍下Code,我们创建一类卡券,比如我们创建了折扣券,其中包含了100的库存量,即有100个用户可以领取,那么每个人领取到的就是一个Code,然后使用卡券,实质上是使用Code。use_custom_code默认值为false,即不使用自定义Code,当为false时, 每次领取卡券,微信会自动生成一个12位的数字作为Code。如果为true,那么我们在发放卡券的时候就需要自定义Code,这个我们在之后会详述。
3. url_name_type: 这个字段不是必须的,他的作用是在卡券界面上添加一个自定义的CELL,和这个字段相配的是custom_url,这两个字段必须同时出现或者不出现。实现的效果是点击自定义Cell跳转到custom_url的链接。
在添加卡券成功后,接口返回卡券的ID。
发放卡券
在创建完成卡券之后,商户需要发放卡券让用户领取,微信目前提供的发放卡券形式有以下几种:(本文只列举微信公开接口,合作接口使用请自行参照文档)
1. 二维码
流程是商户可以通过微信提供的接口生成二维码的Ticket,然后使用Ticket生成二维码,用户通过微信扫描二维码进入卡券领取界面领取卡券。涉及到的接口有:
// 创建二维码Ticket
https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN
// 使用Ticket生成二维码
https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET
使用 wechat-card 生成二维码的步骤很简单,只需要一个步骤:
createCardQRCode("qz_aAidkesdkncsn_AedfZek", function(err, url) {
// url为二维码的URL
});
在得到二维码后,商户可以通过各种方式来传播二维码,用户通过二维码扫描后,可以跳转到微信卡券领取界面。在wechat-card的生成二维码接口中,还有好多配置选项,比如二维码过期时间,二维码是否唯一有效等等的配置,大家可以参照wechat-card文档或者官方文档。
2. JSAPI
这里使用微信内置浏览器的JSAPI跳转到微信卡券的领取界面,由于JSAPI方式设计前端内容较多,所以本文不详述,只介绍几个需要注意的信息,在后续的文章中,会有单独介绍JSAPI各种操作。
在使用JSAPI发放卡券时,使用的时batchAddCard接口,在这个接口需要提交卡券ID和卡券信息,在卡券信息中有个配置项为Signature(签名),这个签名是需要计算的,具体的计算方式为:
将api_ticket、timestamp、card_id、code、openid、balance的value值进行字符串的字典序排序,然后将排序后的字符串连接为一个字符串,进行sha1加密。
用JS代码来介绍上面的概念:
var arr = new Array(api_ticket, timestamp, card_id, code, openid, balance);
// 转为字符串
arr = arr.map(function(n){
return n.toString();
});
// 字典序排序
arr = arr.sort();
// 拼接为字符串
var str = arr.join("");
// 进行SHA1加密,sha1算法需自行实现
var signature = sha1(str);
在 wechat-card 中也提供了计算签名的方法:
var data = ['ApiTicket', 'CardId', 'timestamp'];
wxCard.basic.getSignature(data, function(err, signature) {
// do something ...
});
这里有需要注意的几点:
1. api_ticket: 这个字段为微信卡券API V1.9时新增的内容,其原理和access_token类似:7200秒过期,请求次数有限制。不过不同的是:api_ticket微信会做刷新,也就是说我们在有效期内请求api_ticket,结果都是一样的。所以我们需要和微信接口进行时间对齐,即7200秒进行请求更新我们自己管理的ticket。(有问题?如果在好多不可控因素下导致时间误差怎么办?微信的结论是他们会在一定的时间范围内进行容错处理,所以这个问题应该就可以忽视了。)
2. timestamp: 这个字段是一个时间戳(单位为秒)。需要注意的是,在提交卡券信息时里面也有一个时间戳,要求卡券信息中的时间戳和Signature中的时间戳必须一致。
3. code, openid, balance都是可选字段,需要在某种场合下才是必填选项,详细请参见文档。
核销卡券
领取完卡券后,下一步是使用,对于商户来说就是核销。在微信卡券中,核销卡券的唯一途径就是消耗Code(Code概念请参照上文)。
https://api.weixin.qq.com/card/code/consume?access_token=TOKEN
在wechat-card中,消耗Code的方法如下:
// 下面的code仅用于demo,实际中不存在
var code = "882077290937";
wxCard.code.consumeCode(code, function(err, consumeInfo) {
// do something ...
});
PS: Code从哪里来?
1. 领取卡券后,可以在微信卡包中找到卡券,在卡券上会有一个二维码,或者一串数字,或者两者都有,或者一维码等等的形式(详见卡券的code_type配置)。那么那串数字就是Code,或者扫描二维码的结果就是Code。
2. 如果使用JSAPI拉起卡券列表,在选取卡券后会得到一个加密的Code,使用decryptCode方法可以进行解码得到真实Code,详见文档。这里就不做演示了。
小结
至此,一个从卡券创建到使用卡券的简单流程就介绍完成了。之后的文章将会针对卡券的管理以及其他的功能进行介绍,希望大家关注。最后,提前祝大家新年快乐!!;)