회원카드 영역 (1)
会员卡专区
会员卡升级公告
2016年5月15日起,微信卡券团队对会员卡能力进行全面升级。在原有能力基础上进行以下能力升级,旨在帮助商家更好地进行会员管理。
-强化客户端一级入口:会员到店即用,快速定位商户会员卡;
-自定义卡面能力:开发者可以根据会员身份设置不同的卡面背景;
-门店扫码方案:新用户到店扫码领卡,老用户到店扫码快速打开会员卡,实现会员点餐、买单等多种功能
-支付即会员:支持开发者设置微信支付后为用户下发领卡消息,顾客支付即会员,快速拉新;
-运营策略调整:会员卡新增开放类目限制,自4月20日起,仅限会员卡类目内的商户新建会员卡,原有会员卡不受影响,详情请见:《会员卡公告》
更新日志
版本号 | 更新内容 | 更新时间 |
---|---|---|
V1.0 | 1.支持创建/更新会员卡直接拉出支付付款码付款,微信支付 进一步打通会员卡 2.一键激活接口升级,一键激活支持商户设置绑定老会员url、 设置自定义选项以及设置用户填写一键激活信息后跳转至商户 页面 | 2016-6-20 |
V1.1 | 1.开发者在变动积分/余额消息时,支持开发者控制发/不发系统模板消息 2.支持商户设置某一张卡支持用户修改信息 | 2016-8-16 |
1.新版会员卡介绍
-(a)增加自定义背景,开发者可以设置;
-(b)卡券消息升级,积分/余额变动通过模板消息自动发送,可携带营销信息。
(a)
2.须知
阅读该部分之前请先阅读《微信公众平台开发概述》、《开始开发》以及《微信卡券接口说明》,确保你能了解公众平台和卡券接口的基本术语和调用方法。
一般地,会员卡的接口调用顺序可参考以下流程:
3.会员卡玩法介绍
4.创建会员卡接口详情
4.1 创建会员卡接口
支持开发者调用该接口创建会员卡,并获取card_id,用于投放。调用该接口前,请开发者详读《创建卡券接口》,快速录入会员卡卡面必要信息。
接口调用请求说明
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日,若要设置更久的有效期,可以选择永久有效类型的有效期。
4.2 获取会员卡审核结果
调用接口成功创建会员卡后,会由系统自动提交审核,审核结果将在三个工作日内以事件形式告知开发者,同时支持调用接口主动查询卡券状态。
审核事件推送
生成的卡券通过审核时,微信会把这个事件推送到开发者填写的URL,详情见:审核事件推送,会员卡审核通过后可以正式投放会员卡。
4.3 设置测试白名单接口
若会员卡暂时未审核通,开发者可以将测试人员的微信号设置成白名单,领取未审核通过的卡券。白名单状态领取的卡信息不随卡券实时更新,请开发者注意。
5 投放会员卡接口详情
目前微信会员卡支持通过扫描二维码、在网页直接点击(参考JS-SDK网页接口)、卡券货架、公众号群发以及公众号被动回复消息领取,开发者可以选择一种或者多种。请参考以下各种投放方式详情。
特别注意
1. 开发者调用接口投放的会员卡为无会员信息的“卡套”,会员卡编号、积分、余额等信息需在用户领取会员卡后调用激活/绑定会员卡接口更新上。
2. 调用激活/绑定会员卡接口的凭证为Code码及card_id,开发者需在调用投放会员卡时通过接口或领取卡券事件记录code码与会员OpenID的关系。
5.1 创建二维码接口
创建会员卡二维码,打印后置于店内,顾客扫码领取会员卡,扫描下方二维码体验领取,若已领取可扫码快速打开会员卡。接口详情见:创建二维码接口
5.2 网页内单张/批量添加卡券接口
微信提供addCard接口供商户前端网页调用,用于将一张或多张卡券添加到用户卡包。详情见批量添加卡券接口
(微信扫一扫>微信卡券接口>addcard接口)
5.3 通过卡券货架投放会员卡
卡券货架简介
卡券货架支持开发者通过调用接口生成一个卡券领取H5页面,并获取页面链接,进行卡券投放动作。
开发者也可以通过公众号群发消息或者客服消息为用户发送一张会员卡。
5.5 记录用户领卡行为
用户领取会员卡后,微信会给开发者服务器推送领取会员卡事件通知,以便开发者记录用户OpenID与会员卡code的关联关系,并可以通过事件内的参数区分领取渠道(见1.5)。
5.6 统计投放渠道数据
为方便开发者统计各渠道的卡券投放数据,新增字段outer_id。将不同设值的outer_id填入card_ext的JSON结构中,当用户领取卡券时会将相应设值的outer_id带入领取事件推送中,推送至开发者服务器。
示例: 在二维码投放方式中设置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 | 错误信息。 |
6.2 一键激活
6.2.1 普通一键激活
一键激活是微信提供的快速便捷的激活方案,用户领取后点击“激活会员卡”会跳转至官方的资料填写页面,微信会自动拉取该用户之前填写过的开卡信息,用户无需重复填写, 同时避免了手机号验证的过程,从而实现一键激活的目的,提高了开卡率。具体流程如下图:
步骤一:在创建接口填入wx_activate字段
接口说明
设置微信一键开卡功能,现支持在创建会员卡时填入指定字段指定要一键激活,member_card中增加"wx_activate": true。
若商户使用了自定义卡号,开发者可以设置用户填写信息后跳转至商户的网页,并由开发者进行激活。
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
member_card | ||
wx_activate | 否 | 填写true or false |
POST数据示例:
{ "card": { ························ ························ "member_card": { "wx_activate": true } } }
开发者注意事项
1.填入了自动激活auto_activate字段,激活链接activate_url和一键开卡接口设置都会失效;
2.若同时传入了activate_url,则一键开卡接口设置会失效;
3.建议开发者activate_url、auto_activate和wx_activate只填写一项。
步骤二:设置开卡字段接口
开发者在创建时填入wx_activate字段后,需要调用该接口设置用户激活时需要填写的选项,否则一键开卡设置不生效。
接口调用请求说明
HTTP请求方式: POST URL:https://api.weixin.qq.com/card/membercard/activateuserform/set?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 调用接口凭证 |
POST数据 | 是 | JSON数据 |
{ "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": "职业", "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": [ "喜欢的电影" ] } }
参数名 | 必填 | 类型 | 描述 |
---|---|---|---|
card_id | 是 | string(32) | 卡券ID。 |
required_form | 否 | JSON结构 | 会员卡激活时的必填选项。 |
optional_form | 否 | JSON结构 | 会员卡激活时的选填项。 |
can_modify | 否 | bool | 当前结构(required_form或者optional_form )内 的字段是否允许用户激活后再次修改,商户设置为true 时,需要接收相应事件通知处理修改事件 |
common_field_id_list | 否 | arry | 微信格式化的选项类型。见以下列表。 |
custom_field_list | 否 | arry | 自定义选项名称。 |
rich_field_list | 否 | arry | 自定义富文本类型,包含以下三个字段 |
type | 否 | string(32) | 富文本类型 FORM_FIELD_RADIO 自定义单选 FORM_FIELD_SELECT 自定义选择项 FORM_FIELD_CHECK_BOX 自定义多选 |
name | 否 | string(32) | 字段名 |
values | 否 | arry | 选择项 |
service_statement | 否 | JSON结构 | 服务声明,用于放置商户会员卡守 则 |
name | 否 | string(32) | 会员声明字段名称 |
url | 否 | string(128) | 自定义url |
bind_old_card | 否 | JSON结构 | 绑定老会员链接 |
name | 否 | string(32) | 链接名称 |
url | 否 | string(128) | 自定义url |
common_field_id_list,支持开发者使用以下选项类型
字段值 | 描述 |
---|---|
USER_FORM_INFO_FLAG_MOBILE | 手机号 |
USER_FORM_INFO_FLAG_SEX | 性别 |
USER_FORM_INFO_FLAG_NAME | 姓名 |
USER_FORM_INFO_FLAG_BIRTHDAY | 生日 |
USER_FORM_INFO_FLAG_IDCARD | 身份证 |
USER_FORM_INFO_FLAG_EMAIL | 邮箱 |
USER_FORM_INFO_FLAG_LOCATION | 详细地址 |
USER_FORM_INFO_FLAG_EDUCATION_BACKGRO | 教育背景 |
USER_FORM_INFO_FLAG_CAREER | 职业 |
USER_FORM_INFO_FLAG_INDUSTRY | 行业 |
USER_FORM_INFO_FLAG_INCOME | 收入 |
USER_FORM_INFO_FLAG_HABIT | 兴趣爱好 |
步骤三:接收会员信息事件通知
用户填写、提交资料后,会有事件推送给商家,开发者可以在接收到事件通知后调用激活接口,传入会员卡号、初始积分等信息或者调用拉取会员信息接口获取会员信息,进行会员管理。
推送XML数据包示例
<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>
参数说明
参数 | 说明 |
---|---|
ToUserName | 开发者微信号 |
FromUserName | 发送方帐号(一个OpenID) |
CreateTime | 消息创建时间 (整型) |
MsgType | 消息类型,event |
CardId | 卡券ID |
UserCardCode | 卡券Code码 |
步骤四:同步会员数据
开发者可以在接收到事件通知后调用激活接口,传入会员卡号、初始积分等信息或者调用拉取会员信息接口获取会员信息。
步骤五:拉取会员信息接口
接口说明
支持开发者根据CardID和Code查询会员信息。
接口调用请求说明
HTTP请求方式: POST URL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
POST数据 | 是 | JSON数据 |
access_token | 是 | 调用接口凭证 |
POST数据
{ "card_id": "pbLatjtZ7v1BG_ZnTjbW85GYc_E8", "code": "916679873278"}
返回数据
{ "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 }
参数名 | 说明 |
---|---|
errcode | 错误码,0为正常 |
errmsg | 错误信息 |
openid | 用户在本公众号内唯一识别码 |
nickname | 用户昵称 |
bonus | 积分信息 |
balance | 余额信息 |
sex | 用户性别 |
user_info | 会员信息 |
custom_field_list | 开发者设置的会员卡会员信息类目,如等级。 |
name | 会员信息类目名称 |
value | 会员卡信息类目值,比如等级值等 |
user_card_status | 当前用户的会员卡状态,NORMAL 正常 EXPIRE 已过期 GIFTING 转赠中 GIFT_SUCC 转赠成功 GIFT_TIMEOUT 转赠超时 DELETE 已删除,UNAVAILABLE 已失效 |
has_active | 该卡是否已经被激活,true表示已经被激活,false表示未被激活 |
6.2.2 跳转型一键激活
跳转型一键激活支持用户在提交会员开卡资料后跳转至商户自定义的网页。不同于普通一键激活,跳转型一键激活的激活会员卡动作由商户完成,商户可以在跳转到的网页内做激活、激活奖励、开卡条件判断等逻辑,同时也保证了开卡的实时性,适合使用自定义卡号的商户使用。
步骤一:在创建/更新接口填入跳转型一键激活相关字段
若商户设置用户激活后跳转自己的网页,需要在创建或更新接口传入以下参数。
{ "card": { "member_card": { ························ ························ "wx_activate": true, "wx_activate_after_submit" : true, //是否设置跳转型一键激活 "wx_activate_after_submit_url" : "http://qq.com" //用户提交信息后跳转的网页 } } }
参数名 | 必填 | 类型 | 描述 |
---|---|---|---|
member_card | 是 | JSON接口 | 会员卡结构体 |
wx_activate | 否 | bool | 是否支持一键激活,填true或lse |
wx_activate_after_submit | 否 | bool | 是否支持跳转型一键激活,填true或lse |
wx_activate_after_submit_url | 否 | bool | 跳转型一键激活跳转的地址链接 |
步骤二:设置开卡字段接口
步骤三:获取用户提交资料
用户填写并提交开卡资料后,会跳转到商户的网页,商户可以在网页内获取用户已填写的信息并进行开卡资质判断,信息确认等动作。
具体方式如下:
用户点击提交后,微信会在商户的url后面拼接获取用户填写信息的参数: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。
开发者可以根据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 |