接口說明
適用對象： 服務(wù)商
請求URL：https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/{openid}/coupons/{coupon_code}/appids/{appid}
請求方式：GET
path 指該參數(shù)為路徑參數(shù)
query 指該參數(shù)需在請求URL傳參
body 指該參數(shù)需在請求JSON傳參
請求參數(shù)
| 參數(shù)名 | 變量 | 類型[長度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 券code | coupon_code | string[1,32] | 是 | path 券的唯一標識。 示例值：123446565767 |
| 公眾賬號ID | appid | string[1,32] | 是 | path 支持傳入與當前調(diào)用接口商戶號有綁定關(guān)系的appid。支持小程序appid與公眾號appid。 校驗規(guī)則：傳入的APPID得是與調(diào)用方商戶號（即請求頭里面的商戶號）有綁定關(guān)系的APPID或傳入的APPID得是歸屬商戶號有綁定關(guān)系的APPID 示例值：wx233544546545989 |
| 用戶標識 | openid | string[1,128] | 是 | path Openid信息，用戶在appid下的唯一標識。 校驗規(guī)則：傳入的openid得是調(diào)用方商戶號（即請求頭里面的商戶號）有綁定關(guān)系的APPID獲取的openid或傳入的openid得是歸屬商戶號有綁定關(guān)系的APPID獲取的openid。獲取openid文檔 示例值：2323dfsdf342342 |
請求示例
https://api.mch.weixin.qq.com/v3/marketing/busifavor/users/2323dfsdf342342/coupons/123446565767/appids/wx233544546545989
返回參數(shù)
| 參數(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 |
| 是否允許轉(zhuǎn)贈 | transferable | bool | 否 | 不填默認否，枚舉值： true：是 false：否 該字段暫未開放 示例值：false |
| 是否允許分享領(lǐng)券鏈接 | shareable | bool | 否 | 不填默認否，枚舉值： true：是 false：否 該字段暫未開放 示例值：false |
| 券狀態(tài) | coupon_state | string[1,16] | 否 | 商家券狀態(tài) 枚舉值： |
| +樣式信息 | display_pattern_info | object | 否 | 商家券詳細信息 |
| +券核銷規(guī)則 | coupon_use_rule | 券核銷規(guī)則 | 是 | 券核銷相關(guān)規(guī)則 |
| +自定義入口 | custom_entrance | object | 否 | 卡詳情頁面，可選擇多種入口引導(dǎo)用戶。 |
| 券code | coupon_code | string[1,32] | 否 | 券的唯一標識。 示例值：123446565767 |
| 批次號 | stock_id | string[1,20] | 否 | 微信為每個商家券批次分配的唯一ID，是否指定批次號查詢。 示例值：1002323 |
| 券可使用開始時間 | available_start_time | string[1,32] | 是 | 1、用戶領(lǐng)取到該張券實際可使用的開始時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領(lǐng)先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。 2、若券批次設(shè)置為領(lǐng)取后可用，則開始時間即為券的領(lǐng)取時間；若券批次設(shè)置為領(lǐng)取后第X天可用，則開始時間為券領(lǐng)取時間后第X天00:00:00可用。 示例值：2019-12-30T13:29:35+08:00 |
| 券過期時間 | expire_time | string[1,32] | 是 | 用戶領(lǐng)取到該張券的過期時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領(lǐng)先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。 示例值：2015-05-20T13:29:35+08:00 |
| 券領(lǐng)券時間 | receive_time | string[1,32] | 是 | 用戶領(lǐng)取到該張券的時間，遵循rfc3339標準格式，格式為yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，T出現(xiàn)在字符串中，表示time元素的開頭，HH:mm:ss表示時分秒，TIMEZONE表示時區(qū)（+08:00表示東八區(qū)時間，領(lǐng)先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 |
| 關(guān)聯(lián)的商戶訂單號 | associate_out_trade_no | string[1,128] | 否 | 若商家券操作過關(guān)聯(lián)商戶訂單信息，則該字段返回商家券已關(guān)聯(lián)的商戶訂單號。 示例值: mchtrade_1234554 |
| 券核銷時間 | 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ū)時間，領(lǐng)先UTC 8小時，即北京時間）。例如：2015-05-20T13:29:35.+08:00表示，北京時間2015年5月20日 13點29分35秒。 示例值：2015-05-20T13:29:35+08:00 |
卡券背景顏色圖
返回示例
{
"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": "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"
}
錯誤碼公共錯誤碼
| 狀態(tài)碼 | 錯誤碼 | 描述 | 解決方案 |
|---|---|---|---|
| 400 | PARAM_ERROR | 參數(shù)錯誤 | 查看具體錯誤信息，調(diào)整參數(shù) |
| 400 | SYSTEM_ERROR | 系統(tǒng)錯誤 | 請使用相同參數(shù)稍后重新調(diào)用 |
| 400 | RESOURCE_ALREADY_EXISTS | 批次已存在 | 查看out_request_no字段是否重復(fù)使用 |
| 券已被其他訂單核銷 | 請通過查詢?nèi)疉PI確認券是否已被其他訂單核銷 | ||
| 404 | RESOURCE_NOT_EXISTS | 查詢的資源不存在 | 請檢查查詢資源的對應(yīng)id是否填寫正確 |
| 403 | NOAUTH | 無權(quán)限 | 查看具體錯誤信息，確認是否有權(quán)限 |
| 400 | APPID_MCHID_NOT_MATCH | appid與請求方商戶無關(guān)聯(lián)關(guān)系 | appid與請求方商戶不匹配，請確認appid與請求方商戶是否有關(guān)聯(lián)關(guān)系 |
| 400 | MCH_NOT_EXISTS | 商戶號不存在 | 請確認傳入的商戶號是否正確 |
| 404 | USER_NOT_EXISTS | openid不正確 | 請確認傳入的openid是否正確 |
| 500 | SYSTEM_ERROR | 系統(tǒng)失敗 | 多為網(wǎng)絡(luò)超時引起，重試 |
| 429 | FREQUENCY_LIMITED | 頻率限制 | 調(diào)用太頻繁，請降低調(diào)用接口頻率 |
| 403 | RULELIMIT | 券不在有效期 | 請確認券是否能在當前時間核銷 |
| 400 | INVALID_REQUEST | 發(fā)券模式不合法 | 請更換支持預(yù)上傳code的批次后重試 |
| 上傳的自定義code已達上限 | 請更換一個新的批次后重試 |