微信平臺(tái)開(kāi)發(fā)者創(chuàng)建卡券

1 更新通知

2016年5月15日起，微信卡券團(tuán)隊(duì)對(duì)會(huì)員卡能力進(jìn)行全面升級(jí)。在原有能力基礎(chǔ)上進(jìn)行以下能力升級(jí)，旨在幫助商家更好地進(jìn)行會(huì)員管理。

-強(qiáng)化客戶端一級(jí)入口：會(huì)員到店即用，快速定位商戶會(huì)員卡；

-自定義卡面能力：開(kāi)發(fā)者可以根據(jù)會(huì)員身份設(shè)置不同的卡面背景；

-門(mén)店掃碼方案：新用戶到店掃碼領(lǐng)卡，老用戶到店掃碼快速打開(kāi)會(huì)員卡，實(shí)現(xiàn)會(huì)員點(diǎn)餐、買(mǎi)單等多種功能

-支付即會(huì)員：支持開(kāi)發(fā)者設(shè)置微信支付后為用戶下發(fā)領(lǐng)卡消息，顧客支付即會(huì)員，快速拉新；

-運(yùn)營(yíng)策略調(diào)整：會(huì)員卡新增開(kāi)放類(lèi)目限制，自4月20日起，僅限會(huì)員卡類(lèi)目?jī)?nèi)的商戶新建會(huì)員卡，原有會(huì)員卡不受影響，詳情請(qǐng)見(jiàn)：《會(huì)員卡公告》

2 創(chuàng)建卡券

2.1 接口調(diào)用順序

2.2 接口調(diào)用說(shuō)明

在進(jìn)行卡券創(chuàng)建前，請(qǐng)開(kāi)發(fā)者根據(jù)自身業(yè)務(wù)場(chǎng)景確定以下幾點(diǎn)

2.2.1 明確卡券ID與Code碼的區(qū)別

創(chuàng)建卡券成功后獲取卡券ID，一個(gè)卡券ID代表一類(lèi)卡券，包含相應(yīng)庫(kù)存數(shù)量的Code碼。 

例如： 創(chuàng)建50元代金券，獲取一個(gè)卡券ID（card_id）用于投放，并設(shè)置庫(kù)存100萬(wàn)。顧客小A，領(lǐng)取到商戶投放的50元代金券時(shí)，券面

上會(huì)有一個(gè)唯一的標(biāo)識(shí)碼，即code碼。每個(gè)用戶的code碼都不相同，所以該商戶最終卡券發(fā)放完畢時(shí)，微信將會(huì)派發(fā)100萬(wàn)個(gè)不同的code碼給用戶。

2.2.2 是否自定義Code碼

微信卡券的Code碼可由微信后臺(tái)隨機(jī)分配，同時(shí)支持商戶自定義，兩者的區(qū)別如下：

備注：自定義code碼的開(kāi)發(fā)者若想要獲得和非自定義code商戶相同的群發(fā)卡券、客服消息派發(fā)卡券的能力。可以通過(guò)導(dǎo)入自定義code接口將非定義code導(dǎo)入到微信服務(wù)器，若僅在h5投放則無(wú)須導(dǎo)入，導(dǎo)入code后code由微信隨機(jī)下發(fā)，不可指定。

2.2.3 選擇合適的碼型

商戶可以根據(jù)自身的業(yè)務(wù)模式和能支持的核銷(xiāo)方式，選擇合適的券面碼型，并在創(chuàng)建卡券填入code_type字段。

舉例：若A商戶選了二維碼類(lèi)型的卡券，則A商戶的核銷(xiāo)員在核銷(xiāo)時(shí)可以通過(guò)手機(jī)商戶助手掃碼核銷(xiāo)卡券；若B商戶選擇了僅code類(lèi)型的

碼型，則其核銷(xiāo)員就只能通過(guò)輸入串號(hào)的方式核銷(xiāo)卡券。

2.2.4 記錄用戶領(lǐng)券行為

記錄用戶領(lǐng)券行為有多種方式：

1. 用戶領(lǐng)取卡券后會(huì)推送事件通知開(kāi)發(fā)者，領(lǐng)取卡券事件中包含卡券ID、Code碼、領(lǐng)取人OpenID、轉(zhuǎn)贈(zèng)人OpenID?？ㄈ缓虽N(xiāo)時(shí)同樣會(huì)推送事件，詳情見(jiàn)卡券事件通知。

2. 調(diào)用查詢Code接口獲取該Code碼的狀態(tài)（是否被領(lǐng)取、核銷(xiāo)、刪除），若Code碼被用戶領(lǐng)取且處于有效狀態(tài)，可獲取領(lǐng)券人OpenID。

3. 從卡券詳情頁(yè)跳轉(zhuǎn)外部鏈接時(shí)，微信后臺(tái)會(huì)自動(dòng)帶上卡券ID、Code碼等信息，詳情見(jiàn)跳轉(zhuǎn)外鏈帶參數(shù)說(shuō)明。

4. 在卡券投放接口中加入場(chǎng)景字段outer_str，該字段值會(huì)在用戶領(lǐng)取時(shí)伴隨事件通知商戶。

例如：創(chuàng)建二維碼接口時(shí)設(shè)置outer_str為1，添加卡券JS-SDK時(shí)設(shè)置為2，則可通過(guò)對(duì)領(lǐng)取事件的分析得出兩個(gè)不同投放渠道帶來(lái)的領(lǐng)券效果，及時(shí)調(diào)整投放策略。

2.2.5 活用自定義入口

為滿足商戶功能擴(kuò)展的需求，新增可自定義兩個(gè)卡券內(nèi)的入口，支持跳轉(zhuǎn)到商戶自定義的HTML5網(wǎng)頁(yè)。 

三個(gè)自定義入口基于不同的場(chǎng)景定位設(shè)置，區(qū)別如下：

不同入口示例：

2.3 步驟一：上傳卡券圖片素材

  為了保證商戶的卡券在用戶的微信內(nèi)能快速、穩(wěn)定地加載出圖片素材，我們強(qiáng)烈建議開(kāi)發(fā)者將商戶的卡券素材先調(diào)用接口導(dǎo)入微信

CDN。

2.3.1 上傳圖片接口

開(kāi)發(fā)者需調(diào)用該接口上傳商戶圖標(biāo)至微信服務(wù)器，獲取相應(yīng)logo_url/icon_list/image_url，用于卡券創(chuàng)建。

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

1.上傳的圖片限制文件大小限制1MB，僅支持JPG、PNG格式。

2.調(diào)用接口獲取圖片url僅支持在微信相關(guān)業(yè)務(wù)下使用。

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

HTTP請(qǐng)求方式: POST/FROM
URL:https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN

參數(shù)說(shuō)明

請(qǐng)求數(shù)據(jù)

調(diào)用示例（使用curl命令，用FORM表單方式上傳一個(gè)圖片）：
curl –F
buffer=@test.jpg

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

返回正確的示例：
{"url":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0"}

返回錯(cuò)誤的示例
{"errcode":40009,"errmsg":"invalid image size"}

   參數(shù)說(shuō)明

2.4 步驟二：設(shè)置卡券適用門(mén)店

請(qǐng)點(diǎn)擊查看微信門(mén)店接口文檔，獲取門(mén)店 ID 后填入創(chuàng)建卡券接口中的相應(yīng)字段 location_id_list，即可設(shè)置該卡券的適用門(mén)店。

2.5 步驟三：選取卡券背景顏色

選擇適用色值，在步驟四：創(chuàng)建卡券中將顏色名（如Color010）填入color字段。

目前微信提供包括以上十種色值的共計(jì)十四種色值供開(kāi)發(fā)者使用。

2.6 步驟四：創(chuàng)建卡券

創(chuàng)建卡券接口是微信卡券的基礎(chǔ)接口，用于創(chuàng)建一類(lèi)新的卡券，獲取card_id，創(chuàng)建成功并通過(guò)審核后，商家可以通過(guò)文檔提供的其他接口將卡券下發(fā)給用戶，每次成功領(lǐng)取，庫(kù)存數(shù)量相應(yīng)扣除。

開(kāi)發(fā)者須知

1.需自定義Code碼的商家必須在創(chuàng)建卡券時(shí)候，設(shè)定use_custom_code為true，且在調(diào)用投放卡券接口時(shí)填入指定的Code碼。指定OpenID同理。特別注意：在公眾平臺(tái)創(chuàng)建的卡券均為非自定義Code類(lèi)型。

2.can_share字段指領(lǐng)取卡券原生頁(yè)面是否可分享，建議指定Code碼、指定OpenID等強(qiáng)限制條件的卡券填寫(xiě)false。

3.特別注意：編碼方式僅支持使用UTF-8，否則會(huì)報(bào)錯(cuò)。

4.創(chuàng)建成功后該卡券會(huì)自動(dòng)提交審核，審核結(jié)果將通過(guò)事件通知商戶。開(kāi)發(fā)者可調(diào)用設(shè)置白名單接口設(shè)置用戶白名單，領(lǐng)取未通過(guò)審核的卡券，測(cè)試整個(gè)卡券的使用流程。

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

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

參數(shù)說(shuō)明

POST數(shù)據(jù)示例

{
  "card": {
      "card_type": "GROUPON",
      "groupon": {
          "base_info": {
              "logo_url":  "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
              "brand_name": "微信餐廳",
              "code_type": "CODE_TYPE_TEXT",
              "title": "132元雙人火鍋套餐",
              "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_TIME_RANGE",
                  "begin_timestamp": 1397577600,
                  "end_timestamp": 1472724261
              },
              "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
              ],
              "center_title": "頂部居中按鈕",
              "center_sub_title": "按鈕下方的wording",
              "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",
              "source": "大眾點(diǎn)評(píng)"
          },
           "advanced_info": {
               "use_condition": {
                   "accept_category": "鞋類(lèi)",
                   "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)養(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"
               ]
           },
          "deal_detail": "以下鍋底2選1（有菌王鍋、麻辣鍋、大骨鍋、番茄鍋、清補(bǔ) 涼鍋、酸菜魚(yú)鍋可選）：\n大鍋1份 12元\n小鍋2份 16元 "
      }
  }
}

字段示圖 

團(tuán)購(gòu)券

JSON示例

{
 "card": {
     "card_type": "GROUPON",
     "groupon": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "deal_detail": "示例"
     }
 }
}

代金券

JSON示例

{
 "card": {
     "card_type": "CASH",
     "cash": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "least_cost": 1000,
         "reduce_cost": 100,
     }
 }
}

折扣券

JSON示例：

{
 "card": {
     "card_type": "DISCOUNT",
     "discount": {
         "base_info": {
         ················
         },
          "advanced_info": {
         ················
          },
         "discount": 30
     }
   }
}

兌換券

JSON示例

{
"card": {
    "card_type": "GIFT",
    "gift": {
        "base_info": {
        ················
        },
         "advanced_info": {
        ················
         },
        "gift":"可兌換音樂(lè)木盒一個(gè)"
    }
  }
}

優(yōu)惠券

JSON示例

{
"card": {
    "card_type": "GENERAL_COUPON",
    "general_coupon": {
        "base_info": {
        ················
        },
         "advanced_info": {
        ················
         },
        "default_detail":"優(yōu)惠券專(zhuān)用，填寫(xiě)優(yōu)惠詳情"
    }
  }
}

2.7 卡券基礎(chǔ)信息字段（重要）

  base_info（卡券基礎(chǔ)信息）字段-必填字段

 base_info（卡券基礎(chǔ)信息）字段-非必填字段

Advanced_info（卡券高級(jí)信息）字段

注意事項(xiàng)：

1.高級(jí)字段為商戶額外展示信息字段，非必填,但是填入某些結(jié)構(gòu)體后，須填充完整方可顯示：如填入text_image_list結(jié)構(gòu)體

時(shí)，須同時(shí)傳入image_url和text，否則也會(huì)報(bào)錯(cuò)；
2.填入時(shí)間限制字段（time_limit）,只控制顯示，不控制實(shí)際使用邏輯，不填默認(rèn)不顯示

3.創(chuàng)建卡券時(shí)，開(kāi)發(fā)者填入的時(shí)間戳須注意時(shí)間戳溢出時(shí)間，設(shè)置的時(shí)間戳須早于2038年1月19日

4.預(yù)存code模式的卡券須設(shè)置quantity為0，導(dǎo)入code后方可增加庫(kù)存

返回說(shuō)明

數(shù)據(jù)示例：

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

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

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

注意事項(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

3 設(shè)置快速買(mǎi)單

功能介紹

微信卡券買(mǎi)單功能是微信卡券的一項(xiàng)新的能力，可以方便消費(fèi)者買(mǎi)單時(shí)，直接錄入消費(fèi)金額，自動(dòng)使用領(lǐng)到的優(yōu)惠（券或卡）抵扣，并拉起微信支付快速完成付款。

微信買(mǎi)單（以下統(tǒng)稱微信買(mǎi)單）的好處：

1、無(wú)需商戶具備微信支付開(kāi)發(fā)能力，即可完成訂單生成，與微信支付打通。

2、可以通過(guò)手機(jī)公眾號(hào)、電腦商戶后臺(tái)，輕松操作收款并查看核銷(xiāo)記錄，交易對(duì)賬，并支持離線下載。

3、支持會(huì)員營(yíng)銷(xiāo)，二次營(yíng)銷(xiāo)，如會(huì)員卡交易送積分，抵扣積分，買(mǎi)單后贈(zèng)券等。

開(kāi)通指引

步驟一：申請(qǐng)開(kāi)通內(nèi)測(cè)白名單權(quán)限后，開(kāi)發(fā)者可以登錄微信公眾平臺(tái)mp.weixin.qq.com，進(jìn)入【卡券功能】-【卡券概況】，點(diǎn)擊查看資料和權(quán)限

步驟二：在高級(jí)權(quán)限區(qū)，有標(biāo)注微信買(mǎi)單的權(quán)限狀態(tài)，商戶先需要開(kāi)通微信支付，并為收款門(mén)店配置核銷(xiāo)員，才能激活申請(qǐng)權(quán)限。未獲得權(quán)限時(shí)，點(diǎn)擊“申請(qǐng)“，開(kāi)通買(mǎi)單權(quán)限

步驟三：為收款門(mén)店配置收款員“或直接點(diǎn)擊”卡券核銷(xiāo)“，可前往添加門(mén)店核銷(xiāo)員，便于后續(xù)接收結(jié)算通知。

3.1 設(shè)置買(mǎi)單接口

買(mǎi)單接口說(shuō)明

創(chuàng)建卡券之后，開(kāi)發(fā)者可以通過(guò)設(shè)置微信買(mǎi)單接口設(shè)置該card_id支持微信買(mǎi)單功能。值得開(kāi)發(fā)者注意的是，設(shè)置買(mǎi)單的card_id必須已經(jīng)配置了門(mén)店，否則會(huì)報(bào)錯(cuò)。

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

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

參數(shù)說(shuō)明

POST數(shù)據(jù)

{
  “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“,
  “is_open”: true
}

字段說(shuō)明

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

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

字段說(shuō)明

注意事項(xiàng)：

1.設(shè)置快速買(mǎi)單的卡券須支持至少一家有核銷(xiāo)員門(mén)店，否則無(wú)法設(shè)置成功；

2.若該卡券設(shè)置了center_url（居中使用跳轉(zhuǎn)鏈接）,須先將該設(shè)置更新為空后再設(shè)置自快速買(mǎi)單方可生效。

3.2 買(mǎi)單事件推送

微信買(mǎi)單完成時(shí)，微信會(huì)把這個(gè)事件推送到開(kāi)發(fā)者填寫(xiě)的URL。 推送XML數(shù)據(jù)包示例：

<xml>
<ToUserName><![CDATA[gh_e2243xxxxxxx]]></ToUserName>
<FromUserName><![CDATA[oo2VNuOUuZGMxxxxxxxx]]></FromUserName>
<CreateTime>1442390947</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[user_pay_from_pay_cell]]></Event>
<CardId><![CDATA[po2VNuCuRo-8sxxxxxxxxxxx]]></CardId>
<UserCardCode><![CDATA[38050000000]]></UserCardCode>
<TransId><![CDATA[10022403432015000000000]]></TransId>
<LocationId>291710000</LocationId>
<Fee><![CDATA[10000]]></Fee>
<OriginalFee><![CDATA[10000]]> </OriginalFee>
</xml>

4 設(shè)置自助核銷(xiāo)

功能介紹

自助核銷(xiāo)與掃碼/輸碼核銷(xiāo)互為補(bǔ)充，卡券商戶助手通過(guò)掃碼/輸碼完成核銷(xiāo)的同時(shí)，也確保了用券的真實(shí)性，適合有強(qiáng)對(duì)賬需求的商戶使用；而自助核銷(xiāo)由用戶發(fā)起，全程由用戶操作，適合對(duì)賬需求不強(qiáng)的商戶使用。

目前，自助核銷(xiāo)可能適合以下場(chǎng)景使用：

1.不允許店員上班期間帶手機(jī)；

2.高峰期店內(nèi)人流量大，掃碼/輸碼核銷(xiāo)速度不能滿足短時(shí)需求；

3.會(huì)議入場(chǎng)，短時(shí)有大量核銷(xiāo)任務(wù)；

4.1 設(shè)置自助核銷(xiāo)接口

接口說(shuō)明

創(chuàng)建卡券之后，開(kāi)發(fā)者可以通過(guò)設(shè)置微信買(mǎi)單接口設(shè)置該card_id支持自助核銷(xiāo)功能。值得開(kāi)發(fā)者注意的是，設(shè)置自助核銷(xiāo)的card_id必須已經(jīng)配置了門(mén)店，否則會(huì)報(bào)錯(cuò)。

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

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

參數(shù)說(shuō)明

POST數(shù)據(jù)

{
  “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“,
  “is_open”: true
}

字段說(shuō)明

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

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

字段說(shuō)明

注意事項(xiàng)：

1.設(shè)置自助核銷(xiāo)的卡券須支持至少一家門(mén)店，否則無(wú)法設(shè)置成功；

2.若該卡券設(shè)置了center_url（居中使用跳轉(zhuǎn)鏈接）,須先將該設(shè)置更新為空后再設(shè)置自助核銷(xiāo)功能方可生效。

5 接口調(diào)試工具

開(kāi)發(fā)者可以通過(guò)卡券創(chuàng)建接口在線調(diào)試工具進(jìn)行卡券創(chuàng)建HelloWorld。獲取到access_token后，開(kāi)發(fā)者可以將要POST的JSON數(shù)據(jù)貼至接口調(diào)試工具中，獲得Card_id以進(jìn)行下一步投放動(dòng)作。