查询商家券批次详情
更新时间:2025.07.25商户可通过该接口查询已创建的商家券批次详情信息。
接口说明
支持商户:【普通商户】
请求方式:【GET】/v3/marketing/busifavor/stocks/{stock_id}
请求域名:【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点
【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点 ,指引点击查看
请求参数
Header HTTP头参数
Authorization 必填 string
请参考签名认证生成认证信息
Accept 必填 string
请设置为application/json
path 路径参数
stock_id 必填 string
【批次号】微信为每个商家券批次分配的唯一ID
请求示例
GET
1curl -X GET \ 2 https://api.mch.weixin.qq.com/v3/marketing/busifavor/stocks/100088 \ 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/merchant/4014931831 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 QueryStock { 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/stocks/{stock_id}"; 29 30 public static void main(String[] args) { 31 // TODO: 请准备商户开发必要参数,参考:https://pay.weixin.qq.com/doc/v3/merchant/4013070756 32 QueryStock client = new QueryStock( 33 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/merchant/4013070756 34 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053 35 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 36 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816 37 "/path/to/wxp_pub.pem" // 微信支付公钥文件路径,本地文件路径 38 ); 39 40 QueryStockRequest request = new QueryStockRequest(); 41 request.stockId = "100088"; 42 try { 43 StockGetResponse response = client.run(request); 44 // TODO: 请求成功,继续业务逻辑 45 System.out.println(response); 46 } catch (WXPayUtility.ApiException e) { 47 // TODO: 请求失败,根据状态码执行不同的逻辑 48 e.printStackTrace(); 49 } 50 } 51 52 public StockGetResponse run(QueryStockRequest request) { 53 String uri = PATH; 54 uri = uri.replace("{stock_id}", WXPayUtility.urlEncode(request.stockId)); 55 56 Request.Builder reqBuilder = new Request.Builder().url(HOST + uri); 57 reqBuilder.addHeader("Accept", "application/json"); 58 reqBuilder.addHeader("Wechatpay-Serial", wechatPayPublicKeyId); 59 reqBuilder.addHeader("Authorization", WXPayUtility.buildAuthorization(mchid, certificateSerialNo, privateKey, METHOD, uri, null)); 60 reqBuilder.method(METHOD, null); 61 Request httpRequest = reqBuilder.build(); 62 63 // 发送HTTP请求 64 OkHttpClient client = new OkHttpClient.Builder().build(); 65 try (Response httpResponse = client.newCall(httpRequest).execute()) { 66 String respBody = WXPayUtility.extractBody(httpResponse); 67 if (httpResponse.code() >= 200 && httpResponse.code() < 300) { 68 // 2XX 成功,验证应答签名 69 WXPayUtility.validateResponse(this.wechatPayPublicKeyId, this.wechatPayPublicKey, 70 httpResponse.headers(), respBody); 71 72 // 从HTTP应答报文构建返回数据 73 return WXPayUtility.fromJson(respBody, StockGetResponse.class); 74 } else { 75 throw new WXPayUtility.ApiException(httpResponse.code(), respBody, httpResponse.headers()); 76 } 77 } catch (IOException e) { 78 throw new UncheckedIOException("Sending request to " + uri + " failed.", e); 79 } 80 } 81 82 private final String mchid; 83 private final String certificateSerialNo; 84 private final PrivateKey privateKey; 85 private final String wechatPayPublicKeyId; 86 private final PublicKey wechatPayPublicKey; 87 88 public QueryStock(String mchid, String certificateSerialNo, String privateKeyFilePath, String wechatPayPublicKeyId, String wechatPayPublicKeyFilePath) { 89 this.mchid = mchid; 90 this.certificateSerialNo = certificateSerialNo; 91 this.privateKey = WXPayUtility.loadPrivateKeyFromPath(privateKeyFilePath); 92 this.wechatPayPublicKeyId = wechatPayPublicKeyId; 93 this.wechatPayPublicKey = WXPayUtility.loadPublicKeyFromPath(wechatPayPublicKeyFilePath); 94 } 95 96 public static class QueryStockRequest { 97 @SerializedName("stock_id") 98 @Expose(serialize = false) 99 public String stockId; 100 } 101 102 public static class StockGetResponse { 103 @SerializedName("stock_name") 104 public String stockName; 105 106 @SerializedName("belong_merchant") 107 public String belongMerchant; 108 109 @SerializedName("comment") 110 public String comment; 111 112 @SerializedName("goods_name") 113 public String goodsName; 114 115 @SerializedName("stock_type") 116 public BusiFavorStockType stockType; 117 118 @SerializedName("coupon_use_rule") 119 public CouponUseRule couponUseRule; 120 121 @SerializedName("stock_send_rule") 122 public StockSendRule stockSendRule; 123 124 @SerializedName("custom_entrance") 125 public CustomEntrance customEntrance; 126 127 @SerializedName("display_pattern_info") 128 public DisplayPatternInfo displayPatternInfo; 129 130 @SerializedName("stock_state") 131 public StockStatus stockState; 132 133 @SerializedName("coupon_code_mode") 134 public CouponCodeMode couponCodeMode; 135 136 @SerializedName("stock_id") 137 public String stockId; 138 139 @SerializedName("coupon_code_count") 140 public CouponCodeCount couponCodeCount; 141 142 @SerializedName("notify_config") 143 public NotifyConfig notifyConfig; 144 145 @SerializedName("send_count_information") 146 public SendCount sendCountInformation; 147 148 @SerializedName("subsidy") 149 public Boolean subsidy; 150 } 151 152 public enum BusiFavorStockType { 153 @SerializedName("NORMAL") 154 NORMAL, 155 @SerializedName("DISCOUNT") 156 DISCOUNT, 157 @SerializedName("EXCHANGE") 158 EXCHANGE 159 } 160 161 public static class CouponUseRule { 162 @SerializedName("coupon_available_time") 163 public FavorAvailableTime couponAvailableTime; 164 165 @SerializedName("fixed_normal_coupon") 166 public FixedValueStockMsg fixedNormalCoupon; 167 168 @SerializedName("discount_coupon") 169 public DiscountMsg discountCoupon; 170 171 @SerializedName("exchange_coupon") 172 public ExchangeMsg exchangeCoupon; 173 174 @SerializedName("use_method") 175 public CouponUseMethod useMethod; 176 177 @SerializedName("mini_programs_appid") 178 public String miniProgramsAppid; 179 180 @SerializedName("mini_programs_path") 181 public String miniProgramsPath; 182 } 183 184 public static class StockSendRule { 185 @SerializedName("max_amount") 186 public Long maxAmount; 187 188 @SerializedName("max_coupons") 189 public Long maxCoupons; 190 191 @SerializedName("max_coupons_per_user") 192 public Long maxCouponsPerUser; 193 194 @SerializedName("max_amount_by_day") 195 public Long maxAmountByDay; 196 197 @SerializedName("max_coupons_by_day") 198 public Long maxCouponsByDay; 199 200 @SerializedName("natural_person_limit") 201 public Boolean naturalPersonLimit; 202 203 @SerializedName("prevent_api_abuse") 204 public Boolean preventApiAbuse; 205 206 @SerializedName("transferable") 207 public Boolean transferable; 208 209 @SerializedName("shareable") 210 public Boolean shareable; 211 } 212 213 public static class CustomEntrance { 214 @SerializedName("mini_programs_info") 215 public MiniAppInfo miniProgramsInfo; 216 217 @SerializedName("appid") 218 public String appid; 219 220 @SerializedName("hall_id") 221 public String hallId; 222 223 @SerializedName("store_id") 224 public String storeId; 225 226 @SerializedName("code_display_mode") 227 public CodeDisplayMode codeDisplayMode; 228 } 229 230 public static class DisplayPatternInfo { 231 @SerializedName("description") 232 public String description; 233 234 @SerializedName("merchant_logo_url") 235 public String merchantLogoUrl; 236 237 @SerializedName("merchant_name") 238 public String merchantName; 239 240 @SerializedName("background_color") 241 public String backgroundColor; 242 243 @SerializedName("coupon_image_url") 244 public String couponImageUrl; 245 246 @SerializedName("finder_info") 247 public FinderInfo finderInfo; 248 } 249 250 public enum StockStatus { 251 @SerializedName("UNAUDIT") 252 UNAUDIT, 253 @SerializedName("RUNNING") 254 RUNNING, 255 @SerializedName("STOPED") 256 STOPED, 257 @SerializedName("PAUSED") 258 PAUSED 259 } 260 261 public enum CouponCodeMode { 262 @SerializedName("WECHATPAY_MODE") 263 WECHATPAY_MODE, 264 @SerializedName("MERCHANT_API") 265 MERCHANT_API, 266 @SerializedName("MERCHANT_UPLOAD") 267 MERCHANT_UPLOAD 268 } 269 270 public static class CouponCodeCount { 271 @SerializedName("total_count") 272 public Long totalCount; 273 274 @SerializedName("available_count") 275 public Long availableCount; 276 } 277 278 public static class NotifyConfig { 279 @SerializedName("notify_appid") 280 public String notifyAppid; 281 } 282 283 public static class SendCount { 284 @SerializedName("total_send_num") 285 public Long totalSendNum; 286 287 @SerializedName("total_send_amount") 288 public Long totalSendAmount; 289 290 @SerializedName("today_send_num") 291 public Long todaySendNum; 292 293 @SerializedName("today_send_amount") 294 public Long todaySendAmount; 295 } 296 297 public static class FavorAvailableTime { 298 @SerializedName("available_begin_time") 299 public String availableBeginTime; 300 301 @SerializedName("available_end_time") 302 public String availableEndTime; 303 304 @SerializedName("available_day_after_receive") 305 public Long availableDayAfterReceive; 306 307 @SerializedName("available_week") 308 public AvailableWeek availableWeek; 309 310 @SerializedName("irregulary_avaliable_time") 311 public List<IrregularAvailableTime> irregularyAvaliableTime; 312 313 @SerializedName("wait_days_after_receive") 314 public Long waitDaysAfterReceive; 315 } 316 317 public static class FixedValueStockMsg { 318 @SerializedName("discount_amount") 319 public Long discountAmount; 320 321 @SerializedName("transaction_minimum") 322 public Long transactionMinimum; 323 } 324 325 public static class DiscountMsg { 326 @SerializedName("discount_percent") 327 public Long discountPercent; 328 329 @SerializedName("transaction_minimum") 330 public Long transactionMinimum; 331 } 332 333 public static class ExchangeMsg { 334 @SerializedName("exchange_price") 335 public Long exchangePrice; 336 337 @SerializedName("transaction_minimum") 338 public Long transactionMinimum; 339 } 340 341 public enum CouponUseMethod { 342 @SerializedName("OFF_LINE") 343 OFF_LINE, 344 @SerializedName("MINI_PROGRAMS") 345 MINI_PROGRAMS, 346 @SerializedName("SELF_CONSUME") 347 SELF_CONSUME, 348 @SerializedName("PAYMENT_CODE") 349 PAYMENT_CODE 350 } 351 352 public static class MiniAppInfo { 353 @SerializedName("mini_programs_appid") 354 public String miniProgramsAppid; 355 356 @SerializedName("mini_programs_path") 357 public String miniProgramsPath; 358 359 @SerializedName("entrance_words") 360 public String entranceWords; 361 362 @SerializedName("guiding_words") 363 public String guidingWords; 364 } 365 366 public enum CodeDisplayMode { 367 @SerializedName("NOT_SHOW") 368 NOT_SHOW, 369 @SerializedName("BARCODE") 370 BARCODE, 371 @SerializedName("QRCODE") 372 QRCODE 373 } 374 375 public static class FinderInfo { 376 @SerializedName("finder_id") 377 public String finderId; 378 379 @SerializedName("finder_video_id") 380 public String finderVideoId; 381 382 @SerializedName("finder_video_cover_image_url") 383 public String finderVideoCoverImageUrl; 384 } 385 386 public static class AvailableWeek { 387 @SerializedName("week_day") 388 public List<Long> weekDay; 389 390 @SerializedName("available_day_time") 391 public List<AvailableCurrentDayTime> availableDayTime; 392 } 393 394 public static class IrregularAvailableTime { 395 @SerializedName("begin_time") 396 public String beginTime; 397 398 @SerializedName("end_time") 399 public String endTime; 400 } 401 402 public static class AvailableCurrentDayTime { 403 @SerializedName("begin_time") 404 public Long beginTime; 405 406 @SerializedName("end_time") 407 public Long endTime; 408 } 409 410} 411
需配合微信支付工具库 wxpay_utility 使用,请参考Go
1package main 2 3import ( 4 "demo/wxpay_utility" // 引用微信支付工具库,参考 https://pay.weixin.qq.com/doc/v3/merchant/4015119334 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/merchant/4013070756 15 config, err := wxpay_utility.CreateMchConfig( 16 "19xxxxxxxx", // 商户号,是由微信支付系统生成并分配给每个商户的唯一标识符,商户号获取方式参考 https://pay.weixin.qq.com/doc/v3/merchant/4013070756 17 "1DDE55AD98Exxxxxxxxxx", // 商户API证书序列号,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013053053 18 "/path/to/apiclient_key.pem", // 商户API证书私钥文件路径,本地文件路径 19 "PUB_KEY_ID_xxxxxxxxxxxxx", // 微信支付公钥ID,如何获取请参考 https://pay.weixin.qq.com/doc/v3/merchant/4013038816 20 "/path/to/wxp_pub.pem", // 微信支付公钥文件路径,本地文件路径 21 ) 22 if err != nil { 23 fmt.Println(err) 24 return 25 } 26 27 request := &QueryStockRequest{ 28 StockId: wxpay_utility.String("100088"), 29 } 30 31 response, err := QueryStock(config, request) 32 if err != nil { 33 fmt.Printf("请求失败: %+v\n", err) 34 // TODO: 请求失败,根据状态码执行不同的处理 35 return 36 } 37 38 // TODO: 请求成功,继续业务逻辑 39 fmt.Printf("请求成功: %+v\n", response) 40} 41 42func QueryStock(config *wxpay_utility.MchConfig, request *QueryStockRequest) (response *StockGetResponse, err error) { 43 const ( 44 host = "https://api.mch.weixin.qq.com" 45 method = "GET" 46 path = "/v3/marketing/busifavor/stocks/{stock_id}" 47 ) 48 49 reqUrl, err := url.Parse(fmt.Sprintf("%s%s", host, path)) 50 if err != nil { 51 return nil, err 52 } 53 reqUrl.Path = strings.Replace(reqUrl.Path, "{stock_id}", url.PathEscape(*request.StockId), -1) 54 httpRequest, err := http.NewRequest(method, reqUrl.String(), nil) 55 if err != nil { 56 return nil, err 57 } 58 httpRequest.Header.Set("Accept", "application/json") 59 httpRequest.Header.Set("Wechatpay-Serial", config.WechatPayPublicKeyId()) 60 authorization, err := wxpay_utility.BuildAuthorization(config.MchId(), config.CertificateSerialNo(), config.PrivateKey(), method, reqUrl.RequestURI(), nil) 61 if err != nil { 62 return nil, err 63 } 64 httpRequest.Header.Set("Authorization", authorization) 65 66 client := &http.Client{} 67 httpResponse, err := client.Do(httpRequest) 68 if err != nil { 69 return nil, err 70 } 71 respBody, err := wxpay_utility.ExtractResponseBody(httpResponse) 72 if err != nil { 73 return nil, err 74 } 75 if httpResponse.StatusCode >= 200 && httpResponse.StatusCode < 300 { 76 // 2XX 成功,验证应答签名 77 err = wxpay_utility.ValidateResponse( 78 config.WechatPayPublicKeyId(), 79 config.WechatPayPublicKey(), 80 &httpResponse.Header, 81 respBody, 82 ) 83 if err != nil { 84 return nil, err 85 } 86 response := &StockGetResponse{} 87 if err := json.Unmarshal(respBody, response); err != nil { 88 return nil, err 89 } 90 91 return response, nil 92 } else { 93 return nil, wxpay_utility.NewApiException( 94 httpResponse.StatusCode, 95 httpResponse.Header, 96 respBody, 97 ) 98 } 99} 100 101type QueryStockRequest struct { 102 StockId *string `json:"stock_id,omitempty"` 103} 104 105func (o *QueryStockRequest) MarshalJSON() ([]byte, error) { 106 type Alias QueryStockRequest 107 a := &struct { 108 StockId *string `json:"stock_id,omitempty"` 109 *Alias 110 }{ 111 // 序列化时移除非 Body 字段 112 StockId: nil, 113 Alias: (*Alias)(o), 114 } 115 return json.Marshal(a) 116} 117 118type StockGetResponse struct { 119 StockName *string `json:"stock_name,omitempty"` 120 BelongMerchant *string `json:"belong_merchant,omitempty"` 121 Comment *string `json:"comment,omitempty"` 122 GoodsName *string `json:"goods_name,omitempty"` 123 StockType *BusiFavorStockType `json:"stock_type,omitempty"` 124 CouponUseRule *CouponUseRule `json:"coupon_use_rule,omitempty"` 125 StockSendRule *StockSendRule `json:"stock_send_rule,omitempty"` 126 CustomEntrance *CustomEntrance `json:"custom_entrance,omitempty"` 127 DisplayPatternInfo *DisplayPatternInfo `json:"display_pattern_info,omitempty"` 128 StockState *StockStatus `json:"stock_state,omitempty"` 129 CouponCodeMode *CouponCodeMode `json:"coupon_code_mode,omitempty"` 130 StockId *string `json:"stock_id,omitempty"` 131 CouponCodeCount *CouponCodeCount `json:"coupon_code_count,omitempty"` 132 NotifyConfig *NotifyConfig `json:"notify_config,omitempty"` 133 SendCountInformation *SendCount `json:"send_count_information,omitempty"` 134 Subsidy *bool `json:"subsidy,omitempty"` 135} 136 137type BusiFavorStockType string 138 139func (e BusiFavorStockType) Ptr() *BusiFavorStockType { 140 return &e 141} 142 143const ( 144 BUSIFAVORSTOCKTYPE_NORMAL BusiFavorStockType = "NORMAL" 145 BUSIFAVORSTOCKTYPE_DISCOUNT BusiFavorStockType = "DISCOUNT" 146 BUSIFAVORSTOCKTYPE_EXCHANGE BusiFavorStockType = "EXCHANGE" 147) 148 149type CouponUseRule struct { 150 CouponAvailableTime *FavorAvailableTime `json:"coupon_available_time,omitempty"` 151 FixedNormalCoupon *FixedValueStockMsg `json:"fixed_normal_coupon,omitempty"` 152 DiscountCoupon *DiscountMsg `json:"discount_coupon,omitempty"` 153 ExchangeCoupon *ExchangeMsg `json:"exchange_coupon,omitempty"` 154 UseMethod *CouponUseMethod `json:"use_method,omitempty"` 155 MiniProgramsAppid *string `json:"mini_programs_appid,omitempty"` 156 MiniProgramsPath *string `json:"mini_programs_path,omitempty"` 157} 158 159type StockSendRule struct { 160 MaxAmount *int64 `json:"max_amount,omitempty"` 161 MaxCoupons *int64 `json:"max_coupons,omitempty"` 162 MaxCouponsPerUser *int64 `json:"max_coupons_per_user,omitempty"` 163 MaxAmountByDay *int64 `json:"max_amount_by_day,omitempty"` 164 MaxCouponsByDay *int64 `json:"max_coupons_by_day,omitempty"` 165 NaturalPersonLimit *bool `json:"natural_person_limit,omitempty"` 166 PreventApiAbuse *bool `json:"prevent_api_abuse,omitempty"` 167 Transferable *bool `json:"transferable,omitempty"` 168 Shareable *bool `json:"shareable,omitempty"` 169} 170 171type CustomEntrance struct { 172 MiniProgramsInfo *MiniAppInfo `json:"mini_programs_info,omitempty"` 173 Appid *string `json:"appid,omitempty"` 174 HallId *string `json:"hall_id,omitempty"` 175 StoreId *string `json:"store_id,omitempty"` 176 CodeDisplayMode *CodeDisplayMode `json:"code_display_mode,omitempty"` 177} 178 179type DisplayPatternInfo struct { 180 Description *string `json:"description,omitempty"` 181 MerchantLogoUrl *string `json:"merchant_logo_url,omitempty"` 182 MerchantName *string `json:"merchant_name,omitempty"` 183 BackgroundColor *string `json:"background_color,omitempty"` 184 CouponImageUrl *string `json:"coupon_image_url,omitempty"` 185 FinderInfo *FinderInfo `json:"finder_info,omitempty"` 186} 187 188type StockStatus string 189 190func (e StockStatus) Ptr() *StockStatus { 191 return &e 192} 193 194const ( 195 STOCKSTATUS_UNAUDIT StockStatus = "UNAUDIT" 196 STOCKSTATUS_RUNNING StockStatus = "RUNNING" 197 STOCKSTATUS_STOPED StockStatus = "STOPED" 198 STOCKSTATUS_PAUSED StockStatus = "PAUSED" 199) 200 201type CouponCodeMode string 202 203func (e CouponCodeMode) Ptr() *CouponCodeMode { 204 return &e 205} 206 207const ( 208 COUPONCODEMODE_WECHATPAY_MODE CouponCodeMode = "WECHATPAY_MODE" 209 COUPONCODEMODE_MERCHANT_API CouponCodeMode = "MERCHANT_API" 210 COUPONCODEMODE_MERCHANT_UPLOAD CouponCodeMode = "MERCHANT_UPLOAD" 211) 212 213type CouponCodeCount struct { 214 TotalCount *int64 `json:"total_count,omitempty"` 215 AvailableCount *int64 `json:"available_count,omitempty"` 216} 217 218type NotifyConfig struct { 219 NotifyAppid *string `json:"notify_appid,omitempty"` 220} 221 222type SendCount struct { 223 TotalSendNum *int64 `json:"total_send_num,omitempty"` 224 TotalSendAmount *int64 `json:"total_send_amount,omitempty"` 225 TodaySendNum *int64 `json:"today_send_num,omitempty"` 226 TodaySendAmount *int64 `json:"today_send_amount,omitempty"` 227} 228 229type FavorAvailableTime struct { 230 AvailableBeginTime *time.Time `json:"available_begin_time,omitempty"` 231 AvailableEndTime *time.Time `json:"available_end_time,omitempty"` 232 AvailableDayAfterReceive *int64 `json:"available_day_after_receive,omitempty"` 233 AvailableWeek *AvailableWeek `json:"available_week,omitempty"` 234 IrregularyAvaliableTime []IrregularAvailableTime `json:"irregulary_avaliable_time,omitempty"` 235 WaitDaysAfterReceive *int64 `json:"wait_days_after_receive,omitempty"` 236} 237 238type FixedValueStockMsg struct { 239 DiscountAmount *int64 `json:"discount_amount,omitempty"` 240 TransactionMinimum *int64 `json:"transaction_minimum,omitempty"` 241} 242 243type DiscountMsg struct { 244 DiscountPercent *int64 `json:"discount_percent,omitempty"` 245 TransactionMinimum *int64 `json:"transaction_minimum,omitempty"` 246} 247 248type ExchangeMsg struct { 249 ExchangePrice *int64 `json:"exchange_price,omitempty"` 250 TransactionMinimum *int64 `json:"transaction_minimum,omitempty"` 251} 252 253type CouponUseMethod string 254 255func (e CouponUseMethod) Ptr() *CouponUseMethod { 256 return &e 257} 258 259const ( 260 COUPONUSEMETHOD_OFF_LINE CouponUseMethod = "OFF_LINE" 261 COUPONUSEMETHOD_MINI_PROGRAMS CouponUseMethod = "MINI_PROGRAMS" 262 COUPONUSEMETHOD_SELF_CONSUME CouponUseMethod = "SELF_CONSUME" 263 COUPONUSEMETHOD_PAYMENT_CODE CouponUseMethod = "PAYMENT_CODE" 264) 265 266type MiniAppInfo struct { 267 MiniProgramsAppid *string `json:"mini_programs_appid,omitempty"` 268 MiniProgramsPath *string `json:"mini_programs_path,omitempty"` 269 EntranceWords *string `json:"entrance_words,omitempty"` 270 GuidingWords *string `json:"guiding_words,omitempty"` 271} 272 273type CodeDisplayMode string 274 275func (e CodeDisplayMode) Ptr() *CodeDisplayMode { 276 return &e 277} 278 279const ( 280 CODEDISPLAYMODE_NOT_SHOW CodeDisplayMode = "NOT_SHOW" 281 CODEDISPLAYMODE_BARCODE CodeDisplayMode = "BARCODE" 282 CODEDISPLAYMODE_QRCODE CodeDisplayMode = "QRCODE" 283) 284 285type FinderInfo struct { 286 FinderId *string `json:"finder_id,omitempty"` 287 FinderVideoId *string `json:"finder_video_id,omitempty"` 288 FinderVideoCoverImageUrl *string `json:"finder_video_cover_image_url,omitempty"` 289} 290 291type AvailableWeek struct { 292 WeekDay []int64 `json:"week_day,omitempty"` 293 AvailableDayTime []AvailableCurrentDayTime `json:"available_day_time,omitempty"` 294} 295 296type IrregularAvailableTime struct { 297 BeginTime *time.Time `json:"begin_time,omitempty"` 298 EndTime *time.Time `json:"end_time,omitempty"` 299} 300 301type AvailableCurrentDayTime struct { 302 BeginTime *int64 `json:"begin_time,omitempty"` 303 EndTime *int64 `json:"end_time,omitempty"` 304} 305
应答参数
200 OK
stock_name 必填 string
【商家券批次名称】批次名称,字数上限为21个,一个中文汉字/英文字母/数字均占用一个字数。
belong_merchant 必填 string
【批次归属商户号】批次是归属于哪个商户
注:
普通直连模式,该参数为直连商户号;
服务商模式,该参数为子商户号;
间连模式,该参数为子商户号。
comment 选填 string
【批次备注】仅配置商户可见,用于自定义信息。字数上限为20个,一个中文汉字/英文字母/数字均占用一个字数。
goods_name 必填 string
【适应商品范围】用来描述批次在哪些商品可用,会显示在微信卡包中。字数上限为15个,一个中文汉字/英文字母/数字均占用一个字数。
stock_type 必填 string
【批次类型】批次类型
可选取值:
NORMAL
: 固定面额满减券批次DISCOUNT
: 折扣券批次EXCHANGE
: 换购券批次
coupon_use_rule 必填 object
【核销规则】核销规则
属性 | |||||||||||||||||||||||||||||
coupon_available_time 必填 object 【券可核销时间】日期区间内可以使用优惠
fixed_normal_coupon 选填 object 【固定面额满减券使用规则】固定面额满减,折扣券,换购券使用规则三选一,stock_type为NORMAL时必填。
discount_coupon 选填 object 【折扣券使用规则】固定面额满减,折扣券,换购券使用规则三选一,stock_type为DISCOUNT时必填。
exchange_coupon 选填 object 【换购券使用规则】固定面额满减,折扣券,换购券使用规则三选一,stock_type为EXCHANGE时必填。
use_method 必填 string 【核销方式】核销方式 可选取值:
mini_programs_appid 选填 string 【小程序AppID】核销方式为线上小程序核销才有效 mini_programs_path 选填 string 【小程序path】核销方式为线上小程序核销才有效 |
stock_send_rule 必填 object
【发放规则】发放规则
属性 | |
max_amount 选填 integer 【批次总预算】总预算金额,单位分 max_coupons 选填 integer 【批次最大发放个数】批次最大可发放个数限制 max_coupons_per_user 必填 integer 【用户最大可领个数】用户可领个数,每个用户最多100张券。 max_amount_by_day 选填 integer 【单天发放上限金额】单天发放上限金额 max_coupons_by_day 选填 integer 【单天发放上限个数】单天发放上限个数(stock_type为DISCOUNT或EXCHANGE时可传入此字段控制单天发放上限)。 natural_person_limit 选填 boolean 【是否开启自然人限领】不填默认否,枚举值: prevent_api_abuse 选填 boolean 【可疑账号拦截】true-是;false-否,不填默认否 transferable 选填 boolean 【是否允许转赠,暂不开放】不填默认否,枚举值: shareable 选填 boolean 【是否允许分享链接,暂不开放】不填默认否,枚举值: |
custom_entrance 选填 object
【自定义入口】卡详情页面,可选择多种入口引导用户
属性 | |||||
mini_programs_info 选填 object 【小程序入口】需要小程序APPID、path、入口文案、引导文案。如果需要跳转小程序,APPID、path、入口文案为必填,引导文案非必填。
appid 选填 string 【商户公众号AppID】可配置商户公众号,从券详情可跳转至公众号,用户自定义字段。 hall_id 选填 string 【更多优惠入口;营销馆创建地址:https://pay.weixin.qq.com/index.php/xphp/cfav_market/hall#/pages/list/lis填写微信支付营销馆的馆ID,用户自定义字段。营销馆需在商户平台创建。 store_id 选填 string 【可用门店ID】填写代金券可用门店ID code_display_mode 选填 string 【code展示模式】code展示模式 可选取值:
|
display_pattern_info 选填 object
【样式信息】创建批次时的样式信息
属性 | |||||
description 选填 string(1000) 【使用须知】用于说明详细的活动规则,会展示在代金券详情页。 merchant_logo_url 选填 string 【商户logo】若券归属商户号有认证品牌,则系统将自动拉取对应品牌logo;若券归属商户号不在认证品牌下,需自定义上传logo,未上传时将展示兜底灰色logo样式,影响券详情页用户体验,请及时上传。 merchant_name 选填 string(16) 【商户名称】不支持商户自定义。若券归属商户号有认证品牌,系统将自动拉取认证品牌号下的品牌名称;若券归属商户号不在认证品牌下,则拉取本商户号的商户简称。展示上限12个字符。 background_color 选填 string 【背景颜色】券的背景颜色,可设置10种颜色,色值请下方说明。颜色取值为颜色图中的颜色名称。 coupon_image_url 选填 string 【券详情图片】券详情图片,1074像素(宽)*603像素(高),图片大小不超过2M,支持JPG/PNG格式。仅支持通过《图片上传API》接口获取的图片URL地址。* finder_info 选填 object 【视频号相关信息】视频号相关信息
|
stock_state 必填 string
【批次状态】批次状态
可选取值:
UNAUDIT
: 审核中RUNNING
: 运行中STOPED
: 已停止PAUSED
: 暂停发放
coupon_code_mode 必填 string
【券code模式】券code模式
可选取值:
WECHATPAY_MODE
: 系统分配code,商户无需额外操作MERCHANT_API
: 商户发放时接口指定券codeMERCHANT_UPLOAD
: 商户上传自定义code,发券时系统随机选取上传的券code
stock_id 必填 string
【批次号】批次唯一标识
coupon_code_count 选填 object
【券code数量】当且仅当coupon_code_mode(券code模式)为MERCHANT_UPLOAD(商户上传自定义code)模式时,返回该字段;返回内容为商户上传code的数量信息
属性 | |
total_count 必填 integer 【该批次总共已上传的code总数】该批次总共已上传的code总数 available_count 必填 integer 【该批次当前可用的code数】该批次当前可用的code数 |
notify_config 选填 object
【事件通知配置】事件回调通知商户的配置
属性 | |
notify_appid 选填 string(64) 【事件通知AppID】用于回调通知时,计算返回操作用户的OpenID(诸如领券用户),支持小程序or公众号的AppID;如该字段不填写,则回调通知中涉及到用户身份信息的OpenID与UnionID都将为空。 |
send_count_information 选填 object
【批次发放情况】批次发放情况
属性 | |
total_send_num 选填 integer 【已发放券张数】批次已发放的券数量,满减、折扣、换购类型会返回该字段 total_send_amount 选填 integer 【已发放券金额】批次已发放的预算金额,满减券类型会返回该字段 today_send_num 选填 integer 【单天已发放券张数】批次当天已发放的券数量,设置了单天发放上限的满减、折扣、换购类型返回该字段 today_send_amount 选填 integer 【单天已发放券金额】批次当天已发放的预算金额,设置了当天发放上限的满减券类型返回该字段 |
subsidy 选填 boolean
【是否允许营销补差】该批次发放的券是否允许进行补差
注:该字段暂未开放
应答示例
200 OK
1{ 2 "stock_name" : "8月1日活动券", 3 "belong_merchant" : "10000022", 4 "comment" : "xxx店使用", 5 "goods_name" : "xxx商品使用", 6 "stock_type" : "NORMAL", 7 "coupon_use_rule" : { 8 "coupon_available_time" : { 9 "available_begin_time" : "2015-05-20T13:29:35+08:00", 10 "available_end_time" : "2015-05-20T13:29:35+08:00", 11 "available_day_after_receive" : 3, 12 "available_week" : { 13 "week_day" : [ 14 1 15 ], 16 "available_day_time" : [ 17 { 18 "begin_time" : 3600, 19 "end_time" : 86399 20 } 21 ] 22 }, 23 "irregulary_avaliable_time" : [ 24 { 25 "begin_time" : "2015-05-20T13:29:35+08:00", 26 "end_time" : "2015-05-20T13:29:35+08:00" 27 } 28 ], 29 "wait_days_after_receive" : 7 30 }, 31 "fixed_normal_coupon" : { 32 "discount_amount" : 5, 33 "transaction_minimum" : 100 34 }, 35 "discount_coupon" : { 36 "discount_percent" : 88, 37 "transaction_minimum" : 100 38 }, 39 "exchange_coupon" : { 40 "exchange_price" : 100, 41 "transaction_minimum" : 100 42 }, 43 "use_method" : "OFF_LINE", 44 "mini_programs_appid" : "wx23232232323", 45 "mini_programs_path" : "/path/index/index" 46 }, 47 "stock_send_rule" : { 48 "max_amount" : 100000, 49 "max_coupons" : 100, 50 "max_coupons_per_user" : 5, 51 "max_amount_by_day" : 1000, 52 "max_coupons_by_day" : 100, 53 "natural_person_limit" : false, 54 "prevent_api_abuse" : false, 55 "transferable" : false, 56 "shareable" : false 57 }, 58 "custom_entrance" : { 59 "mini_programs_info" : { 60 "mini_programs_appid" : "wx234545656765876", 61 "mini_programs_path" : "/path/index/index", 62 "entrance_words" : "欢迎选购", 63 "guiding_words" : "获取更多优惠" 64 }, 65 "appid" : "wx324345hgfhfghfg", 66 "hall_id" : "233455656", 67 "store_id" : "233554655", 68 "code_display_mode" : "NOT_SHOW" 69 }, 70 "display_pattern_info" : { 71 "description" : "xxx门店可用", 72 "merchant_logo_url" : "https://xxx", 73 "merchant_name" : "微信支付", 74 "background_color" : "xxxxx", 75 "coupon_image_url" : "图片cdn地址", 76 "finder_info" : { 77 "finder_id" : "sph6Rngt2T4RlUf", 78 "finder_video_id" : "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94", 79 "finder_video_cover_image_url" : "https://wxpaylogo.qpic.cn/xxx" 80 } 81 }, 82 "stock_state" : "UNAUDIT", 83 "coupon_code_mode" : "WECHATPAY_MODE", 84 "stock_id" : "1212", 85 "coupon_code_count" : { 86 "total_count" : 100, 87 "available_count" : 50 88 }, 89 "notify_config" : { 90 "notify_appid" : "wx23232232323" 91 }, 92 "send_count_information" : { 93 "total_send_num" : 1, 94 "total_send_amount" : 34, 95 "today_send_num" : 1, 96 "today_send_amount" : 34 97 }, 98 "subsidy" : false 99} 100
错误码
公共错误码
状态码 | 错误码 | 描述 | 解决方案 |
---|---|---|---|
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 | 系统失败 | 多为网络超时引起,重试 |