卡券
獲取實例
$card = $officialAccount->card;
注意:后文用到的
$card
都為此實例。
通用功能
獲取卡券顏色
$card->colors();
卡券開放類目查詢
$card->categories();
創建卡券
創建卡券接口是微信卡券的基礎接口,用于創建一類新的卡券,獲取 card_id
,創建成功并通過審核后,商家可以通過文檔提供的其他接口將卡券下發給用戶,每次成功領取,庫存數量相應扣除。
$card->create(string $cardType, array $attributes);
-
attributes
array
卡券信息
使用示例:
<?php
$cardType = 'GROUPON';
$attributes = [
'base_info' => [
'brand_name' => '微信餐廳',
'code_type' => 'CODE_TYPE_TEXT',
'title' => '132元雙人火鍋套餐',
// ...
],
'advanced_info' => [
'use_condition' => [
'accept_category' => '鞋類',
'reject_category' => '阿迪達斯',
'can_use_with_other_discount' => true,
],
// ...
],
];
$result = $card->create($cardType, $attributes);
獲取卡券詳情
$cardInfo = $card->get($cardId);
批量查詢卡列表
$card->list($offset = 0, $count = 10, $statusList = 'CARD_STATUS_VERIFY_OK');
-
offset
int
- 查詢卡列表的起始偏移量,從0
開始 -
count
int
- 需要查詢的卡片的數量 -
statusList
- 支持開發者拉出指定狀態的卡券列表,詳見example
使用示例:
// CARD_STATUS_NOT_VERIFY, 待審核;
// CARD_STATUS_VERIFY_FAIL, 審核失敗;
// CARD_STATUS_VERIFY_OK, 通過審核;
// CARD_STATUS_USER_DELETE,卡券被商戶刪除;
// CARD_STATUS_DISPATCH,在公眾平臺投放過的卡券;
$result = $card->list($offset, $count, 'CARD_STATUS_NOT_VERIFY');
更改卡券信息接口
支持更新所有卡券類型的部分通用字段及特殊卡券中特定字段的信息。
$card->update($cardId, $type, $attributes = []);
-
type
string
- 卡券類型
使用示例:
<?php
$cardId = 'pdkJ9uCzKWebwgNjxosee0ZuO3Os';
$type = 'groupon';
$attributes = [
'base_info' => [
'logo_url' => 'http://mmbiz.qpic.cn/mmbiz/2aJY6aCPatSeibYAyy7yct9zJXL9WsNVL4JdkTbBr184gNWS6nibcA75Hia9CqxicsqjYiaw2xuxYZiaibkmORS2oovdg/0',
'center_title' => '頂部居中按鈕',
'center_sub_title' => '按鈕下方的wording',
'center_url' => 'http://www.easyswoolewechat.com',
'custom_url_name' => '立即使用',
'custom_url' => 'http://www.qq.com',
'custom_url_sub_title' => '6個漢字tips',
'promotion_url_name' => '更多優惠',
'promotion_url' => 'http://www.qq.com',
],
// ...
];
$result = $card->update($cardId, $type, $attributes);
刪除卡券
$card->delete($cardId);
創建二維碼
開發者可調用該接口生成一張卡券二維碼供用戶掃碼后添加卡券到卡包。
自定義 Code
碼的卡券調用接口時,POST
數據中需指定 code
,非自定義 code
不需指定,指定 openid
同理。指定后的二維碼只能被用戶掃描領取一次。
$card->createQrCode($cards);
-
cards
array
- 卡券相關信息
使用示例:
<?php
// 領取單張卡券
$cards = [
'action_name' => 'QR_CARD',
'expire_seconds' => 1800,
'action_info' => [
'card' => [
'card_id' => 'pdkJ9uFS2WWCFfbbEfsAzrzizVyY',
'is_unique_code' => false,
'outer_id' => 1,
],
],
];
$result = $card->createQrCode($cards);
<?php
// 領取多張卡券
$cards = [
'action_name' => 'QR_MULTIPLE_CARD',
'action_info' => [
'multiple_card' => [
'card_list' => [
['card_id' => 'pdkJ9uFS2WWCFfbbEfsAzrzizVyY'],
],
],
],
];
$result = $card->createQrCode($cards);
請求成功返回值示例:
{
"errcode": 0,
"errmsg": "ok",
// 獲取 ticket 后需調用換取二維碼接口獲取二維碼圖片,詳情見字段說明。
"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"
}
ticket 換取二維碼圖片
獲取二維碼 ticket
后,開發者可用 ticket
換取二維碼圖片。
$card->getQrCode($ticket);
- string
$ticket
。獲取的二維碼ticket
,憑借此ticket
可以在有效時間內換取二維碼。
使用示例:
<?php
$ticket = 'gQFF8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL01VTzN0T0hsS1BwUlBBYUszbVN5AAIEughxVwMEAKd2AA==';
$result = $card->getQrCode($ticket);
ticket 換取二維碼鏈接
$card->getQrCodeUrl($ticket);
使用示例:
<?php
$ticket = 'gQFF8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL01VTzN0T0hsS1BwUlBBYUszbVN5AAIEughxVwMEAKd2AA==';
$card->getQrCodeUrl($ticket);
創建貨架接口
開發者需調用該接口創建貨架鏈接,用于卡券投放。創建貨架時需填寫投放路徑的場景字段。
$card->createLandingPage($banner, $pageTitle, $canShare, $scene, $cardList);
- string $banner。頁面的
banner
圖 - string $pageTitle。頁面的
title
- bool $canShare。頁面是不是可以分享,
true
或false
- string $scene。投放頁面的場景值,具體值請參考下面的 使用示例。
- array $cardList。卡券列表,每個元素有兩個字段
使用示例:
<?php
$banner = 'http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFN';
$pageTitle = '惠城優惠大派送';
$canShare = true;
// SCENE_NEAR_BY 附近
// SCENE_MENU 自定義菜單
// SCENE_QRCODE 二維碼
// SCENE_ARTICLE 公眾號文章
// SCENE_H5 h5頁面
// SCENE_IVR 自動回復
// SCENE_CARD_CUSTOM_CELL 卡券自定義 cell
$scene = 'SCENE_NEAR_BY';
$cardList = [
['card_id' => 'pdkJ9uLRSbnB3UFEjZAgUxAJrjeY', 'thumb_url' => 'http://test.digilinx.cn/wxApi/Uploads/test.png'],
['card_id' => 'pdkJ9uJ37aU-tyRj4_grs8S45k1c', 'thumb_url' => 'http://test.digilinx.cn/wxApi/Uploads/aa.jpg'],
];
$result = $card->createLandingPage($banner, $pageTitle, $canShare, $scene, $cardList);
圖文消息群發卡券
特別注意:目前該接口僅支持填入非自定義 code
的卡券嗎,自定義 code
的卡券需先進行 code
導入后調用。
$card->getHtml($cardId);
使用示例:
<?php
$cardId = 'pdkJ9uLCEF_HSKO7JdQOUcZ-PUzo';
$result = $card->getHtml($cardId);
設置測試白名單
同時支持 “openid”、“username” 兩種字段設置白名單,總數上限為 10
個。
// 使用 openid
$card->setTestWhitelist($openids);
-
array $openids
:測試的openid
列表
// 使用 username
$card->setTestWhitelistByName($usernames);
-
array $usernames
:測試的微信號列表
使用示例:
<?php
// by openid
$openids = [$openId, $openId2, $openid3, ...];
$result = $card->setTestWhitelist($openids);
// by username
$usernames = ['easyswoole', 'easyswoole wechat'];
$result = $card->setTestWhitelistByName($usernames);
獲取用戶已領取卡券接口
用于獲取用戶卡包里的,屬于該 appid
下所有可用卡券,包括正常狀態和未生效狀態。
$card->getUserCards($openid, $cardId);
使用示例:
<?php
$openid = 'odkJ9uDUz26RY-7DN1mxkznfo9xU';
$cardId = ''; // 卡券ID。不填寫時默認查詢當前 appid 下的卡券。
$result = $card->getUserCards($openid, $cardId);
設置微信買單接口
$card->setPayCell($cardId, $isOpen = true);
-
string $isOpen
。是否開啟買單功能,填true/false
,不填默認true
使用示例:
<?php
$cardId = 'pdkJ9uH7u11R-Tu1kilbaW_zDFow';
// isOpen = true
$result = $card->setPayCell($cardId);
$result = $card->setPayCell($cardId, $isOpen);
修改庫存接口
// 增加庫存
$card->increaseStock($cardId, $amount);
// 減少庫存
$card->reduceStock($cardId, $amount);
-
string $cardId
。卡券ID
-
int $amount
。修改多少庫存
使用示例:
<?php
$cardId = 'pdkJ9uLRSbnB3UFEjZAgUxAJrjeY';
$result = $card->increaseStock($cardId, 100);
卡券 Code
導入 Code 接口
在自定義 Code
卡券成功創建并且通過審核后,必須將自定義 code
按照與發券方的約定數量調用導入 code
接口導入微信后臺。
$card->code->deposit($cardId, $codes);
-
string cardId
。要導入code
的卡券ID
-
array codes
。要導入微信卡券后臺的自定義code
,最多100
個
使用示例:
<?php
$cardId = 'pdkJ9uLCEF_HSKO7JdQOUcZ-PUzo';
$codes = ['11111', '22222', '33333'];
$result = $card->code->deposit($cardId, $codes);
查詢導入 Code 數目
// 要導入 code 的卡券 ID
$card->code->getDepositedCount($cardId);
使用示例:
<?php
$cardId = 'pdkJ9uLCEF_HSKO7JdQOUcZ-PUzo';
$result = $card->code->getDepositedCount($cardId);
核查 Code 接口
為了避免出現導入差錯,強烈建議開發者在查詢完 code
數目的時候核查 code
接口,校驗 code
導入微信后臺的情況。
$card->code->check($cardId, $codes);
使用示例:
<?php
$cardId = 'pdkJ9uLCEF_HSKO7JdQOUcZ-PUzo';
$codes = ['807732265476', '22222', '33333'];
$result = $card->code->check($cardId, $codes);
查詢 Code 接口
$card->code->get($code, $cardId, $checkConsume = true);
-
bool checkConsume
。是否校驗code
核銷狀態,true
和false
使用示例:
<?php
$code = '736052543512';
$cardId = 'pdkJ9uDgnm0pKfrTb1yV0dFMO_Gk';
$result = $card->code->get($code, $cardId);
// check_consume = false
$result = $card->code->get($code, $cardId, false);
核銷 Code 接口
$card->code->consume($code);
// 或者指定 cardId
$card->code->consume($code, $cardId);
使用示例:
<?php
$code = '789248558333';
$cardId = 'pdkJ9uDmhkLj6l5bm3cq9iteQBck';
$result = $card->code->consume($code);
// 或
$result = $card->code->consume($code, $cardId);
Code 解碼接口
$card->code->decrypt($encryptedCode);
使用示例:
<?php
$encryptedCode = 'XXIzTtMqCxwOaawoE91+VJdsFmv7b8g0VZIZkqf4GWA60Fzpc8ksZ/5ZZ0DVkXdE';
$result = $card->code->decrypt($encryptedCode);
更改 Code 接口
$card->code->update($code, $newCode, $cardId);
-
string $newCode
。變更后的有效Code
碼
使用示例:
<?php
$code = '148246271394';
$newCode = '659266965266';
$cardId = '';
$result = $card->code->update($code, $newCode, $cardId);
設置卡券失效
$card->code->disable($code, $cardId);
使用示例:
<?php
$code = '736052543512';
$cardId = '';
$result = $card->code->disable($code, $cardId);
會員卡
會員卡激活
$result = $card->memberCard->activate($info);
-
array $info
。需要激活的會員卡信息
使用示例:
<?php
$info = [
'membership_number' => '357898858', // 會員卡編號,由開發者填入,作為序列號顯示在用戶的卡包里。可與 Code 碼保持等值。
'code' => '916679873278', // 創建會員卡時獲取的初始 code。
'activate_begin_time' => '1397577600', // 激活后的有效起始時間。若不填寫默認以創建時的 data_info 為準。Unix 時間戳格式
'activate_end_time' => '1422724261', // 激活后的有效截至時間。若不填寫默認以創建時的 data_info 為準。Unix 時間戳格式。
'init_bonus' => '持白金會員卡到店消費,可享8折優惠。', // 初始積分,不填為 0。
'init_balance' => '持白金會員卡到店消費,可享8折優惠。', // 初始余額,不填為 0。
'init_custom_field_value1' => '白銀', // 創建時字段 custom_field1 定義類型的初始值,限制為 4 個漢字,12 字節。
'init_custom_field_value2' => '9折', // 創建時字段 custom_field2 定義類型的初始值,限制為 4 個漢字,12 字節。
'init_custom_field_value3' => '200', // 創建時字段 custom_field3 定義類型的初始值,限制為 4 個漢字,12 字節。
];
$result = $card->memberCard->activate($info);
設置開卡字段
$card->memberCard->setActivationForm($cardId, $settings);
-
array settings
。會員卡激活時的選項
使用示例:
<?php
$cardId = 'pdkJ9uJYAyfLXsUCwI2LdH2Pn1AU';
$settings = [
'required_form' => [
'common_field_id_list' => [
'USER_FORM_INFO_FLAG_MOBILE',
'USER_FORM_INFO_FLAG_LOCATION',
'USER_FORM_INFO_FLAG_BIRTHDAY',
],
'custom_field_list' => [
'喜歡的食物',
],
],
'optional_form' => [
'common_field_id_list' => [
'USER_FORM_INFO_FLAG_EMAIL',
],
'custom_field_list' => [
'喜歡的食物',
],
],
];
$result = $card->memberCard->setActivationForm($cardId, $settings);
拉取會員信息
$card->memberCard->getUser($cardId, $code);
使用示例:
<?php
$cardId = 'pbLatjtZ7v1BG_ZnTjbW85GYc_E8';
$code = '916679873278';
$result = $card->memberCard->getUser($cardId, $code);
更新會員信息
$card->memberCard->updateUser($params);
array $info
。可以更新的會員信息
使用示例:
<?php
$info = [
'code' => '916679873278', // 卡券 Code 碼。
'card_id' => 'pbLatjtZ7v1BG_ZnTjbW85GYc_E8', //卡券 ID。
'record_bonus' => '消費30元,獲得3積分', // 商家自定義積分消耗記錄,不超過 14 個漢字。
'bonus' => '100', // 需要設置的積分全量值,傳入的數值會直接顯示,如果同時傳入 add_bonus 和 bonus,則前者無效。
'balance' => '持白金會員卡到店消費,可享8折優惠。', // 需要設置的余額全量值,傳入的數值會直接顯示,如果同時傳入 add_balance 和 balance,則前者無效。
'record_balance' => '持白金會員卡到店消費,可享8折優惠。', // 商家自定義金額消耗記錄,不超過 14 個漢字。
'custom_field_value1' => '100', // 創建時字段 custom_field1 定義類型的最新數值,限制為 4 個漢字,12 字節。
'custom_field_value2' => '200', // 創建時字段 custom_field2 定義類型的最新數值,限制為 4 個漢字,12 字節。
'custom_field_value3' => '300', // 創建時字段 custom_field3 定義類型的最新數值,限制為 4 個漢字,12 字節。
];
$result = $card->memberCard->updateUser($info);
子商戶
添加子商戶
$card->subMerchant->create(array $info);
使用示例:
<?php
$info = [
'brand_name' => 'overtrue',
'logo_url' => 'http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0',
'protocol' => 'qIqwTfzAdJ_1-VJFT0fIV53DSY4sZY2WyhkzZzbV498Qgdp-K5HJtZihbHLS0Ys0',
'end_time' => '1438990559',
'primary_category_id' => 1,
'secondary_category_id' => 101,
'agreement_media_id' => '',
'operator_media_id' => '',
'app_id' => '',
];
$result = $card->subMerchant->create($info);
更新子商戶
$card->subMerchant->update(int $merchantId, array $info = []);
-
int $merchantId
。子商戶ID
-
array $info
。參數與創建子商戶參數一樣
使用示例:
<?php
$info = [
// ...
];
$result = $card->subMerchant->update('12', $info);
特殊票券
機票值機
$card->boardingPass->checkin(array $params);
更新會議門票 - 更新用戶
$card->meetingTicket->updateUser(array $params);
更新電影門票 - 更新用戶
$card->movieTicket->updateUser(array $params);
JSAPI
卡券批量下發到用戶
<?php
$cards = [
['card_id' => 'pdkJ9uLRSbnB3UFEjZAgUxAJrjeY', 'outer_id' => 2],
['card_id' => 'pdkJ9uJ37aU-tyRj4_grs8S45k1c', 'outer_id' => 3],
];
// 返回 json 格式
$json = $card->jssdk->assign($cards);
返回值為 json
,在模板里的用法如下:
wx.addCard({
cardList: <?= $json ?>, // 需要打開的卡券列表
success: function (res) {
var cardList = res.cardList; // 添加的卡券列表信息
}
});
獲取 Ticket
$card->jssdk->getTicket();
// 強制刷新
$card->jssdk->getTicket(true);