alipay.marketing.cashlessvoucher.template.create (无资金券模板创建接口)

创建无资金券模板

公共参数

请求地址:
环境 HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do
公共请求参数:
参数 类型 是否必填 最大长度 描述 示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.marketing.cashlessvoucher.template.create
format String 40 仅支持JSON JSON
charset String 10 请求使用的编码格式,如utf-8,gbk,gb2312等 utf-8
sign_type String 10 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 RSA2
sign String 256 商户请求参数的签名串,详见签名 详见示例
timestamp String 19 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" 2014-07-24 03:07:50
version String 3 调用的接口版本,固定为:1.0 1.0
notify_url String 256 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 http://api.test.alipay.net/atinterface/receive_notify.htm
app_auth_token String 40 详见应用授权概述
biz_content String - 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
voucher_type String 必须 64 券类型,取值范围 代金券:CASHLESS_FIX_VOUCHER;兑换券(暂不支持):EXCHANGE_VOUCHER; CASHLESS_FIX_VOUCHER
brand_name String 必须 12 品牌名。用于在卡包中展示,长度不能超过12个字符,voucher_type值为代金券时:券名称=券面额+’元代金券’,voucher_type值为兑换券时:券名称=品牌名+“兑换券”组成 ,券名称最终用于卡包展示 星巴克
publish_start_time Date 必须 19 发放开始时间,早于该时间不能发券。发放开始时间不能大于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss 2017-04-25 00:00:00
publish_end_time Date 必须 19 发放结束时间,晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss 2017-04-30 23:59:59
voucher_valid_period String 必须 128 券有效期。有两种类型:绝对时间和相对时间。使用JSON字符串表示。绝对时间有3个key:type、start、end,type取值固定为"ABSOLUTE",start和end分别表示券生效时间和失效时间,格式为yyyy-MM-dd HH:mm:ss。绝对时间示例:{"type": "ABSOLUTE", "start": "2017-01-10 00:00:00", "end": "2017-01-13 23:59:59"}。相对时间有3个key:type、duration、unit,type取值固定为"RELATIVE",duration表示从发券时间开始到往后推duration个单位时间为止作为券的使用有效期,unit表示有效时间单位,有效时间单位可枚举:MINUTE, HOUR, DAY。示例:{"type": "RELATIVE", "duration": 1 , "unit": "DAY" },如果此刻发券,那么该券从现在开始生效1(duration)天(unit)后失效。 {"type": "ABSOLUTE", "start": "2017-01-10 00:00:00", "end": "2017-01-13 23:59:59"}
voucher_available_time String 必须 1024 券可用时段,JSON数组字符串,空数组即[],表示不限制,指定每周时间段示例:[{"day_rule": "1,2,3,4,5", "time_begin": "09:00:00", "time_end": "22:00:00"}, {"day_rule": "6,7", "time_begin": "08:00:00", "time_end": "23:00:00"}],数组中每个元素都包含三个key:day_rule, time_begin, time_end,其中day_rule表示周几,取值范围[1, 2, 3, 4, 5, 6, 7](周7表示星期日),多个值使用英文逗号隔开;time_begin和time_end分别表示生效起始时间和结束时间,格式为HH:mm:ss。另外,数组中各个时间规则是或关系。例如,[{"day_rule": "1,2,3,4,5", "time_begin": "09:00:00", "time_end": "22:00:00"}, {"day_rule": "6,7", "time_begin": "08:00:00", "time_end": "23:00:00"}]表示在每周的一,二,三,四,五的早上9点到晚上10点券可用或者每周的星期六和星期日的早上8点到晚上11点券可用。 仅支持代金券 [{"day_rule": "1,2,3,4,5", "time_begin": "09:00:00", "time_end": "22:00:00"}]
out_biz_no String 必须 64 外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号作唯一键 20170101000001654bb46ba
voucher_description String 必须 509 券使用说明。JSON数组字符串,最多可以有10条,每条最多50字。不采用时输入"[]" ["1、本券不可兑换现金,不可找零。","2、每个用户最多可以领取1张。","3、如果订单发生退款,优惠券无法退还。"]
voucher_quantity Number 必须 10 拟发行券的数量。单位为张。该数值必须是大于0的整数。 100
amount Price 特殊可选 10 面额。每张代金券可以抵扣的金额。币种为人民币,单位为元。该数值不能小于0,小数点以后最多保留两位。代金券必填,兑换券不能填 1.01
floor_amount Price 特殊可选 10 最低额度。设置券使用门槛,只有订单金额大于等于最低额度时券才能使用。币种为人民币,单位为元。该数值不能小于0,小数点以后最多保留两位。 代金券必填,兑换券不能填 10.00
rule_conf String 特殊可选 1024 规则配置,JSON字符串,{"PID": "2088512417841101,2088512417841102", "STORE": "123456,678901"},其中PID表示可以核销该券的pid列表,多个值用英文逗号隔开,PID为必传且需与接口调用PID同属一个商家,STORE表示可以核销该券的内部门店ID,多个值用英文逗号隔开 , 兑换券不能指定规则配置 {"PID": "2088512417841101,2088512417841102", "STORE": "123456,678901"}
notify_uri String 可选 128 券变动异步通知地址 https://www.yourdomain.com/reieve/voucher/flux
extension_info String 可选 1024 扩展字段,JSON字符串。目前支持使用模式扩展:{"useMode":"H5","useModeData":{"url":"http://www.yourdomian.com/yourusepage.htm","signKeys":"voucherId,userId,tag","charset":"UTF-8","signType":"RSA2","tag":"this is my tag"}}
其中如果useMode表示自定义的使用模式类型,目前仅支持"H5",表示在券详情页按钮跳转至自定义H5页面,当传入useMode参数后,将会检查useModeData对象数据,其中的url为必传参数;url字段表示客制化使用按钮跳转链接,传入该字段后在券详情使用时点击效果将会跳转此链接,链接将进行白名单过滤,如果无法接入成功请联系技术支持;signKeys字段表示跳转至客制链接时的加签字段,如果不传默认为voucherId,userId,tag;signType为加签类型,目前支持RSA及RSA2,如果不传则不会加签;charset为链接编码格式,不传默认为UTF-8;tag为自定义参数,会直接透传回使用链接;当传入合法加签信息后,券使用链接将为http://www.yourdomain.com/yourusepage.htm?voucherId=当前券id&userId=当前用户id&tag=传入tag&sign=对应算法及key生成的加签数据
{"useMode":"H5","useModeData":{"url":"http://www.yourdomian.com/yourusepage.htm","signType":"RSA2"}}

公共响应参数

参数 类型 是否必填 最大长度 描述 示例值
code String - 网关返回码,详见文档 40004
msg String - 网关返回码描述,详见文档 Business Failed
sub_code String - 业务返回码,详见文档 ACQ.TRADE_HAS_SUCCESS
sub_msg String - 业务返回码描述,详见文档 交易已被支付
sign String - 签名,详见文档 DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

响应参数

参数 类型 是否必填 最大长度 描述 示例值
template_id String 必填 28 模板ID 20140601000730010040000000EB

请求示例

  • JAVA
  • .NET
  • PHP
  • HTTP请求源码
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCashlessvoucherTemplateCreateRequest request = new AlipayMarketingCashlessvoucherTemplateCreateRequest();
request.setBizContent("{" +
"\"voucher_type\":\"CASHLESS_FIX_VOUCHER\"," +
"\"brand_name\":\"星巴克\"," +
"\"publish_start_time\":\"2017-04-2500:00:00\"," +
"\"publish_end_time\":\"2017-04-3023:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\":\\\"ABSOLUTE\\\",\\\"start\\\":\\\"2017-01-1000:00:00\\\",\\\"end\\\":\\\"2017-01-1323:59:59\\\"}\"," +
"\"voucher_available_time\":\"[{\\\"day_rule\\\":\\\"1,2,3,4,5\\\",\\\"time_begin\\\":\\\"09:00:00\\\",\\\"time_end\\\":\\\"22:00:00\\\"}]\"," +
"\"out_biz_no\":\"20170101000001654bb46ba\"," +
"\"voucher_description\":\"[\\\"1、本券不可兑换现金,不可找零。\\\",\\\"2、每个用户最多可以领取1张。\\\",\\\"3、如果订单发生退款,优惠券无法退还。\\\"]\"," +
"\"voucher_quantity\":100," +
"\"amount\":1.01," +
"\"floor_amount\":10.00," +
"\"rule_conf\":\"{\\\"PID\\\":\\\"2088512417841101,2088512417841102\\\",\\\"STORE\\\":\\\"123456,678901\\\"}\"," +
"\"notify_uri\":\"https://www.yourdomain.com/reieve/voucher/flux\"," +
"\"extension_info\":\"{\\\"useMode\\\":\\\"H5\\\",\\\"useModeData\\\":{\\\"url\\\":\\\"http://www.yourdomian.com/yourusepage.htm\\\",\\\"signType\\\":\\\"RSA2\\\"}}\"" +
"}");
AlipayMarketingCashlessvoucherTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"alipay_marketing_cashlessvoucher_template_create_response":{
		"msg":"Success",
		"code":"10000",
		"template_id":"20140601000730010040000000EB"
	}
}

异常示例

  • JSON示例
{
	"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE",
	"alipay_marketing_cashlessvoucher_template_create_response":{
		"msg":"Service Currently Unavailable",
		"code":"20000",
		"sub_msg":"系统繁忙",
		"sub_code":"isp.unknow-error"
	}
}

业务错误码

错误码 错误描述 解决方案
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
SYSTEM_ERROR 系统繁忙 1.发起业务重试 2.联系技术支持
INVALID_PARAMETER 参数有误参数有误,日期数据格式错误 日期格式必须为 yyyy-MM-dd H:mm:ss
INVALID_PARAMETER 参数有误参数有误,券张数格式错误 必须是大于0的整数
INVALID_PARAMETER 参数有误,无效的券面额参数有误,无效的券面额 1. 面额必须大于0元。2. 代金券面额不能小于最小面额。3. 代金券不能高于最大面额。4. 代金券面额与门槛金额比率不能低于最小比率
INVALID_PARAMETER 参数有误参数有误,无效的门槛金额 门槛金额应大于0元
INVALID_PARAMETER 参数有误参数有误,无效的时间 1.发放开始不能大于当前时间15天。 2.券的发放有效期跨度不能大于90天。
INVALID_PARAMETER 参数有误参数有误,无效的相对时间单位 时间单位必须为天(DAY),小时(HOUR),分钟(MINUTE)
INVALID_PARAMETER 参数有误 请按照文档检查参数
INVALID_PARAMETER 参数有误券类型错误 请按照文档要求传入券类型
INVALID_PARAMETER 参数有误传入券规则有误 请按照围挡说明修改券传入规则字段
INVALID_PARAMETER 参数有误业务异常传入业务参数中包含敏感词 请重新修改对应的业务参数
INVALID_PARAMETER 参数有误参数有误券有效期格错误 检查券有效期字段,修复后重新传入

公共错误码

触发通知类型

通知类型 描述 默认开启
voucher.use 若在创建券模板时传入了notify_uri字段并且有效,当创建的券产生核销行为时会执行调用 0

触发通知字段

参数 类型 是否必填 最大长度 描述 示例值
notify_type String [] 必填 16 通知类型。值为vcc_voucher_flux_notify,含义: 券变更通知 vcc_voucher_flux_notify
status String [] 必填 8 表示当前业务行为,可枚举[V_USE],其中V_USE表示券核销 V_USE
biz_content String [] 必填 2048 业务参数,json格式,具体内容请咨询技术支持。 {"alipay_biz_no":"123","biz_time":"2017-11-11 00:00:00","flux_amount":"5.00","voucher_id":"456":"partnerId":"201732321321"}

触发通知示例

https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync&notify_id=91722adff935e8cfa58b3aabf4dead6ibe&notify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&notify_type=vcc_voucher_flux_notify&status=V_USE&biz_content={"alipay_biz_no":"123","biz_time":"2017-11-11 00:00:00","flux_amount":"5.00","voucher_id":"456":"partnerId":"201732321321"}

异步通知验签方式

返回
顶部