前面幾篇介紹了微信支付方面的內容，本篇繼續微信接口的一些其他方面的內容：卡劵管理。卡劵管理是微信接口里面非常復雜的一個部分，里面的接口非常多，我花了不少時間對它進行了封裝處理，重構優化等等工作，卡劵在營銷方面是一個比較好的途徑，可以應用在會員管理、店鋪促銷等方面的活動，不過萬層高樓從底起，我們需要把卡劵管理的相關接口夯實完善，才能在它的基礎上進行更進一步的應用操作。
1、微信卡券接口說明
微信卡券功能是騰訊為商戶提供的一套完整的電子卡券解決方案，商戶可在法律允許的范圍內通過該功能實現電子卡券生成、下發、領取、核銷的閉環，並使用對賬、卡券管理等配套功能。微信卡券功能可分為API接口功能和公眾平台卡券功能，使用兩種功能均可實現卡券生成、下發、領取、核銷，有開發意願的商戶可使用API接口功能，無開發意願商戶可使用公眾平台卡券功能。
微信公眾平台本次增加了微信卡券功能，開放接口供商家使用。 支持開發者調用接口創建多種類型的卡券，通過下發消息、二維碼、JS-SDK等方式進行投放，在用戶使用時通過API接口或卡券商戶助手完成核銷。 同時支持接口獲取統計數據，以及各個環節給予開發者事件推送。
目前支持優惠券（代金券、折扣券、禮品券、團購券）、會員卡、景點門票、電影票、飛機票、紅包、會議門票等多種卡券類型。 開發者可以通過卡券接口快速完成制券、發券及銷券流程：
1、創建卡券接口 開發者可通過該接口，創建卡券，導入/拉取卡券適用門店、獲取卡券顏色列表。
2、卡券投放接口 開發者可通過該接口，生成卡券領取二維碼，也可在網頁內調用JavaScript接口，引導用戶領取卡券。
3、卡券核銷接口
調用核銷接口可對指定卡券進行核銷。支持網頁內調用JavaScript接口拉取卡券列表，用戶選擇卡券后即可完成核銷。
4、卡券管理接口 開發者可通過該接口，對已創建的卡券進行查詢、刪除、更改、設置失效等操作。同時，在卡券通過審核、卡券被領取、卡券被刪除時，均會推送事件通知開發者。
5、特殊卡票接口 支持特殊卡票券（會員卡、電影票、飛機票、紅包、會議門票）的適用場景，提供相應的接口能力，包括激活/綁定會員卡、會員卡交易、更新電影票、在線選座、更新紅包余額、更新會議門票等接口。
6、設置測試用戶白名單 開發者可設置測試用戶白名單，無論卡券是否通過審核均可領取卡券，測試整個卡券的使用流程。
為了了解這個卡劵的復雜性，我們先來看看它的官方的卡劵內容流程圖
這個圖里面涉及的內容很多，同樣卡劵管理的API接口也很多，不過我們總是希望化繁為簡，因此我們可以一步步來了解整個卡劵的內容。
2、卡劵的事件通知
卡劵的相關事件，會由微信后台通知我們的服務后台，因此我們可以對卡劵的創建、使用等各個方面都有相關的事件通知，我們在對應的事件上實現我們的卡劵管理邏輯也是很方便的。
下面列出卡劵管理里面的后台消息通知分類。
這些消息對應的事件，我們可以放到請求的事件類型里面，這樣我們在統一調用事件的時候，就可以對他們進行區分了。
這樣我們在微信消息處理的入口，就可以分別對這些事件進行處理了。WeixinApiDispatch就是一個分發的管理類，它提取請求消息的內容，並構建不同類型的消息參數，傳遞給不同的響應函數進行處理，然后返回封裝好的XML內容，作為響應。
具體的代碼處理邏輯如下圖所示。
這樣我們在代碼里面就可以對相應個事件進行處理了。
其中我們注意到，我們對卡劵的不同事件，把它們的事件信息對象化后進行相應的處理的，如下代碼所示。
case RequestEvent.card_pass_check: //卡劵通過審核 case RequestEvent.card_not_pass_check: //卡劵未通過審核 { // 卡券通過審核(或審核不通過) RequestEventCardCheck info = XmlConvertor.XmlToObject<RequestEventCardCheck>(postStr); if (info != null) { } LogTextHelper.Info(eventName + ((info == null) ? "info is null" : info.ToJson())); } break;
3、卡劵的分類及創建操作
1）卡劵分類
前面介紹了，微信卡劵目前支持優惠券（代金券、折扣券、禮品券、團購券）、會員卡、景點門票、電影票、飛機票、紅包、會議門票等多種卡券類型。我們在微信后台，可以手工創建優惠卷，如下圖所示。
由於各個卡劵之間的數據有相同的部分，也有部分的部分，我們需要在類的層面上對他們進行不同的信息建模。
我們再來定義一個卡劵類型的枚舉，方便我們在代碼中使用，這個枚舉對象也包含了我們前面介紹到的那些卡劵類型了。
/// <summary> /// 卡券類型 /// </summary> public enum CardType { /// <summary> /// 折扣券 /// </summary> DISCOUNT = 0, /// <summary> /// 代金券 /// </summary> CASH = 1, /// <summary> /// 禮品劵、兌換券 /// </summary> GIFT = 2, /// <summary> /// 優惠券/通用券 /// </summary> GENERAL_COUPON = 3, /// <summary> /// 團購券 /// </summary> GROUPON = 4, /// <summary> /// 會員卡 /// </summary> MEMBER_CARD = 5, /// <summary> /// 門票 /// </summary> SCENIC_TICKET = 6, /// <summary> /// 電影票 /// </summary> MOVIE_TICKET = 7, /// <summary> /// 飛機票 /// </summary> BOARDING_PASS = 8, /// <summary> /// 紅包 /// </summary> LUCKY_MONEY = 9, /// <summary> /// 會議門票 /// </summary> MEETING_TICKET = 10, /// <summary> /// 汽車票 /// </summary> BUS_TICKET, }
由於不同類型卡劵的信息不同，因此我們需要封閉創建這些對應的卡劵類，以方便構建對應的信息用於創建操作。
2）創建卡券
創建卡券的接口調用順序
其中上傳圖片，就是采用通用的圖片上傳接口上傳即可，上傳后獲得對應的圖片URL地址。
上傳圖片接口調用請求說明
HTTP請求方式: POST/FROM
URL:https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
優惠劵的背景色，在微信里面有一些參考色樣，如下圖所示。
創建卡券接口是微信卡券的基礎接口，用於創建一類新的卡券，獲取card_id，創建成功並通過審核后，商家可以通過文檔提供的其他接口將卡券下發給用戶，每次成功領取，庫存數量相應扣除。
接口調用請求說明
HTTP請求方式: POST
URL: https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN
參數說明
| 參數 | 是否必須 | 說明 |
|---|---|---|
| access_token | 是 | 調用接口憑證 |
| POST數據 | 是 | Json數據 |
幾種不同類型的卡劵，他們POST的JSON對象信息都是不太一樣的，如團購劵的實體信息如下所示。
團購券
| 參數名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| card_type | 是 | string(24) | GROUPON | 團購券類型。 |
| base_info | 是 | JSON結構 | 見上述示例。 | 基本的卡券數據，見下表，所有卡券類型通用。 |
| deal_detail | 是 | string(3072) | 雙人套餐\n -進口紅酒一支。\n孜然牛肉一份。 | 團購券專用，團購詳情。 |
團購劵JSON示例
{ "card": { "card_type": "GROUPON", "groupon": { "base_info": { ················ }, "advanced_info": { ················ }, "deal_detail": "示例" } } }
而代金券提交的信息如下所示。
代金券
| 參數名 | 必填 | 類型 | 示例值 | 描述 |
|---|---|---|---|---|
| card_type | 是 | string(24) | CASH | 代金券類型。 |
| base_info | 是 | JSON結構 | 見上述示例。 | 基本的卡券數據，見下表，所有卡券通用。 |
| least_cost | 是 | int | 10000 | 代金券專用，表示起用金額（單位為分）,如果無起用門檻則填0。 |
| reduce_cost | 是 | int | 10000 | 代金券專用，表示減免金額。（單位為分） |
代金券JSON示例
{ "card": { "card_type": "CASH", "cash": { "base_info": { ················ }, "advanced_info": { ················ }, "least_cost": 1000, "reduce_cost": 100, } } }
當前其他幾種類型個卡劵也各有不同，不在一一贅述，可以看到每種卡劵攜帶的信息，有部分一樣，有部分不同，但是它們創建卡劵的時候，使用的是同一個接口，這種接口方式在卡劵接口里面很常見。
其中卡劵里面的base_info（卡券基礎信息）字段-必填字段、base_info（卡券基礎信息）字段-非必填字段、Advanced_info（卡券高級信息）字段比較復雜，具體請參考相關的字段說明列表。
創建卡劵的返回說明
數據示例：
{ "errcode":0, "errmsg":"ok", "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI" }
| 參數名 | 描述 |
|---|---|
| errcode | 錯誤碼，0為正常。 |
| errmsg | 錯誤信息。 |
| card_id | 卡券ID。 |
4、創建卡劵的類定義和API封裝
根據這些信息，我們創建卡劵的時候，我們可以定義不同的信息實體，如下所示是卡劵基類和折扣劵的類定義信息。
/// <summary> /// 卡劵基類信息 /// </summary> public class CardJson { /// <summary> /// 基礎信息 /// </summary> public CardBaseInfo base_info { get; set; } /// <summary> /// 高級字段 /// </summary> [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public CardAdvanceInfo advanced_info{ get; set; } } /// <summary> /// 折扣券數據 /// </summary> public class DisCountCardJson : CardJson { /// <summary> /// 折扣券專用，表示打折額度（百分比）。填30就是七折。 /// </summary> [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public int discount { get; set; } }
其他卡劵的信息也是類似，根據需要擴展即可，如會員卡的信息，我們可以按照上面的繼承關系進行字段的補充即可。
/// <summary> /// 會員卡的詳細信息，是CardDetailJson的子類 /// </summary> public class MemberCardJson : CardJson { /// <summary> /// 顯示積分，填寫true或false，如填寫true，積分相關字段均為必填。 /// </summary> [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool supply_bonus { get; set; } /// <summary> /// 是否支持儲值，填寫true或false。如填寫true，儲值相關字段均為必填。 /// </summary> [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool supply_balance { get; set; } /// <summary> /// 特權說明 /// 非必填 /// </summary> [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string prerogative { get; set; } /// <summary> /// 設置為true時用戶領取會員卡后系統自動將其激活，無需調用激活接口 /// </summary> [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool auto_activate { get; set; } /// <summary> /// 設置為true時會員卡支持一鍵激活，不允許同時傳入activate_url字段，否則設置wx_activate失效。 /// 非必填 /// </summary> [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)] public bool wx_activate { get; set; } ..........
還有其他類型的數據，如會議卡劵，電影卡劵信息等類庫也一樣處理，其他的依照此規則擴展即可。
/// <summary> /// 會議門票數據 /// </summary> public class MettingTicketJson : CardJson { /// <summary> /// 會議詳情 /// </summary> [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string meeting_detail { get; set; } /// <summary> /// 會場導覽圖 /// </summary> [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string map_url { get; set; } } /// <summary> /// 門票數據 /// </summary> public class ScenicTicketJson : CardJson { /// <summary> /// 票類型，例如平日全票，套票等 /// 非必填 /// </summary> [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string ticket_class { get; set; } /// <summary> /// 導覽圖url /// 非必填 /// </summary> [JsonProperty(NullValueHandling = NullValueHandling.Ignore)] public string guide_url { get; set; } }
有了這些信息，我們就可以通過統一的接口函數進行卡劵的創建操作了。
在實現函數的最后，我們就是調用接口的URL，提交對應的數據就可以了
var url = string.Format("https://api.weixin.qq.com/card/create?access_token={0}", accessToken); var result = JsonHelper<CardCreateResultJson>.ConvertJson(url, cardData); return result != null ? result.card_id : null;
如果對這個《C#開發微信門戶及應用》系列感興趣，可以關注我的其他文章，系列隨筆如下所示：
C#開發微信門戶及應用(35)--微信支付之企業付款封裝操作
C#開發微信門戶及應用(32)--微信支付接入和API封裝使用
C#開發微信門戶及應用(31)--微信語義理解接口的實現和處理
C#開發微信門戶及應用(28)--微信“搖一搖·周邊”功能的使用和接口的實現
C#開發微信門戶及應用(23)-微信小店商品管理接口的封裝和測試
C#開發微信門戶及應用(21)-微信企業號的消息和事件的接收處理及解密
C#開發微信門戶及應用(19)-微信企業號的消息發送（文本、圖片、文件、語音、視頻、圖文消息等）
C#開發微信門戶及應用(18)-微信企業號的通訊錄管理開發之成員管理
C#開發微信門戶及應用(17)-微信企業號的通訊錄管理開發之部門管理
C#開發微信門戶及應用(15)-微信菜單增加掃一掃、發圖片、發地理位置功能
C#開發微信門戶及應用(14)-在微信菜單中采用重定向獲取用戶數據
C#開發微信門戶及應用(11)--微信菜單的多種表現方式介紹
C#開發微信門戶及應用(10)--在管理系統中同步微信用戶分組信息
C#開發微信門戶及應用(9)-微信門戶菜單管理及提交到微信服務器