alipay.marketing.cashitemvoucher.template.create(有资金单品券创建) 在线调试(沙箱环境)

创建有资金单品券

公共参数

请求地址

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

公共请求参数

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

请求参数

参数 类型 是否必填 最大长度 描述 示例值
voucher_type String 必选 50 有资金单品券券类型,目前仅支持有资金单品代金券(ITEM_BALANCE_FIX_VOUCHER)、有资金单品折扣券(ITEM_BALANCE_DISCOUNT_VOUCHER)、有资金单品特价券(ITEM_BALANCE_SPE_VOUCHER) ITEM_BALANCE_FIX_VOUCHER
brand_name String 必选 12 商家品牌名称。最多12个字符 商户自定义,在通用模板中展示在券LOGO下方。根据券使用场景的不同,该信息的展示位置可能会有不同。 XXX餐馆
goods_cover_image_id String 必选 32 单品券封面图片。 请先通过图片上传接口:alipay.marketing.material.image.upload上传图片。通过图片上传接口获取获得图片资源id以后,将该图片资源id传入,单张大小不超过2MB,格式支持png、gif、jpg、jpeg、bmp,尺寸为800X600 wrRVcFO9RSSVp9ajsBQHQAAAACMAAQQD
goods_name String 必选 12 商品名称。最多12个字 XXX牛肉面
goods_info String 必选 120 商品描述信息。 用于券面展示,向用户介绍商品,最多120字。 好吃的XXX面,不腻
goods_id String 必选 16384 可优惠商品编码。多个编码标点隔开,不能含有重复id,最多3千个单品数量。当用户支付时,交易中的商品编码和单品券配置的商品编码有任一匹配时,可以使用单品优惠券。 787719,17893,abcdef,17893aaa
floor_amount Price 必选 10 消费门槛金额。 达到消费门槛金额以后用户可以享受优惠,消费门槛金额不能小于0.1元,不能超过9999元。 50
voucher_description String 必选 1000 券使用说明。JSON数组字符串,最多可以有10条,每条最多50字。必须写明券的使用条件、领取条件、退款规则,请参考示例; ["1、本券不可兑换现金,不可找零。","2、每个用户最多可以领取1张。","3、如果订单发生退款,优惠券无法退还。"]
rule_conf String 必选 1024 规则配置,JSON字符串,{"PID": "2088512417841101,2088512417841102", "STORE": "123456,678901"},其中PID表示可以核销该券的pid列表,多个值用英文逗号隔开,PID为必传且必须签约当面付,STORE表示可以核销该券的内部门店ID,多个值用英文逗号隔开 。仅支持PID和STOREID核销规则,PID列表和门店ID列表均不能含有重复ID,并且门店ID数量最多支持3000个。 {"PID": "2088512417841101,2088512417841102", "STORE": "123456,678901"}
publish_start_time Date 必选 19 发放开始时间,早于该时间不能发券。发放开始时间不能大于当前时间15天。格式为:yyyy-MM-dd HH:mm:ss 2019-06-25 00:00:00
publish_end_time Date 必选 19 发放结束时间,晚于该时间不能发券。券的发放结束时间和发放开始时间跨度不能大于90天。发放结束时间必须晚于发放开始时间。格式为:yyyy-MM-dd HH:mm:ss 2019-07-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"}
out_biz_no String 必选 64 外部业务单号。用作幂等控制。同一个pid下相同的外部业务单号作唯一键。 20190101000001654bb46ba
voucher_quantity String 必选 8 券发放数量 10000000
fund_account String 必选 64 出资人登录账号。用于发券的资金会从该账号划拨到发券专用账户上。当调用创建接口成功后,会返回付款订单页面,仅当前传入资金账号可进行付款,付款完成后券变更为激活状态,可进行发放。 13040045386
goods_ceiling_quantity Number 特殊可选 10 所有商品最多可享折扣数量。 当用户购买多件时,最多可以对几件特价支付。假设券类型为有资金单品特价券(ITEM_BALANCE_SPE_VOUCHER),商品编码填写A、B,此参数传入2,则订单中不管是A或者B,一共只能优惠2件,第3件以上原价。必须是整数,最低数量为1,最高99。券类型为有资金单品折扣券(ITEM_BALANCE_DISCOUNT_VOUCHER)和有资金单品特价券(ITEM_BALANCE_SPE_VOUCHER)时必填,有资金单品代金券(ITEM_BALANCE_FIX_VOUCHER)下此值必须为0。 1
goods_origin_price Price 特殊可选 10 商品原价。 当voucher_type为有资金单品折扣券(ITEM_BALANCE_DISCOUNT_VOUCHER)和有资金单品特价券(ITEM_BALANCE_SPE_VOUCHER)时必选,有资金单品代金券类型(ITEM_BALANCE_FIX_VOUCHER)下此值必须为空。用于计算最大优惠价格(最大优惠价格的计算方式请参考产品说明文档)。 10.00
amount Price 特殊可选 10 代金券面额。 当voucher_type为有资金单品代金券(ITEM_BALANCE_FIX_VOUCHER)时必选。币种为人民币,单位为元。该数值不能小于0.1,且不能大于999元,代表订单金额达到使用门槛后,本券可抵扣相应面额资金。 代金券面额以门槛消费金额为基准,换算成折扣,不能低于9.95折。 当voucher_type为有资金单品折扣券(ITEM_BALANCE_DISCOUNT_VOUCHER)和有资金单品特价券(ITEM_BALANCE_SPE_VOUCHER)时此值必须为空。 10.00
discount Number 特殊可选 4 单品价格可以享受的折扣力度(如填写0.9就表示9折)。 该值必须大于等于0.1且小于1,小数点以后最多保留两位,voucher_type为有资金单品折扣券(ITEM_BALANCE_DISCOUNT_VOUCHER)时必选,其他券类型场景此值必须为0。 0.88
special_price Price 特殊可选 10 特价面额。使用特定价格购买单品,币种为人民币,最高特价面额不能超过999元,不可为负值。voucher_type为有资金单品特价券(ITEM_BALANCE_SPE_VOUCHER)时必选,其他券类型场景此值必须为空。 5
goods_detail_image_ids String 可选 128 单品券详情图片。 请先通过图片上传接口:alipay.marketing.material.image.upload上传图片。通过图片上传接口获取获得图片资源id以后,将该图片资源id传入,单张大小不超过2MB,格式支持png、gif、jpg、jpeg、bmp,尺寸为800X600。 最多支持3张单品详情图片,图片资源id用英文逗号分隔,不可含有重复资源ID。 wrRVcFO9RSSVp9ajsBQHQAAAACMAAQQD,wrRVcFO9RSSVp9ajsBQHQAAAACMAAAQC
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"}]
notify_uri String 可选 128 券变动异步通知地址 https://www.yourdomain.com/reieve/voucher/flux
redirect_uri String 可选 1024 重定向地址。支付成功后需要重定向的地址,如果为空则不做重定向。 https://www.yourdomain.com/alipay/pay/success

响应参数

参数 类型 是否必填 最大长度 描述 示例值
voucher_discount_limit Price 必填 10 使用一张单品券用户可以获得的最大优惠。计算方式和单张券的最大优惠的上限请参考产品说明文档 50.00
template_id String 必填 28 券模板ID 20140601000730010040000000EB
fund_order_no String 必填 32 资金订单号,模板支付时需要 2017011910002001200202502849
confirm_uri String 必填 256 模板支付确认链接 https://promocenter.alipay.com/voucher/templatePayment.htm?templateId=20140601000730010040000000EB

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCashitemvoucherTemplateCreateRequest request = new AlipayMarketingCashitemvoucherTemplateCreateRequest();
request.setBizContent("{" +
"\"voucher_type\":\"ITEM_BALANCE_FIX_VOUCHER\"," +
"\"brand_name\":\"XXX餐馆\"," +
"\"goods_cover_image_id\":\"wrRVcFO9RSSVp9ajsBQHQAAAACMAAQQD\"," +
"\"goods_name\":\"XXX牛肉面\"," +
"\"goods_info\":\"好吃的XXX面,不腻\"," +
"\"goods_id\":\"787719,17893,abcdef,17893aaa\"," +
"\"floor_amount\":50," +
"\"voucher_description\":\"[\\\"1、本券不可兑换现金,不可找零。\\\",\\\"2、每个用户最多可以领取1张。\\\",\\\"3、如果订单发生退款,优惠券无法退还。\\\"]\"," +
"\"rule_conf\":\"{\\\"PID\\\": \\\"2088512417841101,2088512417841102\\\", \\\"STORE\\\": \\\"123456,678901\\\"}\"," +
"\"publish_start_time\":\"2019-06-25 00:00:00\"," +
"\"publish_end_time\":\"2019-07-30 23:59:59\"," +
"\"voucher_valid_period\":\"{\\\"type\\\": \\\"ABSOLUTE\\\", \\\"start\\\": \\\"2017-01-10 00:00:00\\\", \\\"end\\\": \\\"2017-01-13 23:59:59\\\"}\"," +
"\"out_biz_no\":\"20190101000001654bb46ba\"," +
"\"voucher_quantity\":\"10000000\"," +
"\"fund_account\":\"13040045386\"," +
"\"goods_ceiling_quantity\":1," +
"\"goods_origin_price\":10.00," +
"\"amount\":10.00," +
"\"discount\":0.88," +
"\"special_price\":5," +
"\"goods_detail_image_ids\":\"wrRVcFO9RSSVp9ajsBQHQAAAACMAAQQD,wrRVcFO9RSSVp9ajsBQHQAAAACMAAAQC\"," +
"\"voucher_available_time\":\"[{\\\"day_rule\\\": \\\"1,2,3,4,5\\\", \\\"time_begin\\\": \\\"09:00:00\\\", \\\"time_end\\\": \\\"22:00:00\\\"}]\"," +
"\"notify_uri\":\"https://www.yourdomain.com/reieve/voucher/flux\"," +
"\"redirect_uri\":\"https://www.yourdomain.com/alipay/pay/success\"" +
"  }");
AlipayMarketingCashitemvoucherTemplateCreateResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

响应示例

{
    "alipay_marketing_cashitemvoucher_template_create_response": {
        "code": "10000",
        "msg": "Success",
        "voucher_discount_limit": 50,
        "template_id": "20140601000730010040000000EB",
        "fund_order_no": "2017011910002001200202502849",
        "confirm_uri": "https://promocenter.alipay.com/voucher/templatePayment.htm?templateId=20140601000730010040000000EB"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "alipay_marketing_cashitemvoucher_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.联系技术支持
VOUCHER_TYPE_ERROR 不支持的券类型 不支持的券类型,请根据入参为voucher_type的文档提示修改券类型参数
FLOOR_AMOUNT_OVERFLOW 门槛消费金额超过上限 查看入参信息floor_amount一栏,填写合理范围内的门槛消费金额
PIC_SIZE_ILLEGAL 图片尺寸不符合规则 参考入参信息goods_cover_image_id一栏,选择合适的宽高的图片重新上传
INVALID_DATE_PARAMETER 日期格式错误或者不在预期的时间范围内 可能的原因有(具体错误原因会在接口错误信息中说明,依据具体情况修改入参): 1.入参中间含有错误的日期格式。请参考系统返回的错误详情信息将参数修改成正确的值。 2.券的发放有效期跨度(开始时间到结束时间)不能大于90天 3.发放开始不能大于当前时间15天 4.券的结束时间小于当前时间
SPECIAL_AMOUNT_OVERFLOW 请求参数非法,商品特价金额超过上限 请参考特价金额(special_price)入参字段说明,修改特价金额,不能超过上限值
IMAGE_ID_NOT_EXISTS 图片资源id不存在 请使用正确的图片资源id,或者参考入参goods_cover_image_id说明,重新上传图片,获取图片资源id
PERMISSION_DENIED 此图片资源Id对应的图片的拥有者不是当前接口的调用方 请当前接口调用方调用图片上传接口,重新上传图片
INVALID_FLOOR_PARAMETER 错误的门槛金额 请参考门槛金额(floor_amount)一栏,修改门槛金额入参
GOODS_DUPLICATE 可优惠商品列表含有重复商品id 修改入参商品id集合(goods_id),不能含有重复的商品id
STORE_COUNT_OVERFLOW 核销规则门店数量超过限制 可核销门店数量不能超过限制大小,请修改核销规则入参(rule_conf)
DISCOUNT_AMOUNT_OVERFLOW 单张折扣券优惠金额超过上限 请参考产品文档中单张折扣券优惠金额计算方式和折扣金额的上限说明,修改折扣优惠(discount)入参、或者商品原价(goods_origin_price)入参或者优惠封顶数量上限(goods_ceiling_quantity)入参,使得计算后的折扣金额小于目前允许的折扣金额上限。
INVALID_AMOUNT_PARAMETER 代金券面额以门槛消费金额为基准,换算成折扣,不能低于9.95折 修改amount入参,使得以门槛消费金额为基准,换算成折扣,必须低于9.95折
IMAGE_INFOSEC_CHECK_FAILED 图片安全风险校验不通过|商品图片审核失败 调用营销通用图片上传API,重新上传图片
IMAGE_INFOSEC_CHECK_WAITING 图片还在审核中 请过一分钟以后再尝试调用此接口,如果尝试调用3次以后仍旧出现此错误,请联系技术支持
REQUEST_PARAM_ILLEGAL 参数错误,请参考文档说明修改入参信息 1.入参中的参数边界超过指定范围或者必传参数为空; 2.要传入的值格式不正确; 3.所填写的参数信息没有通过安全校验;
PERIOD_FORMAT_ERROR 券有效期类型格式错误 请参考券的有效期(voucher_valid_period)入参字段说明,修改券有效期入参为合法的格式
AMOUNT_OVERFLOW 参数有误请求参数非法,代金券面额超过指定上限 请查看代金券面额(amount)说明,调整代金券面额
INVALID_RULE_CONFIG 核销规则含有重复数据或者格式不符合要求 请参考入参券核销规则(rule_conf)字段说明,修改入参为合法的格式。有如下原因造成此错误: 1.PID门店存在重复 2.STOREID存在重复 3.门店规则不合法,必须是数字加逗号分隔
INVALID_UNIT_PARAMETER 无效的相对时间单位,请检查voucher_valid_period字段相对时间单位是否合法 请参考券有效期(voucher_valid_period)入参字段说明,修改券有效期中的时间单位为合法的参数
DISCOUNT_AMOUNT_INSUFFICIENT 请求参数非法,折扣券折扣金额不能低于0元 请参考无资金单品折扣券相关入参字段说明,修改入参后系统计算的无资金单品折扣券的最大折扣金额高于0元
INVALID_SPECIAL_AMOUNT_PARAMETER 无效的特价金额 参考文档,修改特价金额值
INVALID_GOODS_IMAGE_PARAMETER 无效的图片参数 检查入参,商品图片是否含有重复的值或者超过了指定的上传张数
INVALID_DISCOUNT_PARAMETER 无效的折扣比例参数 参考文档,修改折扣比例
INVALID_ORIGIN_AMOUNT_PARAMETER 无效的原价参数 参考文档,填写正确的原价金额
INVALID_RULE_PID_PARAMETER 核销规则中PID无效 不在同一个商户或者未填写PID或者PID重复。检查入参,填写正确的核销规则PID
NO_ARRANGEMENT_FACE 商户未签约当面付 检查主体商户或者核销规则中的PID,是否签约了当面付
INVALID_GOODS_CEILING_QUANTITY 无效的封顶件数 参考文档,填写的正确的单品优惠封顶件数
onlineServer