小程序发券插件

更新时间：2023.08.16

支持商户在小程序场景内，向指定用户发放指定批次的支付券或商家券。

# 接口说明

支持商户： 【普通商户】

接口规则： 本接口使用V2版本接口规则，详见V2接口规则 (opens new window)内容

# 小程序接入插件操作

插件版本号：latest（更新时间 2021/06/23）

【推荐】如希望每次默认使用最新版本，可在App.json 文件配置"version": "latest"；

如需指定版本，可点击查看更新记录 (opens new window)选择版本

# 1、添加插件配置（引入插件包）

在小程序配置App.json 文件中加入如下配置：

1{
2  "plugins": {
3    "sendCoupon": {
4      "version": "latest",
5      "provider": "wxf3f436ba9bd4be7b"
6    }
7  }
8}

# 2、在小程序页面中引入发券插件

1）在小程序页面配置文件中加入如下配置，引入send-coupon组件：

1{
2  "usingComponents": {
3    "send-coupon": "plugin://sendCoupon/send-coupon"
4  }
5}

2）在小程序页面的WXML模板中加入如下代码，并填入相关字段，字段说明参见下方小程序发券插件字段说明表

1//page.wxml
2<send-coupon
3    bind:sendcoupon="getcoupon"
4    bind:userconfirm="redirectuser"
5    send_coupon_params="{{send_coupon_params}}"
6    sign="{{sign}}"
7    send_coupon_merchant="{{send_coupon_merchant}}"
8    suggest_immediate_use="{{suggest_immediate_use}}"
9  >
10    <!-- 内部为自定义代码，按钮点击部分的代码写在这里 -->
11    <!-- [[以下为示例代码 -->
12    <view class="text">领券</view>
13    <!-- 以上为示例代码 ]] -->
14  </send-coupon>

# 小程序发券插件字段说明表

bind:sendcoupon / bindsendcoupon【原接口为bindcustomevent，建议更新原接口名称】选填 string

插件在用户点击后成功获取到优惠券信息触发的事件函数名称，使用方法可参考《自定义组件文档》的自定义组件触发事件
注意：查询到优惠券信息不代表用户一定能够看到优惠券弹窗或者发券成功，如果参数send_coupon_result中没有券发送成功（券状态码不为SUCCESS），用户会被告知领券失败

bind:userconfirm / binduserconfirm 选填 string

用户点击弹窗中的确认收券按钮后触发的事件函数名称，可用作跳转到优惠券的使用界面

suggest_immediate_use 选填 boolean

提示优惠券是否要立即使用，如果为true，弹窗中的确认按钮内的文字为“立即使用”，如果为false，则显示为“我知道了”，参数默认值为false
注意：此参数对用户是否立即使用没有约束力，需要商家在用户确认领券事件内自行约束。如果此参数设为true，请在binduserconfirm事件中引导用户使用优惠券

send_coupon_params 必填 array

发券参数，一次最多10张

数组

sign 必填 string(64)

签名计算值。
签名方式：HMAC-SHA256。
签名规则：详见《V2 签名规则》
参与签名字段说明

send_coupon_merchant 必填 string(15)

发券商户号

# 参与签名字段说明

注意

1、当存在发放一张或多张券的情况下，参数名使用下标表示，下标从0开始：发放一张券示例值：out_request_no0=abc123&send_coupon_merchant=10016226&stock_id0=1234567&key=xxxxx

发放多张券示例值：out_request_no0=abc123&out_request_no1=123abc&send_coupon_merchant=10016226&stock_id0=1234567&stock_id1=2345678&key=xxxxx

2、当批次是发放时指定code的类型的情况下：发放一张券示例值：coupon_code0=asdsada&out_request_no0=abc123&send_coupon_merchant=10016226&stock_id0=1234567&key=xxxxx

发放多张券示例值：coupon_code0=asdsada&coupon_code1=asdsada&out_request_no0=abc123&out_request_no1=123abc&send_coupon_merchant=10016226&stock_id0=1234567&stock_id1=2345678&key=xxxxx

3、如果遇到签名失败，请按照下面几项进行检查

签名方式一定要用 HMAC-SHA256
key需要使用APIv2的signkey，设置路径：【微信商户平台-->账户中心-->账户设置-->API安全-->设置API密钥】
确认key的正确性，例如是否是本商户号下的key
签名源串请按照示例参数格式进行拼接，参数顺序按照字典序排列
参数名严格区分大小写
更多规则详见《V2签名规则 (opens new window)》

send_coupon_merchant 必填 string(15)

发券商户号

stock_id{n} 必填 string(20)

微信支付券批次ID，{n}为下标，从0开始，例如stock_id0

out_request_no{n} 必填 string(64)

发券凭证，{n}为下标，从0开始，例如out_request_no0。可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号，需在单个批次单个用户下确保唯一性

coupon_code{n} 选填 string(128)

券code，如果批次是发放时指定code的类型，则发券时必填coupon_code{n}为下标，从0开始，例如stock_id0

customize_send_time 选填 string(32)

商家券在商户业务系统里的实际领取时间，仅针对有设置相对领取时间的批次生效（即批次有设置“生效后N天内有效”或“领取后N天开始生效”时间字段）。传入后，将使用传入的时间点，做为商家券领取时间来计算有效期，而非用户在微信支付系统中点击领取的时间。
遵循rfc3339标准格式，格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。例如：2015-05-20T13:29:35.+08:00表示，北京时间2015年5月20日 13点29分35秒。
目前只支持商家券、支付券暂不支持

create_coupon_merchant{n} 选填 string(15)

创建支付券的商户号； {n}为下标，从0开始，例如create_coupon_merchant0。如果是支付券，则是必填项；商家券无需填写

# 3、在小程序页面对应的JS逻辑中，获取插件实例并执行初始化操作

1javascript
2//page.js
3Page({
4  // 此函数名称可以自定义，跟bindcustomevent绑定的保持一致
5  getcoupon: function(params) {
6    // 插件返回信息在params.detail
7    console.log('getcoupon', params)
8  }
9})

如果事件绑定正确，在用户点击领券后，会触发领券事件，得到返回之后会调用getcoupon函数。

# 返回处理

从回调函数参数detail中，获取参数。

errcode 必填 string（32）

返回整体错误码

msg 必填 string(128)

返回整体错误信息

send_coupon_result 必填 object

发券结果，包含需要发放的每张券的结果信息，是否成功或失败原因

属性

# 返回示例

1javascript
2//获取代码示例
3Page({
4  data: {
5    // ...
6  },
7  onLoad: function() {
8    // ...
9  },
10  getcoupon: function(params) {
11    console.log('getcoupon', params)
12    console.log('detail', params.detail)
13  }
14})

# 错误码

# Detail中errcode返回错误码

错误码	描述	解决方案
OK	调用成功	接口调用成功，具体发券结果（是否发券成功）需查看发券结果（send_coupon_result）中的参数
PARAM_ERROR	参数错误	参数错误，请开发者查看msg中具体的错误信息并进行修复处理
USER_NOT_EXISTS	登录态获取失效	引导用户重试
USER_GET_FAILED	登录态获取失败	报错，提示用户稍后操作
SIGN_ERROR	签名错误	请开发者检查签名正确性
SYSTEMERROR	发券超时	提示报错，提示用户稍后操作
FREQUENCY_LIMITED	发券频率过高	提示报错，引导用户稍后操作。例如“活动太过火爆，请稍后再领取

# 发券结果（send_coupon_result）中的错误码

错误码	描述	解决方案
SUCCESS	该张券发券成功	提示用户领取成功/改变前端领券按钮状态
FAILED	该张券发券失败，查看message中的具体错误信息	提示用户领券失败，请开发者查看message中具体的错误信息并进行修复处理
NOTENOUGH	总预算用完	提示用户领券失败，请增加批次预算
DAYLIMIT	用户达到单天限领	提示用户领券失败，如需继续发放，可调整该批次单天发放上限
NATURELIMIT	用户自然人限领	提示用户领券失败，可提示用户检查其所有微信号领券情况，并请商户留意刷单风险
MAXQUOTA	用户领取张数达到上限	提示用户领券失败，该用户领取数量已达上限
DUPREQUEST	已通过该发券凭证给用户发券	提示用户领取成功/改变前端领券按钮状态
NOTRUNNING	批次状态非运营中	提示用户领券失败，并检查批次状态如果批次是暂停状态，需重启后方可发放如果批次已过期，请更换批次
EXPIRED	该批次已过期	请更换在有效期内的批次，再进行发放
NOTMONEY	账户余额不足	请检查批次号是否正确
USERLIMIT	用户已超限领额度	提示用户已超限领额度
FREQUENCYLIMIT	超过频率限制	可稍后重试

文档是否有帮助

服务商文档

小程序发券插件参考文档

更多支持

开发者社区微信开放平台微信公众平台腾讯客服