微信平臺(tái)投放卡券

更新日志

1 創(chuàng)建二維碼接口

開發(fā)者可調(diào)用該接口生成一張卡券二維碼供用戶掃碼后添加卡券到卡包。

自定義Code碼的卡券調(diào)用接口時(shí)，POST數(shù)據(jù)中需指定code，非自定義code不需指定，指定openid同理。指定后的二維碼只能被用戶掃描領(lǐng)取一次。

獲取二維碼ticket后，開發(fā)者可用通過ticket換取二維碼接口。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/qrcode/create?access_token=TOKEN

參數(shù)說明

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_str":"12b"
  }
 }
}

當(dāng)開發(fā)者設(shè)置掃描二維碼領(lǐng)取多張卡券，此時(shí)POST數(shù)據(jù)為：

{
"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"
}
]
}
}
}

參數(shù)說明

返回?cái)?shù)據(jù)

{
 "errcode": 0,
 "errmsg": "ok",
 "ticket":      "gQHB8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0JIV3lhX3psZmlvSDZmWGVMMTZvAAIEsNnKVQMEIAMAAA==",//獲取ticket后需調(diào)用換取二維碼接口獲取二維碼圖片，詳情見字段說明。
 "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ù)說明

注意事項(xiàng)：

1.自定義code的卡券，生成的二維碼每次只能領(lǐng)取一次，若開發(fā)者想要使用自己的串碼系統(tǒng)并且想要用微信的二維碼

投放，須先將自定義code導(dǎo)入；

2.領(lǐng)取多張的二維碼一次最多填入5個(gè)card_id，否則報(bào)錯(cuò)。

2 HTML5線上發(fā)券（JS-SDK接口）

微信 JS-SDK 僅支持在微信內(nèi)置瀏覽器中使用,其他瀏覽器調(diào)用無效。

微信提供addCard接口供商戶前端網(wǎng)頁調(diào)用,用于將一張或多張卡券添加到用戶卡包。詳情見批量添加卡券接口。

3 通過卡券貨架投放卡券

卡券貨架簡介

卡券貨架支持開發(fā)者通過調(diào)用接口生成一個(gè)卡券領(lǐng)取H5頁面，并獲取頁面鏈接，進(jìn)行卡券投放動(dòng)作。 目前卡券貨架僅支持非自定義code的卡券，自定義code的卡券需先調(diào)用導(dǎo)入code接口將code導(dǎo)入才能正常使用。

3.1 創(chuàng)建貨架接口

接口說明

開發(fā)者需調(diào)用該接口創(chuàng)建貨架鏈接，用于卡券投放。創(chuàng)建貨架時(shí)需填寫投放路徑的場景字段。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/landingpage/create?access_token=$TOKEN

請(qǐng)求參數(shù)說明

POST數(shù)據(jù)

{  
"banner":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7h  icFN",
   "page_title": "惠城優(yōu)惠大派送",
   "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"
       }
   ]
}

參數(shù)說明

返回?cái)?shù)據(jù)說明

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

字段說明

4 群發(fā)卡券

請(qǐng)開發(fā)者特別注意，目前群發(fā)卡券接口僅支持投放非自定義Code碼的卡券。自定義code碼的商戶若想使用該功能需調(diào)用導(dǎo)入code接口將自定義code先導(dǎo)入微信服務(wù)器。

4.1 導(dǎo)入自定義code(僅對(duì)自定義code商戶)

接口簡介

該模塊只針對(duì)自定義code商戶，非自定義code開發(fā)者請(qǐng)自動(dòng)忽略。 開發(fā)者可以將自定義code提前導(dǎo)入至微信服務(wù)器，以獲得和非自定義code商戶同樣的投放能力，如分組群發(fā)、客服消息下發(fā)卡券等。

導(dǎo)入code后的卡券在投放時(shí)等同于非自定義code卡券

新創(chuàng)建卡券

如果開發(fā)者打算新創(chuàng)建一張支持導(dǎo)入code模式的卡券，不同于以往的創(chuàng)建方式，建議開發(fā)者采用以下流程創(chuàng)建預(yù)存code模式卡券，否則會(huì)報(bào)錯(cuò)。

步驟一：創(chuàng)建預(yù)存模式卡券，將庫存quantity初始值設(shè)置為0，并填入get_custom_code_mode字段;

步驟二：待卡券通過審核后，調(diào)用導(dǎo)入code接口并核查code;

步驟三：調(diào)用修改庫存接口，須令卡券庫存小于或等于導(dǎo)入code的數(shù)目。(為了避免混亂建議設(shè)置為相等)

非新創(chuàng)建卡券

如果開發(fā)者已經(jīng)有一張卡券，想把它改為預(yù)存code模式，建議開發(fā)者按照以下流程對(duì)卡券進(jìn)行更新。

步驟一：調(diào)用導(dǎo)入code接口導(dǎo)入一定量的自定義code并核查code;

步驟二：調(diào)用更改卡券信息接口填入get_custom_code_mode字段;

步驟三：調(diào)用修改庫存接口將卡券庫存quantity設(shè)置為與導(dǎo)入code數(shù)目相等的數(shù)字。

4.1.1 填入/更新導(dǎo)入code必需字段

接口說明

自定義code的卡券僅支持API創(chuàng)建，創(chuàng)建時(shí)務(wù)必在base_info中加入以下字段(詳情見接口文檔CreateCard創(chuàng)建卡券接口)， 加入以下兩個(gè)指定字段后，才可以調(diào)用code導(dǎo)入接口進(jìn)行code導(dǎo)入

創(chuàng)建卡券時(shí)JSON示例

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

更新卡券時(shí)JSON示例

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

 注意事項(xiàng)：

 創(chuàng)建/更新填入get_custom_code_mode時(shí)，須檢查庫存數(shù)與已經(jīng)導(dǎo)入code數(shù)目的關(guān)系，當(dāng)導(dǎo)入code的數(shù)目小于庫存數(shù)時(shí)，會(huì)報(bào)錯(cuò)。

4.1.2 導(dǎo)入code接口

在自定義code卡券成功創(chuàng)建并且通過審核后，必須將自定義code按照與發(fā)券方的約定數(shù)量調(diào)用導(dǎo)入code接口導(dǎo)入微信后臺(tái)。

接口說明

開發(fā)者可調(diào)用該接口將自定義code導(dǎo)入微信卡券后臺(tái)，由微信側(cè)代理存儲(chǔ)并下發(fā)code。

注： 1）單次調(diào)用接口傳入code的數(shù)量上限為100個(gè)。

2）每一個(gè) code 均不能為空串。

3）導(dǎo)入結(jié)束后系統(tǒng)會(huì)自動(dòng)判斷提供方設(shè)置庫存與實(shí)際導(dǎo)入code的量是否一致。

4）導(dǎo)入失敗支持重復(fù)導(dǎo)入，提示成功為止。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:http://api.weixin.qq.com/card/code/deposit?access_token=ACCESS_TOKEN

請(qǐng)求參數(shù)說明

POST數(shù)據(jù)

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

字段說明

返回?cái)?shù)據(jù)說明

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

字段說明

4.1.3 查詢導(dǎo)入code數(shù)目接口

接口說明

支持開發(fā)者調(diào)用該接口查詢code導(dǎo)入微信后臺(tái)成功的數(shù)目。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:http://api.weixin.qq.com/card/code/getdepositcount?access_token=ACCESS_TOKEN

請(qǐng)求參數(shù)說明

POST數(shù)據(jù)

{
   "card_id" : " pDF3iY0_dVjb_Pua96MMewA96qvA "
}

字段說明

返回?cái)?shù)據(jù)說明

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

字段說明

4.1.4 核查code接口

為了避免出現(xiàn)導(dǎo)入差錯(cuò)，強(qiáng)烈建議開發(fā)者在查詢完code數(shù)目的時(shí)候核查code接口校驗(yàn)code導(dǎo)入微信后臺(tái)的情況。

接口說明

支持開發(fā)者調(diào)用該接口查詢code導(dǎo)入微信后臺(tái)的情況。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:http://api.weixin.qq.com/card/code/checkcode?access_token=ACCESS_TOKEN

請(qǐng)求參數(shù)說明

POST數(shù)據(jù)

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

字段說明

返回?cái)?shù)據(jù)說明

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

字段說明

4.2 圖文消息群發(fā)卡券

支持開發(fā)者調(diào)用該接口獲取卡券嵌入圖文消息的標(biāo)準(zhǔn)格式代碼，將返回代碼填入上傳圖文素材接口中content字段，即可獲取嵌入卡券的圖文消息素材。

特別注意：目前該接口僅支持填入非自定義code的卡券,自定義code的卡券需先進(jìn)行code導(dǎo)入后調(diào)用。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/mpnews/gethtml?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

{
  "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"
}

返回?cái)?shù)據(jù)

 {
"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\">"
}

4.3 根據(jù)分組群發(fā)卡券消息

支持調(diào)用該接口向指定分組的用戶群發(fā)卡券消息。詳情見根據(jù)分組進(jìn)行群發(fā)接口

目前該接口僅支持填入非自定義code的卡券,自定義code的卡券需先進(jìn)行code導(dǎo)入后調(diào)用。

4.4 根據(jù)OpenID列表群發(fā)卡券消息

支持根據(jù)OpenID群發(fā)原生卡券。訂閱號(hào)不可用，服務(wù)號(hào)認(rèn)證后具備接口權(quán)限。詳情見根據(jù)OpenID列表群發(fā)接口

目前該接口僅支持填入非自定義code的卡券,自定義code的卡券需先進(jìn)行code導(dǎo)入后調(diào)用。

4.5 客服消息下發(fā)卡券

支持開發(fā)者調(diào)用該接口下發(fā)卡券。訂閱號(hào)不可用，服務(wù)號(hào)認(rèn)證后可用。詳情見客服接口-發(fā)消息

目前該接口僅支持填入非自定義code的卡券,自定義code的卡券需先進(jìn)行code導(dǎo)入后調(diào)用。

4.6 預(yù)覽接口

支持開發(fā)者調(diào)用該接口下發(fā)卡券。訂閱號(hào)不可用，服務(wù)號(hào)認(rèn)證后可用。詳情見預(yù)覽接口

5 投放渠道數(shù)據(jù)統(tǒng)計(jì)

為方便開發(fā)者統(tǒng)計(jì)各渠道的卡券投放數(shù)據(jù)，新增字段outer_str（原outer_id）。將不同設(shè)值的outer_str（原outer_id）填入card_ext的json結(jié)構(gòu)中，當(dāng)用戶領(lǐng)取卡券時(shí)會(huì)將相應(yīng)設(shè)值的outer_id帶入領(lǐng)取事件中，推送至開發(fā)者服務(wù)器。

示例： 在二維碼投放方式中設(shè)置outer_str為12b

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

領(lǐng)取事件XML文件

<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>

6 設(shè)置測試白名單

接口說明

由于卡券有審核要求，為方便公眾號(hào)調(diào)試，可以設(shè)置一些測試帳號(hào)，這些帳號(hào)可領(lǐng)取未通過審核的卡券，體驗(yàn)整個(gè)流程。

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

1.同時(shí)支持“openid”、“username”兩種字段設(shè)置白名單，總數(shù)上限為10個(gè)。

2.設(shè)置測試白名單接口為全量設(shè)置，即測試名單發(fā)生變化時(shí)需調(diào)用該接口重新傳入所有測試人員的ID.

3.白名單用戶領(lǐng)取該卡券時(shí)將無視卡券失效狀態(tài)，請(qǐng)開發(fā)者注意。

接口調(diào)用請(qǐng)求說明

HTTP請(qǐng)求方式: POST
URL:https://api.weixin.qq.com/card/testwhitelist/set?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

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

參數(shù)說明

返回說明

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