免費(fèi)AI編程助手
微信優(yōu)惠券 朋友的券專區(qū)
2019-03-14 15:02 更新
更新日志
| 版本號 | 更新內(nèi)容 | 更新時(shí)間 |
|---|---|---|
| V1.1 | 1.限制共享券代金券類型標(biāo)題傳入，統(tǒng)一命名為xxx元代金券，xxx為減免金額字段； 2.禮品券更名為兌換券，限制標(biāo)題傳入，統(tǒng)一命名為：洗手液(商品名)+1(數(shù)量)+瓶（數(shù)量單位），對應(yīng)gift_name,gift_num,和gift_unit字段。 | 2015-12-2 |
| V1.2 | 1.新增朋友的券白名單接口，支持領(lǐng)取共享未通過審核的共享券，僅限白名單list內(nèi)用戶可見。 2.新增朋友的券測試沙箱機(jī)制，未在開放類目內(nèi)的開發(fā)者可以通過沙箱測試號測試創(chuàng)建、領(lǐng)取共享券 3.新增接口充值庫存、券點(diǎn)系列接口，開發(fā)者可以通過接口完成庫存、券點(diǎn)的充值和管理。 4.支持接口創(chuàng)建有門檻朋友的券，目前支持“滿減券”、“指定品類券”和“不與其他優(yōu)惠共享”類型門檻。 | 2015-12-27 |
| V1.3 | 1.根據(jù)開發(fā)者填入的不同門檻，卡券標(biāo)題拼接方案變更； 2.支持開發(fā)者填入使用時(shí)段限制，比如：周一 10：00-20:59可用；周一至周五 10：00-20:59可用 | 2016-2-16 |
| V1.4 | 新創(chuàng)建的朋友的券只能在生效前提前5天投放，否則不可領(lǐng)取 | 2016-4-12 |
朋友的券簡介
“朋友共享的優(yōu)惠券”（以下簡稱“朋友的券”），是基于微信優(yōu)惠券推出的新功能，實(shí)現(xiàn)“一人領(lǐng)取多人共享”的快速社交傳播和轉(zhuǎn)化的效果。
領(lǐng)取并與朋友共享此券，券會自動展示在領(lǐng)取人及其朋友的優(yōu)惠券列表中，領(lǐng)取人及其朋友均可使用此券。商戶可選擇贈送配置：當(dāng)朋友的券被使用后,根據(jù)商戶配置的贈送量,使用者將立即獲贈一張朋友的券,繼續(xù)與朋友共享此券。
朋友的券的優(yōu)勢
1、高曝光量：朋友的券被領(lǐng)取后，將自動展示在領(lǐng)取者及其朋友的微信優(yōu)惠券里，曝光量得到大幅提升。
2、高轉(zhuǎn)化率：一張優(yōu)惠券，傳統(tǒng)玩法下只曝光至一個(gè)用戶，朋友的券新玩法下可以曝光至領(lǐng)取者及其朋友們；同樣的預(yù)算成本，得到更大量的曝光，轉(zhuǎn)化率、收益也會得到有效提升。
3、朋友推薦： 優(yōu)惠經(jīng)過領(lǐng)取者認(rèn)可后才會被共享給朋友們，該朋友的券的價(jià)值有領(lǐng)取者的背書，更值得信賴；同時(shí)微信朋友間的相似喜好，可以進(jìn)一步提高朋友的券的轉(zhuǎn)化率。
4、裂變：朋友的券被用戶或其朋友核銷后，商家可以立即再次贈送優(yōu)惠券供使用者領(lǐng)取共享，且贈券仍為朋友的券。這讓商家的優(yōu)惠在用戶中得到持續(xù)的曝光。
開放對象
朋友的券將按照卡券商戶的類目逐步開放，首批開放朋友的券功能的商戶類目如下。后續(xù)將向更多類目商戶逐步開放，請關(guān)注微信公眾平臺公告。
| 一級類目 | 二級內(nèi)容 |
|---|---|
| 美食 | 粵菜、茶餐廳、川菜、湘菜、東北菜、西北菜、火鍋、自助餐、小吃、快餐、日本料理、韓國料理、東南亞菜、西餐、面包甜點(diǎn)、咖啡廳、江浙菜、其它美食、外賣 |
| 休閑娛樂 | 展覽展出、溫泉洗浴、足療按摩、運(yùn)動健身、棋牌室、KTV、酒吧/俱樂部、藝術(shù)寫真、寵物美容、美容美發(fā)、美甲 |
| 生活服務(wù) | 快遞、寵物醫(yī)療、物業(yè)管理、家政服務(wù)、養(yǎng)生養(yǎng)護(hù) |
| 電影票 | 電影票 |
| 酒店 | 快捷酒店、度假村、星級酒店 |
| 購物 | 母嬰用品、普通食品、鮮花禮品、家紡家裝、鐘表眼鏡、日護(hù)用品、化妝品、運(yùn)動戶外、鞋類箱包、服飾、副食品門市、超市/便利店、購物中心/購物街、百貨商場 |
| 生活服務(wù) | 婚慶服務(wù)、加油站、汽車維修、汽車駕校 |
| 旅游 | 景點(diǎn)門票 |
| 購物 | 便利店、珠寶配飾、家居、建材五金/機(jī)械儀表、樂器、酒類、藥房/藥店、圖書報(bào)刊雜志、數(shù)碼家電 |
| 運(yùn)輸票務(wù) | 機(jī)票、船票、車票 |
特別說明
優(yōu)惠券共享的玩法，將極大地提升優(yōu)惠券的曝光量和使用率。優(yōu)惠券使用后，會引入好友互動，增加社交趣味性。特別地，朋友共享的優(yōu)惠券，需要滿足以下要求1、選擇起用金額為0元的無門檻代金券或無門檻兌換券，或選擇指定門檻類型的代金券或者兌換券，目前支持的門檻類型為：滿減門檻（滿xxx可用）、指定品類門檻（指定xxx可用/不可用）以及不與其他優(yōu)惠共享門檻，詳情請見選擇朋友的券門檻；
2、需要設(shè)置圖文介紹的優(yōu)惠詳情（advanced_info字段）；
3、可選擇每核銷使用1張優(yōu)惠券，再送用戶1張；
4、暫不支持商家自定義Code碼；
開發(fā)者注意事項(xiàng)
1、登錄【微信公眾平臺后臺】，點(diǎn)擊【卡券功能】或者調(diào)用開通券點(diǎn)賬戶接口開通朋友的券券點(diǎn)賬戶，目前商戶后臺該開通入口僅針對指定類目商戶開放，如還沒發(fā)現(xiàn)入口開發(fā)者可以先耐心等待，后續(xù)會逐步放開；2、創(chuàng)建優(yōu)惠券：其中先準(zhǔn)備好LOGO、門店、色值等內(nèi)容，然后使用創(chuàng)建接口，創(chuàng)建起用金額為0元的代金券，并填入圖文介紹，設(shè)置每核銷1張，再贈送用戶1張，得到card_id。
3、調(diào)用兌換庫存、充值券點(diǎn)系列接口為優(yōu)惠券配置庫存，為賬號充值券點(diǎn)。
4、投放朋友的券：設(shè)置庫存后，開發(fā)者可以取card_id通過生成二維碼或者掃碼打開的H5投放，同時(shí)也可以通過微信搖一搖或者微信WIFI渠道打開的H5投放卡券，用戶掃碼即可共享此券。
若卡券未通過審核，開發(fā)者可以通過設(shè)置白名單接口設(shè)置接口白名單領(lǐng)取未審核通過的優(yōu)惠券并共享，共享后僅接口白名單內(nèi)的好友可見。
5、核銷朋友的券：共享的用戶及其好友，可以看到此券，到店出示享受優(yōu)惠，使用后再獲得贈送的卡券繼續(xù)和好友共享，此部分開發(fā)者須使用核銷助手或開發(fā)核銷工具幫助商戶核銷。
6、管理朋友的券：開發(fā)者在卡券投放發(fā)布后可對卡券信息進(jìn)行修改或統(tǒng)計(jì)卡券數(shù)據(jù)。
創(chuàng)建朋友的券
朋友的券樣式
朋友的券較之前的樣式有較大改變，卡券背景色更加突出，強(qiáng)調(diào)券的整潔和美觀的同時(shí)將商戶元素更加有強(qiáng)調(diào)性地展示，同時(shí)支持圖文介紹傳入，給了商戶更大的曝光空間。
接口調(diào)用說明
創(chuàng)建卡券是卡券開發(fā)的第一步，開發(fā)者需要傳入優(yōu)惠內(nèi)容生成一個(gè)card_id，并在通過審核后進(jìn)行投放、核銷等動作。在進(jìn)行卡券創(chuàng)建前，請開發(fā)者根據(jù)自身業(yè)務(wù)場景確定以下幾點(diǎn)
選擇合適的門檻類型
目前朋友的券支持無門檻類型以及指定門檻類型的代金券、兌換券，微信后臺會根據(jù)商戶填寫的門檻類型自動拼接卡券的詳情摘要字段和卡券標(biāo)題字段，開發(fā)者可以根據(jù)需求選擇合適的門檻類型組合，獲得最佳的發(fā)券效果。
商戶按照指定字段填寫門檻有利于優(yōu)惠券審核快速通過，若商戶填寫了非以下類型的門檻，優(yōu)惠券將不會被審核通過。
同時(shí)，微信后臺會根據(jù)卡券選擇的門檻不同而設(shè)置不同的庫存價(jià)格，目前定價(jià)標(biāo)準(zhǔn)為：
1）無門檻類型，保持0.2券點(diǎn)/張； 2）指定品類可用/不可用門檻，0.4券點(diǎn)/張； 3）滿減/買xx可用門檻，0.6券點(diǎn)/張；
不同門檻類型的字段以及展現(xiàn)
微信后臺會根據(jù)開發(fā)者填入不同的門檻字段決定券的樣式和展現(xiàn)，下面以一張50元代金券和兌換蛋撻一個(gè)的兌換券說明不同門檻帶來的 展現(xiàn)邏輯變化。
| 門檻類型 | 適用券種 | 設(shè)置條件 | 詳情摘要 | 標(biāo)題 |
|---|---|---|---|---|
| 無門檻 | 代金券/兌換券 | 不填入任何門檻字段 | 無起用金額限制，全場通用，不限品類 | 50元代金券/蘋果一個(gè) |
| 指定品類可用/不可用門檻 | 代金券 | 填入accept_category（蛋撻）和reject_category（蛋糕）字段 | 適用于蛋撻，不適用于蛋糕 | 蛋撻減50元（填入的accept_catagory小于等于5個(gè)漢字）；50元代金券（填入的accept_catagory大于5個(gè)漢字） |
| 滿減門檻 | 代金券/兌換券 | 填入least_cost（500）字段 | 消費(fèi)滿500元可用 | 全場滿500減50 |
| 買送門檻（限兌換券） | 兌換券 | 填入object_use_for字段 | 購買蛋糕可用 | 買蛋糕送蛋撻 |
| 不與其他優(yōu)惠共享門檻 | 代金券/兌換券 | 填入can_use_with_other_discount （false）字段 | 不與其他優(yōu)惠共享 | 50元代金券 |
注意：
1.門檻字段用于拼接標(biāo)題以及優(yōu)惠說明，會影響商戶卡券庫存定價(jià)，請開發(fā)者務(wù)必按照要求填寫，并提前預(yù)覽生成的卡券；
2.門檻字段一旦設(shè)定即不可更改，請開發(fā)者慎重填寫，及時(shí)預(yù)覽。
3.當(dāng)開發(fā)者同時(shí)填入滿減字段和指定品類可用字段，則會拼接為"羽絨服（accept_catagory字段小于等于5個(gè)字）滿500減50"，"滿500減50"（accept_catagory字段大于5個(gè)字）
選擇合適的code顯示類型
目前卡券支持五種code顯示類型：即二維碼顯示code、二維碼不顯示code、一維碼顯示code、僅code類型和無code類型（僅限支持券）。
對于不同的code類型，需要的核銷方式也不同，對于顯示二維碼和一維碼的卡券可以采用掃碼核銷的方式，對于只顯示code類型的卡券適合用輸碼核銷的方式，而無code類型的優(yōu)惠券，則僅適合用于線上券使用，并且商戶需開發(fā)自定義頁面供用戶核銷卡券。
不同的code類型，開發(fā)者在創(chuàng)建券時(shí)須傳入不同的code_type參數(shù)。
| 類別 | 字段名 | 適用核銷方式 |
|---|---|---|
| 二維碼/一維碼顯示code | CODE_TYPE_QRCODE/CODE_TYPE_BARCODE | 適用于掃碼/輸碼核銷 |
| 二維碼不顯示code | CODE_TYPE_ONLY_QRCODE | 僅適用于掃碼核銷 |
| 僅code類型 | CODE_TYPE_TEXT | 僅適用于輸碼核銷 |
| 無code類型 | CODE_TYPE_NONE | 僅適用于線上核銷，在券面不出現(xiàn)二維碼展開入口 |
記錄用戶領(lǐng)券行為
記錄用戶領(lǐng)券行為有多種方式：
1. 用戶領(lǐng)取卡券后會推送事件通知開發(fā)者，領(lǐng)取卡券事件中包含卡券ID、Code碼、領(lǐng)取人OpenID。卡券被核銷時(shí)同樣會推送事件。
2. 調(diào)用查詢Code接口獲取該Code碼的狀態(tài)（是否被領(lǐng)取、核銷、刪除），若Code碼被用戶領(lǐng)取且處于有效狀態(tài)，可獲取領(lǐng)券人OpenID。
3. 從卡券詳情頁跳轉(zhuǎn)外部鏈接時(shí)，微信后臺會自動帶上卡券ID、Code碼等信息。
活用自定義入口
為滿足商戶功能擴(kuò)展的需求，新增可自定義三個(gè)卡券內(nèi)的入口，支持跳轉(zhuǎn)到商戶自定義url鏈接。
兩個(gè)自定義入口基于不同的場景定位設(shè)置，區(qū)別如下：
| 類別 | 示例 | 字段 | 顯示邏輯 |
|---|---|---|---|
| 使用場景入口 | 立即使用 | center_title、center_sub_title、center_url | 傳入后將覆蓋二維碼展開按鈕，未到有效期時(shí)按鈕置灰 |
| 服務(wù)場景入口 | 在線商城 | custom_url_name、custom_url_sub_title、custom_url | 僅卡券被用戶領(lǐng)取且處于有效狀態(tài)時(shí)顯示（轉(zhuǎn)贈中、核銷后不顯示）。 |
| 營銷場景入口 | 再次購買 | promotion_url_name、promotion_url_sub_title、promotion_url | 卡券處于正常狀態(tài)、轉(zhuǎn)贈中、核銷后等異常狀態(tài)均顯示該入口。 |
接口調(diào)用流程
創(chuàng)建朋友的券請嚴(yán)格按照以下接口調(diào)用流程調(diào)用接口。
開發(fā)者須按照以上流程調(diào)用接口，接口列表如下表。
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 上傳圖片接口 | 上傳卡券logo和卡券圖片，獲得url | 基礎(chǔ)接口 |
| 2 | 選取卡券背景色 | 獲取卡券背景顏色色值colorid | 創(chuàng)建卡券 |
| 3 | 微信門店接口 | 設(shè)置卡券門店并通過審核獲得poiid，用于創(chuàng)建時(shí)填入location_list字段 | 創(chuàng)建卡券 |
| 4 | 創(chuàng)建朋友的券接口 | 創(chuàng)建卡券獲得card_id用于增加庫存、投放等動作 | 創(chuàng)建卡券 |
| 5 | 審核事件推送 | 獲得審核結(jié)果 | 卡券事件推送 |
API詳情
上傳圖片接口
請點(diǎn)擊查看上傳圖片接口，開發(fā)者需調(diào)用接口上傳商家圖標(biāo)LOGO至微信服務(wù)器，獲取相應(yīng)logo_url，用于卡券創(chuàng)建。
注意事項(xiàng)：
1.上傳的圖片限制文件大小限制1MB，支持JPG 格式。
2.調(diào)用接口獲取的url 僅支持在微信相關(guān)業(yè)務(wù)下使用，否則會做相應(yīng)處理。
3.此處必須上傳微信服務(wù)器返回的圖片鏈接，否則報(bào)錯(cuò)；
微信門店接口
請點(diǎn)擊查看微信門店接口文檔，獲取門店 ID 后填入創(chuàng)建卡券接口中的相應(yīng)字段 location_id_list，即可設(shè)置該卡券的適用門店。
選取卡券背景色
請點(diǎn)擊查看 選取卡券背景顏色接口文檔，選擇適用色值，讓優(yōu)惠券變得更加個(gè)性，在步驟四創(chuàng)建卡券中將顏色名（如Color010）填入color字段。
創(chuàng)建朋友的券接口
創(chuàng)建朋友的券接口是創(chuàng)建系列接口最重要的一環(huán)。
朋友的券是在原有卡券的基礎(chǔ)上衍生出的一種高級券的類型，比起普通卡券，朋友的券可以展示有圖文介紹的優(yōu)惠詳情（通過advanced_info字段定義），突出服務(wù)和商品摘要信息。
接口說明
開發(fā)者需調(diào)用該接口創(chuàng)建朋友的券，填入商家信息、LOGO、門店以及相關(guān)的優(yōu)惠和使用字段。創(chuàng)建成功后，會獲得Card_id，用于下一步的投放。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 調(diào)用接口憑證 |
| POST數(shù)據(jù) | 是 | JSON數(shù)據(jù) |
代金券POST示例
{
"card": {
"card_type": "CASH",
"cash": {
"base_info": {
"logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
"brand_name": "微信餐廳",
"code_type": "CODE_TYPE_TEXT",
"color": "Color010",
"service_phone": "020-88888888",
"description": "不可與其他優(yōu)惠同享如需團(tuán)購券發(fā)票，請?jiān)谙M(fèi)時(shí)向商戶 提出",
"date_info": {
"type": "DATE_TYPE_FIX_TIME_RANGE",
"begin_timestamp": 1447397802,
"end_timestamp": 1449893532
},
"can_share": false,
"can_give_friend": false,
"location_id_list": [
272981040,
400183234
],
"get_limit": 3,
"center_title": "快速核銷",
"center_sub_title": "",
"center_url": "www.qq.com",
"custom_url_name": "立即使用",
"custom_url": "http://www.qq.com",
"custom_url_sub_title": "6個(gè)漢字tips",
"promotion_url_name": "更多優(yōu)惠",
"promotion_url": "http://www.qq.com"
},
"advanced_info": {
"use_condition": {
"accept_category": "鞋類",
"reject_category": "阿迪達(dá)斯",
"can_use_with_other_discount": true
},
"abstract": {
"abstract": "微信餐廳推出多種新季菜品，期待您的光臨",
"icon_url_list": [
"http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
]
},
"text_image_list": [
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品精選食材，以獨(dú)特的烹飪方法，最大程度地刺激食 客的味蕾"
},
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品迎合大眾口味，老少皆宜，營養(yǎng)均衡"
}
],
"time_limit": [
{
"type": "MONDAY",
"begin_hour": 0,
"end_hour": 10,
"begin_minute": 10,
"end_minute": 59
},
{
"type": "HOLIDAY"
}
],
"business_service": [
"BIZ_SERVICE_FREE_WIFI",
"BIZ_SERVICE_WITH_PET",
"BIZ_SERVICE_FREE_PARK",
"BIZ_SERVICE_DELIVER"
],
"consume_share_self_num": 1,
"consume_share_card_list": [],
"share_friends": true
},
"reduce_cost": 10
}
}
}兌換券POST示例
{
"card": {
"card_type": "GIFT",
"gift": {
"base_info": {
...
},
"advanced_info": {
...
},
"gift_name": "蘋果",
"gift_num": 1,
"gift_unit": "個(gè)""gift": "送蘋果一個(gè)"
}
}
}朋友的券JSON結(jié)構(gòu)解析
在以上字段中除卡券基本信息之外，代金券與兌換券均相同，故兌換券JSON不作展示。
卡券信息字段
| 字段 | 說明 | 是否必填 |
|---|---|---|
| card_type | 卡券類型，現(xiàn)僅支持代金券類型和兌換券類型，填寫CASH或者GIFT | 是 |
| cash | 代金券類型json結(jié)構(gòu)函數(shù)名 | 是 |
| reduce_cost | 代金券專用，表示減免金額（單位為分），不可填0。 | 是 |
| gift | 兌換券券類型json結(jié)構(gòu)函數(shù)名 | 是 |
| gift_name | 兌換券兌換商品名字，限6個(gè)漢字 | 是 |
| gift_num | 兌換券兌換商品數(shù)目，限三位數(shù)字 | 否 |
| gift_unit | 兌換券兌換商品的數(shù)量單位，限兩個(gè)漢字 | 否 |
| gift | 兌換券類型時(shí)顯示的禮品詳情 | 是 |
Base_info（卡券基礎(chǔ)信息）字段
| 字段 | 說明 | 是否必填 |
|---|---|---|
| base_info | 基本卡券數(shù)據(jù)，對于任何卡券類型base_info字段相同 | 是 |
| logo_url | 卡券商家LOGO，請使用調(diào)用上傳圖片接口獲得的url | 是 |
| code_type | 卡券的code類型 "CODE_TYPE_TEXT"，文本； "CODE_TYPE_BARCODE"，一維碼； "CODE_TYPE_QRCODE"，二維碼； | 是 |
| brand_name | 商家名字,上限為12個(gè)漢字 | 是 |
| color | 券顏色，請參考 | 是 |
| notice | 使用提醒，上限為12個(gè)漢字（一句話描述，展示在首頁，示例：請出示二維碼核銷卡券） | 是 |
| description | 使用說明。長文本描述，可以分行，上限為1000個(gè)漢字 | 是 |
| date_info | 使用日期，有效期的信息，僅支持DATE_TYPE_FIX_TIME_RANGE | 是 |
| begin_timestamp | DATE_TYPE_FIX_TIME_RANGE時(shí)專用，表示起用時(shí)間。從1970年1月1日00:00:00至起用時(shí)間的秒數(shù)，最終需轉(zhuǎn)換為字符串形態(tài)傳入，下同。（單位為秒） | 是 |
| end_timestamp | DATE_TYPE_FIX_TIME_RANGE表示結(jié)束時(shí)間。從1970年1月1日00:00:00至起用時(shí)間的秒數(shù)，最終需轉(zhuǎn)換為字符串形態(tài)傳入。（單位為秒） | 是 |
| location_id_list | 門店位置ID，請參考微信門店接口文檔，朋友的券須至少傳入一個(gè)可用poi_id,否則報(bào)錯(cuò) | 是 |
| can_share | 是否支持分享到對話、朋友圈，與share_friends字段互斥，若創(chuàng)建朋友共享券此處應(yīng)填入false,不可為空 | 是 |
| can_give_friend | 是否支持贈送，與share_friends字段互斥，若創(chuàng)建朋友共享券此處應(yīng)填入false,不可為空 | 是 |
| service_phone | 客服電話 | 否 |
| get_limit | 領(lǐng)取限制，限制用戶掃碼或點(diǎn)擊H5領(lǐng)取的次數(shù) | 否 |
| center_title | 居中置頂?shù)膗rl標(biāo)題，一般為快速核銷或者快速買單，用于跳轉(zhuǎn)商戶自己開發(fā)的核銷或者買單頁面，9個(gè)中文字符以內(nèi)。該cell僅限卡券狀態(tài)正常，且處于有效期內(nèi)的時(shí)候顯示。 | 否 |
| center_sub_title | 居中置頂?shù)膗rl副標(biāo)題，顯示在標(biāo)題下方，12個(gè)中文字符以內(nèi)。該標(biāo)題僅限卡券狀態(tài)正常，且處于有效期內(nèi)的時(shí)候顯示。 | 否 |
| center_url | 居中置頂?shù)膗rl，該url僅限卡券狀態(tài)正常，且處于有效期內(nèi)的時(shí)候顯示。 | 否 |
| custom_url_name | 商家自定義入口名稱，與custom_url字段共同使用，長度限制在5個(gè)漢字內(nèi) | 否 |
| custom_url | 商家自定義入口跳轉(zhuǎn)外鏈的地址鏈接,跳轉(zhuǎn)頁面內(nèi)容需與自定義cell名稱保持匹配 | 否 |
| custom_url_sub_title | 顯示在入口右側(cè)的tips，長度限制在6個(gè)漢字內(nèi) | 否 |
| promotion_url_name | 營銷場景的自定義入口 | 否 |
| promotion_url | 入口跳轉(zhuǎn)外鏈的地址鏈接。 | 否 |
| promotion_url_sub_title | 顯示在入口右側(cè)的tips，長度限制在6個(gè)漢字內(nèi) | 否 |
Advanced_info（卡券高級信息）字段
新增門檻字段，代金券類型（CASH）的卡券可以與滿減門檻（least_cost字段）、指定品類可用/不可用門檻（accept_category/reject_category）不與其他優(yōu)惠共享門檻組合使用。
兌換券類型（GIFT）的卡券可以與滿減門檻（least_cost字段）、買送門檻（object_use_for字段）和不與其他優(yōu)惠共享門檻組合使用。
| 字段 | 說明 | 是否必填 |
|---|---|---|
| advanced_info | 創(chuàng)建優(yōu)惠券特有的高級字段 | 是 |
| use_condition | 使用門檻（條件）字段 | 否 |
| accept_category | 指定可用的商品類目，僅用于代金券類型，填入后將在券面拼寫適用于xxx，標(biāo)題自動拼為xxx減50元（若僅填入5個(gè)字），50元代金券（填入5個(gè)字以上）。 | 否 |
| reject_category | 指定不可用的商品類目，僅用于代金券類型，填入后將在券面拼寫不適用于xxx。 | 否 |
| least_cost | 滿減門檻字段，可用于兌換券和代金券，填入后將在全面拼寫消費(fèi)滿xx元可用，標(biāo)題自動拼為滿xx減xx/滿xx送xx(gift_name) | 否 |
| object_use_for | 購買xx可用類型門檻，僅用于兌換，填入后自動拼寫購買xxx可用，標(biāo)題自動拼為買xx送xx(gift_name) | 否 |
| can_use_with_other_discount | 不可以與其他類型共享門檻，填寫false時(shí)系統(tǒng)將在使用須知里拼寫不可與其他優(yōu)惠共享，默認(rèn)為true | 否 |
| abstract | 封面摘要結(jié)構(gòu)體名稱 | 是 |
| abstract | 封面摘要簡介。 | 是 |
| icon_url_list | 封面圖片列表，僅支持填入一個(gè)封面圖片鏈接，上傳圖片接口上傳獲取圖片獲得鏈接，填寫非CDN鏈接會報(bào)錯(cuò)，并在此填入。建議圖片尺寸像素850*350 | 是 |
| text_image_list | 圖文列表，顯示在詳情內(nèi)頁，優(yōu)惠券券開發(fā)者須至少傳入一組圖文列表 | 是 |
| image_url | 圖片鏈接，必須調(diào)用上傳圖片接口上傳圖片獲得鏈接，并在此填入，否則報(bào)錯(cuò) | 是 |
| text | 圖文描述，5000字以內(nèi) | 是 |
| business_service | 商家服務(wù)類型： BIZ_SERVICE_DELIVER 外賣服務(wù)；BIZ_SERVICE_FREE_PARK 停車位；BIZ_SERVICE_WITH_PET 可帶寵物；BIZ_SERVICE_FREE_WIFI 免費(fèi)wifi，可多選 | 否 |
| time_limit | 使用時(shí)段限制 | 否 |
| type | 限制類型枚舉值：支持填入 MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 HOLIDAY 假期通用 此處只控制顯示，不控制實(shí)際使用邏輯，不填默認(rèn)不顯示 | 否 |
| begin_hour | 當(dāng)前type類型下的起始時(shí)間（小時(shí)），如當(dāng)前結(jié)構(gòu)體內(nèi)填寫了MONDAY，此處填寫了10，則此處表示周一 10:00可用 | 否 |
| begin_minute | 當(dāng)前type類型下的起始時(shí)間（分鐘），如當(dāng)前結(jié)構(gòu)體內(nèi)填寫了MONDAY，begin_hour填寫10，此處填寫了59，則此處表示周一 10:59可用 | 否 |
| end_hour | 當(dāng)前type類型下的結(jié)束時(shí)間（小時(shí)），如當(dāng)前結(jié)構(gòu)體內(nèi)填寫了MONDAY，此處填寫了20，則此處表示周一 10:00-20:00可用 | 否 |
| end_minute | 當(dāng)前type類型下的結(jié)束時(shí)間（分鐘），如當(dāng)前結(jié)構(gòu)體內(nèi)填寫了MONDAY，begin_hour填寫10，此處填寫了59，則此處表示周一 10:59-00:59可用 | 否 |
| consume_share_self_num | 核銷后送券的數(shù)量，可設(shè)置核銷后送本卡券的數(shù)量，限制傳入1張，與consume_share_card_list字段互斥 | 否 |
| consume_share_card_list | 核銷后贈送其他卡券的列表，與consume_share_self_num字段互斥 | 否 |
| card_id | 核銷后贈送的其他卡券card_id，目前僅支持填入一個(gè)共享券card_id，此處必須填入共享券 | 否 |
| num | 核銷后贈送的該card_id數(shù)目，目前僅支持填1 | 否 |
| share_friends | 是否支持分享給朋友使用，填寫true優(yōu)惠券才可被共享 | 是 |
注意事項(xiàng)：
1.門檻字段用于拼接標(biāo)題以及券面的優(yōu)惠說明，請開發(fā)者務(wù)必按照要求選擇填寫，以免造成不必要的麻煩。
2.填入時(shí)間限制字段（time_limit）,只控制顯示，不控制實(shí)際使用邏輯，不填默認(rèn)不顯示。
返回?cái)?shù)據(jù)
{ "errcode": 0, "errmsg": "ok", "card_id": "pbLatjtQrAGz1Iaz08qB_H3NSBrc" }字段說明
| 字段名 | 說明 |
|---|---|
| 錯(cuò)誤碼 | 錯(cuò)誤碼，0為正常，40071為格式錯(cuò)誤，請對比JSON示例排查錯(cuò)誤 |
| errmsg | 錯(cuò)誤信息 |
| card_id | 卡券id |
審核事件推送
生成的卡券通過審核時(shí)，微信會把這個(gè)事件推送到開發(fā)者填寫的URL。 點(diǎn)擊查看卡券事件推送機(jī)制
朋友的券支持買單
同普通卡券一樣，朋友的券一樣支持微信快速買單，開通了微信支付的商戶可以為朋友的券開通買單，便捷收銀。
幫助
錯(cuò)誤碼
| 錯(cuò)誤碼 | 說明 | 排錯(cuò)指引 |
|---|---|---|
| 40079 | 有效期錯(cuò)誤 | 須將有效期設(shè)置為90天以內(nèi) |
| 40141 | 圖片url錯(cuò)誤 | 須使用將圖片上傳至CDN后獲得的url |
| 41025 | 缺少location_list | 創(chuàng)建的JSON中須填入location_list(即poi_id，門店id) |
| 42001 | token過期 | 重新獲取最新的token調(diào)用接口，若有多個(gè)調(diào)用源，需要統(tǒng)一管理token |
| 47001 | 創(chuàng)建JSON結(jié)構(gòu)錯(cuò)誤 | 針對報(bào)錯(cuò)信息提示的位置對比示例排查 |
更多錯(cuò)誤碼，請見卡券全局錯(cuò)誤碼
常見問題
1.為什么朋友的券不能在創(chuàng)建的時(shí)候填入庫存？
朋友的券庫存機(jī)制與普通券不同，開發(fā)者須先創(chuàng)建卡券后，到MP（商戶后臺）用券點(diǎn)充值庫存，不支持在創(chuàng)建的時(shí)候填入庫存。
2.為什么朋友的券只能創(chuàng)建三個(gè)月時(shí)長的卡券？
朋友的券不同于普通卡券，有很強(qiáng)的時(shí)效性和活動性，為了保證用戶的券列表能常來常新，我們約定，每個(gè)商戶最多只能創(chuàng)建時(shí)長不超過三個(gè)月（90天)的卡券。
3.卡券過期了券點(diǎn)會退嗎？
若卡券過期時(shí)，card_id內(nèi)尚有庫存，我們會將庫存折合券點(diǎn)退回商戶的賬戶，周期為T+1（隔日退回）。
配置庫存、充值券點(diǎn)
該部分介紹開發(fā)者怎樣為card_id配置庫存以及充值、管理賬號的券點(diǎn)。
接口說明
創(chuàng)建朋友的券成功后，開發(fā)者可以通過接口為card_id配置庫存，不同于普通券的是，朋友的券庫存須使用券點(diǎn)（什么是券點(diǎn)？）兌換，券點(diǎn)分為免費(fèi)券點(diǎn)和付費(fèi)券點(diǎn)，免費(fèi)券點(diǎn)由微信平臺贈送產(chǎn)生，而付費(fèi)券點(diǎn)由開發(fā)者充值產(chǎn)生。
接口調(diào)用流程
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 開通券點(diǎn)賬戶接口 | 開通券點(diǎn)賬戶 | 庫存接口 |
| 2 | 對優(yōu)惠券批價(jià)接口 | 獲取對當(dāng)前card_id充值一定量的庫存所耗費(fèi)的券點(diǎn)總額 | 庫存接口 |
| 3 | 查詢?nèi)c(diǎn)余額接口 | 查詢賬戶內(nèi)券點(diǎn)是否可以支付本次批價(jià)的庫存充值 | 庫存接口 |
| 4 | 確認(rèn)兌換庫存接口 | 確認(rèn)充值庫存 | 庫存接口 |
| 5 | 充值券點(diǎn)接口 | 使用微信支付充值賬戶內(nèi)的券點(diǎn) | 充值接口 |
| 6 | 查詢訂單詳情接口 | 查詢某次充值訂單的狀態(tài) | 充值接口 |
| 6 | 查詢流水詳情接口 | 查詢庫存、券點(diǎn)訂單的狀態(tài) | 管理接口 |
API詳情
該部分主要介紹庫存、券點(diǎn)接口的調(diào)用方法和傳遞參數(shù)。
開通券點(diǎn)賬戶接口
本接口用于開發(fā)者為當(dāng)前appid開通券點(diǎn)賬戶并獲得免費(fèi)券點(diǎn)獎勵(lì)
接口調(diào)用請求說明
HTTP請求方式: GET https://api.weixin.qq.com/card/pay/activate?access_token=ACCESS_TOKEN
返回?cái)?shù)據(jù)示例
{"errcode": 0, "errmsg": "ok", "reward": 200}返回?cái)?shù)據(jù)示例
| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| reward | 獎勵(lì)券點(diǎn)數(shù)量，以元為單位，微信卡券對每一個(gè)新開通券點(diǎn)賬戶的商戶獎勵(lì)200個(gè)券點(diǎn)，點(diǎn)擊查看券點(diǎn)規(guī)則什么是券點(diǎn)？ |
對優(yōu)惠券批價(jià)
本接口用于提前查詢本次新增庫存需要多少券點(diǎn)
接口調(diào)用請求說明
HTTP請求方式: POST https://api.weixin.qq.com/card/pay/getpayprice?access_token=ACCESS_TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{"card_id": "pbLatjpQxxxxxxxxCEV_cLTwoB7yU", "quantity": "1"}請求參數(shù)說明
| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| card_id | 是 | string(32) | pFS7Fjg8kV1IdDz01r4SQwMkuCKc | 需要來配置庫存的card_id |
| quantity | 是 | int | 100 | 本次需要兌換的庫存數(shù)目 |
返回?cái)?shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIf7Ag5Ww-YdxP-KeT6LeJBttb1xpY0Uf7g8DNHrbUyHopolqfUqPBBLDEmB7Z-91I8",
"price": "0.2",
"free_coin": "0.2",
"pay_coin": "0"
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| order_id | 本次批價(jià)的訂單號，用于下面的確認(rèn)充值庫存接口，僅對當(dāng)前訂單有效且僅可以使用一次，60s內(nèi)可用于兌換庫存。 |
| price | 本次需要支付的券點(diǎn)總額度 |
| free_coin | 本次需要支付的免費(fèi)券點(diǎn)額度 |
| pay_coin | 本次需要支付的付費(fèi)券點(diǎn)額度 |
查詢?nèi)c(diǎn)余額接口
本接口用于開發(fā)者查詢當(dāng)前券點(diǎn)賬戶中的免費(fèi)券點(diǎn)/付費(fèi)券點(diǎn)數(shù)目以及總額。
接口調(diào)用請求說明
HTTP請求方式: GET https://api.weixin.qq.com/card/pay/getcoinsinfo?access_token=ACCESS_TOKEN
返回?cái)?shù)據(jù)示例
{"errcode": 0, "errmsg": "ok", "free_coin": 200 "pay_coin": 1 "total_coin": 201}返回參數(shù)說明
| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| free_coin | 免費(fèi)券點(diǎn)數(shù)目 |
| pay_coin | 免費(fèi)券點(diǎn)數(shù)目 |
| total_coin | 全部券點(diǎn)數(shù)目 |
確認(rèn)兌換庫存接口
本接口用于確認(rèn)兌換庫存，確認(rèn)后券點(diǎn)兌換為庫存，過程不可逆。
接口調(diào)用請求說明
HTTP請求方式: POST https://api.weixin.qq.com/card/pay/confirm?access_token=ACCESS_TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{
"card_id": "pbLatjpxxxxlCEV_cLTwoB7yU",
"order_id": "P9zzllX2VJ5NgiF9kFVarX7bc8r-ms_5Dy091evc2eIuxtZvZobeomE1p9Dw8v7lFBhqKM4YgrZa54uuWhf3hw7KquEOfmx5FplGKRIfkbR7Ag5WwYdxP-KeT6LeJBttb1xpYxxxxxxxxxxxxHrbUyHopolqfUqPBBLDEmB7Z-91I8",
"quantity": "1"
}請求參數(shù)說明
| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| card_id | 是 | string(32) | pFS7Fjg8kV1IdDz01r4SQwMkuCKc | 需要來兌換庫存的card_id |
| quantity | 是 | int | 100 | 本次需要兌換的庫存數(shù)目 |
| order_id | 是 | string | P9zzllX2VJ5NgiF9kFVarX7bc8r | 僅可以使用上面得到的訂單號，保證批價(jià)有效性 |
返回?cái)?shù)據(jù)示例
{"errcode":0, "errmsg":"ok"}參數(shù)說明
| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
特別注意：
上一步獲得的order_id須在60s內(nèi)使用，否則確認(rèn)兌換庫存接口將會失效
充值券點(diǎn)接口
開發(fā)者可以通過此接口為券點(diǎn)賬戶充值券點(diǎn)，1元等于1點(diǎn)。開發(fā)者調(diào)用接口后可以獲得一個(gè)微信支付的支付二維碼鏈接， 開發(fā)者可以將鏈接轉(zhuǎn)化為二維碼掃碼支付。
接口調(diào)用請求說明
HTTP請求方式: POST https://api.weixin.qq.com/card/pay/recharge?access_token=ACCESS_TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{"coin_count": 100}
請求參數(shù)說明
| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| coin_count | 是 | int | 10000 | 需要充值的券點(diǎn)數(shù)目，1點(diǎn)=1元 |
返回?cái)?shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"order_id": "100005790120***221401000171",
"qrcode_url": "weixin://wxpay/bizpayurl?pr=xxxxxxxxx",
"qrcode_buffer": "pwxs*************xxxxxxxxxx"
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| order_id | 本次支付的訂單號，用于查詢訂單狀態(tài) |
| qrcode_url | 支付二維碼的的鏈接，開發(fā)者可以調(diào)用二維碼生成的公開庫轉(zhuǎn)化為二維碼顯示在網(wǎng)頁上，微信掃碼支付 |
| qrcode_buffer | 二維碼的數(shù)據(jù)流，開發(fā)者可以使用寫入一個(gè)文件的方法顯示該二維碼 |
注意：
開發(fā)者可以參考以下方法將buffer顯示二維碼
<?php $file = fopen("test.jpg","w"); echo fwrite($file, $qrcode_buffer); fclose($file); ?>查詢訂單詳情接口
本接口用于查詢充值訂單的狀態(tài)
接口調(diào)用請求說明
HTTP請求方式: POST https://api.weixin.qq.com/card/pay/getorder?access_token=ACCESS_TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{"order_id": "100005790********401000171"}請求參數(shù)說明
| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| order_id | 是 | int | 10000 | 上一步中獲得的訂單號，作為一次交易的唯一憑證 |
返回?cái)?shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"order_info": {
"order_id": "100005790120151221401000171",
"status": "ORDER_STATUS_FINANCE_SUCC",
"create_time": 1450712798,
"pay_finish_time": 1450712905,
"desc": "微信支付充值",
"free_coin_count": "0",
"pay_coin_count": "1",
"refund_free_coin_count": "0",
"refund_pay_coin_count": "0",
"openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY",
"order_type": "ORDER_TYPE_WXPAY"
}
}返回?cái)?shù)據(jù)說明
| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| order_info | 訂單信息結(jié)構(gòu)體 |
| order_id | 訂單號 |
| status | 訂單狀態(tài)， ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代幣成功 ORDER_STATUS_QUANTITY_SUCC 加庫存成功 ORDER_STATUS_HAS_REFUND 已退幣 ORDER_STATUS_REFUND_WAITING 等待退幣確認(rèn) ORDER_STATUS_ROLLBACK 已回退,系統(tǒng)失敗 ORDER_STATUS_HAS_RECEIPT 已開發(fā)票 |
| create_time | 訂單創(chuàng)建時(shí)間 |
| pay_finish_time | 支付完成時(shí)間 |
| desc | 支付描述，一般為微信支付充值 |
| free_coin_count | 本次充值的付費(fèi)券點(diǎn)數(shù)量，以元為單位 |
| pay_coin_count | 二維碼的數(shù)據(jù)流，開發(fā)者可以使用寫入一個(gè)文件的方法顯示該二維碼 |
| refund_free_coin_count | 回退的免費(fèi)券點(diǎn) |
| refund_pay_coin_count | 回退的付費(fèi)券點(diǎn) |
| openid | 支付人的openid |
| order_tpye | 訂單類型，ORDER_TYPE_WXPAY為充值 |
查詢?nèi)c(diǎn)流水詳情接口
本接口用于查詢?nèi)c(diǎn)的流水詳情。
接口調(diào)用請求說明
HTTP請求方式: POSThttps://api.weixin.qq.com/card/pay/getorderlist?access_token=ACCESS_TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{
"offset": 0,
"count": 5,
"order_type": "ORDER_TYPE_WXPAY",
"nor_filter": {
"status": "ORDER_STATUS_SUCC"
},
"sort_info": {
"sort_key": "SORT_BY_TIME",
"sort_type": "SORT_DESC"
},
"begin_time": "1440420538",
"end_time": "1450713203"
}
請求參數(shù)說明
| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| offset | 否 | int | 0 | 分批查詢的起點(diǎn)，默認(rèn)為0 |
| count | 否 | int | 50 | 分批查詢的數(shù)量 |
| begin_time | 否 | int | 14552146398 | 批量查詢訂單的起始事件，為時(shí)間戳，默認(rèn)1周前 |
| end_time | 否 | int | 14552146398 | 批量查詢訂單的結(jié)束事件，為時(shí)間戳，默認(rèn)為當(dāng)前時(shí)間 |
| order_type | 否 | string | ORDER_TYPE_WXPAY | 所要拉取的訂單類型 ORDER_TYPE_SYS_ADD 平臺贈送 ORDER_TYPE_WXPAY 充值 ORDER_TYPE_REFUND 庫存回退券點(diǎn) ORDER_TYPE_REDUCE 券點(diǎn)兌換庫存 ORDER_TYPE_SYS_REDUCE 平臺扣減 |
| nor_filter | 否 | JSON結(jié)構(gòu) | ORDER_STATUS_QUANTITY_SUCC | 反選，不要拉取的訂單 |
| status | 否 | string | ORDER_STATUS_REFUND_WAITING | 不要拉取的訂單狀態(tài) 訂單狀態(tài)包括： ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代幣成功 ORDER_STATUS_QUANTITY_SUCC 加庫存成功 ORDER_STATUS_HAS_REFUND 已退幣 ORDER_STATUS_REFUND_WAITING 等待退幣確認(rèn) ORDER_STATUS_ROLLBACK 已回退,系統(tǒng)失敗 ORDER_STATUS_HAS_RECEIPT 已開發(fā)票 |
| sort_info | 否 | JSON結(jié)構(gòu) | 對結(jié)果排序 | |
| sort_key | 否 | string | SORT_BY_TIME | 排序依據(jù)，SORT_BY_TIME 以訂單時(shí)間排序 |
| sort_type | 否 | string | SORT_DESC | 排序規(guī)則，SORT_ASC 升序 SORT_DESC 降序 |
返回?cái)?shù)據(jù)示例
{
"errcode": 0,
"errmsg": "ok",
"total_num": 1,
"order_list": [
{
"order_id": "100005790120151221401000171",
"status": "ORDER_STATUS_FINANCE_SUCC",
"create_time": 1450712798,
"pay_finish_time": 1450712905,
"desc": "微信支付充值",
"free_coin_count": "0",
"pay_coin_count": "1",
"refund_free_coin_count": "0",
"refund_pay_coin_count": "0",
"openid": "oWE-GwF1gGoyVVZC5PG6GXd4cKMY",
"order_type": "ORDER_TYPE_WXPAY"
}
]
}返回?cái)?shù)據(jù)說明
| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| total_num | 符合條件的訂單總數(shù)量 |
| order_list | 顯示的訂單詳情列表，根據(jù)offset和count來顯示 |
| order_id | 訂單號 |
| status | 訂單狀態(tài)， ORDER_STATUS_WAITING 等待支付 ORDER_STATUS_SUCC 支付成功 ORDER_STATUS_FINANCE_SUCC 加代幣成功 ORDER_STATUS_QUANTITY_SUCC 加庫存成功 ORDER_STATUS_HAS_REFUND 已退幣 ORDER_STATUS_REFUND_WAITING 等待退幣確認(rèn) ORDER_STATUS_ROLLBACK 已回退,系統(tǒng)失敗 ORDER_STATUS_HAS_RECEIPT 已開發(fā)票 |
| create_time | 訂單創(chuàng)建時(shí)間 |
| pay_finish_time | 支付完成時(shí)間 |
| desc | 支付描述，一般為微信支付充值 |
| free_coin_count | 本次充值的付費(fèi)券點(diǎn)數(shù)量，以元為單位 |
| pay_coin_count | 二維碼的數(shù)據(jù)流，開發(fā)者可以使用寫入一個(gè)文件的方法顯示該二維碼 |
| refund_free_coin_count | 回退的免費(fèi)券點(diǎn) |
| refund_pay_coin_count | 回退的付費(fèi)券點(diǎn) |
| openid | 支付人的openid |
| order_tpye | 訂單類型，ORDER_TYPE_WXPAY為充值 |
券點(diǎn)流水詳情事件推送
當(dāng)券點(diǎn)發(fā)生變動時(shí)，微信服務(wù)器會將本次變動的類型、券點(diǎn)數(shù)額以及時(shí)間等信息推送給開發(fā)者服務(wù)器。
接口說明
該部分主要講述微信卡券不同的投放渠道和投放方式，建議開發(fā)者仔細(xì)閱讀本部分文檔，避免在投放過程中出現(xiàn)消費(fèi)者無法共享的情況。
開發(fā)者注意事項(xiàng)
共享券投放與普通券投放略有不同。現(xiàn)共享券僅支持線下二維碼掃碼投放（不包含長按二維碼識別）、搖一搖Beacon投放的H5以及WIFI環(huán)境H5投放場景，共享券同時(shí)支持掃碼跳轉(zhuǎn)H5后領(lǐng)券，其他投放渠道暫不支持。
案例介紹
卡券二維碼投放
場景介紹
二維碼一般用于商戶卡券的店內(nèi)投放、海報(bào)投放和傳單投放，商戶通過接口生成二維碼之后，可以將二維碼貼在收銀臺、海報(bào)、傳單等宣傳物料上。用戶掃碼后可以將卡券共享至共享券列表，供自己和朋友們使用。
使用流程
完成以上流程，開發(fā)者需要：
1.創(chuàng)建朋友的券并再通過審核之后在【微信公眾平臺商戶后臺】增加庫存；
2.調(diào)用創(chuàng)建二維碼接口生成領(lǐng)券二維碼；
3.監(jiān)聽領(lǐng)取時(shí)間推送，記錄卡券發(fā)放量并做數(shù)據(jù)統(tǒng)計(jì)；
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 生成二維碼接口 | 創(chuàng)建二維碼得到二維碼的展示url | 投放接口 |
| 2 | 卡券領(lǐng)取事件推送 | 用戶領(lǐng)取卡券后，獲得用戶的openid、code和card_id等信息 | 事件推送 |
H5網(wǎng)頁投放
場景介紹
開發(fā)者可以開發(fā)領(lǐng)券H5網(wǎng)頁，并將url轉(zhuǎn)化成二維碼或者配置在微信搖一搖或者微信Wi-Fi投放。 該渠道適用于對領(lǐng)取頁面有要求的商戶，可以自定義頁面樣式體現(xiàn)品牌價(jià)值或者自定義領(lǐng)取流程（如加入游戲環(huán)節(jié)）等。
注意：
1.目前僅支持線下場景投放，如卡券二維碼、從掃碼進(jìn)入H5網(wǎng)頁掃碼或者從Wi-Fi或者iBeacon進(jìn)入的網(wǎng)頁領(lǐng)券。其他渠道暫不支持。
2.點(diǎn)擊此處了解Wi-Fi和微信搖一搖搖一搖周邊（iBeacon）
接口調(diào)用流程
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 獲取JSAPI_TICKET接口 | 獲取到JSAPI_TICKET用于參與JS SDK config | 基礎(chǔ)接口 |
| 2 | 獲取卡券API_TICKET接口 | 獲取到卡券API_TICKET用于cardext內(nèi)signarue簽名 | 投放接口 |
| 3 | 批量添加卡券接口 | 將共享券添加到用戶的券列表 | 投放接口 |
| 4 | 卡券領(lǐng)取事件推送 | 用戶領(lǐng)取卡券后，獲得用戶的openid、code和card_id等信息 | 事件推送 |
API詳情
設(shè)置測試白名單接口
當(dāng)朋友的券審核未通過時(shí)，開發(fā)者可以通過設(shè)置白名單的方式領(lǐng)取朋友的券并共享。 共享的未審核狀態(tài)的券僅白名單列表內(nèi)可見。
生成二維碼接口
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | JSON數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
開發(fā)者可以設(shè)置掃描二維碼領(lǐng)取單張卡券，此時(shí)POST數(shù)據(jù)為：
{
"action_name": "QR_CARD",
"expire_seconds": 1800,
"action_info": {
"card": {
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
"code": "198374613512",
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"is_unique_code": false,
"outer_id": 1
}
}
}| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| code | 是 | string(20) | 110201201245 | 卡券Code碼,use_custom_code字段為true的卡券必須填寫，非自定義code不必填寫。。 |
| card_id | 否 | string(32) | pFS7Fjg8kV1IdDz01r4SQwMkuCKc | 卡券ID。 |
| openid | 否 | string(32) | oXch-jkrxp42VQu8ldweCwDt97qo | 指定領(lǐng)取者的openid，只有該用戶能領(lǐng)取。bind_openid字段為true的卡券必須填寫，非指定openid不必填寫。 |
| expire_seconds | 否 | unsigned int | 60 | 指定二維碼的有效時(shí)間，范圍是60 ~ 1800秒。不填默認(rèn)為永久有效。 |
| is_unique_code | 否 | bool | false | 指定下發(fā)二維碼，生成的二維碼隨機(jī)分配一個(gè)code，領(lǐng)取后不可再次掃描。填寫true或false。默認(rèn)false。 |
| outer_id | 否 | int | 12 | 領(lǐng)取場景值，用于領(lǐng)取渠道的數(shù)據(jù)統(tǒng)計(jì)，默認(rèn)值為0，字段類型為整型，長度限制為60位數(shù)字。用戶領(lǐng)取卡券后觸發(fā)的事件推送中會帶上此自定義場景值。 |
注意事項(xiàng)：
1.若開發(fā)者填寫了is_unique_code為true，需要保證卡券已審核通過并有庫存，否則會報(bào)錯(cuò)。
返回?cái)?shù)據(jù)
數(shù)據(jù)示例：
{
"errcode": 0,
"errmsg": "ok",
"ticket": "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",
"expire_seconds": 1800,
"url": "http://weixin.qq.com/q/BHWya_zlfioH6fXeL16o",
"show_qrcode_url": " https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQH98DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0czVzRlSWpsamlyM2plWTNKVktvAAIE6SfgVQMEgDPhAQ%3D%3D"
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| ticket | 獲取的二維碼ticket，憑借此ticket調(diào)用通過ticket換取二維碼接口可以在有效時(shí)間內(nèi)換取二維碼。 |
| url | 二維碼圖片解析后的地址，開發(fā)者可根據(jù)該地址自行生成需要的二維碼圖片 |
| show_qrcode_url | 二維碼顯示地址，點(diǎn)擊后跳轉(zhuǎn)二維碼頁面 |
獲取JSAPI_TICKET接口
接口調(diào)用請求說明
http請求方式: GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=jsapi
返回?cái)?shù)據(jù)
{
"errcode": 0,
"errmsg": "ok",
"ticket": "bxLdikRXVbTPdHSM05e5u5sUoXNKd8-41ZO3MhKoyN5OfkWITDGgnr2fwJ0m9E8NYzWKVZvdVtaUgWvsdshFKA",
"expires_in": 7200
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| ticket | 獲取的JSAPI_TICKET |
| expires_in | 有效時(shí)間，ticket有效時(shí)間為2小時(shí)，2小時(shí)內(nèi)不變 |
獲取卡券API_TICKET接口
接口調(diào)用請求說明
http請求方式: GET https://api.weixin.qq.com/cgi-bin/ticket/getticket?access_token=ACCESS_TOKEN&type=wx_card
返回?cái)?shù)據(jù)
{
"errcode": 0,
"errmsg": "ok",
"ticket": "bxLdikRXVbTPdHSM05e5u5sUoXNKdvsdshFKA",
"expires_in": 7200
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| ticket | 獲取的卡券API_TICKET |
| expires_in | 有效時(shí)間，ticket有效時(shí)間為2小時(shí)，2小時(shí)內(nèi)不變 |
批量添加卡券（addcard）接口
朋友的券領(lǐng)取須指引用戶升級到最新的微信客戶端版本，最低版本要求為：iOS微信版本為6.3.6及以上，Android微信版本為6.3.7及以上。 開發(fā)者可以判斷用戶版本后調(diào)用addcard接口，請點(diǎn)擊查看判斷用戶客戶端版本、批量添加卡券接口。
卡券領(lǐng)取事件
用戶領(lǐng)取朋友的券后，會有事件推送到開發(fā)者服務(wù)器。
幫助
錯(cuò)誤碼
| 錯(cuò)誤碼 | 說明 | 排錯(cuò)指引 |
|---|---|---|
| 40053 | JSON結(jié)構(gòu)錯(cuò)誤 | card_id或者參數(shù)名有誤，請對比示例排查 |
| 43008 | 當(dāng)前賬號未開通支付權(quán)限或未開通支付后送券接口權(quán)限，無法設(shè)置支付后送朋友的券功能 | 前往開通微信支付 |
| 45021 | 贈券規(guī)則列表長度高于10個(gè) | 減少贈券規(guī)則列表的個(gè)數(shù) |
| 47001 | 創(chuàng)建JSON結(jié)構(gòu)錯(cuò)誤 | 針對報(bào)錯(cuò)信息提示的位置對比示例排查 |
更多錯(cuò)誤碼，請見卡券全局錯(cuò)誤碼
常見問題
1.如何區(qū)分領(lǐng)取渠道？
開發(fā)者可以在生成二維碼或者H5添加卡券時(shí)，填入outer_id(自定義渠道值),這個(gè)數(shù)值會隨領(lǐng)取事件推送至開發(fā)者服務(wù)器，從而使得開發(fā)者可以區(qū)分每一個(gè)code（卡券串碼）的投放渠道。
2.為什么長按二維碼不能領(lǐng)取卡券？
目前朋友的券僅支持線下渠道投放，對于線上的場景（如長按二維碼領(lǐng)取、公眾號群發(fā)）等做了限制。
朋友的券核銷
接口說明
此處介紹朋友的券的核銷方式，分為線上和線下核銷兩部分，下面分不同的場景介紹。
案例介紹
線下核銷
機(jī)具掃碼核銷
場景介紹
具有機(jī)具和開發(fā)能力的商戶可以通過機(jī)具掃碼進(jìn)行卡券核銷，開發(fā)者可以通過機(jī)具掃碼獲得卡券code之后，調(diào)用核銷code接口將卡券進(jìn)行核銷，方便快捷。
接口調(diào)用流程
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 查詢code接口 | 查詢code狀態(tài)，獲知當(dāng)前卡券是否可以核銷 | 管理卡券 |
| 2 | 線下核銷code接口 | 設(shè)置卡券門店并通過審核獲得poiid，用于創(chuàng)建時(shí)填入location_list字段 | 核銷卡券 |
| 3 | 卡券核銷事件 | 獲得當(dāng)前卡券的使用人、code和card_id等信息 | 事件推送 |
網(wǎng)頁工具核銷
場景介紹
若開發(fā)者沒有能力進(jìn)行機(jī)具開發(fā)，可以開發(fā)一個(gè)核銷員端使用的網(wǎng)頁進(jìn)行朋友的券的核銷，當(dāng)用戶出示二維碼時(shí)。
接口調(diào)用流程
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 查詢code接口 | 查詢code狀態(tài)，獲知當(dāng)前卡券是否可以核銷 | 管理卡券 |
| 2 | 線下核銷code接口 | 設(shè)置卡券門店并通過審核獲得poiid，用于創(chuàng)建時(shí)填入location_list字段 | 核銷卡券 |
| 3 | 卡券核銷事件 | 獲得當(dāng)前卡券的使用人、code和card_id等信息 | 事件推送 |
卡券商戶助手核銷
場景介紹
手機(jī)核銷助手是基于“卡券商戶助手“公眾號的官方卡券核銷工具，同樣支持朋友的券的核銷。
快速體驗(yàn)
步驟一：關(guān)注“微信卡券商戶助手”
步驟二：進(jìn)入【微信公眾號后臺】-【卡券功能】-【卡券核銷】-【添加核銷員】，為自己的微信號設(shè)置核銷員權(quán)限，并選擇已有的門店。
步驟三：用另一臺手機(jī)領(lǐng)取自己創(chuàng)建的朋友的券，展開二維碼并用已設(shè)置為核銷員的手機(jī)掃碼或者輸碼核銷卡券。
公眾號商戶后臺核銷
商戶可以在電腦登錄公眾號商戶后要，【卡券功能】-【卡券核銷】-【網(wǎng)頁核銷】直接核銷核銷卡券。
線上核銷
線上核銷涉及的接口與線下核銷接口略有不同，線上核銷接口需要消費(fèi)者跳轉(zhuǎn)至H5網(wǎng)頁，所以可能會出現(xiàn)兩個(gè)用戶同時(shí)使用同一張卡券的情況，我們約定，對于沒有點(diǎn)擊卡券上的“出示使用”的核銷，開發(fā)者先調(diào)用占用（mark）接口，將一個(gè)code(卡券串碼)與一個(gè)openid（用戶身份識別碼）關(guān)聯(lián)，保證該code不被另外的人使用。
網(wǎng)頁快速核銷
場景介紹
若開發(fā)者沒有辦法配置核銷員或者商戶沒辦法，可以自定義一個(gè)H5核銷界面，用戶在券面發(fā)起核銷并在開發(fā)者自定義的H5網(wǎng)頁內(nèi)完成核銷和裂變送券的過程。
值得開發(fā)者注意的是，對于自助核銷的卡券，開發(fā)者在創(chuàng)建/更新卡券是可以將code_type字段設(shè)置為CODE_TYPE_NONE,這樣可以隱藏掉卡券上使用二維碼的入口（如下圖），同時(shí)將核銷的url通過創(chuàng)建接口中的center_title center_sub_title，center_url寫入，那么此自定義入口會指定居中（如下圖）
接口調(diào)用流程
API列表
| 步驟 | API名稱 | 用途 | API屬性 |
|---|---|---|---|
| 1 | 獲取自定義跳轉(zhuǎn)鏈接參數(shù) | 獲取加密code（encrypt_code）、card_id和openid | 創(chuàng)建卡券 |
| 2 | code解碼接口 | 通過加密code獲得真實(shí)的code | 核銷卡券 |
| 3 | 查詢code接口 | 查看code狀態(tài)是否可以核銷 | 管理卡券 |
| 4 | Mark(占用)code接口 | 在核銷之前將code鎖住，防止出現(xiàn)兩個(gè)人同時(shí)核銷券的情況 | 核銷卡券 |
| 5 | 線上核銷code接口 | 將卡券核銷掉，須傳入openid和code | 核銷接口 |
| 6 | 卡券核銷事件 | 獲得當(dāng)前卡券的使用人、code和card_id等信息 | 事件推送 |
| 7 | 核銷裂贈券接口（JSSDK） | 拉起裂變領(lǐng)取頁供用戶領(lǐng)取 | 核銷接口 |
API詳情
查詢Code接口
我們強(qiáng)烈建議開發(fā)者在調(diào)用核銷code接口之前調(diào)用查詢code接口，并在核銷之前對非法狀態(tài)的code(如轉(zhuǎn)贈中、已刪除、已核銷等)做出處理。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/code/get?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{ "card_id": "pbLatjorLTVl-tdvZ6zQRIc-Fn6Y", "code": "245645675434", "check_consume": true}| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| code | 是 | string(20) | 110201201245 | 單張卡券的唯一標(biāo)準(zhǔn)。 |
| card_id | 否 | string(32) | pFS7Fjg8kV1IdDz01r4SQwMkuCKc | 卡券ID代表一類卡券。 |
| check_consume | 否 | bool | true | 是否校驗(yàn)code核銷狀態(tài)，填入true和false時(shí)的code異常狀態(tài)返回?cái)?shù)據(jù)不同。 |
當(dāng)check_consume為true時(shí)返回?cái)?shù)據(jù)
卡券狀態(tài)正常：
{
"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
}卡券狀態(tài)異常：
{
"errcode": 40127,
"errmsg": "invalid user-card status! Hint: the card was given to user, but may be deleted or set unavailable ! hint: [iHBD40040ent3]"
}當(dāng)check_consume為false時(shí)返回?cái)?shù)據(jù)
卡券狀態(tài)正常：
{
"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
}卡券狀態(tài)異常：
{
"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
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| openid | 領(lǐng)取該卡券用戶的openid |
| card_id | 卡券ID |
| begin_time | 起始使用時(shí)間 |
| end_time | 結(jié)束時(shí)間 |
| user_card_status | 當(dāng)前code對應(yīng)卡券的狀態(tài)， NORMAL 正常 CONSUMED 已核銷 EXPIRE 已過期 GIFTING 轉(zhuǎn)贈中 GIFT_TIMEOUT 轉(zhuǎn)贈超時(shí) DELETE 已刪除，UNAVAILABLE 已失效； code未被添加或被轉(zhuǎn)贈領(lǐng)取的情況則統(tǒng)一報(bào)錯(cuò)：invalid serial code |
| can_consume | 是否可以核銷，true為可以核銷，false為不可核銷 |
| mark_openid | 當(dāng)前占用此卡券的顧客的openid，核銷時(shí)僅限該openid的用戶可以核銷該卡券 |
| use_count | 當(dāng)前占用這個(gè)卡券的人已經(jīng)使用該card_id的次數(shù) |
注：
1.固定時(shí)長有效期會根據(jù)用戶實(shí)際領(lǐng)取時(shí)間轉(zhuǎn)換，如用戶2013年10月1日領(lǐng)取，固定時(shí)長有效期為90天，即有效時(shí)間為2013年10月1日-12月29日有效。
2.無論check_consume填寫的是true還是false,當(dāng)code未被添加或者code被轉(zhuǎn)贈領(lǐng)取是統(tǒng)一報(bào)錯(cuò)：invalid serial code
拉取卡券列表(ChooseCard)接口
微信 JS SDK 只能在微信內(nèi)置瀏覽器中使用,其他瀏覽器調(diào)用無效。微信提供chooseCard接口供商戶前端網(wǎng)頁調(diào)用,用于拉起用戶名下該商家篩選條件的卡券內(nèi)容。
點(diǎn)擊查看 調(diào)起適用于門店的卡券列表并獲取用戶選擇列表JS SDK
獲取自定義外鏈參數(shù)
為了滿足商戶基于卡券本身的擴(kuò)展訴求，允許卡券內(nèi)頁添加url跳轉(zhuǎn)外鏈。帶有的的字段有openid、encrypt_code、card_id。
假如指定的url為http://www.qq.com，用戶點(diǎn)擊時(shí)，跳轉(zhuǎn)的url則為： http://www.qq.com?card_id=pWXUrtw4ehIUwDTXxkvCC6THenb8&encrypt_code= LPmXP%2BZFM9bdEQPSqcA8%2F%2F6pefbsKaRxnNUMHh5%2Fq6Q%3D &openid=oWXUrt8i3***ymgmPcHKlo0TdgHw
注意：
1.encrypt_code為加密碼碼，需調(diào)用解碼接口獲取真實(shí)Code碼。
2.從url中取出的參數(shù)須經(jīng)過urlencode方可用于post請求。
Code解碼接口
code解碼接口支持兩種場景： 1.商家獲取choosecard_info后，將card_id和encrypt_code字段通過解碼接口，獲取真實(shí)code。 2.卡券內(nèi)跳轉(zhuǎn)外鏈的簽名中會對code進(jìn)行加密處理，通過調(diào)用解碼接口獲取真實(shí)code。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/code/decrypt?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | JSON數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{"encrypt_code": "XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE"}| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| encrypt_code | 是 | string(128) | XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE | 經(jīng)過加密的Code碼。 |
返回?cái)?shù)據(jù)
數(shù)據(jù)示例：
{"errcode":0, "errmsg":"ok", "code":"751234212312"}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
| code | 解密后獲取的真實(shí)Code碼 |
Mark(占用)Code接口
朋友的券由于共享的特性，會出現(xiàn)多個(gè)消費(fèi)者同時(shí)進(jìn)入某一個(gè)卡券的自定義H5網(wǎng)頁的情況，若該網(wǎng)頁涉及線上下單、核銷、支付等行為，會造成兩個(gè)消費(fèi)者同時(shí)使用同一張券，會有一個(gè)消費(fèi)者使用失敗的情況，為此我們設(shè)計(jì)了mark（占用）code接口。
對于出示核銷（消費(fèi)者點(diǎn)擊“出示使用”按鈕）的場景，開發(fā)者直接調(diào)用核銷接口，無需考慮mark邏輯，此時(shí)由客戶端代為完成。
對于消費(fèi)者進(jìn)入H5網(wǎng)頁核銷的情況，我們約定，開發(fā)者在幫助消費(fèi)者核銷卡券之前，必須幫助先將此code（卡券串碼）與一個(gè)openid綁定（即mark?。?，才能進(jìn)一步調(diào)用核銷接口，否則報(bào)錯(cuò)。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/code/mark?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | JSON數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{
"code": "114567897765",
"card_id": "pbxxxxxxxxhjahkdjad",
"openid": "obcdkalgsdklkdooooooo",
"is_mark": true
}| 參數(shù)名 | 必填 | 描述 |
|---|---|---|
| code | 是 | 卡券的code碼。 |
| card_id | 是 | 卡券的ID。 |
| openid | 是 | 用券用戶的openid。 |
| is_mark | 是 | 是否要mark（占用）這個(gè)code，填寫true或者false，表示占用或解除占用。 |
返回?cái)?shù)據(jù)
數(shù)據(jù)示例：
{"errcode":0, "errmsg":"ok"}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼 |
| errmsg | 錯(cuò)誤信息 |
注意：
1. 接口只支持未使用、正常狀態(tài)的朋友的券，開發(fā)者調(diào)用前須查詢code。
2. is_mark不填默認(rèn)為true。
3. 重復(fù)用同一個(gè)openid mark，都返回成功。
4. 用openid_a mark后，用openid_b mark會報(bào)錯(cuò)40146
5. is_mark為false時(shí)取消mark，要求傳入的openid和mark時(shí)一致，否則報(bào)錯(cuò)40416。
6. 不調(diào)用接口解除mark的話，5分鐘后自動解除。（時(shí)間可能根據(jù)產(chǎn)品策略調(diào)整）
線下核銷Code接口
消耗code接口是核銷卡券的唯一接口，僅支持核銷有效期內(nèi)的卡券，否則會返回錯(cuò)誤碼invalid time。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/code/consume?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
非自定義Code卡券的請求 {"code": "12312313"}| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| code | 是 | string(20) | 1231231 | 需核銷的Code碼。 |
返回?cái)?shù)據(jù)
數(shù)據(jù)示例：
{
"errcode": 0,
"errmsg": "ok",
"card": {
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc"
},
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼。 |
| errmsg | 錯(cuò)誤信息。 |
| openid | 用戶在該公眾號內(nèi)的唯一身份標(biāo)識。 |
| card_id | 卡券ID。 |
線上核銷Code接口
線上核銷code接口與普通的核銷code接口不同，開發(fā)者須傳入當(dāng)前使用該卡券顧客的openid才可以核銷。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/code/consume?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
| access_token | 是 | 調(diào)用接口憑證 |
POST數(shù)據(jù)
{"code": "12312313", "openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA" }| 參數(shù)名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| code | 是 | string(20) | 1231231 | 需核銷的Code碼。 |
| openid | 是 | string(20) | oFS7Fjl0WsZ9AMZqrI80nbIq8xrA | 當(dāng)前卡券使用者的openid，通常通過網(wǎng)頁授權(quán)登錄或自定義url跳轉(zhuǎn)參數(shù)獲得。 |
返回?cái)?shù)據(jù)
數(shù)據(jù)示例：
{
"errcode":0,
"errmsg":"ok",
"card":{"card_id":"pFS7Fjg8kV1IdDz01r4SQwMkuCKc"},
"openid":"oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼。 |
| errmsg | 錯(cuò)誤信息。 |
| openid | 用戶在該公眾號內(nèi)的唯一身份標(biāo)識。 |
| card_id | 卡券ID。 |
注意：
1.只有在線上核銷的場景時(shí)，調(diào)用核銷接口才需要傳openid參數(shù)； 2.線下核銷的場景下，核銷接口傳遞的參數(shù)僅為code，無需openid；
核銷事件推送
卡券被核銷時(shí)，微信會把這個(gè)事件推送到開發(fā)者填寫的URL。 點(diǎn)擊查看卡券核銷事件推送
當(dāng)用戶使用優(yōu)惠券后，商家可通過JS SDK再次贈送一張卡券。核銷后再次贈送卡券接口（JS SDK）
該接口僅限6.3.6以上版本客戶端使用，且須配置1.1.0的js文件https://res.wx.qq.com/open/js/jweixin-1.1.0.js
詳情請見核銷后再次贈送卡券接口
幫助
錯(cuò)誤碼
| 錯(cuò)誤碼 | 說明 | 排錯(cuò)指引 |
|---|---|---|
| 40003 | Invalid opened，缺少openid | 核銷時(shí)用戶的卡券未處于展示（mark）狀態(tài)，朋友的券規(guī)定，券必須處于展示（mark）狀態(tài)時(shí)，才允許被核銷 |
| 40056 | 無效code | Code尚未被領(lǐng)取 |
| 40075 | 錯(cuò)誤的encrypt碼 | 請檢查加密碼是否拼寫正確，請檢查在url中取出encrypt_code（加密code）在post之前是否做過urlencode |
| 40078 | 該Code已經(jīng)被刪除或者轉(zhuǎn)贈中 | 建議開發(fā)者在調(diào)用核銷接口之前先調(diào)用【查詢code接口】確認(rèn)code有效后再發(fā)起核銷 |
| 40079 | 卡券過期 | 建議開發(fā)者在調(diào)用核銷接口之前先調(diào)用【查詢code接口】確認(rèn)code有效后再發(fā)起核銷 |
| 40099 | Code已經(jīng)被核銷 | 建議開發(fā)者在調(diào)用核銷接口之前先調(diào)用【查詢code接口】確認(rèn)code有效后再發(fā)起核銷 |
| 40127 | 該Code已經(jīng)被刪除、置為失效或者轉(zhuǎn)贈成功 | 建議開發(fā)者在調(diào)用核銷接口之前先調(diào)用【查詢code接口】確認(rèn)code有效后再發(fā)起核銷 |
更多錯(cuò)誤碼，請見卡券全局錯(cuò)誤碼
常見問題
1、為什么JSSDK拉起卡券列表中沒有卡券？
A:JSSDK拉不起卡券一般為簽名錯(cuò)誤和篩選條件錯(cuò)誤，兩種情況。 簽名錯(cuò)誤是指卡券簽名錯(cuò)誤，建議用http://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=cardsign調(diào)試 篩選條件錯(cuò)誤是指shopid/cardid/和cardtype傳參有誤，比如傳入了cash類型的cardtype,但是實(shí)際上用戶卡包中無此類型卡券。
2、為什么要調(diào)用mark住接口？
A：由于朋友的券會出現(xiàn)在不同的用戶列表中，所以在同一時(shí)刻可能有多個(gè)用戶同時(shí)進(jìn)入開發(fā)者開發(fā)的核銷頁面或者下單、支付頁面，會出現(xiàn)用戶付款但是沒有成功核銷卡券的情況，所以我們約定必須在卡券核銷之前調(diào)用mark住接口將code與當(dāng)前的openid鎖定。 其本質(zhì)是將code與當(dāng)前使用者鎖定的一個(gè)鎖、 比如快速買單和商城下單的場景可以在支付前調(diào)用mark接口，如果mark失敗則停止支付，而開發(fā)了自主核銷頁面的開發(fā)者可以選擇在核銷之前mark住code，從而避免沖突的發(fā)生。
朋友的券管理接口
更新朋友的券信息接口
接口說明
創(chuàng)建朋友的券成功之后開發(fā)者可調(diào)用該接口更改卡券信息，某些需要修改后送審的字段開發(fā)者需慎重處理
開發(fā)者注意事項(xiàng)
1. 更改卡券的部分字段后會重新提交審核，詳情見字段說明，更新成功后可通過調(diào)用查看卡券詳情接口核查更新結(jié)果；
2. 僅填入需要更新的字段，許多開發(fā)者在調(diào)用該接口時(shí)會填入brandname（品牌名稱）等不支持修改的字段，導(dǎo)致更新不成功。
3. 調(diào)用該接口后更改卡券信息后，請務(wù)必調(diào)用查看卡券詳情接口驗(yàn)證是否已成功更改。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/card/update?access_token=TOKEN
參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 調(diào)用接口憑證 |
| POST數(shù)據(jù) | 是 | JSON數(shù)據(jù) |
POST示例
{
"card_id": "pbLatjgOY1_Cxi3mnWBThtG90HGg",
"cash": {
"base_info": {
"code_type": "CODE_TYPE_TEXT",
"color": "Color010",
"service_phone": "020-88888888",
"description": "不可與其他優(yōu)惠同享如需團(tuán)購券發(fā)票，請?jiān)谙M(fèi)時(shí)向商戶提出",
"can_share": false,
"can_give_friend": false,
"location_id_list": [
272981040,
400183234
],
"custom_url_name": "立即使用",
"custom_url": "http://www.qq.com ",
"custom_url_sub_title": "6個(gè)漢字tips",
"promotion_url_name": "更多優(yōu)惠",
"promotion_url": "http://www.qq.com"
},
"advanced_info": {
"time_limit": [
{
"type": "MONDAY"
},
{
"type": "HOLIDAY"
}
],
"text_image_list": [
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品精選食材，以獨(dú)特的烹飪方法，最大程度地刺激食客的味蕾"
},
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品迎合大眾口味，老少皆宜，營養(yǎng)均衡"
}
],
"business_service": [
"BIZ_SERVICE_FREE_WIFI",
"BIZ_SERVICE_WITH_PET",
"BIZ_SERVICE_FREE_PARK",
"BIZ_SERVICE_DELIVER"
],
"consume_share_card_list": [
{
"card_id": "pbLatjpvp0Xq6jtgRRxCKtudkBz8k",
"num": 1
}
],
"consume_share_self_num": 0,
"abstract": {
"abstract": "微信餐廳推出多種新季菜品，期待您的光臨",
"icon_url_list": [
"http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
]
}
}
}
}字段說明
Base_info（卡券基礎(chǔ)信息）字段修改：
| 參數(shù)名 | 是否提審 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| base_info | - | JSON結(jié)構(gòu) | 卡券基礎(chǔ)信息字段。 | |
| logo_url | 是 | string(128) | http://mmbiz.qpic.cn/ | 卡券的商戶logo，建議像素為300*300。 |
| notice | 是 | string（48） | 請出示二維碼核銷卡券。 | 使用提醒，字?jǐn)?shù)上限為16個(gè)漢字。 |
| description | 是 | string（3072） | 不可與其他優(yōu)惠同享\n如需團(tuán)購券發(fā)票，請?jiān)谙M(fèi)時(shí)向商戶提出\n店內(nèi)均可使用，僅限堂食。 | 使用說明。 |
| service_phone | 否 | string（24） | 40012234 | 客服電話。 |
| color | 是 | string（3072） | Color010 | 卡券顏色。 |
| location_id_list | 否 | string（3072） | 1234,2314 | 支持更新適用門店列表。 |
| center_title | 否 | string（18） | 快速使用 | 頂部居中的自定義cell。 |
| center_sub_title | 否 | string（24） | 點(diǎn)擊快速核銷卡券 | 頂部居中的自定義cell說明。 |
| center_url | 否 | string（128） | www.qq.com | 頂部居中的自定義cell的跳轉(zhuǎn)鏈接。 |
| location_id_list | 否 | string（3072） | 1234,2314 | 支持更新適用門店列表。 |
| custom_url_name | 否 | string（16） | 立即使用 | 自定義跳轉(zhuǎn)入口的名字。 |
| custom_url | 否 | string（128） | www.qq.com | 自定義跳轉(zhuǎn)的URL。 |
| custom_url_sub_title | 否 | string（18） | 更多驚喜 | 顯示在入口右側(cè)的提示語。 |
| promotion_url_name | 否 | string（16） | 產(chǎn)品介紹。 | 營銷場景的自定義入口名稱。 |
| promotion_url | 否 | string（128） | www.qq.com； | 入口跳轉(zhuǎn)外鏈的地址鏈接。 |
| promotion_url_sub_title | 否 | string（18） | 賣場大優(yōu)惠。 | 顯示在營銷入口右側(cè)的提示語。 |
| code_type | 否 | string（16） | CODE_TYPE_TEXT。 | Code碼展示類型，"CODE_TYPE_TEXT"，文本；"CODE_TYPE_BARCODE"，一維碼 ；"CODE_TYPE_QRCODE"，二維碼；"CODE_TYPE_ONLY_QRCODE",二維碼無code顯示；"CODE_TYPE_ONLY_BARCODE",一維碼無code顯示；"CODE_TYPE_NONE"，無code類型 |
| get_limit | 否 | int | 1 | 每人可領(lǐng)券的數(shù)量限制。 |
| can_share | 否 | bool | false | 卡券原生領(lǐng)取頁面是否可分享。 |
| can_give_friend | 否 | bool | false | 卡券是否可轉(zhuǎn)贈。 |
| date_info | 否 | Json結(jié)構(gòu) | 見上述示例 | 使用日期，有效期的信息，有效期時(shí)間修改僅支持有效區(qū)間的擴(kuò)大。 |
| type | 否 | string | DATE_TYPE_FIX_TIME_RANGE | 有效期類型，僅支持更改type為DATE_TYPE_FIX_TIME_RANGE 的時(shí)間戳。 |
| begin_timestamp | 否 | unsigned int | 14300000 | 固定日期區(qū)間專用，表示起用時(shí)間。（單位為秒） |
| end_timestamp | 否 | unsigned int | 15300000 | 固定日期區(qū)間專用，表示結(jié)束時(shí)間。最長可將卡券有效期延長至三個(gè)月。 |
Advanced_info（卡券高級信息）字段修改：
特別注意，以下支持更新的字段不在基本信息base_info的結(jié)構(gòu)中。
| 參數(shù)名 | 是否提審 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| advanced_info | 是 | JSON結(jié)構(gòu) | ||
| abstract | 否 | JSON結(jié)構(gòu) | 優(yōu)惠詳情摘要字段。 | |
| abstract | 否 | string(60) | 簡介。 | 本券限領(lǐng)一張，不能與其他優(yōu)惠共同使用。 |
| icon_url_list | 否 | string(3072) | 圖片列表，僅支持填入一個(gè)封面圖片鏈接，上傳圖片接口上傳獲取圖片獲得鏈接，填寫非CDN鏈接會報(bào)錯(cuò)，并在此填入。建議圖片尺寸像素900*375 | http://mmbiz.qpic.cn/mmbiz/xxxxx |
| text_image_list | 否 | string(3072) | 圖文列表，顯示在詳情內(nèi)頁，優(yōu)惠券券開發(fā)者須至少傳入一組圖文列表 | |
| image_url | 否 | string(3072) | 圖片鏈接，必須調(diào)用上傳圖片接口上傳圖片獲得鏈接，并在此填入，否則報(bào)錯(cuò) | http://mmbiz.qpic.cn/mmbiz/xxxxx |
| text | 否 | string(3072) | 圖文描述，5000字以內(nèi) | 一般為商品詳情介紹 |
| business_service | 否 | string(24) | 商家服務(wù)類型 可多選,此處僅控制展示，不填則不顯示 | BIZ_SERVICE_DELIVER 外賣服務(wù)；BIZ_SERVICE_FREE_PARK 停車位；BIZ_SERVICE_WITH_PET 可帶寵物；BIZ_SERVICE_FREE_WIFI 免費(fèi)Wi-Fi |
| time_limit | 是 | string(24) | 使用時(shí)段限制 | |
| type | 是 | string（24） | MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 HOLIDAY 假期通用 | 限制類型，可多選,此處僅控制展示，不填則不顯示 |
| consume_share_self_num | 是 | int | 核銷后送券的數(shù)量，可設(shè)置核銷后送本券的數(shù)量，限制傳入1張，與consume_share_card_list互斥 | 1 |
| consume_share_card_list | 是 | JSON | 核銷后贈送其他卡券的列表 | |
| card_id | 是 | string（24） | pbLatjhvf1xBtaOIhYOCnp7Wv4DA | 核銷后贈送的其他卡券card_id，目前僅支持填入一個(gè)共享券card_id，注意此處必須填入共享券 |
| num | 是 | unsigned int | 1 | 核銷后贈送的該card_id數(shù)目，目前僅支持填1 |
返回?cái)?shù)據(jù)說明
數(shù)據(jù)示例：
{"errcode":0, "errmsg":"ok", "send_check":false}| 參數(shù)名 | 描述 |
|---|---|
| errcode | 錯(cuò)誤碼，0為正常。 |
| errmsg | 錯(cuò)誤信息。 |
| send_check | 是否提交審核，false為修改后不會重新提審，true為修改字段后重新提審，該卡券的狀態(tài)變?yōu)閷徍酥小?/td> |
拉取朋友的券數(shù)據(jù)接口
接口簡介及開發(fā)注意事項(xiàng)
為支持開發(fā)者調(diào)用API查看卡券相關(guān)數(shù)據(jù)，微信卡券團(tuán)隊(duì)封裝數(shù)據(jù)接口并面向具備卡券功能權(quán)限的開發(fā)者開放使用。開發(fā)者調(diào)用該接口可獲取本商戶下的所有卡券相關(guān)的總數(shù)據(jù)以及指定卡券的相關(guān)數(shù)據(jù)。
拉取卡券概況數(shù)據(jù)接口
接口說明
支持調(diào)用該接口拉取本商戶的總體數(shù)據(jù)情況，包括時(shí)間區(qū)間內(nèi)的各指標(biāo)總量。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/datacube/getcardbizuininfo?access_token=ACCESS_TOKEN
請求參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 調(diào)用接口憑證 |
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
POST數(shù)據(jù)
{
"begin_date": "2015-06-15",
//請開發(fā)者按示例格式填寫日期，否則會報(bào)錯(cuò)dateformaterror"end_date": "2015-06-30",
"cond_source": 0
}參數(shù)說明：
| 字段 | 說明 | 是否必填 | 類型 | 示例值 |
|---|---|---|---|---|
| begin_date | 查詢數(shù)據(jù)的起始時(shí)間。 | 是 | string(16) | 2015-06-15 |
| end_date | 查詢數(shù)據(jù)的截至?xí)r間。 | 是 | string(16) | 2015-06-30 |
| cond_source | 卡券來源，0為公眾平臺創(chuàng)建的卡券數(shù)據(jù)、1是API創(chuàng)建的卡券數(shù)據(jù) | 是 | unsigned int | 0 |
返回?cái)?shù)據(jù)說明 數(shù)據(jù)示例：
{
"list": [
{
"ref_date": "2015-06-23",
"view_cnt": 1,
"view_user": 1,
"receive_cnt": 1,
"receive_user": 1,
"verify_cnt": 0,
"verify_user": 0,
"given_cnt": 0,
"given_user": 0,
"expire_cnt": 0,
"expire_user": 0
}
]
}字段說明：
| 字段 | 說明 |
|---|---|
| ref_date | 日期信息 |
| view_cnt | 瀏覽次數(shù) |
| view_user | 瀏覽人數(shù) |
| receive_cnt | 領(lǐng)取次數(shù) |
| receive_user | 領(lǐng)取人數(shù) |
| verify_cnt | 使用次數(shù) |
| verify_user | 使用人數(shù) |
| given_cnt | 轉(zhuǎn)贈次數(shù) |
| given_user | 轉(zhuǎn)贈人數(shù) |
| expire_cnt | 過期次數(shù) |
| expire_user | 過期人數(shù) |
注意：
1. 查詢時(shí)間區(qū)間需<=62天，否則報(bào)錯(cuò){errcode: 61501，errmsg: "date range error"}；
2. 傳入時(shí)間格式需嚴(yán)格參照示例填寫”2015-06-15”，否則報(bào)錯(cuò){errcode":61500,"errmsg":"date format error"}
獲取朋友的券數(shù)據(jù)接口
接口說明
支持開發(fā)者調(diào)用該接口拉取朋友的券在固定時(shí)間區(qū)間內(nèi)的相關(guān)數(shù)據(jù)。
接口調(diào)用請求說明
http請求方式: POST https://api.weixin.qq.com/datacube/getcardcardinfo?access_token=ACCESS_TOKEN
請求參數(shù)說明
| 參數(shù) | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 調(diào)用接口憑證 |
| POST數(shù)據(jù) | 是 | Json數(shù)據(jù) |
POST數(shù)據(jù)
{
"begin_date": "2015-06-15",
"end_date": "2015-06-30",
"cond_source": 0,
"card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE"
}參數(shù)說明：
| 字段 | 說明 | 是否必填 | 類型 | 示例值 |
|---|---|---|---|---|
| begin_date | 查詢數(shù)據(jù)的起始時(shí)間。 | 是 | string(16) | 2015-06-15 |
| end_date | 查詢數(shù)據(jù)的截至?xí)r間。 | 是 | string(16) | 2015-06-30 |
| cond_source | 卡券來源，0為公眾平臺創(chuàng)建的卡券數(shù)據(jù)、1是API創(chuàng)建的卡券數(shù)據(jù) | 是 | unsigned int | 0 |
| card_id | 卡券ID。填寫后，指定拉出該卡券的相關(guān)數(shù)據(jù)。 | 否 | string(32) | po8pktyDLmakNY2fn2VyhkiEPqGE |
返回?cái)?shù)據(jù)說明 數(shù)據(jù)示例：
{
"list": [
{
"ref_date": "2015-06-23",
"card_id": "po8pktyDLmakNY2fn2VyhkiEPqGE",
"card_type": 3,
"view_cnt": 1,
"view_user": 1,
"receive_cnt": 1,
"receive_user": 1,
"verify_cnt": 0,
"verify_user": 0,
"given_cnt": 0,
"given_user": 0,
"expire_cnt": 0,
"expire_user": 0
}
]
}字段說明：
| 字段 | 說明 |
|---|---|
| ref_date | 日期信息 |
| card_id | 卡券ID |
| card_type | cardtype:0：折扣券，1：代金券，2：禮品券，3：優(yōu)惠券，4：團(tuán)購券（暫不支持拉取特殊票券類型數(shù)據(jù)，電影票、飛機(jī)票、會議門票、景區(qū)門票） |
| view_cnt | 瀏覽次數(shù) |
| view_user | 瀏覽人數(shù) |
| receive_cnt | 領(lǐng)取次數(shù) |
| receive_user | 領(lǐng)取人數(shù) |
| verify_cnt | 使用次數(shù) |
| verify_user | 使用人數(shù) |
| given_cnt | 轉(zhuǎn)贈次數(shù) |
| given_user | 轉(zhuǎn)贈人數(shù) |
| expire_cnt | 過期次數(shù) |
| expire_user | 過期人數(shù) |
注意：
1. 查詢時(shí)間區(qū)間需<=62天，否則報(bào)錯(cuò){"errcode:" 61501，errmsg: "date range error"}；
2. 傳入時(shí)間格式需嚴(yán)格參照示例填寫如”2015-06-15”，否則報(bào)錯(cuò)｛"errcode":"date format error"｝
我是第三方開發(fā)者/服務(wù)商
朋友的券目前率先開通了MP流程，同樣支持接口創(chuàng)建朋友的券。目前第三方/服務(wù)商可以利用現(xiàn)有能力幫助沒有開發(fā)能力的商戶創(chuàng)建、投放并核銷朋友的券，并管理朋友的券數(shù)據(jù)。
第三方/服務(wù)商可以通過以下流程完成朋友的券基本流程：
2、商戶通過公眾號授權(quán)將公眾賬號的卡券權(quán)限集授權(quán)給第三方代調(diào)用接口。
3、開發(fā)者根據(jù)垂直行業(yè)特點(diǎn)，幫助商戶完成創(chuàng)建朋友的券、投放朋友的券、 接口兌換庫存、充值券點(diǎn)、核銷朋友的券并完成朋友的券數(shù)據(jù)管理。
4、對于有能力的開發(fā)者可以融合第三方授權(quán)授權(quán)和第三方協(xié)助制券等模式搭建自己的 卡券平臺供子商戶使用。
交流反饋
朋友的券開發(fā)者可以加入開發(fā)者交流五群、六群（QQ群）：512568283、205482166，若開發(fā)過程中遇到問題，也可以發(fā)送郵件到weixin_card@foxmail.com 反饋。
以上內(nèi)容是否對您有幫助：
更多建議：