發(fā)放代金券
場(chǎng)景介紹
用于商戶主動(dòng)調(diào)用接口給用戶發(fā)放代金券的場(chǎng)景，已做防小號(hào)處理，給小號(hào)發(fā)放代金券將返回錯(cuò)誤碼。
注意：通過(guò)接口發(fā)放的代金券不會(huì)進(jìn)入微信卡包
接口請(qǐng)求鏈接
https://api.mch.weixin.qq.com/mmpaymkttransfers/send_coupon
是否需要證書(shū)
請(qǐng)求需要雙向證書(shū)。 詳見(jiàn)證書(shū)使用
請(qǐng)求參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 說(shuō)明 |
|---|---|---|---|---|---|
| 代金券批次id | coupon_stock_id | 是 | 1757 | String | 代金券批次id |
| openid記錄數(shù) | openid_count | 是 | 1 | int | openid記錄數(shù)（目前支持num=1） |
| 商戶單據(jù)號(hào) | partner_trade_no | 是 | 1000009820141203515766 | String | 商戶此次發(fā)放憑據(jù)號(hào)（格式：商戶id+日期+流水號(hào)），商戶側(cè)需保持唯一性 |
| 用戶openid | openid | 是 | onqOjjrXT-776SpHnfexGm1_P7iE | String | Openid信息，用戶在appid下的唯一標(biāo)識(shí) |
| 公眾賬號(hào)ID | appid | 是 | wx5edab3bdfba3dc1c | String(32) | 微信為發(fā)券方商戶分配的公眾賬號(hào)ID，接口傳入的所有appid應(yīng)該為公眾號(hào)的appid（在mp.weixin.qq.com申請(qǐng)的），不能為APP的appid（在open.weixin.qq.com申請(qǐng)的）。 |
| 商戶號(hào) | mch_id | 是 | 10000098 | String(32) | 微信為發(fā)券方商戶分配的商戶號(hào) |
| 操作員 | op_user_id | 否 | 10000098 | String(32) | 操作員賬號(hào), 默認(rèn)為商戶號(hào) 可在商戶平臺(tái)配置操作員對(duì)應(yīng)的api權(quán)限 |
| 設(shè)備號(hào) | device_info | 否 | 013467007045764 | String(32) | 微信支付分配的終端設(shè)備號(hào) |
| 隨機(jī)字符串 | nonce_str | 是 | 1417574675 | String(32) | 隨機(jī)字符串，不長(zhǎng)于32位 |
| 簽名 | sign | 是 | 841B3002FE2220C87A2D08ABD8A8F791 | String(32) | 簽名參數(shù)，詳見(jiàn)簽名生成算法 |
| 協(xié)議版本 | version | 否 | 1.0 | String(32) | 默認(rèn)1.0 |
| 協(xié)議類型 | type | 否 | XML | String(32) | XML【目前僅支持默認(rèn)XML】 |
請(qǐng)求參數(shù)示例：
<xml>
<appid> wx5edab3bdfba3dc1c</appid>
<coupon_stock_id>1757</coupon_stock_id>
<mch_id>10010405</mch_id>
<nonce_str>1417574675</nonce_str>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<openid_count>1</openid_count>
<partner_trade_no>1000009820141203515766</partner_trade_no>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
</xml>
<appid> wx5edab3bdfba3dc1c</appid>
<coupon_stock_id>1757</coupon_stock_id>
<mch_id>10010405</mch_id>
<nonce_str>1417574675</nonce_str>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<openid_count>1</openid_count>
<partner_trade_no>1000009820141203515766</partner_trade_no>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
</xml>
CURL請(qǐng)求帶證書(shū)代碼樣例：
curl --cert 10010405.pem --key 10010405.key -H
"Content-Type：text/xml" -d
'<xml><mch_id>10010405</mch_id><appid>121512345</appid><nonce_str>1417582740</nonce_str><coupon_stock_id>1757</coupon_stock_id><openid_count>1</openid_count><openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid><partner_trade_no>121512345456</partner_trade_no></xml>' https://api.mch.weixin.qq.com/secapi/promotion/send_coupon/ -i返回參數(shù)
| 字段名 | 變量名 | 必填 | 示例值 | 類型 | 說(shuō)明 |
|---|---|---|---|---|---|
| 返回狀態(tài)碼 | return_code | 是 | SUCCESS或者FAIL | String(16) |
SUCCESS/FAIL 此字段是通信標(biāo)識(shí)，非交易標(biāo)識(shí)，交易是否成功需要查看result_code來(lái)判斷 |
| 返回信息 | return_msg | 否 | 成功：返回空 | String(128) | 返回信息，如非空，為通信錯(cuò)誤原因 |
| 公眾賬號(hào)ID | appid | 是 | wx5edab3bdfba3dc1c | String(32) | 微信為發(fā)券方商戶分配的公眾賬號(hào)ID，接口傳入的所有appid應(yīng)該為公眾號(hào)的appid（在mp.weixin.qq.com申請(qǐng)的），不能為APP的appid（在open.weixin.qq.com申請(qǐng)的）。 |
| 商戶號(hào) | mch_id | 是 | 10000098 | String(32) | 微信為發(fā)券方商戶分配的商戶號(hào) |
| 設(shè)備號(hào) | device_info | 否 | 123456sb | String(32) | 微信支付分配的終端設(shè)備號(hào)， |
| 隨機(jī)字符串 | nonce_str | 是 | 1417574675 | String(32) | 隨機(jī)字符串，不長(zhǎng)于32位 |
| 簽名 | sign | 是 | 841B3002FE2220C87A2D08ABD8A8F791 | String(32) | 對(duì)返回參數(shù)簽名計(jì)算后得到的簽名值 |
| 業(yè)務(wù)結(jié)果 | result_code | 是 | SUCCESS或者FAIL | String(16) | SUCCESS/FAIL |
| 錯(cuò)誤代碼 | err_code | 否 | PARAM_ERROR | String(32) | 詳見(jiàn)業(yè)務(wù)錯(cuò)誤代碼章節(jié) |
| 錯(cuò)誤代碼描述 | err_code_des | 否 | 錯(cuò)誤描述信息 | String(128) | 對(duì)錯(cuò)誤信息的描述 |
| 代金券批次id | coupon_stock_id | 是 | 1757 | String | 創(chuàng)建代金券時(shí)生成的批次號(hào)，可在商戶平臺(tái)-代金券管理頁(yè)面查看 |
| 返回記錄數(shù) | resp_count | 是 | 1 | int | 返回記錄數(shù) |
| 成功記錄數(shù) | success_count | 是 | 1或者0 | int | 成功記錄數(shù) |
| 失敗記錄數(shù) | failed_count | 是 | 1或者0 | int | 失敗記錄數(shù) |
| 用戶標(biāo)識(shí) | openid | 是 | onqOjjrXT-776SpHnfexGm1_P7iE | String | 用戶在商戶appid下的唯一標(biāo)識(shí) |
| 代金券id | coupon_id | 是 | 1870 | String |
對(duì)一個(gè)用戶成功發(fā)放代金券則返回代金券id，即ret_code為SUCCESS的時(shí)候； 如果ret_code為FAILED則填寫(xiě)空串"" |
| 返回信息 | ret_msg | 是 | 失敗描述信息，例如：“用戶已達(dá)領(lǐng)用上限” | String | 返回信息，當(dāng)返回碼是FAILED的時(shí)候填寫(xiě)，否則填空串“” |
返回參數(shù)示例：
成功示例格式：
<xml>
<return_code>SUCCESS</return_code>
<appid>wx5edab3bdfba3dc1c</appid>
<mch_id>10000098</mch_id>
<nonce_str>1417579335</nonce_str>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
<result_code>SUCCESS</result_code>
<coupon_stock_id>1717</coupon_stock_id>
<resp_count>1</resp_count>
<success_count>1</success_count>
<failed_count>0</failed_count>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<ret_code>SUCCESS</ret_code>
<coupon_id>6954</coupon_id>
</xml>
<return_code>SUCCESS</return_code>
<appid>wx5edab3bdfba3dc1c</appid>
<mch_id>10000098</mch_id>
<nonce_str>1417579335</nonce_str>
<sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
<result_code>SUCCESS</result_code>
<coupon_stock_id>1717</coupon_stock_id>
<resp_count>1</resp_count>
<success_count>1</success_count>
<failed_count>0</failed_count>
<openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
<ret_code>SUCCESS</ret_code>
<coupon_id>6954</coupon_id>
</xml>
失敗示例格式：
<xml>
? <return_code>SUCCESS</return_code>
? <appid>wx5edab3bdfba3dc1c</appid>
? <mch_id>10000098</mch_id>
? <nonce_str>1417579335</nonce_str>
? <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
? <result_code>FAIL</result_code>
? <err_code>268456007</err_code>
? <err_code_des>你已領(lǐng)取過(guò)該代金券</err_code_des>
? <coupon_stock_id>1717</coupon_stock_id>
? <resp_count>1</resp_count>
? <success_count>0</success_count>
? <failed_count>1</failed_count>
? <openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
? <ret_code>FAIL</ret_code>
? <ret_msg>你已領(lǐng)取過(guò)該代金券</ret_msg>
? <coupon_id></coupon_id>
</xml>
? <return_code>SUCCESS</return_code>
? <appid>wx5edab3bdfba3dc1c</appid>
? <mch_id>10000098</mch_id>
? <nonce_str>1417579335</nonce_str>
? <sign>841B3002FE2220C87A2D08ABD8A8F791</sign>
? <result_code>FAIL</result_code>
? <err_code>268456007</err_code>
? <err_code_des>你已領(lǐng)取過(guò)該代金券</err_code_des>
? <coupon_stock_id>1717</coupon_stock_id>
? <resp_count>1</resp_count>
? <success_count>0</success_count>
? <failed_count>1</failed_count>
? <openid>onqOjjrXT-776SpHnfexGm1_P7iE</openid>
? <ret_code>FAIL</ret_code>
? <ret_msg>你已領(lǐng)取過(guò)該代金券</ret_msg>
? <coupon_id></coupon_id>
</xml>
錯(cuò)誤碼
| 錯(cuò)誤代碼 | 描述 | 解決方案 |
|---|---|---|
| STOCK_NOT_EXIST | 批次不存在 | 請(qǐng)檢查請(qǐng)求參數(shù)中填寫(xiě)的代金券批次id和商戶號(hào)是否正確 |
| BLOCKED_BY_SPAMCHK | 小號(hào)攔截 | 當(dāng)前發(fā)放用戶為小號(hào)，根據(jù)風(fēng)險(xiǎn)管控規(guī)則不允許給小號(hào)發(fā)放。 |
| DAY_BUDGET_NOT_ENOUGH | 批次達(dá)到單天發(fā)放預(yù)算上限 | 發(fā)券數(shù)量已經(jīng)達(dá)到單天發(fā)放上限，可在商戶平臺(tái)批次詳情頁(yè)修改單天發(fā)放預(yù)算 |
| USER_AL_GET_COUPON | 你已領(lǐng)取過(guò)該代金券 | 用戶已領(lǐng)過(guò)，正常邏輯報(bào)錯(cuò) |
| NETWORK ERROR | 網(wǎng)絡(luò)環(huán)境不佳，請(qǐng)重試 | 請(qǐng)重試 |
| AL_STOCK_OVER | 活動(dòng)已結(jié)束 | 活動(dòng)已結(jié)束，屬于正常邏輯錯(cuò)誤 |
| FREQ_OVER_LIMIT | 超過(guò)發(fā)放頻率限制，請(qǐng)稍后再試 | 請(qǐng)控制發(fā)放請(qǐng)求的頻率 |
| PARAM_ERROR | 校驗(yàn)參數(shù)錯(cuò)誤（會(huì)返回具體哪個(gè)參數(shù)錯(cuò)誤） | 根據(jù)錯(cuò)誤提示確認(rèn)參數(shù)無(wú)誤并更正 |
| SIGN_ERROR | 簽名錯(cuò)誤 | 驗(yàn)證簽名有誤 |
| CA_ERROR | 證書(shū)有誤 | 確認(rèn)證書(shū)正確，或者聯(lián)系商戶平臺(tái)更新證書(shū) |
| REQ_PARAM_XML_ERR | 輸入?yún)?shù)xml格式有誤 | 檢查入?yún)⒌膞ml格式是否正確 |
| COUPON_STOCK_ID_EMPTY | 批次ID為空 | 確保批次id正確傳入 |
| MCH_ID_EMPTY | 商戶ID為空 | 確保商戶id正確傳入 |
| CODE_2_ID_ERR | 商戶id有誤 | 檢查商戶id是否正確并合法 |
| OPEN_ID_EMPTY | 用戶openid為空 | 檢查用戶openid是否正確并合法 |
| ERR_VERIFY_SSL_SERIAL | 獲取客戶端證書(shū)序列號(hào)失敗! | 檢查證書(shū)是否正確 |
| ERR_VERIFY_SSL_SN | 獲取客戶端證書(shū)特征名稱(DN)域失敗! | 檢查證書(shū)是否正確 |
| CA_VERIFY_FAILED | 證書(shū)驗(yàn)證失敗 | 檢查證書(shū)是否正確 |
| STOCK_IS_NOT_VALID | 抱歉，該代金券已失效 | 代金券已失效，請(qǐng)確認(rèn)代金券的有效性，重新請(qǐng)求 |
| STOCK_AMOUNT_NOT_ENOUGH | 代金券批次預(yù)算不足 | 商戶可為該代金券批次追加預(yù)算后繼續(xù)發(fā)券 |
| MCH_NO_AUTH | 商戶無(wú)權(quán)限操作 | 該商戶無(wú)權(quán)限進(jìn)行該操作，請(qǐng)前往商戶平臺(tái)開(kāi)通代金券權(quán)限 |
| ACCOUNTERROR | 賬號(hào)行為異常，無(wú)法領(lǐng)券 | 請(qǐng)求的代金券批次已在商戶平臺(tái)開(kāi)啟風(fēng)險(xiǎn)攔截功能，命中的用戶無(wú)法領(lǐng)券，如需給用戶發(fā)券，可創(chuàng)建不開(kāi)啟攔截的批次重發(fā)，或聯(lián)系微信支付客服。 |