微信支付 APIv3 的 Postman (opens new window) 請(qǐng)求前置腳本（Pre-Request Script (opens new window)）。
為了幫助商戶開(kāi)發(fā)者快速上手，我們提供了 Postman 云工作臺(tái) APIv3 Public Workspace (opens new window)。你不用手動(dòng)導(dǎo)入腳本，只需要將集合《微信支付 APIv3 (opens new window)》 fork 到自己的工作臺(tái)，就可以在 Postman 上輕松地構(gòu)造并發(fā)送微信支付 APIv3 請(qǐng)求了。
Postman簽名腳本獲取：Postman調(diào)試工具 (opens new window)
# 前置條件
- Postman (opens new window)，一款業(yè)界知名的 API 構(gòu)建和使用平臺(tái)。建議注冊(cè)一個(gè)賬戶，便于使用它各種功能。
- 成為微信支付商戶 (opens new window)。
- 商戶 API 私鑰：商戶申請(qǐng)商戶API證書(shū)時(shí)，會(huì)生成商戶私鑰，并保存在本地證書(shū)文件夾的文件 apiclient_key.pem 中。
# 快速開(kāi)始
步驟1： Fork 方式導(dǎo)入腳本
點(diǎn)擊按鈕 Run in Postman (opens new window) 進(jìn)入向?qū)В缦聢D所示。
點(diǎn)擊 Fork Collection 進(jìn)入下一步，填入標(biāo)簽 Fork Label 并選擇目的工作臺(tái) Workspace。一般情況下，導(dǎo)入個(gè)人工作臺(tái) My Workspace 即可。
點(diǎn)擊 Fork Collection 完成導(dǎo)入。在你指定的 workspace 中可以看到《微信支付 APIv3》了。
你也可以 本地導(dǎo)入腳本。
步驟2： 配置 Environment
環(huán)境（Environment） (opens new window) 是一組變量 (Varibles) 的集合。 腳本從環(huán)境中讀取變量，用來(lái)計(jì)算請(qǐng)求的簽名。
你可以從《微信支付 APIv3》提供的 商戶參數(shù)模版 (opens new window) 中 fork 一個(gè)空環(huán)境到自己的工作臺(tái)。
接下來(lái)，在你工作臺(tái)的 Enviroments 中找到新建的環(huán)境，點(diǎn)擊 Add a new varialbe 添加新的變量：
mchid：必填，商戶號(hào)。merchant_serial_no：必填，商戶 API 證書(shū)序列號(hào)。apiclient_key.pem：必填，PEM 格式的商戶 API 私鑰。
注意： 為了安全，請(qǐng)仔細(xì)閱讀安全注意事項(xiàng)。
一組常見(jiàn)配置如下圖所示。
步驟3： 發(fā)送請(qǐng)求
我們建議，使用桌面版 Postman App 發(fā)送請(qǐng)求，速度更快，體驗(yàn)更好！
現(xiàn)在回到工作臺(tái)，進(jìn)入《微信支付 APIv3》集合，選擇你要發(fā)送的請(qǐng)求。
然后，填入請(qǐng)求參數(shù)，按照注釋修改 Body 中的參數(shù)。最后，選擇你之前配置的 Environment，再點(diǎn)擊地址欄右側(cè)的Send按鈕，發(fā)送請(qǐng)求吧。
# 實(shí)現(xiàn)原理
Pre-Request Script 是一段 Javascript 腳本。Postman 在請(qǐng)求發(fā)送之前，執(zhí)行這段腳本。腳本做了以下操作：
- 加載依賴庫(kù)
- 讀取 Environment 中的商戶參數(shù)變量
- 根據(jù)請(qǐng)求的方法、URL、參數(shù)、Body 等信息，構(gòu)造簽名串，并計(jì)算請(qǐng)求簽名
- 設(shè)置請(qǐng)求頭
Authorization
注意：有關(guān) Postman 腳本的更多信息，請(qǐng)參考 Scripting in Postman (opens new window)。
# 參數(shù)變量
| 變量名 | 是否必填 | 描述 | 備注 |
|---|---|---|---|
| mchid | 是 | 商戶號(hào) | / |
| merchant_serial_no | 是 | 商戶 API 證書(shū)的證書(shū)序列號(hào) | / |
| apiclient_key.pem | 是 | PEM 格式的商戶 API 私鑰 | / |
| openid | 否 | 用戶的 OpenID，測(cè)試請(qǐng)求中的 | / |
| appid | 否 | 公眾賬號(hào)或者小程序的 AppID | / |
| shangmi | 否 | 值為 true 時(shí)使用商密簽名 | 默認(rèn)值為空，即使用 RSA 簽名 |
| pubkey.pem | 國(guó)密簽名時(shí)必填 | PEM 格式的商戶 API 公鑰 | 如果私鑰 PEM 中包含公鑰，該變量可不填 |
| server_url | 否 | 服務(wù)器地址 | 默認(rèn)為 https://api.mch.weixin.qq.com |
# 依賴庫(kù)
腳本直接使用了：
- forge.min.js (opens new window)，forge (opens new window) 的 PKI、RSA 和 ASN.1。
- sm2.js (opens new window)，騰訊國(guó)密庫(kù) TencentSM-javascript 的 SM2 簽名。
為了避免每次請(qǐng)求都下載依賴庫(kù)，兩個(gè)庫(kù)以源代碼的方式存儲(chǔ)在 Collection Variables。這大大減少了使用網(wǎng)頁(yè)版 Postman 發(fā)送請(qǐng)求時(shí)的耗時(shí)。
# 安全注意事項(xiàng)
商戶 API 私鑰 是非常敏感的信息。使用此代碼時(shí)，應(yīng)記住以下幾點(diǎn)：
- 將配置了私鑰的工作臺(tái)（workspace）的可見(jiàn)性（Visibility）設(shè)置為私有
Personal或者Private，不要 設(shè)置為公開(kāi)Public。 - 私鑰的變量類(lèi)型設(shè)置為
secret。變量值會(huì)以掩碼的形式顯示在屏幕上。 - 私鑰的變量值設(shè)置在
Current Value。Current Value僅保存在本地 Session (opens new window)，不會(huì)被發(fā)送至 Postman 的服務(wù)器。 - 如果使用來(lái)自其他人的 Postman 腳本，請(qǐng)檢查依賴庫(kù)、變量和腳本，確保沒(méi)有被修改，避免被植入不安全代碼。
注意
有關(guān) Postman 的安全機(jī)制，請(qǐng)參考 Postman Security (opens new window)。
# 本地導(dǎo)入腳本
Fork Collection 導(dǎo)入需要注冊(cè) Postman 賬戶。如果你離線或者不希望注冊(cè)，有以下兩種方式本地導(dǎo)入。
- Postman 界面左上角的
Import按鈕 - 菜單
File>Import發(fā)起導(dǎo)入
選擇下載到本地的 wechatpay-apiv3.postman_collection.json (opens new window)，點(diǎn)擊確認(rèn)后，導(dǎo)入便完成了。
你會(huì)發(fā)現(xiàn)在工作臺(tái)的 Collections 里新增了名為 《微信支付 APIv3》 的一組請(qǐng)求。
# 同步上游的變更
我們會(huì)逐步添加新接口和更新已有接口，但是你 fork 到自己工作臺(tái)的集合分支并不會(huì)自動(dòng)同步上游的變更。建議關(guān)注 watch 我們的 Public Workspace，這樣上游變更時(shí)你會(huì)收到來(lái)自 postman 的通知。
這時(shí)，你可使用 pull changes 拉取上游的變更。
postman 的 pull changes 可能會(huì)需要等待一定時(shí)間完成。如果遇到問(wèn)題，重新 fork 也是一個(gè)好辦法。
# 常見(jiàn)問(wèn)題
# 發(fā)送請(qǐng)求時(shí)遇到錯(cuò)誤提示“Error: Too few bytes to parse DER.”或者“Too few bytes to read ASN.1 value.”
通常是環(huán)境 Environments 里配置的變量 merchantPrivateKey 填寫(xiě)有誤導(dǎo)致的。腳本接收的私鑰，以 -----BEGIN PRIVATEKEY----- 開(kāi)始，以 -----END PRIVATE KEY----- 結(jié)束的一串字符串。
# 為什么我發(fā)送請(qǐng)求很慢？
如果你使用的網(wǎng)頁(yè)版 Postman，請(qǐng)使用桌面版 Postman App (opens new window)。因?yàn)闉g覽器中跨域資源共享（CORS）的限制，網(wǎng)頁(yè)版發(fā)送請(qǐng)求是由 Postman 后臺(tái)中轉(zhuǎn)的。
或者使用 Postman desktop agent (opens new window)，更多信息請(qǐng)參考 Postman 相關(guān)博客 (opens new window)。
