{"id":13722296,"url":"https://github.com/wechatpay-apiv3/wechatpay-postman-script","last_synced_at":"2025-04-04T14:06:36.776Z","repository":{"id":37664156,"uuid":"189373507","full_name":"wechatpay-apiv3/wechatpay-postman-script","owner":"wechatpay-apiv3","description":"微信支付 APIv3 的调试工具","archived":false,"fork":false,"pushed_at":"2023-04-25T05:17:44.000Z","size":548,"stargazers_count":382,"open_issues_count":1,"forks_count":347,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-28T13:07:07.005Z","etag":null,"topics":["api","postman","wechat","wechatpay","wechatpay-apiv3"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wechatpay-apiv3.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-05-30T08:13:46.000Z","updated_at":"2025-03-28T07:07:28.000Z","dependencies_parsed_at":"2024-01-06T01:30:47.699Z","dependency_job_id":null,"html_url":"https://github.com/wechatpay-apiv3/wechatpay-postman-script","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechatpay-apiv3%2Fwechatpay-postman-script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechatpay-apiv3%2Fwechatpay-postman-script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechatpay-apiv3%2Fwechatpay-postman-script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechatpay-apiv3%2Fwechatpay-postman-script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wechatpay-apiv3","download_url":"https://codeload.github.com/wechatpay-apiv3/wechatpay-postman-script/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247190231,"owners_count":20898700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","postman","wechat","wechatpay","wechatpay-apiv3"],"created_at":"2024-08-03T01:01:27.022Z","updated_at":"2025-04-04T14:06:36.754Z","avatar_url":"https://github.com/wechatpay-apiv3.png","language":"JavaScript","funding_links":[],"categories":["工具","JavaScript"],"sub_categories":["加解密"],"readme":"# 微信支付 APIv3 Postman 脚本\n\n微信支付 APIv3 的 [Postman](https://www.postman.com) 请求前置脚本（[Pre-Request Script](https://learning.postman.com/docs/writing-scripts/pre-request-scripts/)）。\n\n为了帮助商户开发者快速上手，我们将脚本部署到 Postman 云工作台 [WeChat Pay Public Workspace](https://www.postman.com/wechatpay-dev/workspace/wechat-pay-public-workspace/overview)。你不用手动导入脚本，只需要将集合[《微信支付 APIv3》](https://www.postman.com/wechatpay-dev/workspace/apiv3-public-workspace/collection/3391715-85f478d8-2596-420a-9f21-53376fc6ad0a) fork 到自己的工作台，就可以在 Postman 上轻松地构造并发送微信支付 APIv3 请求了。\n\n## 前置条件\n\n- [Postman](https://www.postman.com/downloads/)，一款业界知名的 API 构建和使用平台。建议注册一个账户，便于使用它各种功能。\n- [成为微信支付商户](https://pay.weixin.qq.com/index.php/apply/applyment_home/guide_normal)。\n- [商户 API 私钥](https://wechatpay-api.gitbook.io/wechatpay-api-v3/ren-zheng/zheng-shu#shang-hu-api-si-yao)：商户申请商户API证书时，会生成商户私钥，并保存在本地证书文件夹的文件 apiclient_key.pem 中。\n\n## 快速开始\n\n### 步骤1：Fork 方式导入脚本\n\n点击按钮 [![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/3391715-85f478d8-2596-420a-9f21-53376fc6ad0a?action=collection%2Ffork\u0026collection-url=entityId%3D3391715-85f478d8-2596-420a-9f21-53376fc6ad0a%26entityType%3Dcollection%26workspaceId%3D5f619604-11ee-42a4-b148-22abec1f0611) 进入向导，如下图所示。\n\n![fork collection step1](https://user-images.githubusercontent.com/1812516/196029034-fb5e9453-fbef-4267-94cc-8566dc008314.png)\n\n点击 `Fork Collection` 进入下一步，填入标签 `Fork Label` 并选择目的工作台 `Workspace`。一般情况下，导入个人工作台 My Workspace 即可。\n\n![fork collection step2](https://user-images.githubusercontent.com/1812516/196031088-2a0683a5-6a46-4704-9f8e-c88b548f4a2d.png)\n\n点击 `Fork Collection` 完成导入。在你指定的 workspace 中可以看到《微信支付 APIv3》了。\n\n![fork collection step3](https://user-images.githubusercontent.com/1812516/196030065-1103c893-4104-4266-aa70-4b589cbfc6e0.png)\n\n你也可以 [本地导入脚本](#本地导入脚本)。\n\n### 步骤2：配置 Environment\n\n[环境（Environment）](https://learning.postman.com/docs/sending-requests/managing-environments/) 是一组变量 (Varibles) 的集合。\n脚本从环境中读取变量，用来计算请求的签名。\n\n你可以从《微信支付 APIv3》提供的 [商户参数模版](https://www.postman.com/wechatpay-dev/workspace/apiv3-public-workspace/environment/3391715-9f0f28eb-c323-4830-b9bc-3d1394562701) 中 fork 一个空环境到自己的工作台。\n\n![fork environment](https://user-images.githubusercontent.com/1812516/196032966-abc65edd-3ff4-42ae-8b3b-b9d97587a301.png)\n\n接下来，在你工作台的 Enviroments 中找到新建的环境，点击 `Add a new varialbe` 添加新的变量：\n\n- `mchid`：必填，商户号。\n- `merchant_serial_no`：必填，商户 API 证书序列号。\n- `apiclient_key.pem`：必填，PEM 格式的商户 API 私钥。\n\n\u003e **Warning**\n\u003e 为了安全，请仔细阅读[安全注意事项](#安全注意事项)。\n\n一组常见配置如下图所示。\n\n![enviroment varibles](https://user-images.githubusercontent.com/1812516/200261861-8073d9b4-bf34-47e1-9a36-5c931cdb935e.png)\n\n### 步骤3：发送请求\n\n\u003e **Note**\n\u003e 我们建议，使用桌面版 Postman app 发送请求，速度更快，体验更好！\n\n现在回到工作台，进入《微信支付 APIv3》集合，选择你要发送的请求。\n\n然后，填入请求参数，按照注释修改 Body 中的参数。\n\n最后，选择你之前配置的 Environment，再点击地址栏右侧的`Send`按钮，发送请求吧。\n\n![send request](https://user-images.githubusercontent.com/1812516/200260900-8e706607-fd68-44dd-95d0-bb4125746e79.png)\n\n## 实现原理\n\n`Pre-Request Script` 是一段 Javascript 脚本。Postman 在请求发送之前，执行这段脚本。脚本做了以下操作：\n\n1. 加载依赖库\n1. 读取 Environment 中的商户参数变量\n1. 根据请求的方法、URL、参数、Body 等信息，构造签名串，并计算请求签名\n1. 设置请求头 `Authorization`\n\n\u003e **Note**\n\u003e 有关 Postman 脚本的更多信息，请参考 [Scripting in Postman](https://learning.postman.com/docs/writing-scripts/intro-to-scripts/)。\n\n### 参数变量\n\n|  变量名   | 是否必填  |  描述  | 备注 |\n| - | :----: | - | - |\n| mchid  | 是 | 商户号  | |\n| merchant_serial_no | 是 | 商户 API 证书的证书序列号 |  |\n| apiclient_key.pem | 是 | PEM 格式的商户 API 私钥 |  |\n| openid | 否 | 用户的 OpenID，测试请求中的 {{openid}} |  |\n| appid | 否 | 公众账号或者小程序的 AppID |  |\n| shangmi | 否 | 值为 `true` 时使用商密签名 | 默认值为空，即使用 RSA 签名 |\n| pubkey.pem | 国密签名时必填 | PEM 格式的商户 API 公钥 | 如果私钥 PEM 中包含公钥，该变量可不填 |\n| server_url | 否 | 服务器地址 | 默认设置为 `https://api.mch.weixin.qq.com` |\n\n### 依赖库\n\n脚本直接使用了：\n\n- [forge.min.js](forge.min.js)，[forge](https://github.com/digitalbazaar/forge) 的 PKI、RSA 和 ASN.1。\n- [sm2.js](sm2.js)，腾讯国密库 TencentSM-javascript 的 SM2 签名。\n\n为了避免每次请求都下载依赖库，两个库以源代码的方式存储在 Collection Variables。这大大减少了使用网页版 Postman 发送请求时的耗时。\n\n## 安全注意事项\n\n**商户 API 私钥**是非常敏感的信息。使用此代码时，应记住以下几点：\n\n- 将配置了私钥的工作台（workspace）的可见性（Visibility）设置为私有 `Personal` 或者 `Private`，**不要**设置为公开 `Public`。\n- 私钥的**变量类型**设置为 `secret`。变量值会以掩码的形式显示在屏幕上。\n- 私钥的**变量值**设置在 `Current Value`。`Current Value` 仅保存在本地 [Session](https://blog.postman.com/sessions-faq/)，不会被发送至 Postman 的服务器。\n- 如果使用来自其他人的 Postman 脚本，请检查依赖库、变量和脚本，确保没有被修改，避免被植入不安全代码。\n\n\u003e **Note**\n\u003e 有关 Postman 的安全机制，请参考 [Postman Security](https://www.postman.com/trust/security/)。\n\n## 如何发起国密请求\n\n使用 [国密-商户参数模版](https://www.postman.com/wechatpay-dev/workspace/apiv3-public-workspace/environment/3391715-ba22edc3-d5f0-4c6e-9b44-b790b5a69218)，在环境变量中设置：\n\n- `shangmi`：值为 `true`。\n- `mchid`：必填，商户号。\n- `merchant_serial_no`：必填，商户 API 证书序列号。\n- `apiclient_key.pem`：必填，PEM 格式的商户 API 私钥。\n- `pubkey.pem`：必填，PEM 格式的商户 API 国密公钥。\n\n这样，脚本会使用国密 SM2 计算签名，发送国密请求了。\n\n## 本地导入脚本\n\n\u003e **Note**\n\u003e 不推荐本地导入脚本，不但麻烦而且容易出错，还不能同步上游的变更\n\nFork Collection 导入需要注册 Postman 账户。如果你不希望注册，可以本地导入脚本。\n\n首先，打开 [WeChatPay APIv3](https://www.postman.com/wechatpay-dev/workspace/wechat-pay-public-workspace/collection/3391715-85f478d8-2596-420a-9f21-53376fc6ad0a) 集合，展开选项后点击 Export：\n\n![export-json](https://user-images.githubusercontent.com/1812516/233817722-e706c51a-444e-4267-8c24-fcd3f6d398ef.png)\n\n下载并保存 `wechatpay-apiv3.postman_collection.json` 文件至本地。然后，有两种方式本地导入 JSON 文件：\n\n- Postman 界面左上角的 `Import` 按钮\n- 菜单 `File` \u003e `Import` 发起导入\n\n选择本地的 `wechatpay-apiv3.postman_collection.json`，点击确认后，导入便完成了。\n\n你会发现在工作台的 Collections 里新增了名为 《WeChatPay APIv3》 的一组请求。[配置 Environment](#步骤2配置-environment) 后即可 [发送请求](#步骤3发送请求)。\n\n## 同步上游的变更\n\n我们会逐步添加新接口和更新已有接口，但是你 fork 到自己工作台的集合分支并不会自动同步上游的变更。建议关注 `watch` 我们的 Public Workspace，这样上游变更时你会收到来自 postman 的通知。\n\n![notification](https://user-images.githubusercontent.com/1812516/200259622-eaac0ec7-e55c-48a2-a710-e720ce677aef.png)\n\n这时，你可使用 `pull changes` 拉取上游的变更。\n\n![pull changes](https://user-images.githubusercontent.com/1812516/200260015-462757c2-4f7c-44db-9663-b901f0b36228.png)\n\npostman 的 `pull changes` 可能会需要等待一定时间完成。如果遇到问题，重新 fork 也是一个好办法。\n\n## 常见问题\n\n### 发送请求时遇到错误提示“Error: Too few bytes to parse DER.”或者“Too few bytes to read ASN.1 value.”\n\n通常是环境 Environments 里配置的变量 `merchantPrivateKey` 填写有误导致的。脚本接收的私钥，以 `-----BEGIN PRIVATEKEY-----` 开始，以 `-----END PRIVATE KEY-----` 结束的一串字符串。\n\n### 为什么我发送请求很慢？\n\n如果你使用的网页版 Postman，请使用桌面版 [Postman app](https://www.postman.com/downloads/)。因为浏览器中跨域资源共享（CORS）的限制，网页版发送请求是由 Postman 后台中转的。\n\n或者使用 [Postman desktop agent](https://www.postman.com/downloads/postman-agent/)，更多信息请参考 [Postman 相关博客](https://blog.postman.com/introducing-the-postman-agent-send-api-requests-from-your-browser-without-limits/)。\n\n## 联系我们\n\n如果你有任何疑问，欢迎访问我们的[开发者社区](https://developers.weixin.qq.com/community/pay)进行反馈。\n\n我们也欢迎各种各样的 issue 和 Merge Request:-)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwechatpay-apiv3%2Fwechatpay-postman-script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwechatpay-apiv3%2Fwechatpay-postman-script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwechatpay-apiv3%2Fwechatpay-postman-script/lists"}