微信卡券接口

1  須知

   閱讀卡券部分接口文檔，請(qǐng)務(wù)必閱讀微信公眾平臺(tái)開(kāi)發(fā)者通用說(shuō)明文檔《微信開(kāi)發(fā)者規(guī)范》和《微信公眾號(hào)接口權(quán)限說(shuō)明》兩個(gè)章節(jié)，以獲知微信公眾平臺(tái)接口的基本調(diào)用方法、開(kāi)發(fā)者規(guī)范以及調(diào)用過(guò)程中異常問(wèn)題的處理。

2 申請(qǐng)沙箱測(cè)試賬號(hào)

如果你沒(méi)有可用的卡券測(cè)試賬號(hào)，可以通過(guò)微信接口測(cè)試號(hào)申請(qǐng)工具申請(qǐng)一個(gè)臨時(shí)測(cè)試號(hào)用于卡券測(cè)試。你可以登錄接口測(cè)試號(hào)申請(qǐng) 通過(guò)微信掃一掃獲得一個(gè)全新的appid(已擁有卡券創(chuàng)建權(quán)限，包括朋友的券)和appsecret用于卡券接口調(diào)用。

注意：該appid創(chuàng)建的卡券不會(huì)被審核通過(guò)，僅限于小范圍測(cè)試，開(kāi)發(fā)者不可用于其他用途。

3 卡券HelloWorld

開(kāi)發(fā)者可以通過(guò)debug工具，快速完成創(chuàng)建卡券、投放卡券和核銷卡券的流程， 若要深入了解卡券接口，則需要對(duì)對(duì)應(yīng)的部分的文檔詳細(xì)閱讀。

步驟一 獲取access_token

頁(yè)面地址：http://mp.weixin.qq.com/debug/

接口類型：基礎(chǔ)支持

接口列表：獲取access_token接口

注意事項(xiàng)：參數(shù)填寫開(kāi)發(fā)者的appid和secret

點(diǎn)擊檢查問(wèn)題，即可返回access_token，access_token的有效期是兩小時(shí)，兩小時(shí)之后須重新獲取

步驟二 上傳卡券logo

頁(yè)面地址：http://mp.weixin.qq.com/debug/

接口類型：基礎(chǔ)支持

接口列表：上傳圖片素材接口

access_token: 上一步獲得的access_token

buffer：你選擇的圖片

點(diǎn)擊檢查問(wèn)題，即可獲取圖片url，在下一步創(chuàng)建卡劵的參數(shù)中需要

步驟三 創(chuàng)建卡券

頁(yè)面地址：http://mp.weixin.qq.com/debug/

接口類型：卡劵接口

接口列表：創(chuàng)建卡劵接口

access_token:第一步獲得的access_token

JSON示例：

{ 
"card": {
  "card_type": "GROUPON",
  "groupon": {
      "base_info": {
          "logo_url": 
"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
          "brand_name":"微信餐廳",
          "code_type":"CODE_TYPE_TEXT",
          "title": "132元雙人火鍋套餐",
          "sub_title": "周末狂歡必備",
          "color": "Color010",
          "notice": "使用時(shí)向服務(wù)員出示此券",
          "service_phone": "020-88888888",
          "description": "不可與其他優(yōu)惠同享\n如需團(tuán)購(gòu)券發(fā)票，請(qǐng)?jiān)谙M(fèi)時(shí)向商戶提出\n店內(nèi)均可使用，僅限堂食",
          "date_info": {
              "type": "DATE_TYPE_FIX_TERM",
              "fixed_term": 15 ,
              "fixed_begin_term": 0
          },
          "sku": {
              "quantity": 500000
          },
          "get_limit": 3,
          "use_custom_code": false,
          "bind_openid": false,
          "can_share": true,
        "can_give_friend": true,
          "location_id_list" : [123, 12321, 345345],
          "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"
      },
      "deal_detail": "以下鍋底2選1（有菌王鍋、麻辣鍋、大骨鍋、番茄鍋、清補(bǔ)涼鍋、酸 菜魚鍋可選）：\n大鍋1份 12元\n小鍋2份 16元 "}
}
}

注意事項(xiàng)：date_info中用的是Unix時(shí)間戳，注意把begin_timestamp修改小于當(dāng)前時(shí)間，end_timestamp修改成今天之后的時(shí)間，這樣在后面核銷卡劵測(cè)試才能成功

接口地址：創(chuàng)建卡券接口

步驟四 創(chuàng)建二維碼投放

頁(yè)面地址：http://mp.weixin.qq.com/debug/

接口類型：卡劵接口

接口列表：創(chuàng)建二維碼ticket接口

access_token：第一步獲得的access_token

JSON示例：

{
"action_name": "QR_CARD", 
"action_info": {
"card": {
"card_id": "po_2DjgJ2zrboM6SzK3qNuje5iWQ", 
   }
 }
}

接口地址：創(chuàng)建二維碼接口

步驟五 顯示二維碼

在上一步的返回中點(diǎn)擊字段show_qrcode_url字段中的鏈接，即可顯示卡券領(lǐng)取二維碼。

示例：https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=gQEr8ToAAAAAAAAAASxodHRwOi8vd2V********NjRjVuAAIE3kqwVQMEgDPhAQ==

打開(kāi)微信掃一掃，然后領(lǐng)取卡劵，如果顯示卡劵未通過(guò)審核，那么需要下一步設(shè)置測(cè)試白名單，如果可以領(lǐng)取就忽略第六步。

可掃描以下二維碼體驗(yàn)微信卡券：

步驟六 設(shè)置測(cè)試白名單

頁(yè)面地址：http://mp.weixin.qq.com/debug/

接口類型：卡劵接口

接口列表：設(shè)置測(cè)試白名單接口

access_token：第一步獲得的access_token

JSON示例：

{ "username":["usr1","usr2"] }

注意事項(xiàng)：其中usr1，sur2是領(lǐng)取卡劵的微信號(hào)

接口地址：設(shè)置白名單接口

步驟七 核銷卡劵

頁(yè)面地址：http://mp.weixin.qq.com/debug/

接口類型：卡劵接口

接口列表：核銷卡劵接口

access_token：第一步獲得的access_token

JSON示例：

{ "code"："759733467744" }

注意事項(xiàng)：僅支持審核通過(guò)且在有效期內(nèi)的卡劵 接口地址：核銷接口

4 卡券接口概覽

微信卡券接口主要圍繞卡券的創(chuàng)建、領(lǐng)取、投放以及卡券核銷設(shè)置了一系列接口，開(kāi)發(fā)者可以根據(jù)自己想實(shí)現(xiàn)的效果選擇合適的接口

進(jìn)行開(kāi)發(fā)，以實(shí)現(xiàn)行業(yè)各有特色的卡券應(yīng)用。

5 卡券術(shù)語(yǔ)介紹

以下是卡券開(kāi)發(fā)過(guò)程中需要了解的關(guān)鍵概念：

6 開(kāi)發(fā)者注意事項(xiàng)

6.1 微信版本判斷

由于微信6.0.2版本后才支持卡券功能模塊，低版本用戶調(diào)用JS-SDK無(wú)效。因此，微信團(tuán)隊(duì)建議商戶通過(guò)user agent來(lái)確定用戶當(dāng)前的版本號(hào)后再調(diào)用添加至卡包JS-SDK接口。以iPhone版本為例，可以通過(guò)user agent可獲取如下版本示例信息：

"Mozilla/5.0(iphone;CPU iphone OS 5_1_1 like Mac OS X)     
AppleWebKit/534.46(KHTML,like Geocko)Mobile/9B206 MicroMessenger/6.0.2 "

其中6.0.2為用戶安裝的微信版本號(hào)。商戶可以判定版本號(hào)是否高于或者等于6.0.2。

6.2 卡券投放限制

公眾號(hào)會(huì)話環(huán)境內(nèi)僅支持調(diào)起該公眾號(hào)域名下的卡券。未經(jīng)平臺(tái)允許不支持在公眾號(hào)會(huì)話內(nèi)推送其他商戶的卡券，否則用戶在領(lǐng)券時(shí)會(huì)提示：“未經(jīng)制券商家授權(quán)，不可投放”。公眾號(hào)會(huì)話外（如朋友圈、對(duì)話環(huán)境）無(wú)此限制。

注意事項(xiàng)

公眾號(hào)的對(duì)話框中發(fā)生的行為以及從公眾號(hào)對(duì)話框跳轉(zhuǎn)的網(wǎng)頁(yè)鏈接均處于該公眾號(hào)的會(huì)話環(huán)境內(nèi)。

6.3 編碼規(guī)則

所有API接口POST的數(shù)據(jù)只支持UTF-8編碼，否則會(huì)返回報(bào)錯(cuò)。

6.4 跳轉(zhuǎn)外鏈帶參數(shù)說(shuō)明

為了滿足商戶基于卡券本身的擴(kuò)展訴求，允許卡券內(nèi)頁(yè)添加url跳轉(zhuǎn)外鏈。

在卡券跳轉(zhuǎn)出去的外鏈均可以帶有卡券信息的參數(shù)，用于開(kāi)發(fā)者在頁(yè)面內(nèi)確認(rèn)用戶身份。

帶有的的字段有encrypt_code、card_id、openid、outer_str（僅會(huì)員卡）。

注意事項(xiàng)： encrypt_code為加密碼碼，需調(diào)用解碼接口獲取真實(shí)Code碼。 假如指定的url為http://www.qq.com，用戶點(diǎn)擊時(shí)，跳轉(zhuǎn)的url則為： http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID&openid=xxxx&outer_str=xxxxx

6.5 聯(lián)系我們

遇到卡券開(kāi)發(fā)問(wèn)題，可以通過(guò)郵箱weixin_card@foxmail.com 聯(lián)系我們。也可以加入開(kāi)發(fā)者QQ交流群205482166 512568283，驗(yàn)證請(qǐng)務(wù)必說(shuō)明商家名及業(yè)務(wù)。

7 卡券資料包下載

開(kāi)發(fā)者可下載卡券接口資料包：

- 創(chuàng)建&簽名工具SDK；

- 卡券接口調(diào)用流程圖；

- 新增接口特性說(shuō)明；

- SDK for Android；

- SDK for iOS；