会员卡专区(2)


     (接上)


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否 booltrue支持全部门店,填入后卡券门店跟随商户门店更新而更新
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)            会员卡自定义卡面背景图            
supply_bonusbool   是否支持积分,仅支持从false变为true,默认为false
bonus_cleared                       string(3072)            积分清零规则。            
bonus_rules                       string(3072)            积分规则。            
supply_balance
bool   是否支持储值,仅支持从false变为true,默认为false
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也可以是一张卡券。


8.3.1 设置跟随推荐接口

接口说明

    调用更新卡券信息接口将增推荐位字段 update到已成功通过审核的卡券。 同时支持在创建卡券时填入相应字段。


接口详情

接口调用请求说明

http请求方式: POST
URL:https://api.weixin.qq.com/card/update?access_token=TOKEN

参数说明

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

使用消息配置卡券

{
   "card_id": "pbLatjkoa7luhR3zIBjtQiaYtnz4",
   "member_card": {
       "activate_msg_operation": {   //若指定的是积分、余额等变动消息赠券,则为modify_msg_operation
           "url_cell": {
               "card_id_list": [
                   "pbLatjhcI6XUxJWA0Au3Gaq5eFPs"
               ],
               "end_time": 1492724561,
               "text": "恭喜你获得一张50元代金券",
               "url": "www.qq.com"
           }
       }
   }
}

字段说明

字段名            说明            
card_id            卡券ID。            
member_card会员卡结构体,如示例
modify_msg_operation            推荐类型,代表积分余额等变动消息赠券         
activate_msg_operation推荐类型,代表会员卡激活消息赠券
url_cell            推荐内容结构体,如示例            
card_id_list    送券的card_id列表,与url字段互斥,不支持普通券和朋友的券混合使用,最多填写10个card_id          
end_time            推荐位展示的截止时间           
text            文本内容            
url            跳转链接,与card_id_list互斥,若设置了跳转url,用户点击模板消息详情后将跳转至该链接领券     

返回数据

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

字段说明



字段名            说明            
错误码            错误码,0为正常;43008为商户没有开通微信支付权限;            
errmsg            错误信息            


开发者注意事项


1.支持一张会员卡同时设置积分/余额变动消息赠券和激活赠券,开发者须分开设置;

2.开发者若填写了card_id_list后,若再填写url字段则card_id_list内容失效;

3.若开发者设置了url,则须支持在url上领券,否则会被视为恶意营销处罚。

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,详情见:是否自定义code码     
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.单次仅限设置10个mchid,若超过10个请多次调用本接口。


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"
        },
        {
            "mchid": "xxxxx",
            "errcode": 0,
            "errmsg": "ok"
        }
    ],
    "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
                        }
                       }
                     }
    }
}

详情请见:更改会员卡信息接口



开发者注意事项


1.设置该功能之前,请确认自己是否开通了微信支付,否则接口报错(开通微信支付

2.通过接口设置会员卡拉出刷卡后,当用户进行支付时通过授权码查询OPENID接口https://pay.weixin.qq.com/wiki/doc/api/micropay.php?chapter=9_13&index=9获取用户openid,

再调用获取用户领取卡券接口http://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1451025272&token=&lang=zh_CN获取该openid的会员身份,并进行相应的批价。

3.仅微信6.3.18及以上版本支持会员卡拉出刷卡支付,低于6.3.18的客户端版本将提示用户升级。

8.6 其他接口

8.6.1 修改库存接口

   调用修改库存接口增减某张卡券的库存,详情见:修改库存接口

8.6.2 查询code接口

     开发者可以通过该接口查询会员卡的基本信息,包括领取人的OpenID、会员卡状态,详情见:查询code接口

8.6.3 获取用户已领取的卡券

   支持开发者调用该接口获取指定用户卡包中属于该appid下的卡券,详情见:获取用户已领取卡券接口

8.6.4 查看卡券详情

   调用该接口可查询card_id创建是传入的字段详情及卡券所处审核状态。详情见:查看卡券详情接口

8.6.5 批量查询卡列表

    开发者可以通过该接口拉取当前商户(appid)下所有的卡券列表,用于卡券管理,详情见:批量查询卡列表接口

8.6.6 删除会员卡

   开发者可以通过该接口删除商户列表的card_id,用于卡券管理,详情见:删除会员卡接口

8.6.7 设置会员卡失效接口

   开发者可以通过该接口将某一个用户的某一张卡券置为失效,用于退款等场景,详情见:设置卡券失效接口

9 管理会员卡

    开发者可以通过该接口拉取会员卡数据,详情见:拉取会员卡数据接口

10 我是第三方

 第三方可以为接入的商户代制会员卡,详情参考:第三方代制专区