创建卡券
- 1 更新通知
- 2 创建卡券
- 2.1 接口调用顺序
- 2.2 接口调用说明
- 2.3 步骤一:上传卡券图片素材
- 2.3.1 上传图片接口
- 2.4 步骤二:设置卡券适用门店
- 2.5 步骤三:选取卡券背景颜色
- 2.6 步骤四:选择卡券类型并创建卡券
- 2.7 卡券基础信息字段(重要)
- 2.8 跳转外链带参数说明
- 3 设置快速买单
- 3.1 设置买单接口
- 3.2 买单事件推送
- 4 设置自助核销
- 4.1 设置自助核销接口
- 5 接口调试工具
# 1 更新通知
2016年5月15日起,微信卡券团队对会员卡能力进行全面升级。在原有能力基础上进行以下能力升级,旨在帮助商家更好地进行会员管理。
-强化客户端一级入口:会员到店即用,快速定位商户会员卡;
-自定义卡面能力:开发者可以根据会员身份设置不同的卡面背景;
-门店扫码方案:新用户到店扫码领卡,老用户到店扫码快速打开会员卡,实现会员点餐、买单等多种功能
-支付即会员:支持开发者设置微信支付后为用户下发领卡消息,顾客支付即会员,快速拉新;
-运营策略调整:会员卡新增开放类目限制,自4月20日起,仅限会员卡类目内的商户新建会员卡,原有会员卡不受影响,详情请见:《会员卡公告》
# 2 创建卡券
# 2.1 接口调用顺序
# 2.2 接口调用说明
在进行卡券创建前,请开发者根据自身业务场景确定以下几点
2.2.1 明确卡券ID与Code码的区别
创建卡券成功后获取卡券ID,一个卡券ID代表一类卡券,包含相应库存数量的Code码。
例如: 创建50元代金券,获取一个卡券ID(card_id)用于投放,并设置库存100万。顾客小A,领取到商户投放的50元代金券时,券面
上会有一个唯一的标识码,即code码。每个用户的code码都不相同,所以该商户最终卡券发放完毕时,微信将会派发100万个不同的code码给用户。
2.2.2 是否自定义Code码
微信卡券的Code码可由微信后台随机分配,同时支持商户自定义,两者的区别如下:
*备注:自定义code码的开发者若想要获得和非自定义code商户相同的群发卡券、客服消息派发卡券的能力。可以通过 导入自定义code接口将非定义code导入到微信服务器,*若仅在h5投放则无须导入,导入code后code由微信随机下发,不可指定。
2.2.3 选择合适的码型
商户可以根据自身的业务模式和能支持的核销方式,选择合适的券面码型,并在创建卡券填入code_type字段。
举例:若A商户选了二维码类型的卡券,则A商户的核销员在核销时可以通过手机商户助手扫码核销卡券;若B商户选择了仅code类型的
码型,则其核销员就只能通过输入串号的方式核销卡券。
2.2.4 记录用户领券行为
记录用户领券行为有多种方式:
- 用户领取卡券后会推送事件通知开发者,领取卡券事件中包含卡券ID、Code码、领取人OpenID、转赠人OpenID。卡券被核销时同样会推送事件,详情见卡券事件通知。
- 调用查询Code接口 获取该Code码的状态(是否被领取、核销、删除),若Code码被用户领取且处于有效状态,可获取领券人OpenID。
- 从卡券详情页跳转外部链接时,微信后台会自动带上卡券ID、Code码等信息,详情见 跳转外链带参数说明
- 在卡券投放接口中加入场景字段outer_str,该字段值会在用户领取时伴随事件通知商户。
例如:创建二维码接口时设置outer_str为1,添加卡券JS-SDK时设置为2,则可通过对领取事件的分析得出两个不同投放渠道带来的领券效果,及时调整投放策略。
2.2.5 活用自定义入口
为满足商户功能扩展的需求,新增可自定义两个卡券内的入口,支持跳转到商户自定义的HTML5网页。
三个自定义入口基于不同的场景定位设置,区别如下:
不同入口示例:
# 2.3 步骤一:上传卡券图片素材
为了保证商户的卡券在用户的微信内能快速、稳定地加载出图片素材,我们强烈建议开发者将商户的卡券素材先调用接口导入微信
CDN。
# 2.3.1 上传图片接口
开发者需调用该接口上传商户图标至微信服务器,获取相应logo_url/icon_list/image_url,用于卡券创建。
开发者注意事项
1.上传的图片限制文件大小限制1MB,仅支持JPG、PNG格式。
2.调用接口获取图片url仅支持在微信相关业务下使用。
接口调用请求说明
HTTP请求方式: POST/FROMURL:https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=ACCESS_TOKEN
参数说明
请求数据
调用示例(使用curl命令,用FORM表单方式上传一个图片):curl –Fbuffer=@test.jpg
返回数据
返回正确的示例:{"url":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0"}返回错误的示例{"errcode":40009,"errmsg":"invalid image size"}
参数说明
# 2.4 步骤二:设置卡券适用门店
请点击查看微信门店接口文档,获取门店 ID 后填入创建卡券接口中的相应字段 location_id_list,即可设置该卡券的适用门店。
# 2.5 步骤三:选取卡券背景颜色
选择适用色值,在步骤四:创建卡券中将颜色名(如Color010)填入color字段。
目前微信提供包括以上十种色值的共计十四种色值供开发者使用。
##2.6 步骤四:创建卡券
创建卡券接口是微信卡券的基础接口,用于创建一类新的卡券,获取card_id,创建成功并通过审核后,商家可以通过文档提供的其他接口将卡券下发给用户,每次成功领取,库存数量相应扣除。
开发者须知
1.需自定义Code码的商家必须在创建卡券时候,设定use_custom_code为true,且在调用投放卡券接口时填入指定的Code码。指定OpenID同理。特别注意:在公众平台创建的卡券均为非自定义Code类型。
2.can_share字段指领取卡券原生页面是否可分享,建议指定Code码、指定OpenID等强限制条件的卡券填写false。
3.特别注意:编码方式仅支持使用UTF-8,否则会报错。
4.创建成功后该卡券会自动提交审核,审核结果将通过事件通知商户。开发者可调用设置白名单接口设置用户白名单,领取未通过审核的卡券,测试整个卡券的使用流程。
接口调用请求说明
HTTP请求方式: POSTURL: https://api.weixin.qq.com/card/create?access_token=ACCESS_TOKEN
参数说明
POST数据示例
{
"card": {
"card_type": "GROUPON",
"groupon": {
"base_info": {
"logo_url":
"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
"brand_name": "微信餐厅",
"code_type": "CODE_TYPE_TEXT",
"title": "132元双人火锅套餐",
"color": "Color010",
"notice": "使用时向服务员出示此券",
"service_phone": "020-88888888",
"description": "不可与其他优惠同享\n如需团购券发票,请在消费时向商户提出\n店内均可使用,仅限堂食",
"date_info": {
"type": "DATE_TYPE_FIX_TIME_RANGE",
"begin_timestamp": 1397577600,
"end_timestamp": 1472724261
},
"sku": {
"quantity": 500000
},
"use_limit":100,
"get_limit": 3,
"use_custom_code": false,
"bind_openid": false,
"can_share": true,
"can_give_friend": true,
"location_id_list": [
123,
12321,
345345
],
"center_title": "顶部居中按钮",
"center_sub_title": "按钮下方的wording",
"center_url": "www.qq.com",
"custom_url_name": "立即使用",
"custom_url": "http://www.qq.com",
"custom_url_sub_title": "6个汉字tips",
"promotion_url_name": "更多优惠",
"promotion_url": "http://www.qq.com",
"source": "大众点评"
},
"advanced_info": {
"use_condition": {
"accept_category": "鞋类",
"reject_category": "阿迪达斯",
"can_use_with_other_discount": true
},
"abstract": {
"abstract": "微信餐厅推出多种新季菜品,期待您的光临",
"icon_url_list": [
"http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj
piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0"
]
},
"text_image_list": [
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sjpiby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品精选食材,以独特的烹饪方法,最大程度地刺激食 客的味蕾"
},
{
"image_url": "http://mmbiz.qpic.cn/mmbiz/p98FjXy8LacgHxp3sJ3vn97bGLz0ib0Sfz1bjiaoOYA027iasqSG0sj piby4vce3AtaPu6cIhBHkt6IjlkY9YnDsfw/0",
"text": "此菜品迎合大众口味,老少皆宜,营养均衡"
}
],
"time_limit": [
{
"type": "MONDAY",
"begin_hour":0,
"end_hour":10,
"begin_minute":10,
"end_minute":59
},
{
"type": "HOLIDAY"
}
],
"business_service": [
"BIZ_SERVICE_FREE_WIFI",
"BIZ_SERVICE_WITH_PET",
"BIZ_SERVICE_FREE_PARK",
"BIZ_SERVICE_DELIVER"
]
},
"deal_detail": "以下锅底2选1(有菌王锅、麻辣锅、大骨锅、番茄锅、清补 凉锅、酸菜鱼锅可选):\n大锅1份 12元\n小锅2份 16元 "
}
}}
字段示图
团购券
JSON示例
{
"card": {
"card_type": "GROUPON",
"groupon": {
"base_info": {
················
},
"advanced_info": {
················
},
"deal_detail": "示例"
}
}
}
代金券
JSON示例
{
"card": {
"card_type": "CASH",
"cash": {
"base_info": {
················
},
"advanced_info": {
················
},
"least_cost": 1000,
"reduce_cost": 100,
}
}
}
折扣券
JSON示例:
{
"card": {
"card_type": "DISCOUNT",
"discount": {
"base_info": {
················
},
"advanced_info": {
················
},
"discount": 30
}
}
}
兑换券
JSON示例
{
"card": {
"card_type": "GIFT",
"gift": {
"base_info": {
················
},
"advanced_info": {
················
},
"gift":"可兑换音乐木盒一个"
}
}
}
优惠券
JSON示例
{
"card": {
"card_type": "GENERAL_COUPON",
"general_coupon": {
"base_info": {
················
},
"advanced_info": {
················
},
"default_detail":"优惠券专用,填写优惠详情"
}
}
}
# 2.7 卡券基础信息字段(重要)
base_info(卡券基础信息)字段-必填字段
base_info(卡券基础信息)字段-非必填字段
Advanced_info(卡券高级信息)字段
注意事项:
1.高级字段为商户额外展示信息字段,非必填,但是填入某些结构体后,须填充完整方可显示:如填入text_image_list结构体
时,须同时传入image_url和text,否则也会报错; 2.填入时间限制字段(time_limit),只控制显示,不控制实际使用逻辑,不填默认不显示;
3.创建卡券时,开发者填入的时间戳须注意时间戳溢出时间,设置的时间戳须早于2038年1月19日;
4.预存code模式的卡券须设置quantity为0,导入code后方可增加库存;
5.卡券自定义cell跳转小程序支持的最低微信客户端版本为6.5.8,低版本用户仍然会跳转url,高版本会跳转小程序;
返回说明
数据示例:
{ "errcode":0, "errmsg":"ok", "card_id":"p1Pj9jr90_SQRaVqYI239Ka1erkI"}
# 2.8 跳转外链带参数说明
为了满足商户基于卡券本身的扩展诉求,允许卡券内页添加url跳转外链。带有的的字段有encrypt_code、card_id。
注意事项: encrypt_code为加密码码,需调用解码接口获取真实Code码。 假如指定的url为http://www.qq.com,用户点击时,跳转的url则为: http://www.qq.com?encrypt_code=ENCRYPT_CODE&card_id=CARDID
# 3 设置快速买单
功能介绍
微信卡券买单功能是微信卡券的一项新的能力,可以方便消费者买单时,直接录入消费金额,自动使用领到的优惠(券或卡)抵扣,并拉起微信支付快速完成付款。
微信买单(以下统称微信买单)的好处:
1、无需商户具备微信支付开发能力,即可完成订单生成,与微信支付打通。
2、可以通过手机公众号、电脑商户后台,轻松操作收款并查看核销记录,交易对账,并支持离线下载。
3、支持会员营销,二次营销,如会员卡交易送积分,抵扣积分,买单后赠券等。
开通指引
步骤一:申请开通内测白名单权限后,开发者可以登录微信公众平台mp.weixin.qq.com,进入【卡券功能】-【卡券概况】,点击查看资料和权限
步骤二:在高级权限区,有标注微信买单的权限状态,商户先需要开通微信支付,并为收款门店配置核销员,才能激活申请权限。未获得权限时,点击“申请“,开通买单权限
步骤三:为收款门店配置收款员“或直接点击”卡券核销“,可前往添加门店核销员,便于后续接收结算通知。
# 3.1 设置买单接口
买单接口说明
创建卡券之后,开发者可以通过设置微信买单接口设置该card_id支持微信买单功能。值得开发者注意的是,设置买单的card_id必须已经配置了门店,否则会报错。
接口调用请求说明
HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/paycell/set?access_token=TOKEN
参数说明
POST数据
{ “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“, “is_open”: true}
字段说明
返回数据
{ "errcode":0, "errmsg":"ok" }
字段说明
注意事项:
1.设置快速买单的卡券须支持至少一家有核销员门店,否则无法设置成功;
2.若该卡券设置了center_url(居中使用跳转链接),须先将该设置更新为空后再设置自快速买单方可生效。
# 3.2 买单事件推送
微信买单完成时,微信会把这个事件推送到开发者填写的URL。 推送XML数据包示例:
<xml>
<ToUserName>< ![CDATA[gh_e2243xxxxxxx] ]></ToUserName>
<FromUserName>< ![CDATA[oo2VNuOUuZGMxxxxxxxx] ]></FromUserName>
<CreateTime>1442390947</CreateTime>
<MsgType>< ![CDATA[event] ]></MsgType>
<Event>< ![CDATA[user_pay_from_pay_cell] ]></Event>
<CardId>< ![CDATA[po2VNuCuRo-8sxxxxxxxxxxx] ]></CardId>
<UserCardCode>< ![CDATA[38050000000] ]></UserCardCode>
<TransId>< ![CDATA[10022403432015000000000] ]></TransId>
<LocationId>291710000</LocationId>
<Fee>< ![CDATA[10000] ]></Fee>
<OriginalFee>< ![CDATA[10000] ]> </OriginalFee>
</xml>
#4 设置自助核销
功能介绍
自助核销与扫码/输码核销互为补充,卡券商户助手通过扫码/输码完成核销的同时,也确保了用券的真实性,适合有强对账需求的商户使用;而自助核销由用户发起,全程由用户操作,适合对账需求不强的商户使用。
目前,自助核销可能适合以下场景使用:
1.不允许店员上班期间带手机;
2.高峰期店内人流量大,扫码/输码核销速度不能满足短时需求;
3.会议入场,短时有大量核销任务;
# 4.1 设置自助核销接口
接口说明
创建卡券之后,开发者可以通过设置微信买单接口设置该card_id支持自助核销功能。值得开发者注意的是,设置自助核销的card_id必须已经配置了门店,否则会报错。
接口调用请求说明
HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/selfconsumecell/set?access_token=TOKEN
参数说明
POST数据
{ “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“, “is_open”: true}
字段说明
返回数据
{ "errcode":0, "errmsg":"ok" }
字段说明
注意事项:
1.设置自助核销的卡券须支持至少一家门店,否则无法设置成功;
2.若该卡券设置了center_url(居中使用跳转链接),须先将该设置更新为空后再设置自助核销功能方可生效。
#5 接口调试工具
开发者可以通过 卡券创建接口在线调试工具进行卡券创建HelloWorld。获取到access_token后,开发者可以将要POST的JSON数据贴至接口调试工具中,获得Card_id以进行下一步投放动作。