查询用户单张券详情API

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


服务商可通过该接口查询微信用户卡包中某一张商家券的详情信息。

接口说明

适用对象:微信支付商户

请求URL:https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/{openid}/coupons/{coupon_code}/appids/{appid}

请求方式:GET

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


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

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


请求参数

参数名 变量 类型 必填 描述
券code coupon_code string(32) path 券的唯一标识。
示例值:123446565767
公众账号ID appid string(32) path 微信为可核销商户分配的公众账号ID,接口传入的所有appid应该为公众号的appid(在mp.weixin.qq.com申请的),不能为APP的appid(在open.weixin.qq.com申请的)。
示例值:wx233544546545989
用户标识 openid string(128) path Openid信息,用户在appid下的唯一标识。
示例值:2323dfsdf342342

请求示例


https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons/123446565767/appids/wx233544546545989
    
{
JAVA示例代码
}
    

返回参数

参数名 变量 类型 必填 描述
批次归属商户号 belong_merchant string(15) 批次归属于哪个商户。
特殊规则:最小长度取值为8。
示例值:10000022
商家券批次名称 stock_name string(24) 批次名称,字数上限为24个字节长度(中文按UTF8编码算字节数)。
示例值:商家券
批次备注 comment string(20) 仅配置商户可见,用于自定义信息。
示例值:xxx可用
适用商品范围 goods_name string(15) 适用商品范围
示例值:xxx商品可用
批次类型 stock_type string(128) 批次类型
NORMAL:固定面额满减券批次
DISCOUNT:折扣券批次
EXCHANGE:换购券批次
示例值:NORMAL
是否允许转赠 transferable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
是否允许分享领券链接 shareable bool 不填默认否,枚举值:
true:是
false:否
该字段暂未开放
示例值:false
券状态 coupon_state string(16)

商家券状态

枚举值:
SENDED:可用
USED:已核销
EXPIRED:已过期
示例值:SENDED

+样式信息 display_pattern_info object 商家券详细信息
参数名 变量 类型 必填 描述
使用须知 description string(1000) 用于说明详细的活动规则,会展示在代金券详情页。
示例值:深圳南山门店可用
商户logo merchant_logo_url string(128) 商户logo的URL地址,可通过图片上传API获得图片URL地址。
示例值:https://qpic.cn/xxx
商户名称 merchant_name string(16) 商户名称,字数上限为16个字节长度(中文按UTF8编码算字节数)
示例值:微信支付
背景颜色 background_color string(15) 代金券的背景颜色,可设置10种颜色,色值请参考卡券背景颜色图。颜色取值为颜色图中的颜色名称。
示例值:Color020
券详情图片 coupon_image_url string(128) 券详情图片, 850像素*350像素,且图片大小不超过2M,支持JPG/PNG格式,可通过图片上传API获得图片URL地址。
示例值:https://qpic.cn/xxx
+券核销规则 coupon_use_rule 券核销规则 券核销相关规则
参数名 变量 类型 必填 描述
+券可核销时间 coupon_available_time object 日期区间内可以使用优惠。
参数名 变量 类型 必填 描述
开始时间 available_begin_time string(32) 批次开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
结束时间 available_end_time string(32) 批次结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
领取后N天内有效 available_day_after_receive int

日期区间内,用户领券后x天内有效。

1、用户在有效期开始前领取代金券,则从有效期第一天开始计算天数。

2、用户在有效期内领取代金券,则从领取当天开始计算天数。

3、无论用户何时领取代金券,代金券在活动有效期结束后均不可用。
特殊规则:取值范围 1 ≤ value ≤ 365
示例值:3

+ 固定周期有效时间段 available_week object 可以设置多个星期下的多个可用时间段,比如每周二10点到18点,用户自定义字段。
参数名 变量 类型 必填 描述
可用星期数 week_day int 0代表周日,1代表周一,以此类推。
示例值:1, 2
+ 当天可用时间段 available_day_time array 可以填写多个时间段,最多不超过3个。
参数名 变量 类型 必填 描述
当天可用开始时间 begin_time int 当天可用开始时间,单位:秒,1代表当天0点0分1秒。
示例值:3600
当天可用结束时间 end_time int 当天可用结束时间,单位:秒,86399代表当天23点59分59秒。
示例值:86399
+ 无规律的有效时间段 irregulary_avaliable_time array 无规律的有效时间,多个无规律时间段,用户自定义字段。
参数名 变量 类型 必填 描述
开始时间 begin_time string(32) 开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
结束时间 end_time string(32) 结束时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2015-05-20T13:29:35.120+08:00
+固定面额满减券使用规则 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(128) 枚举值:
OFF_LINE:线下滴码核销,点击券“立即使用”跳转展示券二维码详情。
MINI_PROGRAMS:线上小程序核销,点击券“立即使用”跳转至配置的商家小程序(需要添加小程序appid和path)。
PAYMENT_CODE:微信支付付款码核销,点击券“立即使用”跳转至微信支付钱包付款码。
SELF_CONSUME:用户自助核销,点击券“立即使用”跳转至用户自助操作核销界面(当前暂不支持用户自助核销)。
示例值:OFF_LINE
小程序appid mini_programs_appid string(32) 条件选填 核销方式为线上小程序核销才有效。
示例值:wx23232232323
小程序path mini_programs_path string(128) 条件选填 核销方式为线上小程序核销才有效。
示例值:/path/index/index
+自定义入口 custom_entrance object 卡详情页面,可选择多种入口引导用户。
参数名 变量 类型 必填 描述
+小程序入口 mini_programs_info object

需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序,APPID、path、入口文案为必填,引导文案非必填。

appid要与归属商户号有M-A or M-m-suba关系。

参数名 变量 类型 必填 描述
商家小程序appid mini_programs_appid string(32) 商家小程序appid要与归属商户号有M-A or M-m-suba关系。
示例值:wx234545656765876
商家小程序path mini_programs_path string(128) 商家小程序path
示例值:/path/index/index
入口文案 entrance_words string(5) 入口文案
示例值:欢迎选购
引导文案 guiding_words string(6) 小程序入口引导文案,用户自定义字段。
示例值:获取更多优惠
商户公众号appid appid string(32) 可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。
示例值:wx324345hgfhfghfg
更多优惠入口;
营销馆创建地址:
https://pay.weixin.qq.com/index.php
/xphp/cfav_market/hall#/pages/list/list
hall_id string(64) 填写微信支付营销馆的馆id,用户自定义字段。
示例值:233455656
可用门店id store_id string(64) 填写代金券可用门店id,用户自定义字段。
示例值:233554655
券code coupon_code string(32) 券的唯一标识。
示例值:123446565767
批次号 stock_id string(20) path 批次号,是否指定批次号查询。
示例值:1002323
券可使用开始时间 available_start_time string(32) 1、用户领取到该张券实际可使用的开始时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
2、若券批次设置为领取后可用,则开始时间即为券的领取时间;若券批次设置为领取后第X天可用,则开始时间为券领取时间后第X天00:00:00可用。
示例值:2019-12-30T13:29:35.120+08:00
券过期时间 expire_time string(32) 用户领取到该张券的过期时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2019-12-31T13:29:35.120+08:00
券领券时间 receive_time string(32) 用户领取到该张券的时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值:2019-12-31T13:29:35.120+08:00
发券请求单号 send_request_no string(32) 发券时传入的唯一凭证
示例值: MCHSEND202003101234
核销请求单号 use_request_no string(32) 核销时传入的唯一凭证(如券已被核销,将返回此字段)
示例值: MCHUSE202003101234
券核销时间 use_time string(32) 券被核销的时间(如券已被核销,将返回此字段);遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss:sss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss:sss表示时分秒毫秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35.120+08:00表示,北京时间2015年5月20日 13点29分35秒。
示例值: 2019-12-31T13:29:35.120+08:00

返回示例


> 200 Response
{
  "belong_merchant": "100000222",
  "stock_name": "商家券",
  "comment": "xxx可用",
  "goods_name": "xxx商品可用",
  "stock_type": "NORMAL",
  "transferable": "false",
  "shareable": "false",
  "coupon_state": "SENDED",
  "display_pattern_info": {
    "description": "xxx门店可用",
    "merchant_logo_url": "https://xxx",
    "merchant_name": "微信支付",
    "background_color": "xxxxx",
    "coupon_image_url": "图片cdn地址"
  },
  "coupon_use_rule": {
    "coupon_available_time": {
      "available_begin_time": "2015-05-20T13:29:35.120+08:00",
      "available_end_time": "2015-05-20T13:29:35.120+08:00",
      "available_day_after_receive": 3,
      "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.120+08:00",
          "end_time": "2015-05-20T13:29:35.120+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"
  },
  "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"
  },
  "coupon_code": "123446565767",
  "stock_id": "1002323",
  "available_start_time": "2019-12-30T13:29:35.120+08:00",
  "expire_time": "2019-12-31T13:29:35.120+08:00",
  "receive_time": "2019-12-30T13:29:35.120+08:00"
  "send_request_no": "MCHSEND202003101234"
  "use_request_no": "MCHSEND202003101234"
  "use_time": "2019-12-30T13:29:35.120+08:00"
}
                                

    http://2323weixin.qq.com
                                

错误码公共错误码

状态码 错误码 描述 解决方案
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.2
2020年03月20日
1. stock_name的字段长度改为24、merchant_name字段长度改为16、核销方式枚举值:“USER_SELF”改为“SELF_CONSUME”;
2. 新增send_request_no、use_request_no、use_time 3字段。
V1.1
2020年01月08日
1. 核销方式(use_method)新增枚举值PAYMENT_CODE、修改批次类型枚举值