C#開發(fā)微信門戶及應(yīng)用(36)--微信卡劵管理的封裝操作
2021-07-25 20:32:27

前面幾篇介紹了微信支付方面的內(nèi)容，本篇繼續(xù)微信接口的一些其他方面的內(nèi)容：卡劵管理?？▌还芾硎俏⑿沤涌诶锩娣浅?fù)雜的一個(gè)部分，里面的接口非常多，我花了不少時(shí)間對(duì)它進(jìn)行了封裝處理，重構(gòu)優(yōu)化等等工作，卡劵在營(yíng)銷方面是一個(gè)比較好的途徑，可以應(yīng)用在會(huì)員管理、店鋪促銷等方面的活動(dòng)，不過(guò)萬(wàn)層高樓從底起，我們需要把卡劵管理的相關(guān)接口夯實(shí)完善，才能在它的基礎(chǔ)上進(jìn)行更進(jìn)一步的應(yīng)用操作。

1、微信卡券接口說(shuō)明

微信卡券功能是騰訊為商戶提供的一套完整的電子卡券解決方案，商戶可在法律允許的范圍內(nèi)通過(guò)該功能實(shí)現(xiàn)電子卡券生成、下發(fā)、領(lǐng)取、核銷的閉環(huán)，并使用對(duì)賬、卡券管理等配套功能。微信卡券功能可分為API接口功能和公眾平臺(tái)卡券功能，使用兩種功能均可實(shí)現(xiàn)卡券生成、下發(fā)、領(lǐng)取、核銷，有開發(fā)意愿的商戶可使用API接口功能，無(wú)開發(fā)意愿商戶可使用公眾平臺(tái)卡券功能。

微信公眾平臺(tái)本次增加了微信卡券功能，開放接口供商家使用。 支持開發(fā)者調(diào)用接口創(chuàng)建多種類型的卡券，通過(guò)下發(fā)消息、二維碼、JS-SDK等方式進(jìn)行投放，在用戶使用時(shí)通過(guò)API接口或卡券商戶助手完成核銷。 同時(shí)支持接口獲取統(tǒng)計(jì)數(shù)據(jù)，以及各個(gè)環(huán)節(jié)給予開發(fā)者事件推送。?

目前支持優(yōu)惠券（代金券、折扣券、禮品券、團(tuán)購(gòu)券）、會(huì)員卡、景點(diǎn)門票、電影票、飛機(jī)票、紅包、會(huì)議門票等多種卡券類型。 開發(fā)者可以通過(guò)卡券接口快速完成制券、發(fā)券及銷券流程：

1、創(chuàng)建卡券接口?開發(fā)者可通過(guò)該接口，創(chuàng)建卡券，導(dǎo)入/拉取卡券適用門店、獲取卡券顏色列表。

2、卡券投放接口?開發(fā)者可通過(guò)該接口，生成卡券領(lǐng)取二維碼，也可在網(wǎng)頁(yè)內(nèi)調(diào)用JavaScript接口，引導(dǎo)用戶領(lǐng)取卡券。

3、卡券核銷接口

調(diào)用核銷接口可對(duì)指定卡券進(jìn)行核銷。支持網(wǎng)頁(yè)內(nèi)調(diào)用JavaScript接口拉取卡券列表，用戶選擇卡券后即可完成核銷。

4、卡券管理接口?開發(fā)者可通過(guò)該接口，對(duì)已創(chuàng)建的卡券進(jìn)行查詢、刪除、更改、設(shè)置失效等操作。同時(shí)，在卡券通過(guò)審核、卡券被領(lǐng)取、卡券被刪除時(shí)，均會(huì)推送事件通知開發(fā)者。

5、特殊卡票接口?支持特殊卡票券（會(huì)員卡、電影票、飛機(jī)票、紅包、會(huì)議門票）的適用場(chǎng)景，提供相應(yīng)的接口能力，包括激活/綁定會(huì)員卡、會(huì)員卡交易、更新電影票、在線選座、更新紅包余額、更新會(huì)議門票等接口。

6、設(shè)置測(cè)試用戶白名單?開發(fā)者可設(shè)置測(cè)試用戶白名單，無(wú)論卡券是否通過(guò)審核均可領(lǐng)取卡券，測(cè)試整個(gè)卡券的使用流程。

為了了解這個(gè)卡劵的復(fù)雜性，我們先來(lái)看看它的官方的卡劵內(nèi)容流程圖

這個(gè)圖里面涉及的內(nèi)容很多，同樣卡劵管理的API接口也很多，不過(guò)我們總是希望化繁為簡(jiǎn)，因此我們可以一步步來(lái)了解整個(gè)卡劵的內(nèi)容。

?

2、卡劵的事件通知

卡劵的相關(guān)事件，會(huì)由微信后臺(tái)通知我們的服務(wù)后臺(tái)，因此我們可以對(duì)卡劵的創(chuàng)建、使用等各個(gè)方面都有相關(guān)的事件通知，我們?cè)趯?duì)應(yīng)的事件上實(shí)現(xiàn)我們的卡劵管理邏輯也是很方便的。

下面列出卡劵管理里面的后臺(tái)消息通知分類。

這些消息對(duì)應(yīng)的事件，我們可以放到請(qǐng)求的事件類型里面，這樣我們?cè)诮y(tǒng)一調(diào)用事件的時(shí)候，就可以對(duì)他們進(jìn)行區(qū)分了。

?

這樣我們?cè)谖⑿畔⑻幚淼娜肟?，就可以分別對(duì)這些事件進(jìn)行處理了。WeixinApiDispatch就是一個(gè)分發(fā)的管理類，它提取請(qǐng)求消息的內(nèi)容，并構(gòu)建不同類型的消息參數(shù)，傳遞給不同的響應(yīng)函數(shù)進(jìn)行處理，然后返回封裝好的XML內(nèi)容，作為響應(yīng)。

具體的代碼處理邏輯如下圖所示。

這樣我們?cè)诖a里面就可以對(duì)相應(yīng)個(gè)事件進(jìn)行處理了。

其中我們注意到，我們對(duì)卡劵的不同事件，把它們的事件信息對(duì)象化后進(jìn)行相應(yīng)的處理的，如下代碼所示。

                            case RequestEvent.card_pass_check:      //卡劵通過(guò)審核
                            case RequestEvent.card_not_pass_check:  //卡劵未通過(guò)審核
                                {
                                    // 卡券通過(guò)審核(或?qū)徍瞬煌ㄟ^(guò))
                                    RequestEventCardCheck info = XmlConvertor.XmlToObject<RequestEventCardCheck>(postStr);
                                    if (info != null)
                                    {
                                    }
                                    LogTextHelper.Info(eventName + ((info == null) ? "info is null" : info.ToJson()));
                                }
                                break;

?

3、卡劵的分類及創(chuàng)建操作

1）卡劵分類

前面介紹了，微信卡劵目前支持優(yōu)惠券（代金券、折扣券、禮品券、團(tuán)購(gòu)券）、會(huì)員卡、景點(diǎn)門票、電影票、飛機(jī)票、紅包、會(huì)議門票等多種卡券類型。我們?cè)谖⑿藕笈_(tái)，可以手工創(chuàng)建優(yōu)惠卷，如下圖所示。

由于各個(gè)卡劵之間的數(shù)據(jù)有相同的部分，也有部分的部分，我們需要在類的層面上對(duì)他們進(jìn)行不同的信息建模。

我們?cè)賮?lái)定義一個(gè)卡劵類型的枚舉，方便我們?cè)诖a中使用，這個(gè)枚舉對(duì)象也包含了我們前面介紹到的那些卡劵類型了。

    /// <summary>
    /// 卡券類型
    /// </summary>
    public enum CardType
    {
        /// <summary>
        /// 折扣券
        /// </summary>
        DISCOUNT = 0,
        /// <summary>
        /// 代金券
        /// </summary>
        CASH = 1,
        /// <summary>
        /// 禮品劵、兌換券
        /// </summary>
        GIFT = 2,
        /// <summary>
        /// 優(yōu)惠券/通用券
        /// </summary>
        GENERAL_COUPON = 3,
        /// <summary>
        /// 團(tuán)購(gòu)券
        /// </summary>
        GROUPON = 4,

        /// <summary>
        /// 會(huì)員卡
        /// </summary>
        MEMBER_CARD = 5,
        /// <summary>
        /// 門票
        /// </summary>
        SCENIC_TICKET = 6,
        /// <summary>
        /// 電影票
        /// </summary>
        MOVIE_TICKET = 7,
        /// <summary>
        /// 飛機(jī)票
        /// </summary>
        BOARDING_PASS = 8,
        /// <summary>
        /// 紅包
        /// </summary>
        LUCKY_MONEY = 9,
        /// <summary>
        /// 會(huì)議門票
        /// </summary>
        MEETING_TICKET = 10,
        /// <summary>
        /// 汽車票
        /// </summary>
        BUS_TICKET,
    }

由于不同類型卡劵的信息不同，因此我們需要封閉創(chuàng)建這些對(duì)應(yīng)的卡劵類，以方便構(gòu)建對(duì)應(yīng)的信息用于創(chuàng)建操作。

?

2）創(chuàng)建卡券

創(chuàng)建卡券的接口調(diào)用順序

其中上傳圖片，就是采用通用的圖片上傳接口上傳即可，上傳后獲得對(duì)應(yīng)的圖片URL地址。

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

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

優(yōu)惠劵的背景色，在微信里面有一些參考色樣，如下圖所示。

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

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

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

?

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

?

?

?

幾種不同類型的卡劵，他們POST的JSON對(duì)象信息都是不太一樣的，如團(tuán)購(gòu)劵的實(shí)體信息如下所示。

?

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

?

?

?

?

?

?

?

?

團(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,
     }
 }
}

當(dāng)前其他幾種類型個(gè)卡劵也各有不同，不在一一贅述，可以看到每種卡劵攜帶的信息，有部分一樣，有部分不同，但是它們創(chuàng)建卡劵的時(shí)候，使用的是同一個(gè)接口，這種接口方式在卡劵接口里面很常見(jiàn)。

其中卡劵里面的base_info（卡券基礎(chǔ)信息）字段-必填字段、base_info（卡券基礎(chǔ)信息）字段-非必填字段、Advanced_info（卡券高級(jí)信息）字段比較復(fù)雜，具體請(qǐng)參考相關(guān)的字段說(shuō)明列表。

?

創(chuàng)建卡劵的返回說(shuō)明

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

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

?

?

?

?

?

4、創(chuàng)建卡劵的類定義和API封裝

根據(jù)這些信息，我們創(chuàng)建卡劵的時(shí)候，我們可以定義不同的信息實(shí)體，如下所示是卡劵基類和折扣劵的類定義信息。

    /// <summary>
    /// 卡劵基類信息
    /// </summary>
    public class CardJson
    {
        /// <summary>
        /// 基礎(chǔ)信息
        /// </summary>
        public CardBaseInfo base_info { get; set; }

        /// <summary>
        /// 高級(jí)字段
        /// </summary>
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public CardAdvanceInfo advanced_info{ get; set; }
    }

    /// <summary>
    /// 折扣券數(shù)據(jù)
    /// </summary>
    public class DisCountCardJson : CardJson
    {
        /// <summary>
        /// 折扣券專用，表示打折額度（百分比）。填30就是七折。
        /// </summary>
        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
        public int discount { get; set; }
    }

其他卡劵的信息也是類似，根據(jù)需要擴(kuò)展即可，如會(huì)員卡的信息，我們可以按照上面的繼承關(guān)系進(jìn)行字段的補(bǔ)充即可。

    /// <summary>
    /// 會(huì)員卡的詳細(xì)信息，是CardDetailJson的子類
    /// </summary>
    public class MemberCardJson : CardJson
    {
        /// <summary>
        /// 顯示積分，填寫true或false，如填寫true，積分相關(guān)字段均為必填。
        /// </summary>
        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
        public bool supply_bonus { get; set; }

        /// <summary>
        /// 是否支持儲(chǔ)值，填寫true或false。如填寫true，儲(chǔ)值相關(guān)字段均為必填。
        /// </summary>
        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
        public bool supply_balance { get; set; }

        /// <summary>
        /// 特權(quán)說(shuō)明
        /// 非必填
        /// </summary>
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string prerogative { get; set; }

        /// <summary>
        /// 設(shè)置為true時(shí)用戶領(lǐng)取會(huì)員卡后系統(tǒng)自動(dòng)將其激活，無(wú)需調(diào)用激活接口
        /// </summary>
        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
        public bool auto_activate { get; set; }

        /// <summary>
        /// 設(shè)置為true時(shí)會(huì)員卡支持一鍵激活，不允許同時(shí)傳入activate_url字段，否則設(shè)置wx_activate失效。
        /// 非必填
        /// </summary>
        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
        public bool wx_activate { get; set; }

        ..........

還有其他類型的數(shù)據(jù)，如會(huì)議卡劵，電影卡劵信息等類庫(kù)也一樣處理，其他的依照此規(guī)則擴(kuò)展即可。

    /// <summary>
    /// 會(huì)議門票數(shù)據(jù)
    /// </summary>
    public class MettingTicketJson : CardJson
    {
        /// <summary>
        /// 會(huì)議詳情
        /// </summary>
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string meeting_detail { get; set; }

        /// <summary>
        /// 會(huì)場(chǎng)導(dǎo)覽圖
        /// </summary>
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string map_url { get; set; }
    }
           
    /// <summary>
    /// 門票數(shù)據(jù)
    /// </summary>
    public class ScenicTicketJson : CardJson
    {
        /// <summary>
        /// 票類型，例如平日全票，套票等
        /// 非必填
        /// </summary>
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string ticket_class { get; set; }
        /// <summary>
        /// 導(dǎo)覽圖url
        /// 非必填
        /// </summary>
        [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
        public string guide_url { get; set; }
    }

有了這些信息，我們就可以通過(guò)統(tǒng)一的接口函數(shù)進(jìn)行卡劵的創(chuàng)建操作了。

在實(shí)現(xiàn)函數(shù)的最后，我們就是調(diào)用接口的URL，提交對(duì)應(yīng)的數(shù)據(jù)就可以了

            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;

?

如果對(duì)這個(gè)《C#開發(fā)微信門戶及應(yīng)用》系列感興趣，可以關(guān)注我的其他文章，系列隨筆如下所示：

C#開發(fā)微信門戶及應(yīng)用(36)--微信卡劵管理的封裝操作

C#開發(fā)微信門戶及應(yīng)用(35)--微信支付之企業(yè)付款封裝操作

C#開發(fā)微信門戶及應(yīng)用(34)--微信裂變紅包

C#開發(fā)微信門戶及應(yīng)用(33)--微信現(xiàn)金紅包的封裝及使用

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

C#開發(fā)微信門戶及應(yīng)用(31)--微信語(yǔ)義理解接口的實(shí)現(xiàn)和處理

C#開發(fā)微信門戶及應(yīng)用(30)--消息的群發(fā)處理和預(yù)覽功能

C#開發(fā)微信門戶及應(yīng)用(28)--微信“搖一搖·周邊”功能的使用和接口的實(shí)現(xiàn)

C#開發(fā)微信門戶及應(yīng)用(27)-公眾號(hào)模板消息管理?

C#開發(fā)微信門戶及應(yīng)用(26)-公眾號(hào)微信素材管理

C#開發(fā)微信門戶及應(yīng)用(25)-微信企業(yè)號(hào)的客戶端管理功能

C#開發(fā)微信門戶及應(yīng)用(24)-微信小店貨架信息管理

C#開發(fā)微信門戶及應(yīng)用(23)-微信小店商品管理接口的封裝和測(cè)試

C#開發(fā)微信門戶及應(yīng)用(22)-微信小店的開發(fā)和使用

C#開發(fā)微信門戶及應(yīng)用(21)-微信企業(yè)號(hào)的消息和事件的接收處理及解密?

C#開發(fā)微信門戶及應(yīng)用(20)-微信企業(yè)號(hào)的菜單管理

C#開發(fā)微信門戶及應(yīng)用(19)-微信企業(yè)號(hào)的消息發(fā)送（文本、圖片、文件、語(yǔ)音、視頻、圖文消息等）

C#開發(fā)微信門戶及應(yīng)用(18)-微信企業(yè)號(hào)的通訊錄管理開發(fā)之成員管理

C#開發(fā)微信門戶及應(yīng)用(17)-微信企業(yè)號(hào)的通訊錄管理開發(fā)之部門管理

C#開發(fā)微信門戶及應(yīng)用(16)-微信企業(yè)號(hào)的配置和使用

C#開發(fā)微信門戶及應(yīng)用(15)-微信菜單增加掃一掃、發(fā)圖片、發(fā)地理位置功能

C#開發(fā)微信門戶及應(yīng)用(14)-在微信菜單中采用重定向獲取用戶數(shù)據(jù)

C#開發(fā)微信門戶及應(yīng)用(13)-使用地理位置擴(kuò)展相關(guān)應(yīng)用

C#開發(fā)微信門戶及應(yīng)用(12)-使用語(yǔ)音處理

C#開發(fā)微信門戶及應(yīng)用(11)--微信菜單的多種表現(xiàn)方式介紹

C#開發(fā)微信門戶及應(yīng)用(10)--在管理系統(tǒng)中同步微信用戶分組信息

C#開發(fā)微信門戶及應(yīng)用(9)-微信門戶菜單管理及提交到微信服務(wù)器

C#開發(fā)微信門戶及應(yīng)用(8)-微信門戶應(yīng)用管理系統(tǒng)功能介紹

C#開發(fā)微信門戶及應(yīng)用(7)-微信多客服功能及開發(fā)集成

C#開發(fā)微信門戶及應(yīng)用(6)--微信門戶菜單的管理操作

C#開發(fā)微信門戶及應(yīng)用(5)--用戶分組信息管理

C#開發(fā)微信門戶及應(yīng)用(4)--關(guān)注用戶列表及詳細(xì)信息管理

C#開發(fā)微信門戶及應(yīng)用(3)--文本消息和圖文消息的應(yīng)答

C#開發(fā)微信門戶及應(yīng)用(2)--微信消息的處理和應(yīng)答

C#開發(fā)微信門戶及應(yīng)用(1)--開始使用微信接口

?