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 344 商户请求参数的签名串,详见签名 详见示例
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 券类型,取值范围为:
1. 定额代金券:CASHLESS_FIX_VOUCHER;
2. 不定额代金券 CASHLESS_RANDOM_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的整数。voucher_type为CASHLESS_FIX_VOUCHER时必填。 100
amount Price 特殊可选 10 面额。每张代金券可以抵扣的金额。币种为人民币,单位为元。该数值有效范围为1~999,小数点以后最多保留两位。代金券必填,兑换券不能填 1.01
total_amount Price 可选 12 券总金额(仅用于不定额券)。币种为人民币,单位为元。该数值需大于等于1,小于等于10,000,000,小数点以后最多保留两位。voucher_type为CASHLESS_RANDOM_VOUCHER时必填。 10000.00
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

响应参数

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

请求示例

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-25 00:00:00\"," +
"\"publish_end_time\":\"2017-04-30 23:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\": \\\"ABSOLUTE\\\", \\\"start\\\": \\\"2017-01-10 00:00:00\\\", \\\"end\\\": \\\"2017-01-13 23: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," +
"\"total_amount\":10000.00," +
"\"floor_amount\":10.00," +
"\"rule_conf\":\"{\\\"PID\\\": \\\"2088512417841101,2088512417841102\\\", \\\"STORE\\\": \\\"123456,678901\\\"}\"," +
"\"notify_uri\":\"https://www.yourdomain.com/reieve/voucher/flux\"" +
"  }");
AlipayMarketingCashlessvoucherTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_marketing_cashlessvoucher_template_create_response": {
        "code": "10000",
        "msg": "Success",
        "template_id": "20140601000730010040000000EB"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

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

业务错误码

公共错误码

错误码错误描述解决方案
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

触发通知示例

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"}
onlineServer