投放卡券

更新日誌

1 建立二維碼介面

取得二維碼ticket後，開發者可用#透過ticket換取二維碼介面。

介面呼叫請求說明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

參數說明

POST資料 

 {
"action_name": "QR_CARD", 
"expire_seconds": 1800,
"action_info": {
"card": {
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc", 
"code": "198374613512",
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"is_unique_code": false ,
"outer_str":"12b"
  }
 }
}

{
"action_name": "QR_MULTIPLE_CARD", 
"action_info": {
"multiple_card": {
"card_list": [
{
"card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo88",
"code":"2392583481",
"outer_str":"12b"
}, 
{
"card_id": "p1Pj9jgj3BcomSgtuW8B1wl-wo98",
"code":"2392583482",
"outer_str":"12b"
}
]
}
}
}

#

{
 "errcode": 0,
 "errmsg": "ok",
 "ticket":      "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",//获取ticket后需调用换取二维码接口获取二维码图片，详情见字段说明。
 "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"
 }

注意事項：

1.自訂code的卡券，產生的二維碼每次只能領取一次，若開發者想要使用自己的字串碼系統並且想要用微信的二維碼投放，必須先將

自訂code導入

微信提供addCard介面供商家前端網頁呼叫,用於將一張或多張卡券加入用戶卡包。詳情請見批次新增卡券介面。

#3 透過卡券貨架上播放卡片

卡券貨架簡介

#卡券貨架支援開發者透過呼叫介面產生卡券領取H5頁面，並獲取頁面鏈接，進行卡券投放動作。 目前卡券貨架僅支援非自訂code的卡券，自訂code的卡券需先呼叫匯入code介面##將code匯入才能正常使用。 #

3.1 建立貨架介面

介面說明

開發者需呼叫該接口創建貨架鏈接，用於卡券投放。建立貨架時需填寫投放路徑的場景欄位。

介面呼叫請求說明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/landingpage/create?access_token=$TOKEN

請求參數說明

POST資料

{  
"banner":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7h  icFN",
   "page_title": "惠城优惠大派送",
   "can_share": true,
   "scene": "SCENE_NEAR_BY",
   "card_list": [
       {
           "card_id": "pXch-jnOlGtbuWwIO2NDftZeynRE",
           "thumb_url": "www.qq.com/a.jpg"
       },
       {
           "card_id": "pXch-jnAN-ZBoRbiwgqBZ1RV60fI",
           "thumb_url": "www.qq.com/b.jpg"
       }
   ]
}

傳回資料說明

{
     "errcode":0,
     "errmsg":"ok",
     "url":"www.test.url",
     "page_id":1
 }

請開發者特別注意，目前群發卡券介面僅支援投放非自訂Code碼的卡券。自訂code碼的商家若想使用此功能需呼叫匯入code介面將自訂code先匯入微信伺服器。

此模組只針對自訂code商戶，非自訂code開發者請自動忽略。  開發者可以將自訂code提前匯入至微信伺服器，以獲得和非自訂code商家相同的投放能力，如分組群發、客服訊息下發卡券等。

匯入code後的卡券在投放時等同於非自訂code卡券

新建立卡券

如果開發者打算新建立一張支援導入code模式的卡券，不同於以往的建立方式，建議開發者採用以下流程建立預存code模式卡券，否則會報錯。

步驟一：建立預存模式卡券，將庫存quantity初始值設為0，並填入get_custom_code_mode字段;

步驟二：待卡券通過審核後，呼叫導入code接口並核查code;

步驟三：呼叫修改庫存接口，須令卡券庫存小於或等於導入code的數目。 (為了避免混亂建議設定為相等)

#非新建立卡券

如果開發者已經有一張卡券，想把它改為預存code模式，建議開發者按照以下流程對卡券進行更新。

步驟一：呼叫導入code介面導入一定量的自訂code並核查code;

步驟二：呼叫更改卡券資訊介面填入get_custom_code_mode欄位;

步驟三：呼叫修改庫存介面將卡券庫存quantity設定為與匯入code數目相等的數字。

#4.1.1 填入/更新匯入code必要欄位

介面說明

自訂code的卡券僅支援API創建，創建時務必在base_info中加入以下欄位(詳情請參閱介面文件CreateCard建立卡券介面)，並加入以下兩個指定欄位後，才可呼叫code導入介面進行code導入

{
 "card": {
     "card_type": "GROUPON",
     "groupon": {
     "base_info": {
     ··········
     "use_custom_code":true,
     "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT",
         },
          "advanced_info": {
      ··········
          },
         "deal_detail": "示例"
     }
   }
}

 {
      "card_id":"ph_gmt7cUVrlRk8swPwx7aDyF-pg",
      "groupon": { 
      "base_info": {
      ·········		            
        "get_custom_code_mode":"GET_CUSTOM_CODE_MODE_DEPOSIT",
      ·········
              }
        }
 }

在自訂code卡券

後，必須將自訂code依照與發券方的約定數量呼叫導入code介面導入微信後台。

開發者可呼叫此介面將自訂code匯入微信卡券後台，由微信側代理程式儲存並下發code。

附註： 1）單次呼叫介面傳入code的數量上限為100個。

2）每一個 code 均不能為空白字串。

3）匯入結束後系統會自動判斷提供者設定庫存與實際匯入code的量是否一致。

4）導入失敗支援重複導入，提示成功為止。

介面呼叫請求說明

HTTP请求方式: POST
URL:http://api.weixin.qq.com/card/code/deposit?access_token=ACCESS_TOKEN

請求參數說明

POST資料

{
   "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA",
   "code": [
       "11111",
       "22222",
       "33333",
       "44444",
       "55555"
   ]
}

傳回資料說明

{
  "errcode":0,
  "errmsg":"ok"
}

支援開發者呼叫該介面查詢code匯入微信後台成功的數目。

HTTP请求方式: POST
URL:http://api.weixin.qq.com/card/code/getdepositcount?access_token=ACCESS_TOKEN

{
   "card_id" : " pDF3iY0_dVjb_Pua96MMewA96qvA "
}

{
  "errcode":0,
  "errmsg":"ok"，
  "count":123
}

HTTP请求方式: POST
URL:http://api.weixin.qq.com/card/code/checkcode?access_token=ACCESS_TOKEN

為了避免匯入錯誤，強烈建議開發者在查詢完code數目的時候核查code介面校驗code導入微信後台的情況。

#支援開發者呼叫該介面查詢code匯入微信後台的情況。

{
   "card_id": "pDF3iY0_dVjb_Pua96MMewA96qvA",
   "code": [
       "11111",
       "22222",
       "33333",
       "44444",
       "55555"
   ]
}

请求参数说明

{
  "errcode":0,
  "errmsg":"ok"
  "exist_code":["11111","22222","33333"],
  "not_exist_code":["44444","55555"]
}

傳回資料說明

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/mpnews/gethtml?access_token=TOKEN

支援開發者呼叫此介面取得卡券嵌入圖文訊息的標準格式程式碼，將回傳程式碼填入上傳圖文素材介面

#中content字段，即可取得嵌入卡券的圖文訊息素材。

特別注意：目前該介面僅支援填入非自訂code的卡券,自訂code的卡券需先進行code導入後呼叫。

{
  "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"
}

 {
"errcode":0,
"errmsg":"ok",
"content":"<iframeclass=\"res_iframecard_iframejs_editor_card\"data-src=\"http: \/\/mp.weixin.qq.com\/bizmall\/appmsgcard?action=show&biz=MjM5OTAwODk4MA%3D%3D&cardid=p1Pj9jnXTLf2nF7lccYScFUYqJ0&wechat_card_js=1#wechat_redirect\">"
}

{
"action_name": "QR_CARD", 
"action_info": {
"card": {
"card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc", 
"code": "198374613512",
"openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
"expire_seconds": "1800"，
"is_unique_code": false ,
"outer_str" : "12b"
  }
 }
}

支援呼叫該介面向指定分組的用戶群發卡券訊息。詳情請見

根據分組進行群發介面

4.4 根據OpenID列表群發卡券訊息

支援根據OpenID群發原生卡券。訂閱號碼不可用，服務號認證後具備介面權限。詳情請見根據OpenID列表群發介面

目前介面僅支援填入非自訂code的卡券,自訂code的卡券需先進行code導入後調用。

4.5 客服訊息下發卡券

支援開發者呼叫該介面下發卡券。訂閱號碼不可用，服務號認證後可用。詳情請見客服介面-發送訊息

目前該介面僅支援填入非自訂code的卡券,自訂code的卡券需先進行code匯入後呼叫。

4.6 預覽介面

支援開發者呼叫該介面下發卡券。訂閱號碼不可用，服務號認證後可用。詳情請見預覽介面

#5 投放頻道資料統計

# #為方便開發者統計各管道的卡券投放數據，新增欄位outer_str（原outer_id）。將不同設值的outer_str（原outer_id）填入card_ext的json結構中，當使用者領取卡券時會將對應設值的outer_id帶入 領取事件##中，推至開發者伺服器。

範例： 在二維碼投放方式中設定outer_str為12b

<xml> <ToUserName><![CDATA[toUser]]></ToUserName> 
<FromUserName><![CDATA[FromUser]]></FromUserName> 
<FriendUserName><![CDATA[FriendUser]]></FriendUserName> 
<CreateTime>123456789</CreateTime> 
<MsgType><![CDATA[event]]></MsgType> 
<Event><![CDATA[user_get_card]]></Event> 
<CardId><![CDATA[cardid]]></CardId> 
<IsGiveByFriend>1</IsGiveByFriend>
<UserCardCode><![CDATA[12312312]]></UserCardCode>
<OuterStr>12b</OuterStr>
</xml>

領取事件XML檔

HTTP请求方式: POST
URL:https://api.weixin.qq.com/card/testwhitelist/set?access_token=TOKEN

6 設定測試白名單

介面說明

由於卡券有審核要求，為方便公眾號調試，可以設定一些測試帳號，這些帳號可領取未通過審核的卡券，體驗整個流程。

開發者註意事項

#1.同時支援「openid」、「username」兩種字段設定白名單，總數上限為10個。

2.設定測試白名單介面為全量設置，即測試名單發生變化時需調用該接口重新傳入所有測試人員的ID.

3.白名單用戶領取該卡券時將無視卡券失效狀態，請開發者註意。

介面呼叫請求說明

{
  "openid": [
      "o1Pj9jmZvwSyyyyyyBa4aULW2mA", 
      "o1Pj9jmZvxxxxxxxxxULW2mA"
               ],
  "username": [
      "afdvvf",
      "abcd"
                ]
 }

參數說明

POST資料

{
   "errcode":0,
   "errmsg":"ok"
}