支持商戶在小程序場景內(nèi),向指定用戶發(fā)放指定批次的支付券或商家券。
# 接口說明
支持商戶: 【普通商戶】
接口規(guī)則: 本接口使用V2版本接口規(guī)則,詳見V2接口規(guī)則 (opens new window)內(nèi)容
# 小程序接入插件操作
插件版本號:latest(更新時間 2021/06/23)
【推薦】如希望每次默認(rèn)使用最新版本,可在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、在小程序頁面中引入發(fā)券插件
1)在小程序頁面配置文件中加入如下配置,引入send-coupon組件:
1{2 "usingComponents": {3 "send-coupon": "plugin://sendCoupon/send-coupon"4 }5}
2)在小程序頁面的WXML模板中加入如下代碼,并填入相關(guān)字段,字段說明參見下方小程序發(fā)券插件字段說明表
1//page.wxml2<send-coupon3 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 <!-- 內(nèi)部為自定義代碼,按鈕點擊部分的代碼寫在這里 -->11 <!-- [[以下為示例代碼 -->12 <view class="text">領(lǐng)券</view>13 <!-- 以上為示例代碼 ]] -->14 </send-coupon>
# 小程序發(fā)券插件字段說明表
- bind:sendcoupon / bindsendcoupon【原接口為bindcustomevent,建議更新原接口名稱】 選填 string插件在用戶點擊后成功獲取到優(yōu)惠券信息觸發(fā)的事件函數(shù)名稱,使用方法可參考《自定義組件文檔
》的自定義組件觸發(fā)事件注意:查詢到優(yōu)惠券信息不代表用戶一定能夠看到優(yōu)惠券彈窗或者發(fā)券成功,如果參數(shù)send_coupon_result中沒有券發(fā)送成功(券狀態(tài)碼不為SUCCESS),用戶會被告知領(lǐng)券失敗 - bind:userconfirm / binduserconfirm 選填 string用戶點擊彈窗中的確認(rèn)收券按鈕后觸發(fā)的事件函數(shù)名稱,可用作跳轉(zhuǎn)到優(yōu)惠券的使用界面
- suggest_immediate_use 選填 boolean提示優(yōu)惠券是否要立即使用,如果為true,彈窗中的確認(rèn)按鈕內(nèi)的文字為“立即使用”,如果為false,則顯示為“我知道了”,參數(shù)默認(rèn)值為false注意:此參數(shù)對用戶是否立即使用沒有約束力,需要商家在用戶確認(rèn)領(lǐng)券事件內(nèi)自行約束。如果此參數(shù)設(shè)為true,請在binduserconfirm事件中引導(dǎo)用戶使用優(yōu)惠券
- send_coupon_params 必填 array發(fā)券參數(shù),一次最多10張
- 數(shù)組
- sign 必填 string(64)簽名計算值。簽名方式:HMAC-SHA256。簽名規(guī)則:詳見《V2 簽名規(guī)則》
參與簽名字段說明 - send_coupon_merchant 必填 string(15)發(fā)券商戶號
# 參與簽名字段說明
注意
1、當(dāng)存在發(fā)放一張或多張券的情況下,參數(shù)名使用下標(biāo)表示,下標(biāo)從0開始: 發(fā)放一張券示例值:out_request_no0=abc123&send_coupon_merchant=10016226&stock_id0=1234567&key=xxxxx
發(fā)放多張券示例值:out_request_no0=abc123&out_request_no1=123abc&send_coupon_merchant=10016226&stock_id0=1234567&stock_id1=2345678&key=xxxxx
2、當(dāng) 批次是發(fā)放時指定code的類型的情況下: 發(fā)放一張券示例值:coupon_code0=asdsada&out_request_no0=abc123&send_coupon_merchant=10016226&stock_id0=1234567&key=xxxxx
發(fā)放多張券示例值: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、如果遇到簽名失敗,請按照下面幾項進(jìn)行檢查
- 簽名方式一定要用 HMAC-SHA256
- key需要使用APIv2的signkey,設(shè)置路徑:【微信商戶平臺-->賬戶中心-->賬戶設(shè)置-->API安全-->設(shè)置API密鑰】
- 確認(rèn)key的正確性,例如是否是本商戶號下的key
- 簽名源串請按照示例參數(shù)格式進(jìn)行拼接,參數(shù)順序按照字典序排列
- 參數(shù)名嚴(yán)格區(qū)分大小寫
- 更多規(guī)則詳見《V2簽名規(guī)則 (opens new window)》
- send_coupon_merchant 必填 string(15)發(fā)券商戶號
- stock_id{n} 必填 string(20)微信支付券批次ID,{n}為下標(biāo),從0開始,例如stock_id0
- out_request_no{n} 必填 string(64)發(fā)券憑證,{n}為下標(biāo),從0開始,例如out_request_no0。可包含英文字母,數(shù)字,|,_,*,-等內(nèi)容,不允許出現(xiàn)其他不合法符號,需在單個批次單個用戶下確保唯一性
- coupon_code{n} 選填 string(128)券code,如果批次是發(fā)放時指定code的類型,則發(fā)券時必填coupon_code{n}為下標(biāo),從0開始,例如stock_id0
- customize_send_time 選填 string(32)商家券在商戶業(yè)務(wù)系統(tǒng)里的實際領(lǐng)取時間,僅針對有設(shè)置相對領(lǐng)取時間的批次生效(即批次有設(shè)置“生效后N天內(nèi)有效”或“領(lǐng)取后N天開始生效”時間字段)。傳入后,將使用傳入的時間點,做為商家券領(lǐng)取時間來計算有效期,而非用戶在微信支付系統(tǒng)中點擊領(lǐng)取的時間 。遵循rfc3339
標(biāo)準(zhǔn)格式,格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出現(xiàn)在字符串中,表示time元素的開頭,HH:mm:ss表示時分秒,TIMEZONE表示時區(qū)(+08:00表示東八區(qū)時間,領(lǐng)先UTC 8小時,即北京時間)。例如:2015-05-20T13:29:35.+08:00表示,北京時間2015年5月20日 13點29分35秒。目前只支持商家券、支付券暫不支持 - create_coupon_merchant{n} 選填 string(15)創(chuàng)建支付券的商戶號; {n}為下標(biāo),從0開始,例如create_coupon_merchant0。 如果是支付券,則是必填項; 商家券無需填寫
# 3、在小程序頁面對應(yīng)的JS邏輯中,獲取插件實例并執(zhí)行初始化操作
1javascript2//page.js3Page({4 // 此函數(shù)名稱可以自定義,跟bindcustomevent綁定的保持一致5 getcoupon: function(params) {6 // 插件返回信息在params.detail7 console.log('getcoupon', params)8 }9})
如果事件綁定正確,在用戶點擊領(lǐng)券后,會觸發(fā)領(lǐng)券事件,得到返回之后會調(diào)用getcoupon函數(shù)。
# 返回處理
從回調(diào)函數(shù)參數(shù)detail中,獲取參數(shù)。
- errcode 必填 string(32)返回整體錯誤碼
- msg 必填 string(128)返回整體錯誤信息
- send_coupon_result 必填 object發(fā)券結(jié)果,包含需要發(fā)放的每張券的結(jié)果信息,是否成功或失敗原因
- 屬性
# 返回示例
1javascript2//獲取代碼示例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 | 調(diào)用成功 | 接口調(diào)用成功,具體發(fā)券結(jié)果(是否發(fā)券成功)需查看發(fā)券結(jié)果(send_coupon_result)中的參數(shù) |
PARAM_ERROR | 參數(shù)錯誤 | 參數(shù)錯誤,請開發(fā)者查看msg中具體的錯誤信息并進(jìn)行修復(fù)處理 |
USER_NOT_EXISTS | 登錄態(tài)獲取失效 | 引導(dǎo)用戶重試 |
USER_GET_FAILED | 登錄態(tài)獲取失敗 | 報錯,提示用戶稍后操作 |
SIGN_ERROR | 簽名錯誤 | 請開發(fā)者檢查簽名正確性 |
SYSTEMERROR | 發(fā)券超時 | 提示報錯,提示用戶稍后操作 |
FREQUENCY_LIMITED | 發(fā)券頻率過高 | 提示報錯,引導(dǎo)用戶稍后操作。例如“活動太過火爆,請稍后再領(lǐng)取 |
# 發(fā)券結(jié)果(send_coupon_result)中的錯誤碼
錯誤碼 | 描述 | 解決方案 |
---|---|---|
SUCCESS | 該張券發(fā)券成功 | 提示用戶領(lǐng)取成功/改變前端領(lǐng)券按鈕狀態(tài) |
FAILED | 該張券發(fā)券失敗,查看message中的具體錯誤信息 | 提示用戶領(lǐng)券失敗,請開發(fā)者查看message中具體的錯誤信息并進(jìn)行修復(fù)處理 |
NOTENOUGH | 總預(yù)算用完 | 提示用戶領(lǐng)券失敗,請增加批次預(yù)算 |
DAYLIMIT | 用戶達(dá)到單天限領(lǐng) | 提示用戶領(lǐng)券失敗,如需繼續(xù)發(fā)放,可調(diào)整該批次單天發(fā)放上限 |
NATURELIMIT | 用戶自然人限領(lǐng) | 提示用戶領(lǐng)券失敗,可提示用戶檢查其所有微信號領(lǐng)券情況,并請商戶留意刷單風(fēng)險 |
MAXQUOTA | 用戶領(lǐng)取張數(shù)達(dá)到上限 | 提示用戶領(lǐng)券失敗,該用戶領(lǐng)取數(shù)量已達(dá)上限 |
DUPREQUEST | 已通過該發(fā)券憑證給用戶發(fā)券 | 提示用戶領(lǐng)取成功/改變前端領(lǐng)券按鈕狀態(tài) |
NOTRUNNING | 批次狀態(tài)非運營中 | 提示用戶領(lǐng)券失敗,并檢查批次狀態(tài) 如果批次是暫停狀態(tài),需重啟后方可發(fā)放 如果批次已過期,請更換批次 |
EXPIRED | 該批次已過期 | 請更換在有效期內(nèi)的批次,再進(jìn)行發(fā)放 |
NOTMONEY | 賬戶余額不足 | 請檢查批次號是否正確 |
USERLIMIT | 用戶已超限領(lǐng)額度 | 提示用戶已超限領(lǐng)額度 |
FREQUENCYLIMIT | 超過頻率限制 | 可稍后重試 |