根据过滤条件查询用户的券
更新时间:2024.11.18商户自定义筛选条件(如创建商户号、归属商户号、发放商户号等),查询指定微信用户卡包中满足对应条件的所有商家券信息。
接口说明
支持商户:【普通服务商】 【渠道商】
请求方式:【GET】/v3/marketing/busifavor/users/{openid}/coupons
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
path 路径参数
openid 必填 string
【用户标识】Openid信息,用户在AppID下的唯一标识。
校验规则:传入的OpenID得是调用方商户号(即请求头里面的商户号)有绑定关系的AppID获取的OpenID或传入的OpenID得是归属商户号有绑定关系的AppID获取的OpenID。获取OpenID文档
query 查询参数
appid 必填 string
【公众账号ID】支持传入与当前调用接口商户号有绑定关系的AppID。支持小程序AppID与公众号AppID。
校验规则:传入的AppID得是与调用方商户号(即请求头里面的商户号)有绑定关系的AppID 或 传入的AppID得是归属商户号有绑定关系的AppID
stock_id 选填 string
【批次号】批次号,是否指定批次号查询
creator_merchant 选填 string
【创建批次的商户号】批次创建方商户号
校验规则:当调用方商户号(即请求头中的商户号)为创建批次方商户号时,该参数必传
belong_merchant 选填 string
【批次归属商户号】批次归属商户号
校验规则:当调用方商户号(即请求头中的商户号)为批次归属商户号时,该参数必传
sender_merchant 选填 string
【批次发放商户号】批次发放商户号
校验规则:当调用方商户号(即请求头中的商户号)为批次发放商户号时,该参数必传;委托营销关系下,请填写委托发券的商户号
offset 选填 integer
【分页页码】分页页码
limit 选填 integer
【分页大小】分页大小
coupon_state 选填 string
【券状态】商家券状态
可选取值::
SENDED
: 可用USED
: 已核销EXPIRED
: 已过期DELETED
: 已删除DEACTIVATED
: 已失效
请求示例
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons?appid=wx233544546545989&stock_id=100088&coupon_state=SENDED&creator_merchant=1000000001&belong_merchant=1000000002&sender_merchant=1000000003&offset=0&limit=20 \ 3 -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \ 4 -H "Accept: application/json" 5
需配合微信支付工具库 WXPayUtility 使用,请参考Java
1package com.java.demo; 2 3import com.java.utils.WXPayUtility; // 引用微信支付工具库,参考:https://pay.weixin.qq.com/doc/v3/partner/4014985777 4 5import com.google.gson.annotations.SerializedName; 6import com.google.gson.annotations.Expose; 7import okhttp3.MediaType; 8import okhttp3.OkHttpClient; 9import okhttp3.Request; 10import okhttp3.RequestBody; 11import okhttp3.Response; 12 13import java.io.IOException; 14import java.io.UncheckedIOException; 15import java.security.PrivateKey; 16import java.security.PublicKey; 17import java.util.ArrayList; 18import java.util.HashMap; 19import java.util.List; 20import java.util.Map; 21 22/** 23 * 根据过滤条件查询用户的券 24 */ 25public class ListCouponsByFilter { 26 private static String HOST = "https://api.mch.weixin.qq.com"; 27 private static String METHOD = "GET"; 28 private static String PATH = "/v3/marketing/busifavor/users/{openid}/coupons"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 32 ListCouponsByFilter client = new ListCouponsByFilter( 33 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 34 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 35 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 ListCouponsByFilterRequest request = new ListCouponsByFilterRequest(); 41 request.openid = "2323dfsdf342342"; 42 request.appid = "wx233544546545989"; 43 request.stockId = "100088"; 44 request.couponState = CouponStatus.SENDED; 45 request.creatorMerchant = "1000000001"; 46 request.belongMerchant = "1000000002"; 47 request.senderMerchant = "1000000003"; 48 request.offset = 0L; 49 request.limit = 20L; 50 try { 51 CouponListResponse response = client.run(request); 52 // TODO: 请求成功,继续业务逻辑 53 System.out.println(response); 54 } catch (WXPayUtility.ApiException e) { 55 // TODO: 请求失败,根据状态码执行不同的逻辑 56 e.printStackTrace(); 57 } 58 } 59 60 public CouponListResponse run(ListCouponsByFilterRequest request) { 61 String uri = PATH; 62 uri = uri.replace("{openid}", WXPayUtility.urlEncode(request.openid)); 63 Map<String, Object> args = new HashMap<>(); 64 args.put("appid", request.appid); 65 args.put("stock_id", request.stockId); 66 args.put("coupon_state", request.couponState); 67 args.put("creator_merchant", request.creatorMerchant); 68 args.put("belong_merchant", request.belongMerchant); 69 args.put("sender_merchant", request.senderMerchant); 70 args.put("offset", request.offset); 71 args.put("limit", request.limit); 72 String queryString = WXPayUtility.urlEncode(args); 73 if (!queryString.isEmpty()) { 74 uri = uri + "?" + queryString; 75 } 76 77 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 78 reqBuilder.addHeader("Accept", "application/json"); 79 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 80 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 81 reqBuilder.method(METHOD, null); 82 Request httpRequest = reqBuilder.build(); 83 84 // 发送HTTP请求 85 OkHttpClient client = new OkHttpClient.Builder().build(); 86 try (Response httpResponse = client.newCall(httpRequest).execute()) { 87 String respBody = WXPayUtility.extractBody(httpResponse); 88 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 89 // 2XX 成功,验证应答签名 90 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 91 httpResponse.headers(), respBody); 92 93 // 从HTTP应答报文构建返回数据 94 return WXPayUtility.fromJson(respBody, CouponListResponse.class); 95 } else { 96 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 97 } 98 } catch (IOException e) { 99 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 100 } 101 } 102 103 private final String mchid; 104 private final String certificateSerialNo; 105 private final PrivateKey privateKey; 106 private final String wechatPayPublicKeyId; 107 private final PublicKey wechatPayPublicKey; 108 109 public ListCouponsByFilter(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 110 this.mchid = mchid; 111 this.certificateSerialNo = certificateSerialNo; 112 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 113 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 114 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 115 } 116 117 public static class ListCouponsByFilterRequest { 118 @SerializedName("openid") 119 @Expose(serialize = false) 120 public String openid; 121 122 @SerializedName("appid") 123 @Expose(serialize = false) 124 public String appid; 125 126 @SerializedName("stock_id") 127 @Expose(serialize = false) 128 public String stockId; 129 130 @SerializedName("creator_merchant") 131 @Expose(serialize = false) 132 public String creatorMerchant; 133 134 @SerializedName("belong_merchant") 135 @Expose(serialize = false) 136 public String belongMerchant; 137 138 @SerializedName("sender_merchant") 139 @Expose(serialize = false) 140 public String senderMerchant; 141 142 @SerializedName("offset") 143 @Expose(serialize = false) 144 public Long offset; 145 146 @SerializedName("limit") 147 @Expose(serialize = false) 148 public Long limit; 149 150 @SerializedName("coupon_state") 151 @Expose(serialize = false) 152 public CouponStatus couponState; 153 } 154 155 public static class CouponListResponse { 156 @SerializedName("data") 157 public List<CouponEntity> data; 158 159 @SerializedName("total_count") 160 public Long totalCount; 161 162 @SerializedName("limit") 163 public Long limit; 164 165 @SerializedName("offset") 166 public Long offset; 167 } 168 169 public enum CouponStatus { 170 @SerializedName("SENDED") 171 SENDED, 172 @SerializedName("USED") 173 USED, 174 @SerializedName("EXPIRED") 175 EXPIRED, 176 @SerializedName("DELETED") 177 DELETED, 178 @SerializedName("DEACTIVATED") 179 DEACTIVATED 180 } 181 182 public static class CouponEntity { 183 @SerializedName("belong_merchant") 184 public String belongMerchant; 185 186 @SerializedName("stock_name") 187 public String stockName; 188 189 @SerializedName("comment") 190 public String comment; 191 192 @SerializedName("goods_name") 193 public String goodsName; 194 195 @SerializedName("stock_type") 196 public BusiFavorStockType stockType; 197 198 @SerializedName("transferable") 199 public Boolean transferable; 200 201 @SerializedName("shareable") 202 public Boolean shareable; 203 204 @SerializedName("coupon_state") 205 public CouponStatus couponState; 206 207 @SerializedName("display_pattern_info") 208 public DisplayPatternInfo displayPatternInfo; 209 210 @SerializedName("coupon_use_rule") 211 public CouponUseRule couponUseRule; 212 213 @SerializedName("custom_entrance") 214 public CustomEntrance customEntrance; 215 216 @SerializedName("coupon_code") 217 public String couponCode; 218 219 @SerializedName("stock_id") 220 public String stockId; 221 222 @SerializedName("available_start_time") 223 public String availableStartTime; 224 225 @SerializedName("expire_time") 226 public String expireTime; 227 228 @SerializedName("receive_time") 229 public String receiveTime; 230 231 @SerializedName("send_request_no") 232 public String sendRequestNo; 233 234 @SerializedName("use_request_no") 235 public String useRequestNo; 236 237 @SerializedName("use_time") 238 public String useTime; 239 240 @SerializedName("associate_out_trade_no") 241 public String associateOutTradeNo; 242 243 @SerializedName("return_request_no") 244 public String returnRequestNo; 245 246 @SerializedName("return_time") 247 public String returnTime; 248 249 @SerializedName("deactivate_request_no") 250 public String deactivateRequestNo; 251 252 @SerializedName("deactivate_time") 253 public String deactivateTime; 254 255 @SerializedName("deactivate_reason") 256 public String deactivateReason; 257 } 258 259 public enum BusiFavorStockType { 260 @SerializedName("NORMAL") 261 NORMAL, 262 @SerializedName("DISCOUNT") 263 DISCOUNT, 264 @SerializedName("EXCHANGE") 265 EXCHANGE 266 } 267 268 public static class DisplayPatternInfo { 269 @SerializedName("description") 270 public String description; 271 272 @SerializedName("merchant_logo_url") 273 public String merchantLogoUrl; 274 275 @SerializedName("merchant_name") 276 public String merchantName; 277 278 @SerializedName("background_color") 279 public String backgroundColor; 280 281 @SerializedName("coupon_image_url") 282 public String couponImageUrl; 283 284 @SerializedName("finder_info") 285 public FinderInfo finderInfo; 286 } 287 288 public static class CouponUseRule { 289 @SerializedName("coupon_available_time") 290 public FavorAvailableTime couponAvailableTime; 291 292 @SerializedName("fixed_normal_coupon") 293 public FixedValueStockMsg fixedNormalCoupon; 294 295 @SerializedName("discount_coupon") 296 public DiscountMsg discountCoupon; 297 298 @SerializedName("exchange_coupon") 299 public ExchangeMsg exchangeCoupon; 300 301 @SerializedName("use_method") 302 public CouponUseMethod useMethod; 303 304 @SerializedName("mini_programs_appid") 305 public String miniProgramsAppid; 306 307 @SerializedName("mini_programs_path") 308 public String miniProgramsPath; 309 } 310 311 public static class CustomEntrance { 312 @SerializedName("mini_programs_info") 313 public MiniAppInfo miniProgramsInfo; 314 315 @SerializedName("appid") 316 public String appid; 317 318 @SerializedName("hall_id") 319 public String hallId; 320 321 @SerializedName("store_id") 322 public String storeId; 323 324 @SerializedName("code_display_mode") 325 public CodeDisplayMode codeDisplayMode; 326 } 327 328 public static class FinderInfo { 329 @SerializedName("finder_id") 330 public String finderId; 331 332 @SerializedName("finder_video_id") 333 public String finderVideoId; 334 335 @SerializedName("finder_video_cover_image_url") 336 public String finderVideoCoverImageUrl; 337 } 338 339 public static class FavorAvailableTime { 340 @SerializedName("available_begin_time") 341 public String availableBeginTime; 342 343 @SerializedName("available_end_time") 344 public String availableEndTime; 345 346 @SerializedName("available_day_after_receive") 347 public Long availableDayAfterReceive; 348 349 @SerializedName("available_week") 350 public AvailableWeek availableWeek; 351 352 @SerializedName("irregulary_avaliable_time") 353 public List<IrregularAvailableTime> irregularyAvaliableTime; 354 355 @SerializedName("wait_days_after_receive") 356 public Long waitDaysAfterReceive; 357 } 358 359 public static class FixedValueStockMsg { 360 @SerializedName("discount_amount") 361 public Long discountAmount; 362 363 @SerializedName("transaction_minimum") 364 public Long transactionMinimum; 365 } 366 367 public static class DiscountMsg { 368 @SerializedName("discount_percent") 369 public Long discountPercent; 370 371 @SerializedName("transaction_minimum") 372 public Long transactionMinimum; 373 } 374 375 public static class ExchangeMsg { 376 @SerializedName("exchange_price") 377 public Long exchangePrice; 378 379 @SerializedName("transaction_minimum") 380 public Long transactionMinimum; 381 } 382 383 public enum CouponUseMethod { 384 @SerializedName("OFF_LINE") 385 OFF_LINE, 386 @SerializedName("MINI_PROGRAMS") 387 MINI_PROGRAMS, 388 @SerializedName("SELF_CONSUME") 389 SELF_CONSUME, 390 @SerializedName("PAYMENT_CODE") 391 PAYMENT_CODE 392 } 393 394 public static class MiniAppInfo { 395 @SerializedName("mini_programs_appid") 396 public String miniProgramsAppid; 397 398 @SerializedName("mini_programs_path") 399 public String miniProgramsPath; 400 401 @SerializedName("entrance_words") 402 public String entranceWords; 403 404 @SerializedName("guiding_words") 405 public String guidingWords; 406 } 407 408 public enum CodeDisplayMode { 409 @SerializedName("NOT_SHOW") 410 NOT_SHOW, 411 @SerializedName("BARCODE") 412 BARCODE, 413 @SerializedName("QRCODE") 414 QRCODE 415 } 416 417 public static class AvailableWeek { 418 @SerializedName("week_day") 419 public List<Long> weekDay; 420 421 @SerializedName("available_day_time") 422 public List<AvailableCurrentDayTime> availableDayTime; 423 } 424 425 public static class IrregularAvailableTime { 426 @SerializedName("begin_time") 427 public String beginTime; 428 429 @SerializedName("end_time") 430 public String endTime; 431 } 432 433 public static class AvailableCurrentDayTime { 434 @SerializedName("begin_time") 435 public Long beginTime; 436 437 @SerializedName("end_time") 438 public Long endTime; 439 } 440 441} 442
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/partner/4015119446 5 "encoding/json" 6 "fmt" 7 "net/http" 8 "net/url" 9 "strings" 10 "time" 11) 12 13func main() { 14 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/partner/4013080340 15 config, err := wxpay_utility.CreateMchConfig( 16 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/partner/4013080340 17 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013058924 18 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 19 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/partner/4013038589 20 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &ListCouponsByFilterRequest{ 28 Openid: wxpay_utility.String("2323dfsdf342342"), 29 Appid: wxpay_utility.String("wx233544546545989"), 30 StockId: wxpay_utility.String("100088"), 31 CouponState: COUPONSTATUS_SENDED.Ptr(), 32 CreatorMerchant: wxpay_utility.String("1000000001"), 33 BelongMerchant: wxpay_utility.String("1000000002"), 34 SenderMerchant: wxpay_utility.String("1000000003"), 35 Offset: wxpay_utility.Int64(0), 36 Limit: wxpay_utility.Int64(20), 37 } 38 39 response, err := ListCouponsByFilter(config, request) 40 if err != nil { 41 fmt.Printf("请求失败: %+v\n", err) 42 // TODO: 请求失败,根据状态码执行不同的处理 43 return 44 } 45 46 // TODO: 请求成功,继续业务逻辑 47 fmt.Printf("请求成功: %+v\n", response) 48} 49 50func ListCouponsByFilter(config *wxpay_utility.MchConfig, request *ListCouponsByFilterRequest) (response *CouponListResponse, err error) { 51 const ( 52 host = "https://api.mch.weixin.qq.com" 53 method = "GET" 54 path = "/v3/marketing/busifavor/users/{openid}/coupons" 55 ) 56 57 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 58 if err != nil { 59 return nil, err 60 } 61 reqUrl.Path = strings.Replace(reqUrl.Path, "{openid}", url.PathEscape(*request.Openid), -1) 62 query := reqUrl.Query() 63 if request.Appid != nil { 64 query.Add("appid", *request.Appid) 65 } 66 if request.StockId != nil { 67 query.Add("stock_id", *request.StockId) 68 } 69 if request.CouponState != nil { 70 query.Add("coupon_state", fmt.Sprintf("%v", *request.CouponState)) 71 } 72 if request.CreatorMerchant != nil { 73 query.Add("creator_merchant", *request.CreatorMerchant) 74 } 75 if request.BelongMerchant != nil { 76 query.Add("belong_merchant", *request.BelongMerchant) 77 } 78 if request.SenderMerchant != nil { 79 query.Add("sender_merchant", *request.SenderMerchant) 80 } 81 if request.Offset != nil { 82 query.Add("offset", fmt.Sprintf("%v", *request.Offset)) 83 } 84 if request.Limit != nil { 85 query.Add("limit", fmt.Sprintf("%v", *request.Limit)) 86 } 87 reqUrl.RawQuery = query.Encode() 88 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 89 if err != nil { 90 return nil, err 91 } 92 httpRequest.Header.Set("Accept", "application/json") 93 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 94 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 95 if err != nil { 96 return nil, err 97 } 98 httpRequest.Header.Set("Authorization", authorization) 99 100 client := &http.Client{} 101 httpResponse, err := client.Do(httpRequest) 102 if err != nil { 103 return nil, err 104 } 105 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 106 if err != nil { 107 return nil, err 108 } 109 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 110 // 2XX 成功,验证应答签名 111 err = wxpay_utility.ValidateResponse( 112 config.WechatPayPublicKeyId(), 113 config.WechatPayPublicKey(), 114 &httpResponse.Header, 115 respBody, 116 ) 117 if err != nil { 118 return nil, err 119 } 120 response := &CouponListResponse{} 121 if err := json.Unmarshal(respBody, response); err != nil { 122 return nil, err 123 } 124 125 return response, nil 126 } else { 127 return nil, wxpay_utility.NewApiException( 128 httpResponse.StatusCode, 129 httpResponse.Header, 130 respBody, 131 ) 132 } 133} 134 135type ListCouponsByFilterRequest struct { 136 Openid *string `json:"openid,omitempty"` 137 Appid *string `json:"appid,omitempty"` 138 StockId *string `json:"stock_id,omitempty"` 139 CreatorMerchant *string `json:"creator_merchant,omitempty"` 140 BelongMerchant *string `json:"belong_merchant,omitempty"` 141 SenderMerchant *string `json:"sender_merchant,omitempty"` 142 Offset *int64 `json:"offset,omitempty"` 143 Limit *int64 `json:"limit,omitempty"` 144 CouponState *CouponStatus `json:"coupon_state,omitempty"` 145} 146 147func (o *ListCouponsByFilterRequest) MarshalJSON() ([]byte, error) { 148 type Alias ListCouponsByFilterRequest 149 a := &struct { 150 Openid *string `json:"openid,omitempty"` 151 Appid *string `json:"appid,omitempty"` 152 StockId *string `json:"stock_id,omitempty"` 153 CreatorMerchant *string `json:"creator_merchant,omitempty"` 154 BelongMerchant *string `json:"belong_merchant,omitempty"` 155 SenderMerchant *string `json:"sender_merchant,omitempty"` 156 Offset *int64 `json:"offset,omitempty"` 157 Limit *int64 `json:"limit,omitempty"` 158 CouponState *CouponStatus `json:"coupon_state,omitempty"` 159 *Alias 160 }{ 161 // 序列化时移除非 Body 字段 162 Openid: nil, 163 Appid: nil, 164 StockId: nil, 165 CreatorMerchant: nil, 166 BelongMerchant: nil, 167 SenderMerchant: nil, 168 Offset: nil, 169 Limit: nil, 170 CouponState: nil, 171 Alias: (*Alias)(o), 172 } 173 return json.Marshal(a) 174} 175 176type CouponListResponse struct { 177 Data []CouponEntity `json:"data,omitempty"` 178 TotalCount *int64 `json:"total_count,omitempty"` 179 Limit *int64 `json:"limit,omitempty"` 180 Offset *int64 `json:"offset,omitempty"` 181} 182 183type CouponStatus string 184 185func (e CouponStatus) Ptr() *CouponStatus { 186 return &e 187} 188 189const ( 190 COUPONSTATUS_SENDED CouponStatus = "SENDED" 191 COUPONSTATUS_USED CouponStatus = "USED" 192 COUPONSTATUS_EXPIRED CouponStatus = "EXPIRED" 193 COUPONSTATUS_DELETED CouponStatus = "DELETED" 194 COUPONSTATUS_DEACTIVATED CouponStatus = "DEACTIVATED" 195) 196 197type CouponEntity struct { 198 BelongMerchant *string `json:"belong_merchant,omitempty"` 199 StockName *string `json:"stock_name,omitempty"` 200 Comment *string `json:"comment,omitempty"` 201 GoodsName *string `json:"goods_name,omitempty"` 202 StockType *BusiFavorStockType `json:"stock_type,omitempty"` 203 Transferable *bool `json:"transferable,omitempty"` 204 Shareable *bool `json:"shareable,omitempty"` 205 CouponState *CouponStatus `json:"coupon_state,omitempty"` 206 DisplayPatternInfo *DisplayPatternInfo `json:"display_pattern_info,omitempty"` 207 CouponUseRule *CouponUseRule `json:"coupon_use_rule,omitempty"` 208 CustomEntrance *CustomEntrance `json:"custom_entrance,omitempty"` 209 CouponCode *string `json:"coupon_code,omitempty"` 210 StockId *string `json:"stock_id,omitempty"` 211 AvailableStartTime *time.Time `json:"available_start_time,omitempty"` 212 ExpireTime *time.Time `json:"expire_time,omitempty"` 213 ReceiveTime *time.Time `json:"receive_time,omitempty"` 214 SendRequestNo *string `json:"send_request_no,omitempty"` 215 UseRequestNo *string `json:"use_request_no,omitempty"` 216 UseTime *time.Time `json:"use_time,omitempty"` 217 AssociateOutTradeNo *time.Time `json:"associate_out_trade_no,omitempty"` 218 ReturnRequestNo *string `json:"return_request_no,omitempty"` 219 ReturnTime *time.Time `json:"return_time,omitempty"` 220 DeactivateRequestNo *string `json:"deactivate_request_no,omitempty"` 221 DeactivateTime *time.Time `json:"deactivate_time,omitempty"` 222 DeactivateReason *string `json:"deactivate_reason,omitempty"` 223} 224 225type BusiFavorStockType string 226 227func (e BusiFavorStockType) Ptr() *BusiFavorStockType { 228 return &e 229} 230 231const ( 232 BUSIFAVORSTOCKTYPE_NORMAL BusiFavorStockType = "NORMAL" 233 BUSIFAVORSTOCKTYPE_DISCOUNT BusiFavorStockType = "DISCOUNT" 234 BUSIFAVORSTOCKTYPE_EXCHANGE BusiFavorStockType = "EXCHANGE" 235) 236 237type DisplayPatternInfo struct { 238 Description *string `json:"description,omitempty"` 239 MerchantLogoUrl *string `json:"merchant_logo_url,omitempty"` 240 MerchantName *string `json:"merchant_name,omitempty"` 241 BackgroundColor *string `json:"background_color,omitempty"` 242 CouponImageUrl *string `json:"coupon_image_url,omitempty"` 243 FinderInfo *FinderInfo `json:"finder_info,omitempty"` 244} 245 246type CouponUseRule struct { 247 CouponAvailableTime *FavorAvailableTime `json:"coupon_available_time,omitempty"` 248 FixedNormalCoupon *FixedValueStockMsg `json:"fixed_normal_coupon,omitempty"` 249 DiscountCoupon *DiscountMsg `json:"discount_coupon,omitempty"` 250 ExchangeCoupon *ExchangeMsg `json:"exchange_coupon,omitempty"` 251 UseMethod *CouponUseMethod `json:"use_method,omitempty"` 252 MiniProgramsAppid *string `json:"mini_programs_appid,omitempty"` 253 MiniProgramsPath *string `json:"mini_programs_path,omitempty"` 254} 255 256type CustomEntrance struct { 257 MiniProgramsInfo *MiniAppInfo `json:"mini_programs_info,omitempty"` 258 Appid *string `json:"appid,omitempty"` 259 HallId *string `json:"hall_id,omitempty"` 260 StoreId *string `json:"store_id,omitempty"` 261 CodeDisplayMode *CodeDisplayMode `json:"code_display_mode,omitempty"` 262} 263 264type FinderInfo struct { 265 FinderId *string `json:"finder_id,omitempty"` 266 FinderVideoId *string `json:"finder_video_id,omitempty"` 267 FinderVideoCoverImageUrl *string `json:"finder_video_cover_image_url,omitempty"` 268} 269 270type FavorAvailableTime struct { 271 AvailableBeginTime *time.Time `json:"available_begin_time,omitempty"` 272 AvailableEndTime *time.Time `json:"available_end_time,omitempty"` 273 AvailableDayAfterReceive *int64 `json:"available_day_after_receive,omitempty"` 274 AvailableWeek *AvailableWeek `json:"available_week,omitempty"` 275 IrregularyAvaliableTime []IrregularAvailableTime `json:"irregulary_avaliable_time,omitempty"` 276 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 277} 278 279type FixedValueStockMsg struct { 280 DiscountAmount *int64 `json:"discount_amount,omitempty"` 281 TransactionMinimum *int64 `json:"transaction_minimum,omitempty"` 282} 283 284type DiscountMsg struct { 285 DiscountPercent *int64 `json:"discount_percent,omitempty"` 286 TransactionMinimum *int64 `json:"transaction_minimum,omitempty"` 287} 288 289type ExchangeMsg struct { 290 ExchangePrice *int64 `json:"exchange_price,omitempty"` 291 TransactionMinimum *int64 `json:"transaction_minimum,omitempty"` 292} 293 294type CouponUseMethod string 295 296func (e CouponUseMethod) Ptr() *CouponUseMethod { 297 return &e 298} 299 300const ( 301 COUPONUSEMETHOD_OFF_LINE CouponUseMethod = "OFF_LINE" 302 COUPONUSEMETHOD_MINI_PROGRAMS CouponUseMethod = "MINI_PROGRAMS" 303 COUPONUSEMETHOD_SELF_CONSUME CouponUseMethod = "SELF_CONSUME" 304 COUPONUSEMETHOD_PAYMENT_CODE CouponUseMethod = "PAYMENT_CODE" 305) 306 307type MiniAppInfo struct { 308 MiniProgramsAppid *string `json:"mini_programs_appid,omitempty"` 309 MiniProgramsPath *string `json:"mini_programs_path,omitempty"` 310 EntranceWords *string `json:"entrance_words,omitempty"` 311 GuidingWords *string `json:"guiding_words,omitempty"` 312} 313 314type CodeDisplayMode string 315 316func (e CodeDisplayMode) Ptr() *CodeDisplayMode { 317 return &e 318} 319 320const ( 321 CODEDISPLAYMODE_NOT_SHOW CodeDisplayMode = "NOT_SHOW" 322 CODEDISPLAYMODE_BARCODE CodeDisplayMode = "BARCODE" 323 CODEDISPLAYMODE_QRCODE CodeDisplayMode = "QRCODE" 324) 325 326type AvailableWeek struct { 327 WeekDay []int64 `json:"week_day,omitempty"` 328 AvailableDayTime []AvailableCurrentDayTime `json:"available_day_time,omitempty"` 329} 330 331type IrregularAvailableTime struct { 332 BeginTime *time.Time `json:"begin_time,omitempty"` 333 EndTime *time.Time `json:"end_time,omitempty"` 334} 335 336type AvailableCurrentDayTime struct { 337 BeginTime *int64 `json:"begin_time,omitempty"` 338 EndTime *int64 `json:"end_time,omitempty"` 339} 340
应答参数
200 OK
data 选填 array[object]
【结果集】
属性 | |||||||||||||||||||||||||||||||||||||||||||||||||
belong_merchant 必填 string 【批次归属商户号】代金券的所属商户号 stock_name 必填 string 【商家券批次名称】批次名称,字数上限为21个,一个中文汉字/英文字母/数字均占用一个字数。 comment 选填 string 【批次备注】仅配置商户可见,用于自定义信息。字数上限为20个,一个中文汉字/英文字母/数字均占用一个字数。 goods_name 必填 string 【适用商品范围】适用商品范围,字数上限为15个,一个中文汉字/英文字母/数字均占用一个字数。 stock_type 必填 string 【批次类型】批次类型 可选取值::
transferable 选填 boolean 【是否允许转赠】不填默认否,枚举值: shareable 选填 boolean 【是否允许分享领券链接】不填默认否,枚举值: coupon_state 选填 string 【券状态】商家券状态 可选取值::
display_pattern_info 选填 object 【样式信息】
coupon_use_rule 必填 object 【券核销规则】
custom_entrance 选填 object 【自定义入口】
coupon_code 选填 string 【券code】券的唯一标识 stock_id 选填 string 【批次号】批次号 available_start_time 选填 string 【券可使用开始时间】用户领取到的这张券实际可使用的开始时间:如批次设置的领取后可用,则开始时间即为券的领取时间; 如批次设置的领取后第X天可用,则为领取时间后第X天00:00:00 expire_time 选填 string 【券过期时间】用户领取到这张券的过期时间 receive_time 选填 string 【券领取时间】用户领取到这张券的时间 send_request_no 选填 string 【发券请求单号】发券时传入的唯一凭证 use_request_no 选填 string 【核销请求单号】核销时传入的唯一凭证(如券已被核销,将返回此字段) use_time 选填 string 【券核销时间】券被核销的时间(如券已被核销,将返回此字段) associate_out_trade_no 选填 string 【关联的商户订单号】若商家券操作过关联商户订单信息,则该字段返回商家券已关联的商户订单号。 return_request_no 选填 string 【回退请求单号】回退时传入的唯一凭证(如券发生了退回,将返回此字段) return_time 选填 string 【券回退时间】券被回退的时间(如券发生了退回,将返回此字段) deactivate_request_no 选填 string 【失效请求单号】失效时传入的唯一凭证(如果一张券已失效,将返回此字段) deactivate_time 选填 string 【券失效时间】券被失效的时间(如果一张券已失效,将返回此字段) deactivate_reason 选填 string 【失效原因】失效一张券的原因(如果一张券已失效,可能返回此字段) |
total_count 必填 integer
【总数量】总数量
limit 必填 integer
【分页大小】分页大小
offset 必填 integer
【分页页码】分页页码
应答示例
200 OK
1{ 2 "data" : [ 3 { 4 "belong_merchant" : "100000222", 5 "stock_name" : "商家券", 6 "comment" : "xxx可用", 7 "goods_name" : "xxx商品可用", 8 "stock_type" : "NORMAL", 9 "transferable" : false, 10 "shareable" : false, 11 "coupon_state" : "SENDED", 12 "display_pattern_info" : { 13 "description" : "xxx门店可用", 14 "merchant_logo_url" : "https://xxx", 15 "merchant_name" : "微信支付", 16 "background_color" : "xxxxx", 17 "coupon_image_url" : "图片cdn地址", 18 "finder_info" : { 19 "finder_id" : "sph6Rngt2T4RlUf", 20 "finder_video_id" : "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94", 21 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/xxx" 22 } 23 }, 24 "coupon_use_rule" : { 25 "coupon_available_time" : { 26 "available_begin_time" : "2015-05-20T13:29:35+08:00", 27 "available_end_time" : "2015-05-20T13:29:35+08:00", 28 "available_day_after_receive" : 3, 29 "available_week" : { 30 "week_day" : [ 31 1 32 ], 33 "available_day_time" : [ 34 { 35 "begin_time" : 3600, 36 "end_time" : 86399 37 } 38 ] 39 }, 40 "irregulary_avaliable_time" : [ 41 { 42 "begin_time" : "2015-05-20T13:29:35+08:00", 43 "end_time" : "2015-05-20T13:29:35+08:00" 44 } 45 ], 46 "wait_days_after_receive" : 7 47 }, 48 "fixed_normal_coupon" : { 49 "discount_amount" : 5, 50 "transaction_minimum" : 100 51 }, 52 "discount_coupon" : { 53 "discount_percent" : 88, 54 "transaction_minimum" : 100 55 }, 56 "exchange_coupon" : { 57 "exchange_price" : 100, 58 "transaction_minimum" : 100 59 }, 60 "use_method" : "OFF_LINE", 61 "mini_programs_appid" : "wx23232232323", 62 "mini_programs_path" : "/path/index/index" 63 }, 64 "custom_entrance" : { 65 "mini_programs_info" : { 66 "mini_programs_appid" : "wx234545656765876", 67 "mini_programs_path" : "/path/index/index", 68 "entrance_words" : "欢迎选购", 69 "guiding_words" : "获取更多优惠" 70 }, 71 "appid" : "wx324345hgfhfghfg", 72 "hall_id" : "233455656", 73 "store_id" : "233554655", 74 "code_display_mode" : "NOT_SHOW" 75 }, 76 "coupon_code" : "123446565767", 77 "stock_id" : "1002323", 78 "available_start_time" : "2019-12-30T13:29:35+08:00", 79 "expire_time" : "2019-12-31T13:29:35+08:00", 80 "receive_time" : "2019-12-30T13:29:35+08:00", 81 "send_request_no" : "MCHSEND202003101234", 82 "use_request_no" : "MCHUSE202003101234", 83 "use_time" : "2019-12-31T13:29:35+08:00", 84 "associate_out_trade_no" : "2000-01-01T00:00:00+08:00", 85 "return_request_no" : "MCHRETURN202003101234", 86 "return_time" : "2020-07-31T13:29:35+08:00", 87 "deactivate_request_no" : "MCHRETURN202003101234", 88 "deactivate_time" : "2020-07-31T13:29:35+08:00", 89 "deactivate_reason" : "此券使用时间错误" 90 } 91 ], 92 "total_count" : 100, 93 "limit" : 10, 94 "offset" : 1 95} 96
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
500 | SYSTEM_ERROR | 系统异常,请稍后重试 | 请稍后重试 |
业务错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
400 | APPID_MCHID_NOT_MATCH | AppID与请求方商户无关联关系 | AppID与请求方商户不匹配,请确认AppID与请求方商户是否有关联关系 |
400 | INVALID_REQUEST | 发券模式不合法 | 请更换支持预上传code的批次后重试 |
400 | INVALID_REQUEST | 上传的自定义code已达上限 | 请更换一个新的批次后重试 |
400 | MCH_NOT_EXISTS | 商户号不存在 | 请确认传入的商户号是否正确 |
400 | RESOURCE_ALREADY_EXISTS | 批次已存在 | 查看out_request_no字段是否重复使用 |
400 | RESOURCE_ALREADY_EXISTS | 券已被其他订单核销 | 请通过查询券API确认券是否已被其他订单核销 |
400 | SYSTEM_ERROR | 系统错误 | 请使用相同参数稍后重新调用 |
403 | NO_AUTH | 无权限 | 查看具体错误信息,确认是否有权限 |
403 | RULE_LIMIT | 券不在有效期内 | 请确认券是否能在当前时间核销 |
404 | RESOURCE_NOT_EXISTS | 查询的资源不存在 | 请检查查询资源的对应ID是否填写正确 |
404 | USER_NOT_EXISTS | OpenID不正确 | 请确认传入的OpenID是否正确 |
429 | FREQUENCY_LIMITED | 频率限制 | 调用太频繁,请降低调用接口频率 |
500 | SYSTEM_ERROR | 系统失败 | 多为网络超时引起,重试 |