创建商家券API

最新更新时间:2020.07.24 版本说明


服务商可以通过该接口为有需求的商户创建商家券。

接口说明

适用对象:直连商户 服务商 渠道商

请求URL:https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks

请求方式:POST

接口规则:https://wechatpay-api.gitbook.io/wechatpay-api-v3


path 指该参数为路径参数

query 指该参数需在请求URL传参

body 指该参数需在请求JSON传参


请求参数

参数名 变量 类型[长度限制] 必填 描述
商家券批次名称 stock_name string[1,21] body 批次名称,字数上限为21个字节长度(中文按UTF8编码算字节数)。
示例值:8月1日活动券
批次归属商户号 belong_merchant string[8,15] body 批次归属于哪个商户。
示例值:10000022
批次备注 comment string[1,20] body 仅配置商户可见,用于自定义信息。
示例值:活动使用
适用商品范围 goods_name string[1,15] body 用来描述批次在哪些商品可用,会显示在微信卡包中。
示例值:xxx商品使用
批次类型 stock_type string[1,32] body 批次类型
NORMAL:固定面额满减券批次
DISCOUNT:折扣券批次
EXCHANGE:换购券批次
示例值:NORMAL
+核销规则 coupon_use_rule object body 券核销相关规则
参数名 变量 类型[长度限制] 必填 描述
+券可核销时间 coupon_available_time object 日期区间内可以使用优惠。
参数名 变量 类型[长度限制] 必填 描述
开始时间 available_begin_time string[1,32] 批次开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
结束时间 available_end_time string[1,32] 批次结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
生效后N天内有效 available_day_after_receive int 日期区间内,券生效后x天内有效。例如生效当天内有效填1,生效后2天内有效填2,以此类推……注意,用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数,无论用户何时领取商家券,商家券在活动有效期结束后均不可用。可配合wait_days_after_receive一同填写,也可单独填写。单独填写时,有效期内领券后立即生效,生效后x天内有效。
示例值:3
+ 固定周期有效时间段 available_week object 可以设置多个星期下的多个可用时间段,比如每周二10点到18点,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
可用星期数 week_day array[int] 条件选填 0代表周日,1代表周一,以此类推
当填写available_day_time时,week_day必填
示例值:1, 2
+ 当天可用时间段 available_day_time array 可以填写多个时间段,最多不超过2个。
参数名 变量 类型[长度限制] 必填 描述
当天可用开始时间 begin_time int 当天可用开始时间,单位:秒,1代表当天0点0分1秒。
示例值:3600
当天可用结束时间 end_time int 当天可用结束时间,单位:秒,86399代表当天23点59分59秒。
示例值:86399
+ 无规律的有效时间段 irregulary_avaliable_time array 无规律的有效时间,多个无规律时间段,用户自定义字段。
参数名 变量 类型[长度限制] 必填 描述
开始时间 begin_time string[1,32] 开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
结束时间 end_time string[1,32] 结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00
领取后N天开始生效 wait_days_after_receive int 日期区间内,用户领券后需等待x天开始生效。例如领券后当天开始生效则无需填写,领券后第2天开始生效填1,以此类推……用户在有效期开始前领取商家券,则从有效期第1天开始计算天数,用户在有效期内领取商家券,则从领取当天开始计算天数。无论用户何时领取商家券,商家券在活动有效期结束后均不可用。需配合available_day_after_receive一同填写,不可单独填写。
示例值:7
+固定面额满减券使用规则 fixed_normal_coupon object 三选一 stock_type为NORMAL时必填。
参数名 变量 类型[长度限制] 必填 描述
优惠金额 discount_amount int 优惠金额,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:5
消费门槛 transaction_minimum int 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+折扣券使用规则 discount_coupon object stock_type为DISCOUNT时必填。
参数名 变量 类型[长度限制] 必填 描述
折扣比例 discount_percent int 折扣百分比,例如:88为八八折。
示例值:88
消费门槛 transaction_minimum int 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
+换购券使用规则 exchange_coupon object stock_type为EXCHANGE时必填。
参数名 变量 类型[长度限制] 必填 描述
单品换购价 exchange_price int 单品换购价,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
消费门槛 transaction_minimum int 消费门槛,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 10000000
示例值:100
核销方式 use_method string[1,128] 枚举值:
OFF_LINE:线下滴码核销,点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS:线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序appid和path)。
PAYMENT_CODE:微信支付付款码核销,点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME:用户自助核销,点击券“立即使用”跳转至用户自助操作核销界面(当前暂不支持用户自助核销)。
示例值:OFF_LINE
小程序appid mini_programs_appid string[1,32] 条件选填 核销方式为线上小程序核销才有效。
示例值:wx23232232323
小程序path mini_programs_path string[1,128] 条件选填 核销方式为线上小程序核销才有效。
示例值:/path/index/index
+发放规则 stock_send_rule object body 券发放相关规则
参数名 变量 类型[长度限制] 必填 描述
批次总预算 max_amount int 总预算金额,单位:分。
特殊规则:取值范围 1 ≤ value ≤ 100000000000
示例值:100000
批次最大发放个数 max_coupons int 条件选填 当stock_type为DISCOUNT或EXCHANGE类型时,必须填写。
特殊规则:取值范围 1 ≤ value ≤ 1000000000
示例值:100
用户最大可领个数 max_coupons_per_user int 用户可领个数,每个用户最多100张券 。
示例值:5
单天发放上限金额 max_amount_by_day int 单天发放上限金额,单位:分(stock_type为NORMAL时可传入此字段控制单天发放上限)。
特殊规则:取值范围 1 ≤ value ≤ 10000000000
示例值:1000
单天发放上限个数 max_coupons_by_day int 单天发放上限个数(stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限)。
特殊规则:取值范围 1 ≤ value ≤ 1000000000
示例值:100
是否开启自然人限制 natural_person_limit bool 不填默认否,枚举值:
true:是
false:否
示例值:false
可疑账号拦截 prevent_api_abuse bool 不填默认否,枚举值:
true:是
false:否
示例值:false
是否允许转赠 transferable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
是否允许分享链接 shareable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
商户请求单号 out_request_no string[1,128] body 商户创建批次凭据号(格式:商户id+日期+流水号),商户侧需保持唯一性。
示例值:100002322019090134234sfdf
+自定义入口 custom_entrance object body 卡详情页面,可选择多种入口引导用户。
参数名 变量 类型[长度限制] 必填 描述
+小程序入口 mini_programs_info object 需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序,APPID、path、入口文案为必填,引导文案非必填。
appid要与归属商户号有M-A or M-m-suba关系。
参数名 变量 类型[长度限制] 必填 描述
商家小程序appid mini_programs_appid string[1,32] 商家小程序appid要与归属商户号有M-A or M-m-suba关系。
示例值:wx234545656765876
商家小程序path mini_programs_path string[1,128] 商家小程序path
示例值:/path/index/index
入口文案 entrance_words string[1,5] 入口文案
示例值:欢迎选购
引导文案 guiding_words string[1,6] 小程序入口引导文案,用户自定义字段。
示例值:获取更多优惠
商户公众号appid appid string[1,32] 可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。
示例值:wx324345hgfhfghfg
更多优惠入口;
营销馆创建地址:
https://pay.weixin.qq.com/index.php
/xphp/cfav_market/hall#/pages/list/list
hall_id string[1,64] 填写微信支付营销馆的馆id,用户自定义字段。
示例值:233455656
可用门店id store_id string[1,64] 填写代金券可用门店id,用户自定义字段。
示例值:233554655
code展示模式 code_display_mode string[1,8] 枚举值:
NOT_SHOW:不展示code
BARCODE:一维码
QRCODE:二维码
示例值:BARCODE
+样式信息 display_pattern_info object body 创建批次时的样式信息。
参数名 变量 类型[长度限制] 必填 描述
使用须知 description string[1,1000] 用于说明详细的活动规则,会展示在代金券详情页。
示例值:xxx门店可用
商户logo merchant_logo_url string[1,128] 商户logo的URL地址,仅支持通过《图片上传API》接口获取的图片URL地址。
1、商户logo大小需为120像素*120像素。
2、支持JPG/JPEG/PNG格式,且图片小于1M。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string[1,16] 商户名称,字数上限为16个字节长度(中文按UTF8编码算字节数)
示例值:微信支付
背景颜色 background_color string[1,16] 券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值:Color020
券详情图片 coupon_image_url string[1,128] 券详情图片,850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,仅支持通过《图片上传API》接口获取的图片URL地址。
示例值:https://qpic.cn/xxx
券code模式 coupon_code_mode string[1,128] body 枚举值:
WECHATPAY_MODE:系统分配券code。(固定22位纯数字)
MERCHANT_API:商户发放时接口指定券code。
MERCHANT_UPLOAD:商户上传自定义code,发券时系统随机选取上传的券code。
示例值:WECHATPAY_MODE
+事件通知配置 notify_config object body 事件回调通知商户的配置。
参数名 变量 类型[长度限制] 必填 描述
事件通知appid notify_appid string[1,64] 用于回调通知时,计算返回操作用户的openid(诸如领券用户),支持小程序or公众号的APPID;如该字段不填写,则回调通知中涉及到用户身份信息的openid与unionid都将为空。
示例值:wx23232232323

请求示例


{
  "stock_name":"8月1日活动券",
  "belong_merchant":"10000098",
  "comment": "活动使用",
  "goods_name": "填写代金券可适用的商品或服务",
  "stock_type": "NORMAL",
  "coupon_use_rule": {
    "coupon_available_time": {
      "available_begin_time": "2015-05-20T13:29:35+08:00",
      "available_end_time": "2015-05-20T13:29:35+08:00",
      "available_day_after_receive": 3,
      "wait_days_after_receive":7,
      "available_week": {
        "week_day": [
          1,
          2
        ],
        "available_day_time": [
          {
            "begin_time": 3600,
            "end_time": 86399
          }
        ]
      },
      "irregulary_avaliable_time": [
        {
          "begin_time": "2015-05-20T13:29:35+08:00",
          "end_time": "2015-05-20T13:29:35+08:00"
        }
      ]
    },
    "fixed_normal_coupon": {
      "discount_amount": 5,
      "transaction_minimum": 100
    },
    "discount_coupon": {
      "discount_percent": 88,
      "transaction_minimum":100
    },
    "exchange_coupon":{
      "exchange_price":100,
      "transaction_minimum":100
    },
    "use_method": "OFF_LINE",
    "mini_programs_appid":"wx23232232323",
    "mini_programs_path":"/path/index/index"
  },
  "stock_send_rule": {
    "max_amount": 100000,
    "max_coupons": 100,
    "max_coupons_per_user": 5,
    "max_amount_by_day": 1000,
    "max_coupons_by_day": 100,
    "natural_person_limit": "false",
    "prevent_api_abuse": "false",
    "transferable": "false",
    "shareable": "false"
  },
  "out_request_no": "100002322019090134234sfdf",
  "custom_entrance": {
    "mini_programs_info": {
      "mini_programs_appid": "wx234545656765876",
      "mini_programs_path": "/path/index/index",
      "entrance_words": "欢迎选购",
      "guiding_words": "获取更多优惠"
    },
    "appid": "wx324345hgfhfghfg",
    "hall_id": "233455656",
    "store_id": "233554655"
  },
  "display_pattern_info": {
    "description": "xxx门店可用",
    "merchant_logo_url": "https://xxx",
    "merchant_name": "微信支付",
    "background_color": "xxxxx",
    "coupon_image_url": "图片cdn地址"
  },
  "coupon_code_mode": "WECHATPAY_MODE"
}

    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型[长度限制] 必填 描述
批次号 stock_id string[1,20] 微信为每个商家券批次分配的唯一ID。
示例值:98065001
创建时间 create_time string[1,32] 创建时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35+08:00

返回示例


{
  "stock_id": "98065001",
  "create_time": "2015-05-20T13:29:35+08:00"
}
                                

    http://2323weixin.qq.com
                                

跳转小程序带参数说明

如果商家券配置了跳转小程序的入口(包括立即使用以及自定义入口),跳转链接会带有批次号、openid以及加密的code,解密方式可参考解密说明



/path/index/index.html?stock_id=128695000000007&openid=o7tgX0RiTlJo9IXVVfemjFSlFMo4&nonce=B9Jr9gtzMSs7&associate=COUPON_CODE&ciphertext=nmARA5zbjlL%2FaCiKN7S3h1z%2FGhmCfNW9IGQHX6XqTR3zYzQ43sQ%3D
                                

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 参数错误 查看具体错误信息,调整参数
400 SYSTEM_ERROR 系统错误 请使用相同参数稍后重新调用
400 RESOURCE_ALREADY_EXISTS 批次已存在 查看out_request_no字段是否重复使用
券已被其他订单核销 请通过查询券API确认券是否已被其他订单核销
404 RESOURCE_NOT_EXISTS 查询的资源不存在 请检查查询资源的对应id是否填写正确
403 NOAUTH 无权限 查看具体错误信息,确认是否有权限
400 APPID_MCHID_NOT_MATCH appid与请求方商户无关联关系 appid与请求方商户不匹配,请确认appid与请求方商户是否有关联关系
400 MCH_NOT_EXISTS 商户号不存在 请确认传入的商户号是否正确
404 USER_NOT_EXISTS openid不正确 请确认传入的openid是否正确
500 SYSTEM_ERROR 系统失败 多为网络超时引起,重试
429 FREQUENCY_LIMITED 频率限制 调用太频繁,请降低调用接口频率
403 RULELIMIT 券不在有效期 请确认券是否能在当前时间核销
400 INVALID_REQUEST 发券模式不合法 请更换支持预上传code的批次后重试
上传的自定义code已达上限 请更换一个新的批次后重试

版本说明

关闭
V1.4
2020年07月24日
1.新增code展示模式字段code_display_mode
V1.3
2020年03月20日
1.stock_name的字段长度改为24、merchant_name字段长度改为16、核销方式枚举值:“USER_SELF”改为“SELF_CONSUME”
V1.2
2020年01月10日
1. 新增事件通知配置(notify_config)字段