会员卡专区(二)
8 管理会员卡
8.1 拉取会员信息(积分查询)接口
接口说明
支持开发者根据card_id和Code查询会员信息,包括激活资料、积分信息以及余额等信息。
接口调用请求说明
HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/membercard/userinfo/get?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
POST数据 | 是 | JSON数据 |
access_token | 是 | 调用接口凭证 |
POST数据
{ "card_id": "pbLatjtZ7v1BG_ZnTjbW85GYc_E8", "code": "916679873278"}
参数名 | 是否必填 | 说明 |
---|---|---|
cardid | 是 | 查询会员卡的cardid |
code | 是 | 所查询用户领取到的code值 |
返回数据
{ "errcode": 0, "errmsg": "ok", "openid": "obLatjjwDolFjRRd3doGIdwNqRXw", "nickname": "Fourier", "membership_number": "316510891298", "bonus": 460, "sex": "MALE", "user_info": { "common_field_list": [ { "name": "USER_FORM_INFO_FLAG_MOBILE", "value": "15521328888" }, { "name": "USER_FORM_INFO_FLAG_NAME", "value": "微信" } ], "custom_field_list": [] }, "user_card_status": "NORMAL" }
参数名 | 说明 |
---|---|
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 已失效 |
8.2 更改会员卡信息接口
接口说明
支持更改会员卡卡面信息以及卡券属性信息。
接口调用请求说明
HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/update?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
POST数据 | 是 | Json数据 |
access_token | 是 | 调用接口凭证 |
POST数据
{ "card_id": "ph_gmt7cUVrlRk8swPwx7aDyF-pg", "member_card": { "background_pic_url": "https://mmbiz.qlogo.cn/mmbiz/0?wx_fmt=jpeg", "base_info": { "logo_url": "http:\/\/www.supadmin.cn\/uploads\/allimg\/120216\/1_120216214725_1.jpg", "color": "Color010", "notice": "使用时向服务员出示此券", "service_phone": "020-88888888", "description": "不可与其他优惠同享\n如需团购券发票,请在消费时向商户提出\n店内均可使用,仅限堂食\n餐前不可打包,餐后未吃完,可打包\n本团购券不限人数,建议2人使用,超过建议人数须另收酱料费5元/位\n本单谢绝自带酒水饮料", "location_id_list": [ 123, 12321, 345345 ] }, "bonus_cleared": "aaaaaaaaaaaaaa", "bonus_rules": "aaaaaaaaaaaaaa", "prerogative": "", "auto_activate": true, //也可以填写wx_activate"activate_url":"" } }
支持修改字段:
base_info字段:
参数名 | 是否提审 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
logo_url | 是 | string(128) | http://mmbiz .qpic.cn/ | 卡券的商户logo,建议像素为300*300。 |
notice | 是 | string(48) | 请出示二维 码核销卡券。 | 使用提醒,字数上限为16个汉字。 |
description | 是 | string(3072) | 不可与其 他优惠同享 | 使用说明。 |
service_phone | 否 | string(24) | 40012234 | 客服电话。 |
color | 是 | string(3072) | Color010 | 卡券颜色。 |
location_id_list | 否 | string(3072) | 1234,2314 | 支持更新适用门店列表。 |
use_all_locations | 否 | bool | true | 支持全部门店,填入后卡券门店跟随商户门店更新而更新 |
center_title | 否 | string(18) | 立即使用 | 会员卡中部的跳转按钮名称 ,建议用作使用用途 |
center_sub_title | 否 | string(24) | 到店后使用 | 会员卡中部按钮解释wording |
center_url | 否 | string(128) | www.qq.com | 会员卡中部按钮对应跳转的url |
custom_url_name | 否 | string(16) | 立即使用 | 自定义跳转入口的名字。 |
custom_url | 否 | string(128) | www.qq.com | 自定义跳转的URL。 |
custom_url_sub_title | 否 | string(18) | 更多惊喜 | 显示在入口右侧的提示语。 |
promotion_url_name | 否 | string(16) | 产品介绍。 | 营销场景的自定义入口名称。 |
promotion_url | 否 | string(128) | www.qq.com; | 入口跳转外链的地址链接。 |
promotion_url_sub_title | 否 | string(18) | 卖场大优惠。 | 显示在营销入口右侧的提示语。 |
code_type | 否 | string(16) | CODE_TYPE _TEXT。 | Code码展示类型, "CODE_TYPE_TEXT" 文本 "CODE_TYPE_BARCODE"一维码 "CODE_TYPE_QRCODE 二维码 "CODE_TYPE_ONLY_QRCODE" 仅显示二维码 "CODE_TYPE_ONLY_BARCODE" 仅显示一维码 "CODE_TYPE_NONE" 不显示任何码型 |
get_limit | 否 | int | 1 | 每人可领券的数量限制 |
can_share | 否 | bool | false | 卡券原生领取页面是否可分享 |
can_give_friend | 否 | bool | false | 卡券是否可转赠 |
date_info | 否 | Json结构 | 见上述示例 | 使用日期,有效期的信息,有效期时间修改仅支持有效区间的扩大 |
type | 否 | int | 1 | 有效期类型,仅支持更改type为1的时间戳,不支持填入2 |
begin_timestamp | 否 | unsigned int | 14300000 | 固定日期区间专用,表示起用时间。(单位为秒) |
end_timestamp | 否 | unsigned int | 15300000 | 固定日期区间专用,表示结束时间。结束时间仅支持往后延长。 |
会员卡专属字段修改:
特别注意,以下支持更新的字段不在基本信息base_info的结构中。
参数名 | 是否提审 | 类型 | 描述 |
---|---|---|---|
background_pic_url | 否 | string(128) | 会员卡自定义卡面背景图 |
bonus_cleared | 是 | string(3072) | 积分清零规则。 |
bonus_rules | 是 | string(3072) | 积分规则。 |
balance_rules | 是 | string(3072) | 储值说明。 |
prerogative | 是 | string(3072) | 特权说明。 |
wx_activate | 否 | bool | 是否开通一键开卡 设置为true时,该卡将支持一键开卡详情见一键开卡。 该选项与activate_url互斥。 |
auto_activate | 否 | bool | 是否开通自动激活 ,设置为true时用户领取会员卡自动设置为激活, 详情见自动激活。 |
activate_url | 否 | string(128) | 激活链接 |
custom_field1 | 否 | Json结构 | 自定义会员信息类目,会员卡激活后显示。 |
custom_field2 | 否 | Json结构 | 自定义会员信息类目,会员卡激活后显示。 |
custom_field3 | 否 | Json结构 | 自定义会员信息类目,会员卡激活后显示。 |
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 |
custom_cell1 | 否 | JSON结构 | 自定义会员信息类目,会员卡激活后显示 |
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 | 折扣,该会员卡享受的折扣优惠 |
返回数据说明
数据示例:
{ "errcode":0, "errmsg":"ok", "send_check":true}
参数名 | 描述 |
---|---|
errcode | 错误码,0为正常。 |
errmsg | 错误信息。 |
send_check | 此次更新是否需要提审,true为需要,false为不需要。 |
开发者注意事项注
1. 更改卡券的部分字段后会重新提交审核,详情见字段说明,更新成功后可通过调用查看卡券详情接口核查更新结果;
2. 仅填入需要更新的字段,许多开发者在调用该接口时会填入brandname等不支持修改的字段,导致更新不成功。
3. 调用该接口后更改卡券信息后,请务必调用查看卡券详情接口验证是否已成功更改。
8.3 设置跟随推荐
功能介绍
支持开发者在积分变动消息底部,配置卡券或设置跳转外链URL,具体形式如下图,可以是URL也可以是一张卡券。
开发者注意事项
一、支持两种类型的跟随推荐配置
1. 广告语+URL,支持商户配置16个汉字长度的文案,及点击跳转的链接。
2. 推荐卡券,支持商户配置一个本公众号下的卡券。
二、推荐位有效期控制
1. 广告语+URL类型,支持商户根据活动期限自定义展示时间。
2. 推荐卡券类型,由微信后台判断卡券的有效性,当卡券已过期、已被领完、已被置为失效会自动下架展示。
8.3.1 设置跟随推荐接口
接口说明
调用更新卡券信息接口将增推荐位字段 update到已成功通过审核的卡券。 同时支持在创建卡券时填入相应字段。
接口详情
接口调用请求说明
http请求方式: POSThttps://api.weixin.qq.com/card/update?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 调用接口凭证 |
POST数据 | 是 | Json数据 |
使用消息配置卡券
{ "card_id": "ph_gmt7cUVrlRk8swPwx7aDyF-pg", "member_card": { "modify_msg_operation": { "card_cell": { "end_time": 1452724561, "card_id": "p1Pj9jr90_SQRaVqYI239Ka1erkI" } } } }
使用消息配置URL
{ "card_id": "ph_gmt7cUVrlRk8swPwx7aDyF-pg", "member_card": { "modify_msg_operation": { "url_cell": { "end_time": 1452724561, "text": "更多优惠", "url": "www.qq.com" } } } }
字段说明
字段名 | 说明 |
---|---|
card_id | 卡券ID。 |
modify_msg_operation | 积分余额变动消息类型 |
card_cell | 卡券类型的推荐位。Json结构参考示例。 |
url_cell | 链接类型的推荐位。Json结构参考示例。 |
card_id | 需要在运营位投放的卡券id |
end_time | 推荐位展示的截止时间。 |
text | 文本内容。 |
url | 跳转链接。 |
返回数据
{ "errcode":0, "errmsg":"ok" }
字段说明
字段名 | 说明 |
---|---|
错误码 | 错误码,0为正常;43008为商户没有开通微信支付权限; |
errmsg | 错误信息 |
8.4 设置支付即会员
8.4.1 增加支付即会员规则接口
开通微信支付的商户可以设置,用户在微信支付后自动为用户发送一条领卡消息,用户点击消息即可领取会员卡。
接口说明
支持商户设置支付即会员的规则,可以区分时间段和金额区间发会员卡。
接口调用请求说明
HTTP请求方式: POST URL:https://api.weixin.qq.com/card/paygiftmembercard/add?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
POST数据 | 是 | Json数据 |
access_token | 是 | 调用接口凭证 |
POST数据
{ "card_id": "xxxxxxxxa", "jump_url": "mp.weixin.qq.com/wiki", "mchid_list": [ "123", "1234", "12345" ], "begin_time": 146324567, "end_time": 147234567, "min_cost": 1000, "max_cost": 10000000, "is_locked": true }
字段说明
字段名 | 说明 |
---|---|
card_id | 卡券ID,仅支持非自定义code模式的card_id和预存code模式的card_id。 |
jump_url | 模板消息跳转的url,可以是商户自定义的领卡网页链接 |
mchid_list | 支持赠券规则的商户号列表 |
begin_time | 规则生效时间 |
end_time | 规则结束时间 |
min_cost | 本次规则生效支付金额下限,与分为单位 |
max_cost | 本次规则生效支付金额上限,与分为单位 |
is_locked | 是否允许其他appid设置本规则内已经设置过的商户号,默认为true |
返回数据说明
数据示例:
{ "errcode": 0, "errmsg": "ok", "succ_list":[ "134xxxxxx" ], "fail_list":[ { "mchid": "xxxxx", "errcode": 0, "errmsg": "ok", "occupy_appid": "wxxxxxxxxxxx" }, { "mchid": "xxxxx", "errcode": 0, "errmsg": "ok", "occupy_appid": "wxxxxxxxxxxx" } ] }
参数名 | 描述 |
---|---|
errcode | 错误码,0为正常。 |
errmsg | 错误信息。 |
succ_list | 设置成功的mchid列表 |
fail_list | 设置失败的mchid列表 |
mchid | 支付的商户号 |
occupy_appid | 设置失败原因为重复设置时,该mchid当前被占用的appid,商户须使用该appid解除绑定后重新设置。 |
开发者注意事项注
1. 会员卡领卡消息针对单个新用户仅发送一次,若该用户已经接收或者已经领取过会员卡则不会重复发送;
2. 通过该规则设置的card_id的制券appid必须和当前mch_id的主体appid一致,否则报错72001;
3.仅支持会员卡类型的卡券,否则报错:72003;
4.设置支付即会员时,须确认调用接口的appid和当前card_id主体一致,以及appid与mchid有绑定关系,否则报错:72002;
5.须保证mchid之前没有被其他appid设置过,否则报错72004;
6.单次仅限设置100个mchid,若超过100个请多次调用本接口。
8.4.2 删除支付即会员规则接口
删除之前已经设置的支付即会员规则。
接口说明
支持商户设置支付即会员的规则,可以区分时间段和金额区间发会员卡。
接口调用请求说明
HTTP请求方式: POST URL:https://api.weixin.qq.com/card/paygiftmembercard/delete?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
POST数据 | 是 | Json数据 |
access_token | 是 | 调用接口凭证 |
POST数据
{ "card_id": "xxxxxxxxa", "mchid_list": [ 123, 1234, 12345 ] }
字段说明
字段名 | 说明 |
---|---|
card_id | 卡券ID。 |
mchid_list | 本次删除的支付即会员的商户号列表 |
返回数据说明
数据示例:
{ "errcode": 0, "errmsg": "ok", "succ_list":[ { "mchid": "xxxxx", "errcode": 0, "errmsg": "ok", "occupy_appid": "wxxxxxxxxxxx" }, { "mchid": "xxxxx", "errcode": 0, "errmsg": "ok", "occupy_appid": "wxxxxxxxxxxx" } ], "fail_list":[ { "mchid": "xxxxx", "errcode": 0, "errmsg": "ok", "occupy_appid": "wxxxxxxxxxxx" }, { "mchid": "xxxxx", "errcode": 0, "errmsg": "ok", "occupy_appid": "wxxxxxxxxxxx" } ] }
参数名 | 描述 |
---|---|
errcode | 错误码,0为正常。 |
errmsg | 错误信息。 |
succ_list | 设置成功的mchid列表 |
fail_list | 设置失败的mchid列表 |
mchid | 支付的商户号 |
occupy_appid | 设置失败原因为重复设置时,该mchid当前被占用的appid,商户须使用该appid解除绑定后重新设置。 |
8.4.3 查询商户号支付即会员规则接口
接口说明
可以查询某个商户号是否支持支付即会员功能
接口调用请求说明
HTTP请求方式: POST URL:https://api.weixin.qq.com/card/paygiftmembercard/get?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
POST数据 | 是 | Json数据 |
access_token | 是 | 调用接口凭证 |
POST数据
{"mchid":"xxxxxxxx"}
字段说明
字段名 | 说明 |
---|---|
mchid | 要查询的支付商户号。 |
返回数据说明
数据示例:
{ "errcode": 0, "errmsg": ok, "card_id": "xxxxxxxxxxxxxxxxxx", "occupy_appid": "wxxxxxxxxxxx", "is_locked": true }
8.5 设置会员卡拉出微信支付刷卡界面
通过接口创建支持刷卡类型的会员卡,用户点击快速买单后即可拉出刷卡界面进行支付。以下为示意图:
8.5.1 创建会员卡支持微信支付刷卡
商户可以创建一张会员卡支持微信支付刷卡,须在创建会员卡接口的JSON中加入以下字段:
{ "card": { "card_type": "MEMBER_CARD", "member_card": { "base_info": { "pay_info": { "swipe_card": { "is_swipe_card":true } } } } } }
8.5.2 更新会员卡支持微信支付刷卡
商户可以更新已有会员卡支持微信支付刷卡,须在更新会员卡接口的JSON中加入以下字段:
{ "card_id": "ph_gmt7cUVrlRk8swPwx7aDyF-pg", "member_card": { "base_info": { "pay_info": { "swipe_card": { "is_swipe_card":true } } } } }