支付宝-创建商家券活动
1、修订记录
| 修订记录 | 日期 | 说明 |
|---|---|---|
| 1.0 | 2025.10.20 | 支付宝-创建商家券活动 |
2、业务说明
（1）接口说明
支付宝-创建商家券活动
请求主体类型：application/json
请求方式：POST
3、请求地址
| 环境 | HTTPS请求地址 |
|---|---|
| 测试环境 | https://appdev.ysepay-test.com/openapi/ysMarket/createActive |
| 正式环境 | https://ysgate.ysepay.com/openapi/ysMarket/createActive |
4、请求参数说明
4.1、公共请求参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| timeStamp | String | Y | 发送请求的时间，格式"yyyy-MM-dd HH:mm:ss" |
| method | String(128) | Y | 接口名称，固定值：ysMarket.createActive |
| charset | String(10) | Y | 请求使用的编码格式，如utf-8,gbk,gb2312等,固定为utf-8 |
| sign | String | Y | 商户请求参数的签名串（签名算法默认为国密）,详见demo,注意:请用商户私钥进行签名 |
| check | String | Y | 银盛公钥加密随机生成的字符串（key）得到的加密值，详见demo |
| bizContent | String | Y | 业务参数的集合，最大长度不限，除公共参数外所有请求参数都必须放在这个参数中传递。注意：需要通过AES以及随机生成的字符串（key）加密业务参数集合，得到bizContent |
| reqId | String | Y | 请求唯一流水号,商户系统唯一，要求32个字符内（最少14个字符），只能是数字、大小写字母_-且在同一个商户号下唯一。最后12位要求格式为"yyMMddHHmmss" 示例值：xy1415220315145602 |
| certId | String | Y | 发起方商户号，服务商在银盛给自己开设的商户号，即可当作发起方商户号，由银盛生成并下发。 注意：不同于子商户号，服务商发展的商户即为子商户号 |
| version | String | Y | 调用的接口版本，固定为：1.0 |
4.2、业务请求参数
（bizContent加密前的json数据明文字符串）
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| callBackUrl | String | Y | 回调地址 |
| activityBaseInfo | Object | Y | 活动基础信息 |
| outBizNo | String(64) | Y | 外部业务单号 |
| voucherSendModeInfo | Object | Y | 券发放模式信息 |
| voucherDeductInfo | Object | N | 券优惠抵扣信息 |
| voucherAvailableScopeInfo | Object | Y | 券可用范围 |
| voucherUseRuleInfo | Object | Y | 券核销限制 |
| voucherCustomerGuideInfo | Object | Y | 券引导详情 |
| voucherDisplayPatternInfo | Object | Y | 券展示信息 |
4.2.1 activityBaseInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| activityName | String | Y | 活动名称 |
| codeMode | String | Y | 码模式,枚举值： 商户上传自定义code: MERCHANT_UPLOAD 发奖时指定券码发奖: MERCHANT_API |
4.2.2 voucherSendModeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherSendMode | String | Y | 券发放模式,枚举值： 直领模式: DIRECT_SEND_MODE |
| voucherSendRuleInfo | Object | Y | 券发放规则 |
| deliveryChannelList | Array | N | 推广渠道列表,枚举值: 消费券频道: CONSUME_VOUCHER 示例:["CONSUME_VOUCHER"] |
4.2.2.1 voucherSendRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| quantity | int | Y | 发行券的数量,取值[1,99999999] |
| publishStartTime | String | Y | 券发放开始时间,格式：yyyy-MM-dd HH:mm:ss |
| publishEndTime | String | Y | 券发放结束时间,格式：yyyy-MM-dd HH:mm:ss 【注意事项】1.publish_end_time必须大于当前时间 2.publish_end_time必须大于publish_start_time 3.券发放结束时间publish_end_time 与 券发放开始时间publish_start_time 间隔必须小于等于180天 |
| quantityLimitPerUser | int | N | 每人领取限制,每个支付宝账号的可领券张数，不填写或填入0表示不限制 |
| naturalPersonLimit | boolean | N | 是否做身份证号限制,如用户使用同一身份证号注册或绑定多个支付宝账号，此用户只能通过一个支付宝账号完成领取 |
| phoneNumberLimit | boolean | N | 是否开启电话号码领取限制,如一个手机号注册或绑定多个支付宝账号，此用户仅能通过一个支付宝账号完成领取 |
| quantityDayLimitPerUser | int | N | 每人每日可领取限制,填0或者不填表示不限制 【注意事项】 1.字段有值且不为0且quantityLimitPerUser有值且不为0时，字段值不能大于quantityLimitPerUser的值 2.字段有值且不为0时quantityWeekLimitPerUser和quantityMonthLimitPerUser必须为0或者不填 |
| quantityWeekLimitPerUser | int | N | 每人每周可领取限制,填0或者不填表示不限制 【注意事项】 1.字段有值且不为0且quantityLimitPerUser有值且不为0时，字段值不能大于quantity_limit_per_user的值 2.字段有值且不为0时quantityDayLimitPerUser和quantityMonthLimitPerUser必须为0或者不填 |
| quantityMonthLimitPerUser | int | N | 每人每月可领取限制,填0或者不填表示不限制 【注意事项】 1.字段有值且不为0且quantityLimitPerUser有值且不为0时，字段值不能大于quantityLimitPerUser的值 2.字段有值且不为0时quantityDayLimitPerUser和quantityWeekLimitPerUser必须为0或者不填 |
4.2.3 voucherDeductInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherType | String | N | 券类型,枚举值: 满减券: FIX_VOUCHER 折扣券: DISCOUNT_VOUCHER 特价券: SPECIAL_VOUCHER 兑换券: EXCHANGE_VOUCHER |
| discountVoucherInfo | Object | N | 折扣券详情,voucherType = DISCOUNT_VOUCHER时必传 |
| exchangeVoucherInfo | Object | N | 兑换券详情,【注意事项】1、券类型为兑换券时必传。 2、指定小程序可用商品voucher_available_item_info时，不支持兑换券类型 |
| fixVoucherInfo | Object | N | 满减券详情,voucherType = FIX_VOUCHER必传 |
| specialVoucherInfo | Object | N | 特价券详情,【注意事项】1.voucher_type=SPECIAL_VOUCHER时必传 2.商品信息voucher_available_scope_info. voucher_available_goods_info必传 |
4.2.3.1 discountVoucherInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| ceilingAmount | String | Y | 封顶金额,取值范围:[0.1,15000] 【注意事项】： 1.币种为人民币，单位为元。 2.小数点以后最多保留两位。 |
| discount | String | Y | 折扣率,【描述】折扣率,比如：6.5折填入6.5。取值范围：[0.1,9.9] 【注意事项】取值范围：0.1<=x<=9.9，比如：6.5折填入6.5; |
| floorAmount | String | N | 门槛金额,【描述】门槛金额。取值范围：[0.1,50000] 【注意事项】1.该字段不填写，认为无门槛。 2.币种为人民币，单位为元。 3.小数点以后最多保留两位。 |
| voucherDeductThresholdInfo | Object | N | 优惠门槛信息 |
4.2.3.1.1 voucherDeductThresholdInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherGoodsQuantitySpecInfo | Object | N | 商品规格信息 |
4.2.3.1.1.1 voucherGoodsQuantitySpecInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| directionalType | String | Y | 定向类型,【描述】定向类型用于规格设置，比如：FIX 表示 固定满X件，APPOINT 表示指定第N件 【枚举值】 固定: FIX 指定: APPOINT |
| specificationQuantity | int | Y | 数量 |
| specificationUnit | String | Y | 单位,【枚举值】 件: COUNT_NUMBER 单: ORDER_NUMBER |
4.2.3.2 exchangeVoucherInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| amount | String | N | 券的价值,【注意事项】币种为人民币，单位为元。小数点以后最多保留两位。 取值范围:0.1<=x<=3000 |
| floorAmount | String | N | 门槛金额,【描述】优惠门槛金额，表示只有当订单金额大于等于门槛金额时券才能使用。该字段为空时表示无门槛。 门槛金额的校验由服务商(商户)核销时自行校验，支付宝侧只做展示使用。 【注意事项】币种为人民币，单位为元。小数点以后最多保留两位。 设置门槛：取值范围:0.1<=x<= 50000。 如果设置了门槛金额，则必须大于等于0.1，不可以等于0 |
| exchangeGoodsInfo | Object | Y | 兑换商品信息 |
| voucherDeductThresholdInfo | Object | N | 优惠门槛信息 |
4.2.3.2.1 exchangeGoodsInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| exchangeGoodsName | String | Y | 兑换商品名称 |
4.2.3.2.2 voucherDeductThresholdInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherExpressInfo | Object | N | 邮费信息 |
| voucherGoodsQuantitySpecInfo | Object | N | 商品规格信息 |
4.2.3.2.2.1 voucherExpressInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| payExpress | String | Y | 邮费标识,【描述】邮费标识，属于券的服务，用于用户门槛信息展示 【枚举值】 付邮费: PAY_FOR_EXPRESS 免邮费: FREE_FOR_EXPRESS 【注意事项】如果不涉及邮费信息，可以选择不填 |
4.2.3.2.2.2 voucherGoodsQuantitySpecInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| directionalType | String | Y | 定向类型,【描述】定向类型用于规格设置，比如：FIX 表示 固定满X件，APPOINT 表示指定第N件 【枚举值】 固定: FIX 指定: APPOINT |
| specificationQuantity | String | Y | 数量 |
| specificationUnit | String | Y | 单位,【枚举值】 件: COUNT_NUMBER 单: ORDER_NUMBER |
4.2.3.3 fixVoucherInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| amount | String | Y | 券面额,【描述】面额，每张代金券可以抵扣的金额。 取值范围： [0.1,3000] 限制： 1.币种为人民币，单位为元。 2.小数点以后最多保留两位。 【注意事项】币种为人民币，单位为元。小数点以后最多保留两位。 取值范围:0.1<=x<=3000 |
| floorAmount | String | N | 门槛金额,【描述】门槛金额。取值范围： [0.1,50000] 【注意事项】1.该字段不填写，认为无门槛。 2.币种为人民币，单位为元。 3.小数点以后最多保留两位。 |
| voucherDeductThresholdInfo | Object | N | 优惠门槛信息 |
4.2.3.3.1 voucherDeductThresholdInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherGoodsQuantitySpecInfo | Object | N | 商品规格信息 |
4.2.3.3.1.1 voucherGoodsQuantitySpecInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| directionalType | String | Y | 定向类型,【描述】定向类型用于规格设置，比如：FIX 表示 固定满X件 【枚举值】 固定: FIX |
| specificationQuantity | String | Y | 数量 |
| specificationUnit | String | Y | 单位,【枚举值】 件: COUNT_NUMBER 单: ORDER_NUMBER |
4.2.3.4 specialVoucherInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| floorAmount | String | N | 门槛金额,【描述】门槛金额。取值范围：[0.1,50000] 【注意事项】1.该字段不填写，认为无门槛。 2.币种为人民币，单位为元。 3.小数点以后最多保留两位。 |
| specialAmount | String | Y | 特价,【描述】特价，即：原价-特价=优惠金额。 取值范围:[0,999] 限制： 1.原价voucherAvailableScopeInfo.voucherAvailableGoodsInfo.originAmount必传。 2.商品名称voucherAvailableScopeInfo.voucherAvailableGoodsInfo.goodsName必传。 3.原价必须大于特价，即:originAmount>specialAmount; 4.币种为人民币，单位为元。 5.小数点以后最多保留两位。 【注意事项】币种为人民币，单位为元。小数点以后最多保留两位; 取值范围:0<=x<=999; 原价必须大于特价，即:originAmount>specialAmount; |
| voucherDeductThresholdInfo | Object | N | 优惠门槛信息 |
4.2.3.4.1 voucherDeductThresholdInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherExpressInfo | Object | N | 邮费信息 |
| voucherGoodsQuantitySpecInfo | Object | N | 商品规格信息 |
4.2.3.4.1.1 voucherExpressInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| payExpress | String | Y | 邮费标识,【枚举值】 付邮费: PAY_FOR_EXPRESS 免邮费: FREE_FOR_EXPRESS 【注意事项】如果不涉及邮费信息，可以选择不填 |
4.2.3.4.1.2 voucherGoodsQuantitySpecInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| directionalType | String | Y | 定向类型,【描述】定向类型用于规格设置，比如：FIX 表示 固定满X件，APPOINT 表示指定第N件 【枚举值】 固定: FIX 指定: APPOINT |
| specificationQuantity | String | Y | 数量 |
| specificationUnit | String | N | 单位,【枚举值】 件: COUNT_NUMBER 单: ORDER_NUMBER |
4.2.4 voucherAvailableScopeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherAvailableGeographyScope | Object | Y | 券可用地理位置,【注意事项】指定小程序可用商品voucherAvailableItemInfo时，为线上核销，不支持传入可用地理位置信息 |
| voucherAvailableGoodsInfo | Object | N | 券可用商品 |
4.2.4.1 voucherAvailableGeographyScope具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| availableGeographyScopeType | String | N | 券可用地理位置类型,【描述】券可用地理位置类型（二选一） 可用门店: SHOP 可用城市: CITY_CODE 【枚举值】 可用门店: SHOP 可用城市: CITY_CODE |
| availableGeographyCityInfo | Object | N | 券可用城市,availableGeographyScopeType=CITY_CODE时必传，allCity和availableCityCodes二选一上送 |
| availableGeographyShopInfo | Object | N | 券可用门店,availableGeographyScopeType=SHOP时必传，availableGeographyAllShop、availableRealShopIds和availableShopIds三选一上送 |
4.2.4.1.1 availableGeographyCityInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| allCity | boolean | N | 是否全国,【描述】是否全国。枚举值： true：是 false: 否 【注意事项】选择全国后，无须填写available_city_codes字段。系统默认填充全国全部城市信息。 与availableCityCodes二选一上送 |
| availableCityCodes | Array | N | 城市编码,城市编码，取值 文档 中区域类型=3的地区码，比如：呼和浩特，150100 与allCity二选一上送 |
4.2.4.1.2 availableGeographyShopInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| availableGeographyAllShop | Object | N | 全部门店可用 |
4.2.4.1.2.1 availableGeographyAllShop具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| availableBrandId | String | N | 全部门店可用的品牌ID,【描述】全部门店可用的品牌ID 提示: 1.目前只支持传入当前券归属商户的品牌ID 2.品牌ID可以在登录b.alipay.com-账户中心-品牌管理里查看。如果没有品牌，可以先创建品牌。Sop： 注意事项 1.只支持传入单个品牌ID 2.传入品牌ID后，券的商户品牌和logo仍以voucher_display_pattern_info传入为准。 【注意事项】1、只允许入参当前调用接口PID创建的品牌，代运营模式取被代运营商户的品牌。 2、自动同步和更新品牌下的全部门店 |
| excludeShopIds | Array | N | 券不可使用的门店列表,【描述】券不可使用的门店列表，指定商户全部门店可用时可通过该字段排除部分不可用门店 |
| merchantIds | Array | N | 全部门店可用的商户ID,【描述】全部门店可用的商户ID 限制: 1.目前只支持传当前活动归属的商户ID 2.目前只支持传入单个商户ID 【注意事项】1.目前只支持传当前活动归属的商户ID 2.目前只支持传入单个商户ID |
4.2.4.2 voucherAvailableGoodsInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| goodsName | String | Y | 商品名称 |
| originAmount | String | N | 原价,【描述】商品原价 【注意事项】voucherDeductInfo.voucherType=SPECIAL_VOUCHER\DISCOUNT_VOUCHER时必传 |
4.2.5 voucherUseRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherUseTimeInfo | Object | Y | 券核销时间 |
4.2.5.1 voucherUseTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| absolutePeriodInfo | Object | N | 券绝对时间可用,periodType=ABSOLUTE时必传 |
| periodType | String | N | 券有效期,【枚举值】 绝对时间: ABSOLUTE 相对时间: RELATIVE |
| relativePeriodInfo | Object | N | 券相对时间,periodType=RELATIVE时必传 |
4.2.5.1.1 absolutePeriodInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| validBeginTime | String | Y | 券可使用的开始时间,格式：yyyy-MM-dd HH:mm:ss |
| validEndTime | String | Y | 券可使用的结束时间,格式：yyyy-MM-dd HH:mm:ss 【注意事项】券可使用的结束时间validEndTime 必须大于 券的发放结束时间 publishEndTime |
| timeRestrictInfo | Object | N | 核销时间限制 |
4.2.5.1.1.1 timeRestrictInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| disablePeriodInfo | Array | N | 不可用时间段 |
| usablePeriodInfo | Array | N | 可用时间段 |
# 4.2.5.1.1.1.1 disablePeriodInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRuleInfo | Object | N | 日期规则,当ruleType = DATE时，不能为空 |
| holidayRuleInfo | Object | N | 法定节假日规则,当ruleType = HOLIDAY时必填 |
| ruleType | String(32) | Y | 规则类型,【枚举值】 周期类型: WEEK 日期类型: DATE 法定节假日类型: HOLIDAY |
| weekRuleInfo | Object | N | 周期规则 |
## 4.2.5.1.1.1.1.1 dateRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRangeInfo | Object | Y | 日期范围 |
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.1.1.1.1.1 dateRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginDate | String | Y | 开始日期,格式：yyyy-MM-dd |
| endDate | String | Y | 结束日期,格式：yyyy-MM-dd |
### 4.2.5.1.1.1.1.1.2 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间,格式：HH:mm:ss |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.1.1.1.1.2.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间,格式：HH:mm:ss |
| endTimeType | String | Y | 结束时间类型,【描述】结束时间类型 【枚举值】 当日: SAME_DAY 次日: NEXT_DAY |
## 4.2.5.1.1.1.1.2 holidayRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.1.1.1.2.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间,格式：HH:mm:ss |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.1.1.1.2.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间,格式：HH:mm:ss |
| endTimeType | String | Y | 结束时间类型,【描述】结束时间类型 【枚举值】 当日: SAME_DAY 次日: NEXT_DAY |
## 4.2.5.1.1.1.1.3 weekRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| weekDay | String | Y | 星期数 |
| timeRangeInfo | Object | N | 时间段 |
### 4.2.5.1.1.1.1.3.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.1.1.1.3.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
# 4.2.5.1.1.1.2 usablePeriodInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRuleInfo | Object | N | 日期规则 |
| holidayRuleInfo | Object | N | 法定节假日规则 |
| weekRuleInfo | Object | N | 周期规则 |
| ruleType | String(32) | Y | 规则类型 |
## 4.2.5.1.1.1.2.1 dateRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRangeInfo | Object | Y | 日期范围 |
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.1.1.2.1.1 dateRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginDate | String | Y | 开始日期 |
| endDate | String | Y | 结束日期 |
### 4.2.5.1.1.1.2.1.2 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.1.1.2.1.2.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
## 4.2.5.1.1.1.2.2 holidayRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.1.1.2.2.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.1.1.2.2.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
## 4.2.5.1.1.1.2.3 weekRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| weekDay | String | Y | 星期数 |
| timeRangeInfo | Object | N | 时间段 |
### 4.2.5.1.1.1.2.3.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.1.1.2.3.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
4.2.5.1.2 relativePeriodInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| validDaysAfterReceive | int | Y | 券生效后 N 天内可以使用,【描述】用户领券后需要等待N天，券才可以生效。 【注意事项】字段值为0表示用户领券后立刻生效 |
| waitDaysAfterReceive | int | Y | 用户领券后需要等待 N 天生效,【描述】券生效后N天内可以使用。 可以配合waitDaysAfterReceive字段使用。 比如：waitDaysAfterReceive=1，validDaysAfterReceive=2，今天时1号0点0分0秒，那么2号0点0分0秒券生效可以开始使用，4号23点59分59秒，有效期到期不可用。 【注意事项】validDaysAfteReceive必须大于0 |
| timeRestrictInfo | Object | N | 核销时间限制 |
4.2.5.1.2.1 timeRestrictInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| disablePeriodInfo | Array | N | 不可用时间段 |
| usablePeriodInfo | Array | N | 可用时间段,当ruleType = WEEK时必填 |
# 4.2.5.1.2.1.1 disablePeriodInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRuleInfo | Object | N | 日期规则 |
| ruleType | String(32) | Y | 规则类型 |
| holidayRuleInfo | Object | N | 法定节假日规则 |
| weekRuleInfo | Object | N | 周期规则 |
## 4.2.5.1.2.1.1.1 dateRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRangeInfo | Object | Y | 日期范围 |
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.2.1.1.1.1 dateRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginDate | String | Y | 开始日期 |
| endDate | String | Y | 结束日期 |
### 4.2.5.1.2.1.1.1.2 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.2.1.1.1.2.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
## 4.2.5.1.2.1.1.2 holidayRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.2.1.1.2.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.2.1.1.2.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
## 4.2.5.1.2.1.1.3 weekRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| weekDay | String | Y | 星期数 |
| timeRangeInfo | Object | N | 时间段 |
### 4.2.5.1.2.1.1.3.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.2.1.1.3.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
# 4.2.5.1.2.1.2 usablePeriodInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| weekRuleInfo | Object | N | 周期规则 |
| ruleType | String | Y | 规则类型 |
| holidayRuleInfo | Object | N | 法定节假日规则 |
| dateRuleInfo | Object | N | 日期规则 |
## 4.2.5.1.2.1.2.1 weekRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| weekDay | String | Y | 星期数,【描述】星期数，以“,”连接多个星期数 【示例值】1,2 |
| timeRangeInfo | Object | N | 时间段 |
### 4.2.5.1.2.1.2.1.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间,格式：HH:mm:ss |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.2.1.2.1.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | N | 结束时间,格式：HH:mm:ss |
| endTimeType | String | N | 结束时间类型,【枚举值】 当日: SAME_DAY 次日: NEXT_DAY |
## 4.2.5.1.2.1.2.2 holidayRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.2.1.2.2.1 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.2.1.2.2.1.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
## 4.2.5.1.2.1.2.3 dateRuleInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| dateRangeInfo | Object | Y | 日期范围 |
| timeRangeInfo | Object | Y | 时间段 |
### 4.2.5.1.2.1.2.3.1 dateRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginDate | String | Y | 开始日期 |
| endDate | String | Y | 结束日期 |
### 4.2.5.1.2.1.2.3.2 timeRangeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| beginTime | String | Y | 开始时间 |
| endTimeInfo | Object | N | 结束时间 |
#### 4.2.5.1.2.1.2.3.2.1 endTimeInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| endTime | String | Y | 结束时间 |
| endTimeType | String | Y | 结束时间类型 |
4.2.6 voucherCustomerGuideInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherUseGuideInfo | Object | Y | 券核销详情 |
4.2.6.1 voucherUseGuideInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| miniAppUseGuideInfo | Object | N | 小程序核销引导,【注意事项】1. useGuideMode包含MINI_APP时必传 2.miniAppUrl和miniAppServiceCodes只能二选一 |
| useGuideMode | Array | N | 使用引导模式,【描述】券核销引导，可以多选。OFFLINE_CODE：券码扫码核销，控制卡包是否可展示券码，填写则展示。MINI_APP：小程序线上核销，控制卡包是否可展示“去使用”小程序引导，填写则展示。 【枚举值】 券码扫码核销: OFFLINE_CODE 小程序线上核销: MINI_APP 【注意事项】1. 传入MINI_APP，则miniAppUseGuideInfo必传。 2. 该字段为列表类型。 |
4.2.6.1.1 miniAppUseGuideInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| miniAppServiceCodes | Array | N | 小程序服务编码 |
| miniAppUrl | String | N | 指定跳转到mini_app_id时的具体页面路径,【描述】小程序跳转链接 【注意事项】1、必须是支付宝小程序链接 ，小程序拼接规则：scheme介绍 2、小程序链接里的APPID必须是当前账户或同公司其他账户（同MID）名下的小程序 【示例值】alipays://platformapi/startapp?appId=xxxx |
4.2.7 voucherDisplayPatternInfo具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| brandLogo | String(128) | Y | 商家logo |
| brandName | String(12) | Y | 商户品牌名称 |
| customerServiceMobile | String(20) | N | 客服电话 |
| customerServiceUrl | String(255) | N | 客服链接 |
| voucherDescription | String(1000) | Y | 券详细使用说明 |
| voucherImage | String(64) | N | 券封面图 |
| voucherName | String | N | 对消费者展示的券(商品)名称 |
| voucherDetailImages | Array | N | 图片详情列表 |
5、响应参数说明
请注意：银盛后期会对返回参数保留扩展的权力，扩展方式为新增参数但不会删除参数，请商户在解析银盛返回参数时要支持银盛可能扩展参数这种情况。5.1、公共响应参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| code | String(5) | Y | 网关响应码，示例值：00000 ，详见网关公共响应码 |
| msg | String(50) | Y | 网关响应码描述 |
| subCode | String | Y | 业务响应码，参见具体的API接口文档 |
| subMsg | String | Y | 业务响应描述 |
| timeStamp | String | Y | 响应时间，格式"yyyy-MM-dd HH:mm:ss" |
| norce | String(128) | Y | 随机参数 |
| sign | String | Y | 响应参数的签名串，详见demo, 注意:请用银盛公钥进行验签 |
| businessData | String | Y | 业务响应参数集合， 注意：银盛网关通过AES加密业务响应参数集合，得到businessData，商户需要对其进行解密，详情请见demo |
5.2、业务响应参数
响应业务参数businessData(json数据)
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| activityId | String | Y | 活动id |
| voucherAvailableScopeResultInf | Object | N | 券可用范围结果 |
5.2.1.1 voucherAvailableScopeResultInf具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| voucherAvailableGeographyScope | Object | N | 可用地理位置 |
5.2.1.1.1 voucherAvailableGeographyScope具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| availableGeographyShopResultIn | Object | N | 可用门店结果 |
5.2.1.1.1.1 availableGeographyShopResultIn具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| successAvailableShopIds | Array | N | 可用门店结果 |
| failAvailableShopInfos | Array | N | 失败的可用门店 |
| availableGeographyAllShopResul | Object | N | 全部门店结果 |
# 5.2.1.1.1.1.1 failAvailableShopInfos具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| failMessage | String | N | 请求失败提示信息 |
| shopId | String | N | 门店 ID |
| realShopId | String | N | 物理门店ID |
| failReasons | Array | Y | 请求失败的原因,【枚举值】 门店信息不全: SHOP_INFO_NOT_PASS 门店不存在: SHOP_NOT_EXIST 门店与商户没有关联关系: MERCHANT_SHOP_RELATION_NOT_EXIST 活动不存在该门店: ACTIVITY_SHOP_NOT_EXIST |
# 5.2.1.1.1.1.2 availableGeographyAllShopResul具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| failExcludeShopInfos | Array | N | 请求失败的不可用门店详情 |
| successExcludeShopIds | Array | N | 请求成功的不可用门店列表 |
## 5.2.1.1.1.1.2.1 failExcludeShopInfos具体参数
| 参数 | 类型(长度） | 必填 | 参数说明 |
|---|---|---|---|
| failMessage | String | N | 请求失败提示信息 |
| failReasons | Array | Y | 请求失败的原因,【枚举值】 门店信息不全: SHOP_INFO_NOT_PASS 门店不存在: SHOP_NOT_EXIST 门店与商户没有关联关系: MERCHANT_SHOP_RELATION_NOT_EXIST 活动不存在该门店: ACTIVITY_SHOP_NOT_EXIST |
| shopId | String | N | 门店 ID |
| realShopId | String | N | 物理门店ID |
6、业务响应码 网关公共响应码
| 响应码 | 响应码描述 | 解决方案 |
|---|---|---|
| 0 | 成功 | |
| 901009999 | 系统错误 | |
| 901001001 | 参数校验不通过 | |
| 901001101 | 发起方权限不足 | |
| 901001002 | 业务校验不通过 | |
| 901029998 | 支付宝渠道返回失败 | |
| 901029999 | 支付宝渠道异常 |