alipay.marketing.exchangevoucher.template.create(兑换券模板创建接口) 在线调试(沙箱环境)

创建兑换券模板

公共参数

请求地址

环境HTTPS请求地址
正式环境 https://openapi.alipay.com/gateway.do

公共请求参数

参数 类型 是否必填最大长度描述示例值
app_id String 32 支付宝分配给开发者的应用ID 2014072300007148
method String 128 接口名称 alipay.marketing.exchangevoucher.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
app_auth_token String 40 详见应用授权概述
biz_content String 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档

请求参数

参数 类型 是否必填 最大长度 描述 示例值
out_biz_no String 必选 64 外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号作唯一键。 20180101000001654bb46ba
voucher_type String 必选 64 券类型,目前仅支持兑换券,即:EXCHANGE_VOUCHER EXCHANGE_VOUCHER
brand_name String 必选 12 品牌名。用于在卡包中展示,长度不能超过12个字符。 星巴克
voucher_name String 必选 20 券名称。用于在卡包中展示,长度不能超过20个字符。展示的实际名称为:券名称+兑换券。如,voucher_name为咖啡。则,卡包展示名称为:咖啡兑换券。 咖啡
voucher_quantity Number 必选 12 拟发行券的数量。单位为张。该数值必须是大于0的整数。 100
publish_start_time String 必选 19 发放开始时间,早于该时间不能发券。发放开始时间不能大于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss 2018-04-25 00:00:00
publish_end_time String 必选 19 发放结束时间,晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss 2018-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"}]
voucher_description String 必选 509 券使用说明。JSON数组字符串,最多可以有10条,每条最多50字。不采用时输入"[]" ["1、本券不可兑换现金,不可找零。","2、每个用户最多可以领取1张。","3、如果订单发生退款,优惠券无法退还。"]
use_type String 必选 20 用户核销方式设置,必填。目前仅支持:H5 H5
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页面;useModeData表示使用模式对象数据,必填,其中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"}}

响应参数

参数 类型 是否必填 最大长度 描述 示例值
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");
AlipayMarketingExchangevoucherTemplateCreateRequest request = new AlipayMarketingExchangevoucherTemplateCreateRequest();
request.setBizContent("{" +
"\"out_biz_no\":\"20180101000001654bb46ba\"," +
"\"voucher_type\":\"EXCHANGE_VOUCHER\"," +
"\"brand_name\":\"星巴克\"," +
"\"voucher_name\":\"咖啡\"," +
"\"voucher_quantity\":100," +
"\"publish_start_time\":\"2018-04-25 00:00:00\"," +
"\"publish_end_time\":\"2018-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\\\"}]\"," +
"\"voucher_description\":\"[\\\"1、本券不可兑换现金,不可找零。\\\",\\\"2、每个用户最多可以领取1张。\\\",\\\"3、如果订单发生退款,优惠券无法退还。\\\"]\"," +
"\"use_type\":\"H5\"," +
"\"notify_uri\":\"https://www.yourdomain.com/reieve/voucher/flux\"," +
"\"extension_info\":\"{\\\"useMode\\\":\\\"H5\\\",\\\"useModeData\\\":{\\\"url\\\":\\\"http://www.yourdomian.com/yourusepage.htm\\\",\\\"signType\\\":\\\"RSA2\\\"}}\"" +
"  }");
AlipayMarketingExchangevoucherTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

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

异常示例

{
    "alipay_marketing_exchangevoucher_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 参数有误,无效的时间 1.发放开始不能大于当前时间15天。 2.券的发放有效期跨度不能大于90天。
INVALID_PARAMETER 参数有误,无效的相对时间单位 时间单位必须为天(DAY),小时(HOUR),分钟(MINUTE)
INVALID_PARAMETER 参数有误 请按照文档检查参数
INVALID_PARAMETER 参数有误,券类型错误 请按照文档要求传入券类型
INVALID_PARAMETER 参数有误,传入业务参数中包含敏感词 请重新修改对应的业务参数
INVALID_PARAMETER 参数有误,券有效期格错误 检查券有效期字段,修复后重新传入
onlineServer