浅谈微信卡券功能开发（2）

2023-10-21 16:43:34

回顾

继续介绍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，详见文档。这里就不做演示了。

小结

至此，一个从卡券创建到使用卡券的简单流程就介绍完成了。之后的文章将会针对卡券的管理以及其他的功能进行介绍，希望大家关注。最后，提前祝大家新年快乐！！;)

浅谈微信卡券功能开发（2）

码农公寓

相关文章