- 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码给用户。
参数名 | 描述 |
---|---|
card_id | 卡券ID。一个卡券ID对应一类卡券,包含了相应库存数量的Code码。 |
code | 卡券Code码。一张卡券的唯一标识,核销卡券时使用此串码,支持商户自定义。 |
2.2.2 是否自定义Code码
微信卡券的Code码可由微信后台随机分配,同时支持商户自定义,两者的区别如下:
类别 | 使用场景 | 创建 | 投放 | 核销 |
---|---|---|---|---|
自定义Code码 | 通常为商户在现有业 务已有一套Code码体系。 | "use_custom_code":true ,仅支持API创建。 | 卡券投放接口中填入code字段值。 | 仅支持调用API接口核销。 |
非自定义Code码 | 可使用微信的Code码体 系完成投放、核销。 | "use_custom_code":false ,支持API创建、公众平台创建 (默认为非自定义Code码)。 | 卡券投放接口中无需填写code字段,由微信后台分配。 | 支持卡券核销助手公众号核销、公众平台网页核销、API接口核销。 |
导入code模式 | 商户须用自己的code码体系 ,且要通过微信渠道下发卡券 (如:二维码/群发/货架等) | "use_custom_code":tru e且get_custom_code_mode: " GET_CUSTOM_CODE_MODE_DEPOSIT " | 卡券侧随机在导入的code中下发,不可指定,投放接口不可传code字段 | 核销时需同时传入card_id和code,仅支持API |
*备注:自定义code码的开发者若想要获得和非自定义code商户相同的群发卡券、客服消息派发卡券的能力。可以通过 导入自定义code接口将非定义code导入到微信服务器,*若仅在h5投放则无须导入,导入code后code由微信随机下发,不可指定。
2.2.3 选择合适的码型
商户可以根据自身的业务模式和能支持的核销方式,选择合适的券面码型,并在创建卡券填入code_type字段。
举例:若A商户选了二维码类型的卡券,则A商户的核销员在核销时可以通过手机商户助手扫码核销卡券;若B商户选择了仅code类型的
码型,则其核销员就只能通过输入串号的方式核销卡券。
类别 | 字段名 | 适用核销方式 |
---|---|---|
二维码/一维码显示code | CODE_TYPE_QRCODE/CODE_TYPE_BARCODE | 适用于扫码/输码核销 |
二维码不显示code | CODE_TYPE_ONLY_QRCODE | 仅适用于扫码核销 |
仅code类型 | CODE_TYPE_TEXT | 仅适用于输码核销 |
无code类型 | CODE_TYPE_NONE | 仅适用于线上核销,开发者须自定义跳转链接跳转至H5页面,允许用户核销掉卡券,自定义cell的名称可以命名为“立即使用” |
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网页。
三个自定义入口基于不同的场景定位设置,区别如下:
类别 | 示例 | 字段 | 显示逻辑 |
---|---|---|---|
使用场景入口 | 立即使用 | 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 | 卡券处于正常状态、转赠中、核销后等异常状态均显示该入口。 |
不同入口示例:
# 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
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
buffer | 是 | 文件的数据流 |
access_token | 是 | 调用接口凭证 |
请求数据
调用示例(使用curl命令,用FORM表单方式上传一个图片):curl –Fbuffer=@test.jpg
返回数据
返回正确的示例:{"url":"http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0"}返回错误的示例{"errcode":40009,"errmsg":"invalid image size"}
参数说明
参数名 | 描述 |
---|---|
errcode | 错误码 |
errmsg | 错误信息 |
url | 商户图片url,用于创建卡券接口中填入。特别注意:该链接仅用于微信相关业务,不支持引用。 |
# 2.4 步骤二:设置卡券适用门店
请点击查看微信门店接口文档,获取门店 ID 后填入创建卡券接口中的相应字段 location_id_list,即可设置该卡券的适用门店。
# 2.5 步骤三:选取卡券背景颜色
选择适用色值,在步骤四:创建卡券中将颜色名(如Color010)填入color字段。
目前微信提供包括以上十种色值的共计十四种色值供开发者使用。
背景颜色名称 | 色值 |
---|---|
Color010 | #63b359 |
Color020 | #2c9f67 |
Color030 | #509fc9 |
Color040 | #5885cf |
Color050 | #9062c0 |
Color060 | #d09a45 |
Color070 | #e4b138 |
Color080 | #ee903c |
Color081 | #f08500 |
Color082 | #a9d92d |
Color090 | #dd6549 |
Color100 | #cc463d |
Color101 | #cf3e36 |
Color102 | #5E6671 |
##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
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 调用接口凭证 |
POST数据 | 是 | Json数据 |
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元 "
}
}}
字段示图
团购券
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
card_type | 是 | string(24) | GROUPON | 团购券类型。 |
base_info | 是 | JSON结构 | 见上述示例。 | 基本的卡券数据 ,见下表,所有卡券类型通用。 |
deal_detail | 是 | string( 3072 ) | 双人套餐\n -进口红酒一支。\n孜然牛肉一份。 | 团购券专用,团购详情。 |
JSON示例
{
"card": {
"card_type": "GROUPON",
"groupon": {
"base_info": {
················
},
"advanced_info": {
················
},
"deal_detail": "示例"
}
}
}
代金券
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
card_type | 是 | string(24) | CASH | 代金券类型。 |
base_info | 是 | JSON结构 | 见上述示例。 | 基本的卡券数据,见下表,所有卡券通用。 |
least_cost | 是 | int | 10000 | 代金券专用,表示起用金额(单位为分),如果无起用门槛则填0。 |
reduce_cost | 是 | int | 10000 | 代金券专用,表示减免金额。(单位为分) |
JSON示例
{
"card": {
"card_type": "CASH",
"cash": {
"base_info": {
················
},
"advanced_info": {
················
},
"least_cost": 1000,
"reduce_cost": 100,
}
}
}
折扣券
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
card_type | 是 | string(24) | DISCOUNT | 折扣券类型。 |
base_info | 是 | Json结构 | 见上述示例。 | 基本的卡券数据 ,见下表,所有卡券通用。 |
discount | 是 | int | 30 | 折扣券专用,表示打折额度(百分比)。填30就是七折。 |
JSON示例:
{
"card": {
"card_type": "DISCOUNT",
"discount": {
"base_info": {
················
},
"advanced_info": {
················
},
"discount": 30
}
}
}
兑换券
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
card_type | 是 | string(24) | GIFT | 兑换券类型。 |
base_info | 是 | Json结构 | 见上述示例。 | 基本的卡券数据 ,所有卡券通用。 |
gift | 是 | string(3072) | 可兑换音乐木盒一个。 | 兑换券专用,填写兑换内容的名称。 |
JSON示例
{
"card": {
"card_type": "GIFT",
"gift": {
"base_info": {
················
},
"advanced_info": {
················
},
"gift":"可兑换音乐木盒一个"
}
}
}
优惠券
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
card_type | 是 | string(24) | GENERAL_COUPON | 优惠券类型。 |
base_info | 是 | Json结构 | 见上述示例。 | 基本的卡券数据 ,见下表,所有卡券通用。 |
default_detail | 是 | string(3072) | 音乐木盒。 | 优惠券专用,填写优惠详情。 |
JSON示例
{
"card": {
"card_type": "GENERAL_COUPON",
"general_coupon": {
"base_info": {
················
},
"advanced_info": {
················
},
"default_detail":"优惠券专用,填写优惠详情"
}
}
}
# 2.7 卡券基础信息字段(重要)
base_info(卡券基础信息)字段-必填字段
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
logo_url | 是 | strin g(128) | http://mmbiz.qpic.cn/ | 卡券的商户logo,建议像素为300*300。 |
code_type | 是 | string(16) | CODE_TYPE_TEXT | 码型: "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 | 是 | string(36) | 海底捞 | 商户名字,字数上限为12个汉字。 |
title | 是 | string(27) | 双人套餐100元兑换券 | 卡券名,字数上限为9个汉字。(建议涵盖卡券属性、服务及金额)。 |
color | 是 | string(16) | Color010 | 券颜色。按色彩规范标注填写Color010-Color100。 |
notice | 是 | string(48) | 请出示二维码 | 卡券使用提醒,字数上限为16个汉字。 |
description | 是 | strin g (3072) | 不可与其他优惠同享 | 卡券使用说明,字数上限为1024个汉字。 |
sku | 是 | JSON结构 | 见上述示例。 | 商品信息。 |
quantity | 是 | int | 100000 | 卡券库存的数量,上限为100000000。 |
date_info | 是 | JSON结构 | 见上述示例。 | 使用日期,有效期的信息。 |
type | 是 | string | DATE_TYPE_FIX TIME_RANGE 表示固定日期区间,DATE_TYPE FIX_TERM 表示固定时长 (自领取后按天算。 | 使用时间的类型,旧文档采用的1和2依然生效。 |
begin_time stamp | 是 | unsigned int | 14300000 | type为DATE_TYPE_FIX_TIME_RANGE时专用,表示起用时间。从1970年1月1日00:00:00至起用时间的秒数,最终需转换为字符串形态传入。(东八区时间,UTC+8,单位为秒) |
end_time stamp | 是 | unsigned int | 15300000 | 表示结束时间 , 建议设置为截止日期的23:59:59过期 。 ( 东八区时间,UTC+8,单位为秒 ) |
fixed_term | 是 | int | 15 | type为DATE_TYPE_FIX_TERM时专用,表示自领取后多少天内有效,不支持填写0。 |
fixed_begin _term | 是 | int | 0 | type为DATE_TYPE_FIX_TERM时专用,表示自领取后多少天开始生效,领取后当天生效填写0。(单位为天) |
end_time s tamp | 否 | unsigned int | 15300000 | 可用于DATE_TYPE_FIX_TERM时间类型,表示卡券统一过期时间 , 建议设置为截止日期的23:59:59过期 。 ( 东八区时间,UTC+8,单位为秒 ),设置了fixed_term卡券,当时间达到end_timestamp时卡券统一过期 |
base_info(卡券基础信息)字段-非必填字段
参数名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|
use_custom_code | 否 | bool | true | 是否自定义Code码 。填写true或false,默认为false。 通常自有优惠码系统的开发者选择 自定义Code码,并在卡券投放时带入 Code码,详情见 是否自定义Code码 。 |
get_custom_code_mode | 否 | string(32) | GET_CUSTOM_COD E_MODE_DEPOSIT | 填入 GET_CUSTOM_CODE_MODE_DEPOSIT 表示该卡券为预存code模式卡券, 须导入超过库存数目的自定义code后方可投放, 填入该字段后,quantity字段须为0,须导入code 后再增加库存 |
bind_openid | 否 | bool | true | 是否指定用户领取,填写true或false 。默认为false。通常指定特殊用户群体 投放卡券或防止刷券时选择指定用户领取。 |
service_phone | 否 | string(24) | 40012234 | 客服电话。 |
location_id_list | 否 | array | 1234,2312 | 门店位置poiid。 调用 POI门店管理接 口 获取门店位置poiid。具备线下门店 的商户为必填。 |
use_all_locations | 否 | bool | true | 设置本卡券支持全部门店,与location_id_list互斥 |
center_title | 否 | string(18) | 立即使用 | 卡券顶部居中的按钮,仅在卡券状 态正常(可以核销)时显示 |
center_sub_title | 否 | string(24) | 立即享受优惠 | 显示在入口下方的提示语 ,仅在卡券状态正常(可以核销)时显示。 |
center_url | 否 | string(128) | www.qq.com | 顶部居中的url ,仅在卡券状态正常(可以核销)时显示。 |
center_app_brand_user_name | 否 | string(128) | gh_86a091e50ad4@app | 卡券跳转的小程序的user_name,仅可跳转该 公众号绑定的小程序 。 |
center_app_brand_pass | 否 | string(128) | API/cardPage | 卡券跳转的小程序的path |
custom_url_name | 否 | string(15) | 立即使用 | 自定义跳转外链的入口名字。 |
custom_url | 否 | string(128) | www.qq.com | 自定义跳转的URL。 |
custom_url_sub_title | 否 | string(18) | 更多惊喜 | 显示在入口右侧的提示语。 |
custom _app_brand_user_name | 否 | string(128) | gh_86a091e50ad4@app | 卡券跳转的小程序的user_name,仅可跳转该 公众号绑定的小程序 。 |
custom _app_brand_pass | 否 | string(128) | API/cardPage | 卡券跳转的小程序的path |
promotion_url_name | 否 | string(15) | 产品介绍 | 营销场景的自定义入口名称。 |
promotion_url | 否 | string(128) | www.qq.com | 入口跳转外链的地址链接。 |
promotion_url_sub_title | 否 | string(18) | 卖场大优惠。 | 显示在营销入口右侧的提示语。 |
promotion _app_brand_user_name | 否 | string(128) | gh_86a091e50ad4@app | 卡券跳转的小程序的user_name,仅可跳转该 公众号绑定的小程序 。 |
promotion _app_brand_pass | 否 | string(128) | API/cardPage | 卡券跳转的小程序的path |
get_limit | 否 | int | 1 | 每人可领券的数量限制,不填写默认为50。 |
use_limit | 否 | int | 100 | 每人可核销的数量限制,不填写默认为50。 |
can_share | 否 | bool | false | 卡券领取页面是否可分享。 |
can_give_friend | 否 | bool | false | 卡券是否可转赠。 |
Advanced_info(卡券高级信息)字段
字段 | 是否必填 | 类型 | 说明 |
---|---|---|---|
advanced_info | 否 | JSON结构 | 创建优惠券特有的高级字段 |
use_condition | 否 | JSON结构 | 使用门槛(条件)字段,若不填写使用条件则在券面拼写 :无最低消费限制,全场通用,不限品类;并在使用说明显示: 可与其他优惠共享 |
accept_category | 否 | string(512) | 指定可用的商品类目,仅用于代金券类型 ,填入后将在券面拼写适用于xxx |
reject_category | 否 | string( 512 ) | 指定不可用的商品类目,仅用于代金券类型 ,填入后将在券面拼写不适用于xxxx |
least_cost | 否 | int | 满减门槛字段,可用于兑换券和代金券 ,填入后将在全面拼写消费满xx元可用。 |
object_use_for | 否 | string( 512 ) | 购买xx可用类型门槛,仅用于兑换 ,填入后自动拼写购买xxx可用。 |
can_use_with_other_discount | 否 | bool | 不可以与其他类型共享门槛 ,填写false时系统将在使用须知里 拼写“不可与其他优惠共享”, 填写true时系统将在使用须知里 拼写“可与其他优惠共享”, 默认为true |
abstract | 否 | JSON结构 | 封面摘要结构体名称 |
abstract | 否 | string(24 ) | 封面摘要简介。 |
icon_url_list | 否 | array | 封面图片列表,仅支持填入一 个封面图片链接, 上传图片接口 上传获取图片获得链接,填写 非CDN链接会报错,并在此填入。 建议图片尺寸像素850*350 |
text_image_list | 否 | JSON结构 | 图文列表,显示在详情内页 ,优惠券券开发者须至少传入 一组图文列表 |
image_url | 否 | string(128 ) | 图片链接,必须调用 上传图片接口 上传图片获得链接,并在此填入, 否则报错 |
text | 否 | string(512 ) | 图文描述 |
business_service | 否 | array | 商家服务类型: BIZ_SERVICE_DELIVER 外卖服务; BIZ_SERVICE_FREE_PARK 停车位; BIZ_SERVICE_WITH_PET 可带宠物; BIZ_SERVICE_FREE_WIFI 免费wifi, 可多选 |
time_limit | 否 | JSON结构 | 使用时段限制,包含以下字段 |
type | 否 | string(24 ) | 限制类型枚举值:支持填入 MONDAY 周一 TUESDAY 周二 WEDNESDAY 周三 THURSDAY 周四 FRIDAY 周五 SATURDAY 周六 SUNDAY 周日 此处只控制显示, 不控制实际使用逻辑,不填默认不显示 |
begin_hour | 否 | int | 当前type类型下的起始时间(小时) ,如当前结构体内填写了MONDAY, 此处填写了10,则此处表示周一 10:00可用 |
begin_minute | 否 | int | 当前type类型下的起始时间(分钟) ,如当前结构体内填写了MONDAY, begin_hour填写10,此处填写了59, 则此处表示周一 10:59可用 |
end_hour | 否 | int | 当前type类型下的结束时间(小时) ,如当前结构体内填写了MONDAY, 此处填写了20, 则此处表示周一 10:00-20:00可用 |
end_minute | 否 | int | 当前type类型下的结束时间(分钟) ,如当前结构体内填写了MONDAY, begin_hour填写10,此处填写了59, 则此处表示周一 10:59-00:59可用 |
注意事项:
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"}
参数名 | 描述 |
---|---|
errcode | 错误码,0为正常。 |
errmsg | 错误信息。 |
card_id | 卡券ID。 |
# 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
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 调用接口凭证 |
POST数据 | 是 | Json数据 |
POST数据
{ “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“, “is_open”: true}
字段说明
字段名 | 说明 |
---|---|
card_id | 卡券ID。 |
is_open | 是否开启买单功能,填true/false |
返回数据
{ "errcode":0, "errmsg":"ok" }
字段说明
字段名 | 说明 |
---|---|
错误码 | 错误码,0为正常;43008为商户没有开通微信支付权限或者没有在商户后台申请微信买单功能; |
errmsg | 错误信息 |
注意事项:
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>
参数 | 说明 |
---|---|
ToUserName | 开发者微信号。 |
FromUserName | 发送方账号(一个OpenID)。 |
CreateTime | 消息创建时间 (整型)。 |
MsgType | 消息类型,event。 |
Event | 事件类型,User_pay_from_pay_cell(微信买单事件) |
CardId | 卡券ID。 |
UserCardCode | 卡券Code码。 |
TransId | 微信支付交易订单号(只有使用买单功能核销的卡券才会出现) |
LocationName | 门店名称,当前卡券核销的门店名称(只有通过卡券商户助手和买单核销时才会出现) |
Fee | 实付金额,单位为分 |
OriginalFee | 应付金额,单位为分 |
#4 设置自助核销
功能介绍
自助核销与扫码/输码核销互为补充,卡券商户助手通过扫码/输码完成核销的同时,也确保了用券的真实性,适合有强对账需求的商户使用;而自助核销由用户发起,全程由用户操作,适合对账需求不强的商户使用。
目前,自助核销可能适合以下场景使用:
1.不允许店员上班期间带手机;
2.高峰期店内人流量大,扫码/输码核销速度不能满足短时需求;
3.会议入场,短时有大量核销任务;
# 4.1 设置自助核销接口
接口说明
创建卡券之后,开发者可以通过设置微信买单接口设置该card_id支持自助核销功能。值得开发者注意的是,设置自助核销的card_id必须已经配置了门店,否则会报错。
接口调用请求说明
HTTP请求方式: POSTURL:https://api.weixin.qq.com/card/selfconsumecell/set?access_token=TOKEN
参数说明
参数 | 是否必须 | 说明 |
---|---|---|
access_token | 是 | 调用接口凭证 |
POST数据 | 是 | Json数据 |
POST数据
{ “card_id”:“ph_gmt7cUVrlRk8swPwx7aDyF-pg“, “is_open”: true}
字段说明
字段名 | 说明 |
---|---|
card_id | 卡券ID。 |
is_open | 是否开启自助核销功能,填true/false,默认为false |
need_verify_cod | 用户核销时是否需要输入验证码, 填true/false, 默认为false |
need_remark_amount | 用户核销时是否需要备注核销金额, 填true/false, 默认为false |
返回数据
{ "errcode":0, "errmsg":"ok" }
字段说明
字段名 | 说明 |
---|---|
错误码 | 错误码,0为正常;45046为该card_id已经设置了买单功能,不可变更为自助核销功能,设置冲突 |
errmsg | 错误信息 |
注意事项:
1.设置自助核销的卡券须支持至少一家门店,否则无法设置成功;
2.若该卡券设置了center_url(居中使用跳转链接),须先将该设置更新为空后再设置自助核销功能方可生效。
#5 接口调试工具
开发者可以通过 卡券创建接口在线调试工具进行卡券创建HelloWorld。获取到access_token后,开发者可以将要POST的JSON数据贴至接口调试工具中,获得Card_id以进行下一步投放动作。