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