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

前面幾篇介紹了微信支付方面的內(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)取、核銷，有開(kāi)發(fā)意愿的商戶可使用API接口功能，無(wú)開(kāi)發(fā)意愿商戶可使用公眾平臺(tái)卡券功能。
微信公眾平臺(tái)本次增加了微信卡券功能，開(kāi)放接口供商家使用。 支持開(kā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é)給予開(kāi)發(fā)者事件推送。
目前支持優(yōu)惠券（代金券、折扣券、禮品券、團(tuán)購(gòu)券）、會(huì)員卡、景點(diǎn)門票、電影票、飛機(jī)票、紅包、會(huì)議門票等多種卡券類型。 開(kāi)發(fā)者可以通過(guò)卡券接口快速完成制券、發(fā)券及銷券流程：
1、創(chuàng)建卡券接口 開(kāi)發(fā)者可通過(guò)該接口，創(chuàng)建卡券，導(dǎo)入/拉取卡券適用門店、獲取卡券顏色列表。
2、卡券投放接口 開(kāi)發(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、卡券管理接口 開(kāi)發(fā)者可通過(guò)該接口，對(duì)已創(chuàng)建的卡券進(jìn)行查詢、刪除、更改、設(shè)置失效等操作。同時(shí)，在卡券通過(guò)審核、卡券被領(lǐng)取、卡券被刪除時(shí)，均會(huì)推送事件通知開(kāi)發(fā)者。
5、特殊卡票接口 支持特殊卡票券（會(huì)員卡、電影票、飛機(jī)票、紅包、會(huì)議門票）的適用場(chǎng)景，提供相應(yīng)的接口能力，包括激活/綁定會(huì)員卡、會(huì)員卡交易、更新電影票、在線選座、更新紅包余額、更新會(huì)議門票等接口。
6、設(shè)置測(cè)試用戶白名單 開(kāi)發(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ō)明


團(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#開(kāi)發(fā)微信門戶及應(yīng)用》系列感興趣，可以關(guān)注我的其他文章.

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容