更新时间：2023-07-17 17:05:53文档更新记录 >收藏订阅更新我的文档设置返回文档1 简介对接商家券，需要感知的实体模型主要有商家券活动、商家券券码和核销状态，它们之间的关系如下图所示。2 商家券活动商家举办的一场特定优惠规则的营销活动，以券的形式将活动权益发放出去。2.1 商家券活动的字段列表字段中文名字段英文名字段类型最大长度描述示例值活动idactivity_idstring128活动id2016042700826004508401111111活动名称activity_namestring20不对用户进行展示，仅供商家在后台管理活动使用。满10减1活动券码模式code_modestring20枚举值： merchant_upload：商户上传自定义code，发券时系统随机选取上传的券code发放。merchant_upload券类型voucher_typestring16枚举值： fix_voucher：满减券； discount_voucher：折扣券； special_voucher：特价券； exchange_voucher: 兑换券；fix_voucher券发放开始时间publish_start_timedate20格式为：yyyy-mm-dd hh:mm:ss2017-01-01 00:00:01券发放结束时间publish_end_timedate20格式为：yyyy-mm-dd hh:mm:ss 限制： 券发放结束时间 publish_end_time 与 券发放开始时间 publish_start_time 间隔必须小于等于180天2017-01-29 23:59:59活动归属商户信息belong_merchant_infobelongmerchantinfo如果该复杂对象不填。则默认为该商家券活动的归属者是调用者本人。 如果填写，则认为该商家券活动的归属者是该商户。 限制:服务商身份接入时必传券展示信息voucher_display_infovoucherdisplayinfo券展示信息券核销规则voucher_use_rulevoucheruserule券核销规则券发放规则voucher_send_rulevouchersendruledetail券发放规则券自定义入口customer_guidecustomerguide券自定义入口发券数量上限voucher_quantitynumber10券总预算值，不可减少，只能增加。 限制： 券总预算<= 999999 code_mode= merchant_upload的情况下， voucher_quantity需要与导入码的总数量保持一致。15券已发放数量publish_countnumber32券已发放数量，查询营销活动时返回5券已核销数量used_countnumber32券已核销数量，查询营销活动时返回52.1.1 活动归属商户信息 belongmerchantinfo字段中文名字段英文名字段类型最大长度描述示例值合作业务类型business_typestring16默认为isv_for_merchant 枚举值: isv 服务商平台模式 isv_for_merchant 服务商代运营模式isv_for_merchant商户id类型merchant_id_typestring10枚举值： smid 间连smid pid 直连pid 特别说明： 如果merchant_id_type选择smid。则表明当前商家券活动的归属者是该smid所绑定的支付宝pid。 因此要求该smid必须绑定相应的支付宝pid。 限制: 服务商代运营模式必传smid商户idmerchant_idstring32限制: 服务商代运营模式必传20881021111111112.1.2 券展示信息 voucherdisplayinfo字段中文名字段英文名字段类型最大长度描述示例值商户品牌名称brand_namestring12如果不设置品牌名称，则默认使用支付宝商家系统中维护的商家别名。 如果没有维护商家别名，则使用默认名称： 商家优惠。 用户领取优惠券后，品牌名称会对用户进行展示 限制: 服务商平台模式必传商家优惠商家logobrand_logostring64需要通过 alipay.marketing.material.image.upload接口上传图片，指定file_key为promo_brand_logo，返回的resource_id即为该参数的值 限制: 服务商平台模式必传 上传图片尺寸600*600，支持格式：png、jpg、jpeg、bmp，大小不超过2mbadedsktiqo-u5vjuqvbcqwaaacmaaqed券补充说明voucher_commentstring12该字段为可运营字段，可描述商品特色 会展示在用户支付宝卡包券详情页 限制: 该字段在兑换券场景下必传食材新鲜，品质之选券详细使用说明voucher_descriptionstring1000券详细使用说明1、本券不可兑换现金，不可找零。2、每个用户最多可以领取1张。3、如果订单发生退款，优惠券无法退还。券详情页封面图voucher_imagestring64会展示在用户支付宝卡包券详情页 需要通过 alipay.marketing.material.image.upload接口上传图片，指定file_key为promo_voucher_image，接口返回的resource_id即为该参数的值 限制: 该字段在兑换券场景下必传 上传图片尺寸670*335，支持格式：png、jpg、jpeg、bmp，大小不超过2mbadedsktiqo-u5vjuqvbcqwaaacmaaqed券详细图列表voucher_detail_imagesstring[]256会展示在用户支付宝卡包券详情页 需要通过 alipay.marketing.material.image.upload接口上传图片，指定file_key为promo_voucher_detail_image ,接口返回的resource_id即为该参数的值 上传图片尺寸600*600，支持格式：png、jpg、jpeg、bmp，大小不超过2mb 限制 1.voucher_image填入，该值才能填入； 2.最多3张；["adedsktiqo-u5vjuqvbcqwaaacmaaqe1","adedsktiqo-u5vjuqvbcqwaaacmaaqe2","adedsktiqo-u5vjuqvbcqwaaacmaaqe3"]2.1.3 券核销规则 voucheruserule字段中文名字段英文名字段类型最大长度描述示例值面额amountprice16面额，每张代金券可以抵扣的金额。 限制： 币种为人民币，单位为元。小数点以后最多保留两位。 取值范围:0.1<=x<=300050.00门槛金额loor_amountprice16该字段不填写，认为无门槛。 限制： 只有当订单金额大于等于门槛金额时券才能使用。 币种为人民币，单位为元。小数点以后最多保留两位。 设置门槛：取值范围:0.1<=x<= 50000。 如果设置了门槛金额，则必须大于等于0.1，不可以等于01000.00商品名称goods_namestring12商品名称美味甜甜圈2.1.4 券发放规则 vouchersendruledetail字段中文名字段英文名字段类型最大长度描述示例值发行券的数量voucher_quantitynumber10限制： code_mode=merchant_upload模式下数量必须为0或者选择不填。 其他模式下该数值必须是大于0的整数。0每人领取限制voucher_quantity_limit_per_usernumber10默认按照支付宝uid进行领取限制; 不填写或填入0，默认没有领取限制.1是否开启自然人领取限制natural_person_limitboolean8自然人表示按照身份证纬度进行领取限制。true是否开启电话号码领取限制phone_number_limitboolean8是否开启电话号码领取限制false2.1.5 券自定义入口 customerguide字段中文名字段英文名字段类型最大长度描述示例值券可使用的门店列表shop_idsstring[]8400000列表中的门店id是通过调用接口ant.merchant.expand.shop.create创建门店返回的支付宝门店id 接口参数是列表类型。 限制： shop_ids中的门店id必须是支付宝门店id。 shop_ids如果包含重复的门店id会自动进行去重操作。 修改门店列表，只允许增加不允许减少。["2018051000502000000011111111","2018040200502000000011111111","2018062800502000000022271997"]代运营商业关系门店列表real_shop_idsstring[]8400000列表中的门店id是调用接口alipay.business.relation.shop.create创建门店返回的real_shop_id 接口参数是列表类型。 限制： real_shop_ids中的门店id必须是代运营商业关系门店id。 real_shop_ids如果包含重复的门店id会自动进行去重操作。 修改门店列表，只允许增加不允许减少。["2018051000502000000011111111","2018040200502000000011111111","2018062800502000000022271997"]卡包详情页可跳转的小程序appidmini_app_idstring16限制： 该appid归属的pid必须和当前商户保持一致。 目前mini_app_id、shop_ids、real_shop_ids必须三选一。2021238412323412指定跳转到小程序的具体页面路径mini_app_pathstring64限制： 该小程序路径是相对路径。/index/path/path2.2 商家券活动支持的操作api中文名api英文名创建商家券活动alipay.marketing.activity.ordervoucher.create修改商家券活动基本信息alipay.marketing.activity.ordervoucher.modify修改商家券活动发券数量上限alipay.marketing.activity.ordervoucher.append查询商家券活动alipay.marketing.activity.ordervoucher.query取消商家券活动alipay.marketing.activity.ordervoucher.stop3 商家券券码商家券活动发放的符合活动规则的优惠券，每张优惠券有不同的券码。3.1 商家券券码的字段列表字段中文名字段英文名字段类型最大长度描述示例值券码voucher_codestring64单个code最长64位。 code允许包含的字符有0-9、a-z、a-z、-、_、 、=、|。123ab3.2 商家券券码支持的操作api中文名api英文名导入商家券券码alipay.marketing.activity.ordervoucher.codedeposit统计商家券券码数量alipay.marketing.activity.ordervoucher.codecount4 核销状态商家券属于外券，实际核销由服务商自行负责，但需将券的核销状态同步给支付宝。4.1 核销状态的字段列表字段中文名字段英文名字段类型最大长度描述示例值核销时间biz_dtdate20外部优惠券的核销时间。 格式为：yyyy-mm-dd hh:mm:ss2017-01-01 00:00:01核销的券码voucher_codestring64待核销的券码。abe44交易渠道trade_channelstring64枚举值： zhifubao_trade_channel： 支付宝交易渠道 wx_trade_channel： 微信交易渠道 other_trade_channel： 其他交易渠道zhifubao_trade_channel核销的代运营商业关系门店idreal_shop_idstring64用户核销优惠券的代运营商业关系门店id，调用接口alipay.business.relation.shop.create创建门店返回的real_shop_id。 限制: 传入的门店id必须是创建商家券customer_guide对象中real_shop_ids中的门店id。2018051000502000000011111111核销的支付门店idshop_idstring64用户核销优惠券的支付门店id,调用接口ant.merchant.expand.shop.create创建门店返回的门店id。 限制: 传入的门店id必须是创建商家券customer_guide对象中shop_ids中的门店id2018051000502000000011111111核销的支付宝交易流水号trade_nostring64该交易在支付宝系统中的交易流水号。 注意：若用户使用支付宝为交易的渠道，本参数必填。2021042322001426261436764012核销订单总金额total_feeprice9订单优惠前的总金额 限制： 该笔订单的资金总额，取值范围[0.01,100000000]，精确到小数点后2位。999.99商品信息goods_detailgoodsdetaildto[]商品明细信息。 限制： 当前交易中存在商品信息，则建议传入商品明细信息。4.1.1 商品信息 goodsdetaildto字段中文名字段英文名字段类型最大长度描述示例值商品编号goods_idstring32商品编号apple-01商品名称goods_namestring256商品名称ipad商品数量quantitynumber10商品数量1商品单价priceprice9单位：元 精确到小数点后2位。2000.004.2 核销状态支持的操作api中文名api英文名同步核销状态alipay.marketing.activity.ordervoucher.use取消核销状态alipay.marketing.activity.ordervoucher.refund
