朋友的券=创建朋友的券


上一篇 : 朋友的券-朋友的券说明 下一篇: 朋友的券-配置库存、充值券点



创建朋友的券

1朋友的券样式

朋友的券较之前的样式有较大改变,卡券背景色更加突出,强调券的整洁和美观的同时将商户元素更加有强调性地展示,同时支持图文介绍传入,给了商户更大的曝光空间。

0 (1).jpg

2接口调用说明

创建卡券是卡券开发的第一步,开发者需要传入优惠内容生成一个card_id,并在通过审核后进行投放、核销等动作。在进行卡券创建前,请开发者根据自身业务场景确定以下几点

2.1选择合适的门槛类型

目前朋友的券支持无门槛类型以及指定门槛类型的代金券、兑换券,微信后台会根据商户填写的门槛类型自动拼接卡券的详情摘要字段卡券标题字段,开发者可以根据需求选择合适的门槛类型组合,获得最佳的发券效果。

商户按照指定字段填写门槛有利于优惠券审核快速通过,若商户填写了非以下类型的门槛,优惠券将不会被审核通过。

同时,微信后台会根据卡券选择的门槛不同而设置不同的库存价格,目前定价标准为:

   1)无使用门槛的券,0.2券点/张;
  2)制券中,选择了适用范围/消费条件的券,0.4券点/张;仅勾选不可与其他优惠共享,0.2券点/张

不同门槛类型的字段以及展现

微信后台会根据开发者填入不同的门槛字段决定券的样式和展现,下面以一张50元代金券和兑换蛋挞一个的兑换券说明不同门槛带来的 展现逻辑变化。

门槛类型 适用券种 设置条件 详情摘要 标题
无门槛 代金券/兑换券 不填入任何门槛字段 无起用金额限制,全场通用,不限品类 50元代金券/苹果一个
指定品类可用/不可用门槛 代金券 填入accept_category(蛋挞)和reject_category(蛋糕)字段 适用于蛋挞,不适用于蛋糕 蛋挞减50元(填入的accept_catagory小于等于5个汉字);50元代金券(填入的accept_catagory大于5个汉字)
满减门槛 代金券/兑换券 填入least_cost(500)字段 消费满500元可用 全场满500减50
买送门槛(限兑换券) 兑换券 填入object_use_for字段 购买蛋糕可用 买蛋糕送蛋挞
不与其他优惠共享门槛 代金券/兑换券 填入can_use_with_other_discount (false)字段 不与其他优惠共享 50元代金券

注意:

1.门槛字段用于拼接标题以及优惠说明,会影响商户卡券库存定价,请开发者务必按照要求填写,并提前预览生成的卡券;

2.门槛字段一旦设定即不可更改,请开发者慎重填写,及时预览。

3.当开发者同时填入满减字段和指定品类可用字段,则会拼接为"羽绒服(accept_catagory字段小于等于5个字)满500减50","满500减50"(accept_catagory字段大于5个字)

2.2选择合适的code显示类型

目前卡券支持五种code显示类型:即二维码显示code、二维码不显示code、一维码显示code、仅code类型和无code类型(仅限支持券)。

对于不同的code类型,需要的核销方式也不同,对于显示二维码和一维码的卡券可以采用扫码核销的方式,对于只显示code类型的卡券适合用输码核销的方式,而无code类型的优惠券,则仅适合用于线上券使用,并且商户需开发自定义页面供用户核销卡券。

不同的code类型,开发者在创建券时须传入不同的code_type参数。

类别 字段名 适用核销方式
二维码/一维码显示code CODE_TYPE_QRCODE/CODE_TYPE_BARCODE 适用于扫码/输码核销
二维码不显示code CODE_TYPE_ONLY_QRCODE 仅适用于扫码核销
仅code类型 CODE_TYPE_TEXT 仅适用于输码核销
无code类型 CODE_TYPE_NONE 仅适用于线上核销,在券面不出现二维码展开入口

2.3记录用户领券行为

记录用户领券行为有多种方式:

  1. 用户领取卡券后会推送事件通知开发者,领取卡券事件中包含卡券ID、Code码、领取人OpenID。卡券被核销时同样会推送事件,详情见卡券事件推送

  2. 调用查询Code接口获取该Code码的状态(是否被领取、核销、删除),若Code码被用户领取且处于有效状态,可获取领券人OpenID。

  3. 从卡券详情页跳转外部链接时,微信后台会自动带上卡券ID、Code码等信息,详情见跳转外链带参数说明

2.4活用自定义入口

为满足商户功能扩展的需求,新增可自定义三个卡券内的入口,支持跳转到商户自定义url链接。

两个自定义入口基于不同的场景定位设置,区别如下:

类别 示例 字段 显示逻辑
使用场景入口 立即使用 center_title、center_sub_title、center_url 传入后将覆盖二维码展开按钮,未到有效期时按钮置灰
服务场景入口 在线商城 custom_url_name、custom_url_sub_title、custom_url 仅卡券被用户领取且处于有效状态时显示(转赠中、核销后不显示)。
营销场景入口 再次购买 promotion_url_name、promotion_url_sub_title、promotion_url 卡券处于正常状态、转赠中、核销后等异常状态均显示该入口。

3接口调用流程

创建朋友的券请严格按照以下接口调用流程调用接口。

0.png

开发者须按照以上流程调用接口,接口列表如下表。

4 API详情

4.1上传图片接口

请点击查看上传图片接口,开发者需调用接口上传商家图标LOGO至微信服务器,获取相应logo_url,用于卡券创建。

注意事项:

1.上传的图片限制文件大小限制1MB,支持JPG 格式。

2.调用接口获取的url 仅支持在微信相关业务下使用,否则会做相应处理。

3.此处必须上传微信服务器返回的图片链接,否则报错;

4.2微信门店接口

请点击查看微信门店接口文档,获取门店 ID 后填入创建卡券接口中的相应字段 location_id_list,即可设置该卡券的适用门店。

4.3选取卡券背景色

请点击查看选取卡券背景颜色接口文档,选择适用色值,让优惠券变得更加个性,在步骤四创建卡券中将颜色名(如Color010)填入color字段。

4.4创建朋友的券接口

创建朋友的券接口是创建系列接口最重要的一环

朋友的券是在原有卡券的基础上衍生出的一种高级券的类型,比起普通卡券,朋友的券可以展示有图文介绍的优惠详情(通过advanced_info字段定义),突出服务和商品摘要信息。

接口说明

开发者需调用该接口创建朋友的券,填入商家信息、LOGO、门店以及相关的优惠和使用字段。创建成功后,会获得Card_id,用于下一步的投放。

接口调用请求说明

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

参数说明

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

代金券POST示例

{
   "card": {
       "card_type": "CASH",
       "cash": {
           "base_info": {
               "logo_url": "http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmx ibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0",
               "brand_name": "微信餐厅",
               "code_type": "CODE_TYPE_TEXT",
               "color": "Color010",
               "service_phone": "020-88888888",
               "description": "不可与其他优惠同享如需团购券发票,请在消费时向商户 提出",
               "date_info": {
                   "type": "DATE_TYPE_FIX_TIME_RANGE",
                   "begin_timestamp": 1447397802,
                   "end_timestamp": 1449893532
               },
               "can_share": false,
               "can_give_friend": false,
               "location_id_list": [
                   272981040,
                   400183234
               ],
               "use_limit":50,
               "get_limit": 3,
               "center_title": "快速核销",
               "center_sub_title": "",
               "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"
           },
           "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"
               ],
               "consume_share_self_num": 1,
               "consume_share_card_list": [],
               "share_friends": true
           },
           "reduce_cost": 10
       }
   }}

兑换券POST示例

{
   "card": {
       "card_type": "GIFT",
       "gift": {
           "base_info": {
               ...
           },
           "advanced_info": {
               ...
           },
           "gift_name": "苹果",
           "gift_num": 1,
           "gift_unit": "个""gift": "送苹果一个"
       }
   }}

朋友的券JSON结构解析

0.jpg

在以上字段中除卡券基本信息之外,代金券与兑换券均相同,故兑换券JSON不作展示。

卡券信息字段

字段 说明 是否必填
card_type 卡券类型,现仅支持代金券类型和兑换券类型,填写CASH或者GIFT
cash 代金券类型json结构函数名
reduce_cost 代金券专用,表示减免金额(单位为分),不可填0。
gift 兑换券券类型json结构函数名
gift_name 兑换券兑换商品名字,限6个汉字
gift_num 兑换券兑换商品数目,限三位数字
gift_unit 兑换券兑换商品的数量单位,限两个汉字
gift 兑换券类型时显示的礼品详情

Base_info(卡券基础信息)字段

字段 说明 是否必填
base_info 基本卡券数据,对于任何卡券类型base_info字段相同
logo_url 卡券商家LOGO,请使用调用 上传图片接口 获得的url
code_type 卡券的code类型 "CODE_TYPE_TEXT",文本; "CODE_TYPE_BARCODE",一维码; "CODE_TYPE_QRCODE",二维码; "CODE_TYPE_ONLY_QRCODE",二维码无code显示; "CODE_TYPE_ONLY_BARCODE",一维码无code显示; "CODE_TYPE_NONE"无code类型
brand_name 商家名字,上限为12个汉字
color 券颜色,请参考 选取卡券背景颜色接口文档
notice 使用提醒,上限为12个汉字(一句话描述,展示在首页,示例:请出示二维码核销卡券)
description 使用说明。长文本描述,可以分行,上限为1000个汉字
date_info 使用日期,有效期的信息,仅支持DATE_TYPE_FIX_TIME_RANGE
begin_timestamp DATE_TYPE_FIX_TIME_RANGE时专用,表示起用时间。从1970年1月1日00:00:00至起用时间的秒数,最终需转换为字符串形态传入,下同。(单位为秒)
end_timestamp DATE_TYPE_FIX_TIME_RANGE表示结束时间。从1970年1月1日00:00:00至起用时间的秒数,最终需转换为字符串形态传入。(单位为秒)
location_id_list 门店位置ID,请参考 微信 门店接口文档 ,朋友的券须至少传入一个可用poi_id,否则报错
can_share 是否支持分享到对话、朋友圈,与share_friends字段互斥,若创建朋友共享券此处应填入false,不可为空
can_give_friend 是否支持赠送,与share_friends字段互斥,若创建朋友共享券此处应填入false,不可为空
service_phone 客服电话
get_limit 领取限制,限制用户扫码或点击H5领取的次数
use_lim it 使用次数限制,限制单个微信号使用的次数
center_title 居中置顶的url标题,一般为快速核销或者快速买单,用于跳转商户自己开发的核销或者买单页面,9个中文字符以内。该cell仅限卡券状态正常,且处于有效期内的时候显示。
center_sub_title 居中置顶的url副标题,显示在标题下方,12个中文字符以内。该标题仅限卡券状态正常,且处于有效期内的时候显示。
center_url 居中置顶的url,该url仅限卡券状态正常,且处于有效期内的时候显示。
custom_url_name 商家自定义入口名称,与custom_url字段共同使用,长度限制在5个汉字内
custom_url 商家自定义入口跳转外链的地址链接,跳转页面内容需与自定义cell名称保持匹配
custom_url_sub_title 显示在入口右侧的tips,长度限制在6个汉字内
promotion_url_name 营销场景的自定义入口
promotion_url 入口跳转外链的地址链接。
promotion_url_sub_title 显示在入口右侧的tips,长度限制在6个汉字内

Advanced_info(卡券高级信息)字段

新增门槛字段,代金券类型(CASH)的卡券可以与满减门槛(least_cost字段)、指定品类可用/不可用门槛(accept_category/reject_category)不与其他优惠共享门槛组合使用。

兑换券类型(GIFT)的卡券可以与满减门槛(least_cost字段)、买送门槛(object_use_for字段)和不与其他优惠共享门槛组合使用。

字段 说明 是否必填
advanced_info 创建优惠券特有的高级字段
use_condition 使用门槛(条件)字段
accept_category 指定可用的商品类目,仅用于代金券类型,填入后将在券面拼写适用于xxx,标题自动拼为xxx减50元(若仅填入5个字),50元代金券(填入5个字以上)。
reject_category 指定不可用的商品类目,仅用于代金券类型,填入后将在券面拼写不适用于xxx。
least_cost 满减门槛字段,可用于兑换券和代金券,填入后将在全面拼写消费满xx元可用,标题自动拼为满xx减xx/满xx送xx(gift_name)
object_use_for 购买xx可用类型门槛,仅用于兑换,填入后自动拼写购买xxx可用,标题自动拼为买xx送xx(gift_name)
can_use_with_other_discount 不可以与其他类型共享门槛,填写false时系统将在使用须知里拼写不可与其他优惠共享,默认为true
abstract 封面摘要结构体名称
abstract 封面摘要简介。
icon_url_list 封面图片列表,仅支持填入一个封面图片链接, 上传图片接口 上传获取图片获得链接,填写非CDN链接会报错,并在此填入。建议图片尺寸像素850*350
text_image_list 图文列表,显示在详情内页,优惠券券开发者须至少传入一组图文列表
image_url 图片链接,必须调用 上传图片接口 上传图片获得链接,并在此填入,否则报错
text 图文描述,5000字以内
business_service 商家服务类型: BIZ_SERVICE_DELIVER 外卖服务;BIZ_SERVICE_FREE_PARK 停车位;BIZ_SERVICE_WITH_PET 可带宠物;BIZ_SERVICE_FREE_WIFI 免费wifi,可多选
time_limit 使用时段限制
type 限制类型枚举值:支持填入 MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 HOLIDAY 假期通用 此处只控制显示,不控制实际使用逻辑,不填默认不显示
begin_hour 当前type类型下的起始时间(小时),如当前结构体内填写了MONDAY,此处填写了10,则此处表示周一 10:00可用
begin_minute 当前type类型下的起始时间(分钟),如当前结构体内填写了MONDAY,begin_hour填写10,此处填写了59,则此处表示周一 10:59可用
end_hour 当前type类型下的结束时间(小时),如当前结构体内填写了MONDAY,此处填写了20,则此处表示周一 10:00-20:00可用
end_minute 当前type类型下的结束时间(分钟),如当前结构体内填写了MONDAY,begin_hour填写10,此处填写了59,则此处表示周一 10:59-00:59可用
consume_share_self_num 核销后送券的数量,可设置核销后送 本卡券 的数量,限制传入1张,与consume_share_card_list字段互斥
consume_share_card_list 核销后赠送 其他卡券 的列表,与consume_share_self_num字段互斥
card_id 核销后赠送的其他卡券card_id,目前仅支持填入一个共享券card_id,此处必须填入共享券
num 核销后赠送的该card_id数目,目前仅支持填1
share_friends 是否支持分享给朋友使用,填写true优惠券才可被共享

注意事项:

1.门槛字段用于拼接标题以及券面的优惠说明,请开发者务必按照要求选择填写,以免造成不必要的麻烦。

2.填入时间限制字段(time_limit),只控制显示,不控制实际使用逻辑,不填默认不显示。

返回数据

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

字段说明

字段名 说明
错误码 错误码,0为正常,40071为格式错误,请对比JSON示例排查错误
errmsg 错误信息
card_id 卡券id

4.5审核事件推送

生成的卡券通过审核时,微信会把这个事件推送到开发者填写的URL。 点击查看卡券事件推送机制

4.6朋友的券支持买单

同普通卡券一样,朋友的券一样支持微信快速买单,开通了微信支付的商户可以点击设置买单接口为朋友的券开通买单,便捷收银。

5 帮助

5.1错误码

错误码 说明 排错指引
40079 有效期错误 须将有效期设置为90天以内
40141 图片url错误 须使用将图片上传至CDN后获得的url
41025 缺少location_list 创建的JSON中须填入location_list(即poi_id,门店id)
42001 token过期 重新获取最新的token调用接口,若有多个调用源,需要统一管理token
47001 创建JSON结构错误 针对报错信息提示的位置对比示例排查

更多错误码,请见卡券全局错误码

5.2常见问题

1.为什么朋友的券不能在创建的时候填入库存?

朋友的券库存机制与普通券不同,开发者须先创建卡券后,到MP(商户后台)用券点充值库存,不支持在创建的时候填入库存。

2.为什么朋友的券只能创建三个月时长的卡券?

朋友的券不同于普通卡券,有很强的时效性和活动性,为了保证用户的券列表能常来常新,我们约定,每个商户最多只能创建时长不超过三个月(90天)的卡券。

3.卡券过期了券点会退吗?

若卡券过期时,card_id内尚有库存,我们会将库存折合券点退回商户的账户,周期为T+1(隔日退回)。


上一篇 : 朋友的券-朋友的券说明 下一篇: 朋友的券-配置库存、充值券点