会员卡升级公告

2016年5月15日起，微信卡券团队对会员卡能力进行全面升级。在原有能力基础上进行以下能力升级，旨在帮助商家更好地进行会员管理。

-强化客户端一级入口：会员到店即用，快速定位商户会员卡；

-自定义卡面能力：开发者可以根据会员身份设置不同的卡面背景；

-门店扫码方案：新用户到店扫码领卡，老用户到店扫码快速打开会员卡，实现会员点餐、买单等多种功能

-支付即会员：支持开发者设置微信支付后为用户下发领卡消息，顾客支付即会员，快速拉新；

-运营策略调整：会员卡新增开放类目限制，自4月20日起，仅限会员卡类目内的商户新建会员卡，原有会员卡不受影响，详情请见：《会员卡公告》

更新日志

1.新版会员卡介绍

    -(a)增加自定义背景，开发者可以设置;

    -(b)卡券消息升级，积分/余额变动通过模板消息自动发送，可携带营销信息。

     （a）

微信公众平台开发概述》、《开始开发》以及《微信卡券接口说明》，确保你能了解公众平台和卡券接口的基本术语和调用方法。

一般地，会员卡的接口调用顺序可参考以下流程：

               门店扫码方案                                                会员卡快速买单                                    会员卡与CRM打通

                                  

          会员卡与支付系统打通                                            老会员绑定

创建卡券接口》，快速录入会员卡卡面必要信息。

接口调用请求说明

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

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	JSON数据

POST数据示例：

{
    "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": "使用时向服务员出示此券",
                "service_phone": "020-88888888",
                "description": "不可与其他优惠同享",
                "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个汉字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
        }
    }
}

接口字段对应表

参数说明

参数名	必填	类型	描述
card_type	是	string(24)	会员卡类型。
background_                 pic_url	否	string(128)	商家自定义会员卡背景图，须                 先调用上传图片接口将背景图上传至CDN，否则报错， 卡面设计请遵循微信会员卡自定义背景设计规范  ,像素大小控制在 1000像素*600像素以下
base_info	是	JSON结构	基本的卡券数据，见下表，所有卡券类型通用。
prerogative	是	string（3072）	会员卡特权说明。
auto_activate	否	bool	设置为true时用户领取会员卡后系统自动将其激活，无需调用激活接口。
wx_activate	否	bool	设置为true时会员卡支持一键开卡，不允许同时传入activate_url字段，否则设置wx_activate失效。填入该字段后仍需调用接口设置开卡项方可生效。
supply_bonus	是	bool	显示积分，填写true或false，如填写true，积分相关字段均为必填。
bonus_url	否	string(128)	设置跳转外链查看积分详情。仅适用于积分无法通过激活接口同步的情况下使用该字段。
supply_balance	是	bool	是否支持储值，填写true或false。如填写true，储值相关字段均为必填。
balance_url	否	string(128)	设置跳转外链查看余额详情。仅适用于余额无法通过激活接口同步的情况下使用该字段。
custom_field1	否	JSON结构	自定义会员信息类目，会员卡激活后显示,包含name_type和url字段
custom_field2	否	JSON结构	自定义会员信息类目，会员卡激活后显示，包含name_type和url字段
custom_field3	否	JSON结构	自定义会员信息类目，会员卡激活后显示，包含name_type和url字段
name_type	否	string(24)	会员信息类目名称。 FIELD_NAME_TYPE_LEVEL              等级 FIELD_NAME_TYPE_COUPON        优惠券                 FIELD_NAME_TYPE_STAMP            印花 FIELD_NAME_TYPE_DISCOUNT      折扣 FIELD_NAME_TYPE_ACHIEVEMEN  成就 FIELD_NAME_TYPE_MILEAGE          里程
url	否	string（128）	点击类目跳转外链url
bonus_cleared	否	string（128）	积分清零规则。
bonus_rules	否	string（128）	积分规则。
balance_rules	否	string（128）	储值说明。
activate_url	是	string（128）	激活会员卡的url。
custom_cell1	否	JSON结构	自定义会员信息类目，会员卡激活后显示。
name	是	string（15）	入口名称。
tips	是	string（18）	入口右侧提示语，6个汉字内。
url	是	string（128）	入口跳转链接。
bonus_rule	否	JSON结构	积分规则。用于微信买单功能。
cost_money_unit	否	int	消费金额。以分为单位。
increase_bonus	否	int	对应增加的积分。
max_increase_bonus	否	int	用户单次可获取的积分上限。
init_increase_bonus	否	int	初始设置积分。
cost_bonus_unit	否	int	每使用5积分。
reduce_money	否	int	抵扣xx元，（这里以分为单位）
least_money_to_use_bonus	否	int	抵扣条件，满xx元（这里以分为单位）可用。
max_reduce_bonus	否	int	抵扣条件，单笔最多使用xx积分。
discount	否	int	折扣，该会员卡享受的折扣优惠,填10就是九折。

base_info字段：

参数名	必填	类型	描述
logo_url	是	string(128)	卡券的商户logo，建议像素为300*300。
code_type	是	string(16)	Code展示类型，                 "CODE_TYPE_TEXT"                 文本                 "CODE_TYPE_BARCODE"                 一维码                  "CODE_TYPE_QRCODE"                 二维码                 "CODE_TYPE_ONLY_QRCODE" 仅显示二维码             "CODE_TYPE_ONLY_BARCODE" 仅显示一维码    "CODE_TYPE_NONE"                 不显示任何码型
brand_name	是	string（36）	商户名字,字数上限为12个汉字。
title	是	string（27）	卡券名，字数上限为9个汉字 (建议涵盖卡券属性、服务及金额)。
color	是	string（16）	券颜色。按色彩规范标注填写Color010-Color100
notice	是	string（48）	卡券使用提醒，字数上限为16个汉字。
description	是	string（3072）	卡券使用说明，字数上限为1024个汉字。
sku	是	JSON结构	商品信息。
quantity	是	int	卡券库存的数量，不支持填写0，上限为100000000。
date_info	是	JSON结构	使用日期，有效期的信息。
type	是	string	使用时间的类型 支持固定时长有效类型 固定日期有效类型 永久有效类型(DATE_TYPE_PERMANENT)
begin_timestamp	否	unsigned int	type为DATE_TYPE_FIX_TIME_RANGE时专用， 表示起用时间。从1970年1月1日00:00:00至起用时间的秒数 （东八区时间，单位为秒）
end_timestamp	否	unsigned int	type为DATE_TYPE_FIX_TERM_RANGE时专用，表示结束时间 （东八区时间，单位为秒）
fixed_term	否	int	type为DATE_TYPE_FIX_TERM时专用，表示自领取后多少天内有效，领取后当天有效填写0（单位为天）
fixed_begin_term	否	int	type为DATE_TYPE_FIX_TERM时专用，表示自领取后多少天开始生效。（单位为天）
use_custom_code	否	bool	是否自定义Code码。填写true或false，默认为false 通常自有优惠码系统的开发者选择自定义Code码
bind_openid	否	bool	是否指定用户领取，填写true或false。默认为false
service_phone	否	string（24）	客服电话
location_id_list	否	array	门店位置ID。调用POI门店管理接口获取门店位置ID。
use_all_locations	否	bool	会员卡是否支持全部门店，填写后商户门店更新时会自动同步至卡券
center_title	否	string（18）	卡券中部居中的按钮，仅在卡券激活后且可用状态时显示
center_sub                 _title	否	string（24）	显示在入口下方的提示语，仅在卡券激活后且可用状态时显示
center_url	否	string（128）	顶部居中的url，仅在卡券激活后且可用状态时显示
custom_url                 _name	否	string（15）	自定义跳转外链的入口名字。
custom_url	否	string（128）	自定义跳转的URL。
custom_url_sub_title	否	string（18）	显示在入口右侧的提示语。
promotion_url_name	否	string（15）	营销场景的自定义入口名称。
promotion_url	否	string（128）	入口跳转外链的地址链接。
promotion_url_sub_title	否	string（18）	显示在营销入口右侧的提示语。
get_limit	否	int	每人可领券的数量限制，建议会员卡每人限领一张
can_share	否	bool	卡券领取页面是否可分享，默认为true
can_give_friend	否	bool	卡券是否可转赠,默认为true
need_push_on_view	否	bool	填写true为用户点击进入会员卡时推送事件，默认为false。

返回说明

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

参数名	描述
errcode	错误码，0为正常。
errmsg	错误信息。
card_id	卡券ID。

开发者注意事项

1. 仅部分类目可创建会员卡，非开放类目将返回错误码，类目明细见会员卡公告

2.创建会员卡时，需设置会员卡激活后呈现的信息类目，目前支持积分、余额、等级、优惠券、里程、印花、成就、折扣等类型，微信6.2以上版本显示会员信息类目的上限为3个，即创建时类目字段supply_bonus 、supply_balance、 custom_field1、custom_field2 、custom_field3最多选择三项填写。

3.创建卡券时，开发者填入的时间戳须注意时间戳溢出时间，设置的时间戳须早于2038年1月19日，若要设置更久的有效期，可以选择永久有效类型的有效期。

审核事件推送，会员卡审核通过后可以正式投放会员卡。

 JS-SDK网页接口）、卡券货架、公众号群发以及公众号被动回复消息领取，开发者可以选择一种或者多种。请参考以下各种投放方式详情。

特别注意

1. 开发者调用接口投放的会员卡为无会员信息的“卡套”，会员卡编号、积分、余额等信息需在用户领取会员卡后调用激活/绑定会员卡接口更新上。

2. 调用激活/绑定会员卡接口的凭证为Code码及card_id，开发者需在调用投放会员卡时通过接口或领取卡券事件记录code码与会员OpenID的关系。

创建二维码接口

批量添加卡券接口

  

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

领取事件推送中，推送至开发者服务器。

示例： 在二维码投放方式中设置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
        }
    }
}

领取事件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 激活会员卡

    当用户领取会员卡“卡套”后，支持调用该接口对会员卡进行激活，并设置会员信息的初始值，如积分、余额、等级、会员卡编号等会员信息。目前，微信会员卡支持三种激活方式，分别是接口激活、一键激活和自动激活。

开发者注意事项

1.开发者可以根据业务场景需要选择合适的激活流程。三种激活流方法只能选择一种；

2.激活会员卡需传入用户领取时获取的Code码，将该Code码对应设置会员卡编号membership_number。

6.1 接口激活

激活方式说明

    接口激活通常需要开发者开发用户填写资料的网页。通常有两种激活流程：

   1. 用户必须在填写资料后才能领卡，领卡后开发者调用激活接口为用户激活会员卡；

  2. 是用户可以先领取会员卡，点击激活会员卡跳转至开发者设置的资料填写页面，填写完成后开发者调用激活接口为用户激活会员卡。

接口详情

接口调用请求说明

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

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	JSON数据

{
    "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"
}

参数名	必填	类型	描述
membership_number	是	string(20)	会员卡编号，由开发者填入，作为序列号显示在用户的卡包里。可与Code码保持等值。
code	是	string(20)	创建会员卡时获取的初始code。
card_id	否	string（32）	卡券ID,自定义code卡券必填
background_pic_url	否	string（128）	商家自定义会员卡背景图，须                 先调用上传图片接口将背景图上传至CDN，否则报错， 卡面设计请遵循微信会员卡自定义背景设计规范
activate_begin_time	否	unsigned int	激活后的有效起始时间。若不填写默认以创建时的 data_info 为准。Unix时间戳格式。
activate_end_time	否	unsigned int	激活后的有效截至时间。若不填写默认以创建时的 data_info 为准。Unix时间戳格式。
init_bonus	否	int	初始积分，不填为0。
init_balance	否	int	初始余额，不填为0。
init_custom_field_value1	否	string（12）	创建时字段custom_field1定义类型的初始值，限制为4个汉字，12字节。
init_custom_field_value2	否	string（12）	创建时字段custom_field2定义类型的初始值，限制为4个汉字，12字节。
init_custom_field_value3	否	string（12）	创建时字段custom_field3定义类型的初始值，限制为4个汉字，12字节。

返回说明

数据示例：

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

参数名	描述
errcode	错误码，0为正常。
errmsg	错误信息。

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。

      开发者可以根据activate_ticket获取到用户填写的信息，用于开发者页面的逻辑判断。

    接口说明

    支持开发者根据activate_ticket获取到用户填写的信息。

接口调用请求说明

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

参数说明

参数	是否必须	说明
POST数据	是	JSON数据
access_token	是	调用接口凭证

POST数据

 {
    "activate_ticket" : "abcdefg"
}

返回数据

  {
    "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": []
    }
}  

    步骤四：调用接口激活会员卡

    开发者可以在接收到事件通知后调用激活接口，传入会员卡号、初始积分等信息或者调用拉取会员信息接口获取会员信息。

6.3 自动激活

接口说明

    设置会员卡自动激活功能，需在创建会员卡时填入指定字段，base_info中增加"auto_activate": true，获取card_id。 

    值得注意的是，传入自动激活字段auto_activate之后，一键开卡设置和接口激活设置的激活url均不再显示，用户领取卡片之后，系统自动帮用户激活，积分、储值等自定义显示信息均为0，开发者可以通过更新会员信息接口更新用户会员数据。

参数说明

参数	是否必须	说明
member_card
auto_activate	否	填写true or false

7 更新会员信息

    当会员持卡消费后，支持开发者调用该接口更新会员信息。会员卡交易后的每次信息变更需通过该接口通知微信，便于后续消息通知及其他扩展功能。

接口调用请求说明

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

参数说明

参数	是否必须	说明
access_token	是	调用接口凭证
POST数据	是	JSON数据

{
    "code": "12312313",
    "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI",
    "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg",
    "record_bonus": "消费30元，获得3积分",
    "bonus": 3000,
    //可以传入第三方系统记录的积分全量值"balance": 3000,
    //可以传入第三方系统记录的余额全量值"record_balance": "购买焦糖玛琪朵一杯，扣除金额30元。",
    "custom_field_value1": "xxxxx"，
    "notify_optional": {
        "is_notify_bonus": false,
        "is_notify_balance": true,
        "is_notify_custom_field1":true
    }
}

    值得注意的是，如果开发者做不到实时同步积分、余额至微信端，我们强烈建议开发者可以在每天的固定时间点变更积分，一天不超过三次。当传入的积分值与之前无变化时（传入的bonus=原来的bonus），不会有积分变动通知。

参数说明：

参数名	必填	类型	示例值	描述
code	是	string(20)	1231123	卡券Code码。
card_id	是	string（32）	p1Pj9jr90_SQ                 RaVqYI239Ka1erkI	卡券ID。
background_pic_url	否	string（128）	https://mmbiz.qlogo.cn/	支持商家激活时针对单个会员卡分配自定义的会员卡背景。
bonus	是	int	100	需要设置的积分全量值，传入的数值会直接显示
record_bonus	否	string(42)	消费30元，获得3积分	商家自定义积分消耗记录，不超过14个汉字。
balance	是	int	100	需要设置的余额全量值，传入的数值会直接显示
record_balance	否	string(42)	购买焦糖玛                 琪朵一杯，扣除金额30元。	商家自定义金额消耗记录，不超过14个汉字。
custom_field_value1	否	string（12）	白金	创建时字段custom_field1定义类型的最新数值，限制为4个汉字，12字节。
custom_field_value2	否	string（12）	8折	创建时字段custom_field2定义类型的最新数值，限制为4个汉字，12字节。
custom_field_value3	否	string（12）	500	创建时字段custom_field3定义类型的最新数值，限制为4个汉字，12字节。
notify_optional	否	JSON	--	控制原生消息结构体，包含各字段的消息控制字段
is_notify_bonus	否	bool	true	积分变动时是否触发系统模板消息，默认为true
is_notify_balance	否	bool	true	余额变动时是否触发系统模板消息，默认为true
is_notify_custom_field1	否	bool	false	自定义group1变动时是否触发系统模板消息，默认为false。（2、3同理）

返回说明

数据示例：

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

参数名	描述
errcode	错误码，0为正常
errmsg	错误信息
result_bonus	当前用户积分总额
result_balance	当前用户预存总金额
openid	用户openid