C#開發微信門戶及應用(36)--微信卡劵管理的封裝操做

時間 2019-11-29

標籤 c# 開發微信門戶應用管理封裝欄目 C# 简体版

原文原文鏈接

前面幾篇介紹了微信支付方面的內容，本篇繼續微信接口的一些其餘方面的內容：卡劵管理。卡劵管理是微信接口裏面很是複雜的一個部分，裏面的接口很是多，我花了很多時間對它進行了封裝處理，重構優化等等工做，卡劵在營銷方面是一個比較好的途徑，能夠應用在會員管理、店鋪促銷等方面的活動，不過萬層高樓從底起，咱們須要把卡劵管理的相關接口夯實完善，才能在它的基礎上進行更進一步的應用操做。html

一、微信卡券接口說明

微信卡券功能是騰訊爲商戶提供的一套完整的電子卡券解決方案，商戶可在法律容許的範圍內經過該功能實現電子卡券生成、下發、領取、覈銷的閉環，並使用對帳、卡券管理等配套功能。微信卡券功能可分爲API接口功能和公衆平臺卡券功能，使用兩種功能都可實現卡券生成、下發、領取、覈銷，有開發意願的商戶可以使用API接口功能，無開發意願商戶可以使用公衆平臺卡券功能。api

微信公衆平臺本次增長了微信卡券功能，開放接口供商家使用。支持開發者調用接口建立多種類型的卡券，經過下發消息、二維碼、JS-SDK等方式進行投放，在用戶使用時經過API接口或卡券商戶助手完成核銷。同時支持接口獲取統計數據，以及各個環節給予開發者事件推送。服務器

目前支持優惠券（代金券、折扣券、禮品券、團購券）、會員卡、景點門票、電影票、飛機票、紅包、會議門票等多種卡券類型。開發者能夠經過卡券接口快速完成制券、發券及銷券流程：微信

一、建立卡券接口 開發者可經過該接口，建立卡券，導入/拉取卡券適用門店、獲取卡券顏色列表。微信公衆平臺

二、卡券投放接口 開發者可經過該接口，生成卡券領取二維碼，也可在網頁內調用JavaScript接口，引導用戶領取卡券。ide

三、卡券覈銷接口函數

調用覈銷接口可對指定卡券進行覈銷。支持網頁內調用JavaScript接口拉取卡券列表，用戶選擇卡券後便可完成核銷。post

四、卡券管理接口 開發者可經過該接口，對已建立的卡券進行查詢、刪除、更改、設置失效等操做。同時，在卡券經過審覈、卡券被領取、卡券被刪除時，均會推送事件通知開發者。測試

五、特殊卡票接口 支持特殊卡票券（會員卡、電影票、飛機票、紅包、會議門票）的適用場景，提供相應的接口能力，包括激活/綁定會員卡、會員卡交易、更新電影票、在線選座、更新紅包餘額、更新會議門票等接口。微信支付

六、設置測試用戶白名單 開發者可設置測試用戶白名單，不管卡券是否經過審覈都可領取卡券，測試整個卡券的使用流程。

爲了瞭解這個卡劵的複雜性，咱們先來看看它的官方的卡劵內容流程圖

這個圖裏面涉及的內容不少，一樣卡劵管理的API接口也不少，不過咱們老是但願化繁爲簡，所以咱們能夠一步步來了解整個卡劵的內容。

二、卡劵的事件通知

卡劵的相關事件，會由微信後臺通知咱們的服務後臺，所以咱們能夠對卡劵的建立、使用等各個方面都有相關的事件通知，咱們在對應的事件上實現咱們的卡劵管理邏輯也是很方便的。

下面列出卡劵管理裏面的後臺消息通知分類。

這些消息對應的事件，咱們能夠放到請求的事件類型裏面，這樣咱們在統一調用事件的時候，就能夠對他們進行區分了。

這樣咱們在微信消息處理的入口，就能夠分別對這些事件進行處理了。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;

三、卡劵的分類及建立操做

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。

四、建立卡劵的類定義和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#開發微信門戶及應用(36)--微信卡劵管理的封裝操做

C#開發微信門戶及應用(35)--微信支付之企業付款封裝操做

C#開發微信門戶及應用(34)--微信裂變紅包

C#開發微信門戶及應用(33)--微信現金紅包的封裝及使用

C#開發微信門戶及應用(32)--微信支付接入和API封裝使用

C#開發微信門戶及應用(31)--微信語義理解接口的實現和處理

C#開發微信門戶及應用(30)--消息的羣發處理和預覽功能

C#開發微信門戶及應用(28)--微信「搖一搖·周邊」功能的使用和接口的實現

C#開發微信門戶及應用(27)-公衆號模板消息管理

C#開發微信門戶及應用(26)-公衆號微信素材管理

C#開發微信門戶及應用(25)-微信企業號的客戶端管理功能