微信支付-開發(fā)者文檔

返回上一層文檔首頁 / 根據(jù)過濾條件查詢用戶券

根據(jù)過濾條件查詢用戶券API

最新更新時間：2023.11.23 版本說明

商戶自定義篩選條件（如創(chuàng)建商戶號、歸屬商戶號、發(fā)放商戶號等），查詢指定微信用戶卡包中滿足對應條件的所有商家券信息。

接口說明

適用對象： 服務商

請求URL：https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/{openid}/coupons

請求方式：GET

path 指該參數(shù)為路徑參數(shù)

query 指該參數(shù)需在請求URL傳參

body 指該參數(shù)需在請求JSON傳參

請求參數(shù)

參數(shù)名	變量	類型[長度限制]	必填	描述
用戶標識	openid	string[1,128]	是	path Openid信息，用戶在appid下的唯一標識。校驗規(guī)則：傳入的openid得是調用方商戶號（即請求頭里面的商戶號）有綁定關系的APPID獲取的openid或傳入的openid得是歸屬商戶號有綁定關系的APPID獲取的openid。獲取openid文檔示例值：2323dfsdf342342
公眾賬號ID	appid	string[1,32]	是	query 支持傳入與當前調用接口商戶號有綁定關系的appid。支持小程序appid與公眾號appid。校驗規(guī)則：傳入的APPID得是與調用方商戶號（即請求頭里面的商戶號）有綁定關系的APPID 或傳入的APPID得是歸屬商戶號有綁定關系的APPID 示例值：wx233544546545989
批次號	stock_id	string[1,20]	否	query 微信為每個商家券批次分配的唯一ID，是否指定批次號查詢。示例值：9865000
券狀態(tài)	coupon_state	string[1,16]	否	query 券狀態(tài) 枚舉值： SENDED：可用 USED：已核銷 EXPIRED：已過期示例值：SENDED
創(chuàng)建批次的商戶號	creator_merchant	string[1,32]	否	query 批次創(chuàng)建方商戶號校驗規(guī)則：當調用方商戶號（即請求頭中的商戶號）為創(chuàng)建批次方商戶號時，該參數(shù)必傳示例值：1000000001
批次歸屬商戶號	belong_merchant	string[8,15]	否	query 批次歸屬商戶號校驗規(guī)則：當調用方商戶號（即請求頭中的商戶號）為批次歸屬商戶號時，該參數(shù)必傳示例值：1000000002
批次發(fā)放商戶號	sender_merchant	string[1,32]	否	query 批次發(fā)放商戶號校驗規(guī)則：當調用方商戶號（即請求頭中的商戶號）為批次發(fā)放商戶號時，該參數(shù)必傳；委托營銷關系下，請?zhí)顚懳邪l(fā)券的商戶號示例值：1000000003
分頁頁碼	offset	int	否	query 分頁頁碼示例值：0
分頁大小	limit	int	否	query 分頁大小示例值：20

請求示例


https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons?appid=wx233544546545989&stock_id=9865000&coupon_state=USED&creator_merchant=1000000001&offset=0&limit=20

    
｛
JAVA示例代碼
｝

返回參數(shù)

說明：為提升API性能，返回參數(shù)中“結果集>樣式信息>使用須知（description）”字段內容將不再返回，即查詢結果不再返回使用須知，改動將于2020年7月8日12:00生效。如您業(yè)務中需要使用該字段，建議使用“查詢用戶單張券詳情API”

參數(shù)名

變量

類型[長度限制]

必填

描述

+結果集

data

array

是

結果集

參數(shù)名

變量

類型[長度限制]

必填

描述

批次歸屬商戶號

belong_merchant

string[8,15]

是

批次歸屬于哪個商戶。
示例值：10000022

商家券批次名稱

stock_name

string[1,21]

是

批次名稱，字數(shù)上限為21個，一個中文漢字/英文字母/數(shù)字均占用一個字數(shù)。
示例值：商家券

批次備注

comment

string[1,20]

否

僅配置商戶可見，用于自定義信息。字數(shù)上限為20個，一個中文漢字/英文字母/數(shù)字均占用一個字數(shù)。
示例值：xxx可用

適用商品范圍

goods_name

string[1,15]

是

適用商品范圍，字數(shù)上限為15個，一個中文漢字/英文字母/數(shù)字均占用一個字數(shù)。
示例值：xxx商品可用

批次類型

stock_type

string[1,128]

是

批次類型
NORMAL：固定面額滿減券批次
DISCOUNT：折扣券批次
EXCHANGE：換購券批次
示例值：NORMAL

是否允許轉贈

transferable

bool

否

不填默認否，枚舉值：
true：是
false：否
該字段暫未開放
示例值：false

是否允許分享領券鏈接

shareable

bool

否

不填默認否，枚舉值：
true：是
false：否
該字段暫未開放
示例值：false

券狀態(tài)

coupon_state

string[1,16]

否

商家券狀態(tài)
枚舉值：
SENDED：可用
USED：已核銷
EXPIRED：已過期
示例值：SENDED

+樣式信息

display_pattern_info

object

否

商家券詳細信息

參數(shù)名

變量

類型[長度限制]

必填

描述

商戶logo

merchant_logo_url

string[1,128]

否

商戶logo的URL地址，可通過《圖片上傳API》獲得圖片URL地址。
示例值：https://qpic.cn/xxx

商戶名稱

merchant_name

string[1,16]

否

商戶名稱，字數(shù)上限為16個，一個中文漢字/英文字母/數(shù)字均占用一個字數(shù)。
示例值：微信支付

背景顏色

background_color

string[1,16]

否

代金券的背景顏色，可設置10種顏色，色值請參考卡券背景顏色圖。顏色取值為顏色圖中的顏色名稱。
示例值：Color020

券詳情圖片

coupon_image_url

string[1,128]

否

券詳情圖片，850像素*350像素，且圖片大小不超過2M，支持JPG/PNG格式，可通過《圖片上傳API》獲得圖片URL地址。
示例值：https://qpic.cn/xxx

+ 視頻號相關信息

finder_info

object

否

視頻號相關信息

參數(shù)名	變量	類型[長度限制]	必填	描述
視頻號ID	finder_id	string[1,32]	是	關聯(lián)視頻號將展示在優(yōu)惠券詳情的頂部右側，作為跳轉去視頻號的入口，請求參數(shù)請配置視頻號ID，請前往視頻號助手管理查看視頻號ID 示例值：sph6Rngt2T4RlUf
視頻號視頻ID	finder_video_id	string[1,256]	是	券詳情視頻內容，支持配置關聯(lián)視頻號下的具體視頻內容，請求參數(shù)請配置視頻ID，請前往視頻號助手管理后臺復制具體視頻ID 示例值：export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94
視頻號封面圖	finder_video_cover_image_url	string[1,256]	是	截取的視頻號圖片將在券到期提醒消息、券詳情中展示。 1.圖片尺寸：716像素（寬）*402像素（高）；圖片大小不超過2M，支持JPG/PNG格式。 2.僅支持通過《圖片上傳API》接口獲取的圖片URL地址。示例值：https://wxpaylogo.qpic.cn/xxx

+券核銷規(guī)則

coupon_use_rule

券核銷規(guī)則

是

券核銷相關規(guī)則

參數(shù)名

變量

類型[長度限制]

必填

描述

+券可核銷時間

coupon_available_time

object

是

日期區(qū)間內可以使用優(yōu)惠。

參數(shù)名

變量

類型[長度限制]

必填

描述

開始時間

available_begin_time

string[1,32]

是

批次開始時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35+08:00表示，北京時間2015年5月20日 13點29分35秒。
注意：開始時間設置有效期最長為1年。
示例值：2015-05-20T13:29:35+08:00

結束時間

available_end_time

string[1,32]

是

批次結束時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35+08:00表示，北京時間2015年5月20日 13點29分35秒。
注意：結束時間設置有效期最長為1年。
示例值：2015-05-20T13:29:35+08:00

生效后N天內有效

available_day_after_receive

int

否

日期區(qū)間內，券生效后x天內有效。例如生效當天內有效填1，生效后2天內有效填2，以此類推。注意，用戶在有效期開始前領取商家券，則從有效期第1天開始計算天數(shù)，用戶在有效期內領取商家券，則從領取當天開始計算天數(shù)，無論用戶何時領取商家券，商家券在活動有效期結束后均不可用。可配合wait_days_after_receive一同填寫，也可單獨填寫。單獨填寫時，有效期內領券后立即生效，生效后x天內有效。
示例值：3

+ 固定周期有效時間段

available_week

object

否

可以設置多個星期下的多個可用時間段，比如每周二10點到18點，用戶自定義字段。

參數(shù)名

變量

類型[長度限制]

必填

描述

可用星期數(shù)

week_day

array[int]

否

0代表周日，1代表周一，以此類推。
示例值：1, 2

+ 當天可用時間段

available_day_time

array

否

可以填寫多個時間段，最多不超過2個。

參數(shù)名	變量	類型[長度限制]	必填	描述
當天可用開始時間	begin_time	int	否	當天可用開始時間，單位：秒，1代表當天0點0分1秒。示例值：3600
當天可用結束時間	end_time	int	否	當天可用結束時間，單位：秒，86399代表當天23點59分59秒。示例值：86399

+ 無規(guī)律的有效時間段

irregulary_avaliable_time

array

否

無規(guī)律的有效時間，多個無規(guī)律時間段，用戶自定義字段。

參數(shù)名	變量	類型[長度限制]	必填	描述
開始時間	begin_time	string[1,32]	否	開始時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先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出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先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

否

日期區(qū)間內，用戶領券后需等待x天開始生效。例如領券后當天開始生效則無需填寫，領券后第2天開始生效填1，以此類推。用戶在有效期開始前領取商家券，則從有效期第1天開始計算天數(shù)，用戶在有效期內領取商家券，則從領取當天開始計算天數(shù)。無論用戶何時領取商家券，商家券在活動有效期結束后均不可用。需配合available_day_after_receive一同填寫，不可單獨填寫。
示例值：7

+固定面額滿減券使用規(guī)則

fixed_normal_coupon

object

三選一

stock_type為NORMAL時必填。

參數(shù)名	變量	類型[長度限制]	必填	描述
優(yōu)惠金額	discount_amount	int64	是	優(yōu)惠金額，單位：分。特殊規(guī)則：取值范圍 1 ≤ value ≤ 10000000 示例值：5
消費門檻	transaction_minimum	int64	是	消費門檻，單位：分。特殊規(guī)則：取值范圍 1 ≤ value ≤ 10000000 示例值：100

+折扣券使用規(guī)則

discount_coupon

object

stock_type為DISCOUNT時必填

參數(shù)名	變量	類型[長度限制]	必填	描述
折扣比例	discount_percent	int	是	折扣百分比，例如：86為八六折示例值：86
消費門檻	transaction_minimum	int64	是	消費門檻，單位分特殊規(guī)則：取值范圍 1 ≤ value ≤ 10000000 示例值：100

+換購券使用規(guī)則

exchange_coupon

object

stock_type為EXCHANGE時必填。

參數(shù)名	變量	類型[長度限制]	必填	描述
單品換購價	exchange_price	int64	是	單品換購價，單位：分。特殊規(guī)則：取值范圍 0 ≤ value ≤ 10000000 示例值：100
消費門檻	transaction_minimum	int64	是	消費門檻，單位：分。特殊規(guī)則：取值范圍 0 ≤ 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

+自定義入口

custom_entrance

object

否

卡詳情頁面，可選擇多種入口引導用戶。

參數(shù)名

變量

類型[長度限制]

必填

描述

+小程序入口

mini_programs_info

object

否

需要小程序APPID、path、入口文案、引導文案。如果需要跳轉小程序，APPID、path、入口文案為必填，引導文案非必填。

appid要與歸屬商戶號有M-A or M-m-suba關系。

參數(shù)名	變量	類型[長度限制]	必填	描述
商家小程序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]	是	入口文案，字數(shù)上限為5個，一個中文漢字/英文字母/數(shù)字均占用一個字數(shù)。示例值：歡迎選購
引導文案	guiding_words	string[1,6]	否	小程序入口引導文案，用戶自定義字段。字數(shù)上限為6個，一個中文漢字/英文字母/數(shù)字均占用一個字數(shù)。示例值：獲取更多優(yōu)惠

商戶公眾號appid

appid

string[1,32]

否

可配置商戶公眾號，從券詳情可跳轉至公眾號，用戶自定義字段。
示例值：wx324345hgfhfghfg

營銷館id

hall_id

string[1,64]

否

填寫微信支付營銷館的館id，用戶自定義字段。營銷館需在服務商平臺創(chuàng)建。
示例值：233455656

可用門店id

store_id

string[1,64]

否

填寫代金券可用門店id，用戶自定義字段。
示例值：233554655

code展示模式

code_display_mode

string[1,8]

否

枚舉值：
NOT_SHOW：不展示code
BARCODE：一維碼
QRCODE：二維碼
示例值：BARCODE

券code

coupon_code

string[1,32]

否

券的唯一標識。
示例值：123446565767

批次號

stock_id

string[1,20]

否

微信為每個商家券批次分配的唯一ID，是否指定批次號查詢。
示例值：1002323

券可使用開始時間

available_start_time

string[1,32]

是

1、用戶領取到該張券實際可使用的開始時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。
示例值：2015-05-20T13:29:35+08:00

券過期時間

expire_time

string[1,32]

是

用戶領取到該張券的過期時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。
示例值：2015-05-20T13:29:35+08:00

券領券時間

receive_time

string[1,32]

是

用戶領取到該張券的時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。
示例值：2015-05-20T13:29:35+08:00

發(fā)券請求單號

send_request_no

string[1,128]

是

發(fā)券時傳入的唯一憑證
示例值: MCHSEND202003101234

核銷請求單號

use_request_no

string[1,32]

否

核銷時傳入的唯一憑證（如券已被核銷，將返回此字段）
示例值: MCHUSE202003101234

券核銷時間

use_time

string[1,32]

否

券被核銷的時間（如券已被核銷，將返回此字段）；遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。
示例值：2015-05-20T13:29:35+08:00

總數(shù)量

total_count

int

是

總數(shù)量
示例值：?100

分頁頁碼

offset

int

是

分頁頁碼
示例值：1

分頁大小

limit

int

是

分頁大小
示例值：10

卡券背景顏色圖

返回示例

正常示例



{
  "data": [
    {
      "belong_merchant": "100000222",
      "stock_name": "商家券",
      "comment": "xxx可用",
      "goods_name": "xxx商品可用",
      "stock_type": "NORMAL",
      "transferable": false,
      "shareable": "false",
      "coupon_state": "SENDED",
      "display_pattern_info": {
        "merchant_logo_url": "https://xxx",
        "merchant_name": "微信支付",
        "background_color": "Color020",
        "coupon_image_url": "https://qpic.cn/xxx",
        "finder_info": {
          "finder_id": "sph6Rngt2T4RlUf",
          "finder_video_cover_image_url": "https://wxpaylogo.qpic.cn/xxx",
          "finder_video_id": "export/UzFfAgtgekIEAQAAAAAAb4MgnPInmAAAAAstQy6ubaLX4KHWvLEZgBPEwIEgVnk9HIP-zNPgMJofG6tpdGPJNg_ojtEjoT94"
        }
      },
      "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,
          "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
        },
        "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": "獲取更多優(yōu)惠"
        },
        "appid": "wx324345hgfhfghfg",
        "hall_id": "233455656",
        "store_id": "233554655"
      },
      "coupon_code": "123446565767",
      "stock_id": "1002323",
      "available_start_time": "2019-12-30T13:29:35+08:00",
      "expire_time": "2019-12-31T13:29:35+08:00",
      "receive_time": "2019-12-30T13:29:35+08:00",
	  "send_request_no": "MCHSEND202003101234",
	  "use_request_no": "MCHSEND202003101234",
	  "use_time": "2019-12-30T13:29:35+08:00"
    }
  ],
  "total_count": 100,
  "limit": 10,
  "offset": 1
}


    http://2323weixin.qq.com

錯誤碼公共錯誤碼

狀態(tài)碼	錯誤碼	描述	解決方案
400	PARAM_ERROR	參數(shù)錯誤	查看具體錯誤信息，調整參數(shù)
400	SYSTEM_ERROR	系統(tǒng)錯誤	請使用相同參數(shù)稍后重新調用
400	RESOURCE_ALREADY_EXISTS	批次已存在	查看out_request_no字段是否重復使用
400	RESOURCE_ALREADY_EXISTS	券已被其他訂單核銷	請通過查詢券API確認券是否已被其他訂單核銷
404	RESOURCE_NOT_EXISTS	查詢的資源不存在	請檢查查詢資源的對應id是否填寫正確
403	NOAUTH	無權限	查看具體錯誤信息，確認是否有權限
400	APPID_MCHID_NOT_MATCH	appid與請求方商戶無關聯(lián)關系	appid與請求方商戶不匹配，請確認appid與請求方商戶是否有關聯(lián)關系
400	MCH_NOT_EXISTS	商戶號不存在	請確認傳入的商戶號是否正確
404	USER_NOT_EXISTS	openid不正確	請確認傳入的openid是否正確
500	SYSTEM_ERROR	系統(tǒng)失敗	多為網(wǎng)絡超時引起，重試
429	FREQUENCY_LIMITED	頻率限制	調用太頻繁，請降低調用接口頻率
403	RULELIMIT	券不在有效期	請確認券是否能在當前時間核銷
400	INVALID_REQUEST	發(fā)券模式不合法	請更換支持預上傳code的批次后重試
400	INVALID_REQUEST	上傳的自定義code已達上限	請更換一個新的批次后重試

视频一区二区三区自拍_千金肉奴隷1985未删减版在线观看_国产成人黄色视频在线播放_少女免费播放片高清在线观看_国产精品v欧美精品v

微信支付合作伙伴平臺

根據(jù)過濾條件查詢用戶券API

接口說明

請求參數(shù)

請求示例

返回參數(shù)

返回示例

錯誤碼公共錯誤碼