微信平臺會員卡專區(qū)（一）

會員卡升級公告

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

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

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

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

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

-運(yùn)營策略調(diào)整：會員卡新增開放類目限制，自4月20日起，僅限會員卡類目內(nèi)的商戶新建會員卡，原有會員卡不受影響，詳情請見：《會員卡公告》

更新日志

1.新版會員卡介紹

    -(a)增加自定義背景，開發(fā)者可以設(shè)置;

    -(b)卡券消息升級，積分/余額變動通過模板消息自動發(fā)送，可攜帶營銷信息。

     （a）

2.須知

閱讀該部分之前請先閱讀《微信公眾平臺開發(fā)概述》、《開始開發(fā)》以及《微信卡券接口說明》，確保你能了解公眾平臺和卡券接口的基本術(shù)語和調(diào)用方法。

一般地，會員卡的接口調(diào)用順序可參考以下流程：

3.會員卡玩法介紹

               門店掃碼方案                                                會員卡快速買單                                    會員卡與CRM打通

          會員卡與支付系統(tǒng)打通                                            老會員綁定

4.創(chuàng)建會員卡接口詳情

4.1 創(chuàng)建會員卡接口

    支持開發(fā)者調(diào)用該接口創(chuàng)建會員卡，并獲取card_id，用于投放。調(diào)用該接口前，請開發(fā)者詳讀《創(chuàng)建卡券接口》，快速錄入會員卡卡面必要信息。

接口調(diào)用請求說明

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

參數(shù)說明

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

{
    "card": {
        "card_type": "MEMBER_CARD",
        "member_card": {
            "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/",
            "base_info": {
                "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZ/0",
                "brand_name": "海底撈",
                "code_type": "CODE_TYPE_TEXT",
                "title": "海底撈會員卡",
                "color": "Color010",
                "notice": "使用時(shí)向服務(wù)員出示此券",
                "service_phone": "020-88888888",
                "description": "不可與其他優(yōu)惠同享",
                "date_info": {
                    "type": "DATE_TYPE_PERMANENT"
                },
                "sku": {
                    "quantity": 50000000
                },
                "get_limit": 3,
                "use_custom_code": false,
                "can_give_friend": true,
                "location_id_list": [
                    123,
                    12321
                ],
                "custom_url_name": "立即使用",
                "custom_url": "http://weixin.qq.com",
                "custom_url_sub_title": "6個(gè)漢字tips",
                "promotion_url_name": "營銷入口1",
                "promotion_url": "http://www.qq.com",
                "need_push_on_view": true
            },
            "supply_bonus": true,
            "supply_balance": false,
            "prerogative": "test_prerogative",
            "auto_activate": true,
            "custom_field1": {
                "name_type": "FIELD_NAME_TYPE_LEVEL",
                "url": "http://www.qq.com"
            },
            "activate_url": "http://www.qq.com",
            "custom_cell1": {
                "name": "使用入口2",
                "tips": "激活后顯示",
                "url": "http://www.xxx.com"
            },
            "bonus_rule": {
                "cost_money_unit": 100,
                "increase_bonus": 1,
                "max_increase_bonus": 200,
                "init_increase_bonus": 10,
                "cost_bonus_unit": 5,
                "reduce_money": 100,
                "least_money_to_use_bonus": 1000,
                "max_reduce_bonus": 50
            },
            "discount": 10
        }
    }
}

接口字段對應(yīng)表

參數(shù)說明

base_info字段：

返回說明

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

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

1. 僅部分類目可創(chuàng)建會員卡，非開放類目將返回錯(cuò)誤碼，類目明細(xì)見會員卡公告

2.創(chuàng)建會員卡時(shí)，需設(shè)置會員卡激活后呈現(xiàn)的信息類目，目前支持積分、余額、等級、優(yōu)惠券、里程、印花、成就、折扣等類型，微信6.2以上版本顯示會員信息類目的上限為3個(gè)，即創(chuàng)建時(shí)類目字段supply_bonus 、supply_balance、 custom_field1、custom_field2 、custom_field3最多選擇三項(xiàng)填寫。

3.創(chuàng)建卡券時(shí)，開發(fā)者填入的時(shí)間戳須注意時(shí)間戳溢出時(shí)間，設(shè)置的時(shí)間戳須早于2038年1月19日，若要設(shè)置更久的有效期，可以選擇永久有效類型的有效期。

4.2 獲取會員卡審核結(jié)果

    調(diào)用接口成功創(chuàng)建會員卡后，會由系統(tǒng)自動提交審核，審核結(jié)果將在三個(gè)工作日內(nèi)以事件形式告知開發(fā)者，同時(shí)支持調(diào)用接口主動查詢卡券狀態(tài)。

審核事件推送

    生成的卡券通過審核時(shí)，微信會把這個(gè)事件推送到開發(fā)者填寫的URL，詳情見：審核事件推送，會員卡審核通過后可以正式投放會員卡。

  4.3 設(shè)置測試白名單接口

     若會員卡暫時(shí)未審核通，開發(fā)者可以將測試人員的微信號設(shè)置成白名單，領(lǐng)取未審核通過的卡券。白名單狀態(tài)領(lǐng)取的卡信息不隨卡券實(shí)時(shí)更新，請開發(fā)者注意。

5  投放會員卡接口詳情

    目前微信會員卡支持通過掃描二維碼、在網(wǎng)頁直接點(diǎn)擊（參考JS-SDK網(wǎng)頁接口）、卡券貨架、公眾號群發(fā)以及公眾號被動回復(fù)消息領(lǐng)取，開發(fā)者可以選擇一種或者多種。請參考以下各種投放方式詳情。

特別注意

1. 開發(fā)者調(diào)用接口投放的會員卡為無會員信息的“卡套”，會員卡編號、積分、余額等信息需在用戶領(lǐng)取會員卡后調(diào)用激活/綁定會員卡接口更新上。

2. 調(diào)用激活/綁定會員卡接口的憑證為Code碼及card_id，開發(fā)者需在調(diào)用投放會員卡時(shí)通過接口或領(lǐng)取卡券事件記錄code碼與會員OpenID的關(guān)系。

5.1 創(chuàng)建二維碼接口

    創(chuàng)建會員卡二維碼，打印后置于店內(nèi)，顧客掃碼領(lǐng)取會員卡，掃描下方二維碼體驗(yàn)領(lǐng)取，若已領(lǐng)取可掃碼快速打開會員卡。接口詳情見：創(chuàng)建二維碼接口

5.2 網(wǎng)頁內(nèi)單張/批量添加卡券接口

    微信提供addCard接口供商戶前端網(wǎng)頁調(diào)用,用于將一張或多張卡券添加到用戶卡包。詳情見批量添加卡券接口

 （微信掃一掃>微信卡券接口>addcard接口）

5.3 通過卡券貨架投放會員卡

卡券貨架簡介

    卡券貨架支持開發(fā)者通過調(diào)用接口生成一個(gè)卡券領(lǐng)取H5頁面，并獲取頁面鏈接，進(jìn)行卡券投放動作。

5.4 公眾號消息投放會員卡

    開發(fā)者也可以通過公眾號群發(fā)消息或者客服消息為用戶發(fā)送一張會員卡。

5.5 記錄用戶領(lǐng)卡行為

    用戶領(lǐng)取會員卡后，微信會給開發(fā)者服務(wù)器推送領(lǐng)取會員卡事件通知，以便開發(fā)者記錄用戶OpenID與會員卡code的關(guān)聯(lián)關(guān)系，并可以通過事件內(nèi)的參數(shù)區(qū)分領(lǐng)取渠道（見1.5）。

5.6 統(tǒng)計(jì)投放渠道數(shù)據(jù)

    為方便開發(fā)者統(tǒng)計(jì)各渠道的卡券投放數(shù)據(jù)，新增字段outer_id。將不同設(shè)值的outer_id填入card_ext的JSON結(jié)構(gòu)中，當(dāng)用戶領(lǐng)取卡券時(shí)會將相應(yīng)設(shè)值的outer_id帶入領(lǐng)取事件推送中，推送至開發(fā)者服務(wù)器。

示例： 在二維碼投放方式中設(shè)置outer_id為1

{
    "action_name": "QR_CARD",
    "action_info": {
        "card": {
            "card_id": "pFS7Fjg8kV1IdDz01r4SQwMkuCKc",
            "code": "198374613512",
            "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA",
            "expire_seconds": 1800,
            "is_unique_code": false,
            "outer_id": 1
        }
    }
}

領(lǐng)取事件XML文件

<xml> 
  <ToUserName><![CDATA[toUser]]></ToUserName>  
  <FromUserName><![CDATA[FromUser]]></FromUserName>  
  <FriendUserName><![CDATA[FriendUser]]></FriendUserName>  
  <CreateTime>123456789</CreateTime>  
  <MsgType><![CDATA[event]]></MsgType>  
  <Event><![CDATA[user_get_card]]></Event>  
  <CardId><![CDATA[cardid]]></CardId>  
  <IsGiveByFriend>1</IsGiveByFriend>  
  <UserCardCode><![CDATA[12312312]]></UserCardCode>  
  <OuterId>1</OuterId>
</xml>

6 激活會員卡

    當(dāng)用戶領(lǐng)取會員卡“卡套”后，支持調(diào)用該接口對會員卡進(jìn)行激活，并設(shè)置會員信息的初始值，如積分、余額、等級、會員卡編號等會員信息。目前，微信會員卡支持三種激活方式，分別是接口激活、一鍵激活和自動激活。

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

1.開發(fā)者可以根據(jù)業(yè)務(wù)場景需要選擇合適的激活流程。三種激活流方法只能選擇一種；

2.激活會員卡需傳入用戶領(lǐng)取時(shí)獲取的Code碼，將該Code碼對應(yīng)設(shè)置會員卡編號membership_number。

6.1 接口激活

激活方式說明

    接口激活通常需要開發(fā)者開發(fā)用戶填寫資料的網(wǎng)頁。通常有兩種激活流程：

   1. 用戶必須在填寫資料后才能領(lǐng)卡，領(lǐng)卡后開發(fā)者調(diào)用激活接口為用戶激活會員卡；

  2. 是用戶可以先領(lǐng)取會員卡，點(diǎn)擊激活會員卡跳轉(zhuǎn)至開發(fā)者設(shè)置的資料填寫頁面，填寫完成后開發(fā)者調(diào)用激活接口為用戶激活會員卡。

接口詳情

接口調(diào)用請求說明

HTTP請求方式: POST
URL:https://api.weixin.qq.com/card/membercard/activate?access_token=TOKEN

參數(shù)說明

{
    "init_bonus": 100,
    "init_balance": 200,
    "membership_number": "AAA00000001",
    "code": "12312313",
    "card_id": "xxxx_card_id",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "init_custom_field_value1": "xxxxx"
}

返回說明

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

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

6.2 一鍵激活 

6.2.1 普通一鍵激活

     一鍵激活是微信提供的快速便捷的激活方案，用戶領(lǐng)取后點(diǎn)擊“激活會員卡”會跳轉(zhuǎn)至官方的資料填寫頁面，微信會自動拉取該用戶之前填寫過的開卡信息，用戶無需重復(fù)填寫， 同時(shí)避免了手機(jī)號驗(yàn)證的過程，從而實(shí)現(xiàn)一鍵激活的目的，提高了開卡率。具體流程如下圖：

步驟一：在創(chuàng)建接口填入wx_activate字段

接口說明

    設(shè)置微信一鍵開卡功能，現(xiàn)支持在創(chuàng)建會員卡時(shí)填入指定字段指定要一鍵激活，member_card中增加"wx_activate": true。 

    若商戶使用了自定義卡號，開發(fā)者可以設(shè)置用戶填寫信息后跳轉(zhuǎn)至商戶的網(wǎng)頁，并由開發(fā)者進(jìn)行激活。

參數(shù)說明

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

{    
"card": {      
 ························     
 ························    
"member_card": {            
"wx_activate": true        
}    
}
}

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

1.填入了自動激活auto_activate字段，激活鏈接activate_url和一鍵開卡接口設(shè)置都會失效；

2.若同時(shí)傳入了activate_url，則一鍵開卡接口設(shè)置會失效；

3.建議開發(fā)者activate_url、auto_activate和wx_activate只填寫一項(xiàng)。

步驟二：設(shè)置開卡字段接口

    開發(fā)者在創(chuàng)建時(shí)填入wx_activate字段后，需要調(diào)用該接口設(shè)置用戶激活時(shí)需要填寫的選項(xiàng)，否則一鍵開卡設(shè)置不生效。

接口調(diào)用請求說明

HTTP請求方式: POST
URL:https://api.weixin.qq.com/card/membercard/activateuserform/set?access_token=TOKEN

參數(shù)說明

{
    "card_id": "pbLatjnrwUUdZI641gKdTMJzHGfc",
    "service_statement": {
        "name": "會員守則",
        "url": "www.qq.com"
    },
    "bind_old_card": {
        "name": "老會員綁定",
        "url": "www.weixin.qq.com"
    },
    "required_form": {
        "can_modify"：false,
        "rich_field_list": [
            {
                "type": "FORM_FIELD_RADIO",
                "name": "興趣",
                "values": [
                    "鋼琴",
                    "舞蹈",
                    "足球"
                ]
            },
            {
                "type": "FORM_FIELD_SELECT",
                "name": "喜好",
                "values": [
                    "郭敬明",
                    "韓寒",
                    "南派三叔"
                ]
            },
            {
                "type": "FORM_FIELD_CHECK_BOX",
                "name": "職業(yè)",
                "values": [
                    "賽車手",
                    "旅行家"
                ]
            }
        ],
        "common_field_id_list": [
            "USER_FORM_INFO_FLAG_MOBILE"
        ]
    },
    "optional_form": {
        "can_modify"：false,
        "common_field_id_list": [
            "USER_FORM_INFO_FLAG_LOCATION",
            "USER_FORM_INFO_FLAG_BIRTHDAY"
        ],
        "custom_field_list": [
            "喜歡的電影"
        ]
    }
}

common_field_id_list，支持開發(fā)者使用以下選項(xiàng)類型

步驟三：接收會員信息事件通知

    用戶填寫、提交資料后，會有事件推送給商家，開發(fā)者可以在接收到事件通知后調(diào)用激活接口，傳入會員卡號、初始積分等信息或者調(diào)用拉取會員信息接口獲取會員信息，進(jìn)行會員管理。

推送XML數(shù)據(jù)包示例

<xml> 
  <ToUserName> <![CDATA[gh_3fcea188bf78]]></ToUserName>  
  <FromUserName><![CDATA[obLatjlaNQKb8FqOvt1M1x1lIBFE]]></FromUserName>  
  <CreateTime>1432668700</CreateTime>  
  <MsgType><![CDATA[event]]></MsgType>  
  <Event><![CDATA[submit_membercard_user_info]]></Event>  
  <CardId><![CDATA[pbLatjtZ7v1BG_ZnTjbW85GYc_E8]]></CardId>  
  <UserCardCode><![CDATA[018255396048]]></UserCardCode> 
</xml>

參數(shù)說明

步驟四：同步會員數(shù)據(jù)

    開發(fā)者可以在接收到事件通知后調(diào)用激活接口，傳入會員卡號、初始積分等信息或者調(diào)用拉取會員信息接口獲取會員信息。

步驟五：拉取會員信息接口

接口說明

    支持開發(fā)者根據(jù)CardID和Code查詢會員信息。

接口調(diào)用請求說明

HTTP請求方式: POST
URL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

{   "card_id": "pbLatjtZ7v1BG_ZnTjbW85GYc_E8",   "code": "916679873278"}

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

{
    "errcode": 0,
    "errmsg": "ok",
    "openid": "obLatjjwDolFj******wNqRXw",
    "nickname": "*******",
    "membership_number": "658*****445",
    "bonus": 995,
    "sex": "MALE",
    "user_info": {
        "common_field_list": [
            {
                "name": "USER_FORM_INFO_FLAG_MOBILE",
                "value": "15*****518"
            },
            {
                "name": "USER_FORM_INFO_FLAG_NAME",
                "value": "HK"
            },
            {
                "name": "USER_FORM_INFO_FLAG_EDUCATION_BACKGROUND",
                "value": "研究生"
            }
        ],
        "custom_field_list": []
    },
    "user_card_status": "NORMAL",
    "has_active": false
}

6.2.2 跳轉(zhuǎn)型一鍵激活

    跳轉(zhuǎn)型一鍵激活支持用戶在提交會員開卡資料后跳轉(zhuǎn)至商戶自定義的網(wǎng)頁。不同于普通一鍵激活，跳轉(zhuǎn)型一鍵激活的激活會員卡動作由商戶完成，商戶可以在跳轉(zhuǎn)到的網(wǎng)頁內(nèi)做激活、激活獎勵(lì)、開卡條件判斷等邏輯，同時(shí)也保證了開卡的實(shí)時(shí)性，適合使用自定義卡號的商戶使用。

    步驟一：在創(chuàng)建/更新接口填入跳轉(zhuǎn)型一鍵激活相關(guān)字段

  若商戶設(shè)置用戶激活后跳轉(zhuǎn)自己的網(wǎng)頁，需要在創(chuàng)建或更新接口傳入以下參數(shù)。

{   
 "card": {        
 "member_card": {    
 ························     
 ························   
 "wx_activate": true,
 "wx_activate_after_submit" : true,   //是否設(shè)置跳轉(zhuǎn)型一鍵激活
 "wx_activate_after_submit_url" : "http://qq.com"      //用戶提交信息后跳轉(zhuǎn)的網(wǎng)頁
 }   
 }
 }

       步驟二：設(shè)置開卡字段接口

       步驟三：獲取用戶提交資料

       用戶填寫并提交開卡資料后，會跳轉(zhuǎn)到商戶的網(wǎng)頁，商戶可以在網(wǎng)頁內(nèi)獲取用戶已填寫的信息并進(jìn)行開卡資質(zhì)判斷，信息確認(rèn)等動作。

具體方式如下：

       用戶點(diǎn)擊提交后，微信會在商戶的url后面拼接獲取用戶填寫信息的參數(shù)：activate_ticket、openid、card_id和加密code-encrypt_code,如商戶填寫的wx_activate_after_submit_url為 www.qq.com,則拼接后的url為www.qq.com&card_id=pbLatjvFdsLDUMoN8JqcsGeiMHKk&encrypt_code=Bupk8bb9xxxxxx3rdXV6fClBVtkHQplYohdzGvgDl4%3D&outer_str=&openid=obLatjjwDxxxxxxxoGIdwNqRXw&activate_ticket=fDZv9eMQAFfrNr3XBoqhb%2F%2BMSDM0yjDF6CdiUhC%2BOlEaxb0clsUxxxxxxxxxxxd6yQsjRMRu4kAcKTibYLN5tmHBdll1b6zQRsLF53MpKjGU%3D。

      開發(fā)者可以根據(jù)activate_ticket獲取到用戶填寫的信息，用于開發(fā)者頁面的邏輯判斷。

    接口說明

    支持開發(fā)者根據(jù)activate_ticket獲取到用戶填寫的信息。

接口調(diào)用請求說明

HTTP請求方式: POST
URL:https://api.weixin.qq.com/card/membercard/activatetempinfo/get?access_token=TOKEN

參數(shù)說明

POST數(shù)據(jù)

 {
    "activate_ticket" : "abcdefg"
}

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

  {
    "errcode": 0,
    "errmsg": "ok",
    "info": {
        "common_field_list": [
            {
                "name": "USER_FORM_INFO_FLAG_MOBILE",
                "value": "15*****518"
            },
            {
                "name": "USER_FORM_INFO_FLAG_NAME",
                "value": "HK"
            },
            {
                "name": "USER_FORM_INFO_FLAG_EDUCATION_BACKGROUND",
                "value": "研究生"
            }
        ],
        "custom_field_list": []
    }
}  

    步驟四：調(diào)用接口激活會員卡

    開發(fā)者可以在接收到事件通知后調(diào)用激活接口，傳入會員卡號、初始積分等信息或者調(diào)用拉取會員信息接口獲取會員信息。

6.3 自動激活

接口說明

    設(shè)置會員卡自動激活功能，需在創(chuàng)建會員卡時(shí)填入指定字段，base_info中增加"auto_activate": true，獲取card_id。 

    值得注意的是，傳入自動激活字段auto_activate之后，一鍵開卡設(shè)置和接口激活設(shè)置的激活url均不再顯示，用戶領(lǐng)取卡片之后，系統(tǒng)自動幫用戶激活，積分、儲值等自定義顯示信息均為0，開發(fā)者可以通過更新會員信息接口更新用戶會員數(shù)據(jù)。

參數(shù)說明

7 更新會員信息

    當(dāng)會員持卡消費(fèi)后，支持開發(fā)者調(diào)用該接口更新會員信息。會員卡交易后的每次信息變更需通過該接口通知微信，便于后續(xù)消息通知及其他擴(kuò)展功能。

接口調(diào)用請求說明

HTTP請求方式: POST
URL:https://api.weixin.qq.com/card/membercard/updateuser?access_token=TOKEN

參數(shù)說明

{
    "code": "12312313",
    "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "record_bonus": "消費(fèi)30元，獲得3積分",
    "bonus": 3000,
    //可以傳入第三方系統(tǒng)記錄的積分全量值"balance": 3000,
    //可以傳入第三方系統(tǒng)記錄的余額全量值"record_balance": "購買焦糖瑪琪朵一杯，扣除金額30元。",
    "custom_field_value1": "xxxxx"，
    "notify_optional": {
        "is_notify_bonus": false,
        "is_notify_balance": true,
        "is_notify_custom_field1":true
    }
}

    值得注意的是，如果開發(fā)者做不到實(shí)時(shí)同步積分、余額至微信端，我們強(qiáng)烈建議開發(fā)者可以在每天的固定時(shí)間點(diǎn)變更積分，一天不超過三次。當(dāng)傳入的積分值與之前無變化時(shí)（傳入的bonus=原來的bonus），不會有積分變動通知。

參數(shù)說明：

返回說明

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

{
    "errcode": 0,
    "errmsg": "ok",
    "result_bonus": 100,
    "result_balance": 200,
    "openid": "oFS7Fjl0WsZ9AMZqrI80nbIq8xrA"
}