# Postman (/zh/docs/pix-processamento/postman)

<QuickLinks>
  <QuickLink href="https://dev.payzu.com.br" title="Postman 文档" />

  <QuickLink href="/openapi.json" title="OpenAPI" />

  <QuickLink href="/api-scalar" title="Scalar" />

  <QuickLink href="/api-swagger" title="Swagger" />
</QuickLinks>

官方 PayZu Pix collection 发布于 &#x2A;*[dev.payzu.com.br](https://dev.payzu.com.br)**（Postman），通过 `{{token}}` 使用 **Bearer Auth**，并预置 **3 个环境**：Sandbox、Production 和 Mock。

[docs.payzu.com.br/payzu-pix.postman\_collection.json](https://docs.payzu.com.br/payzu-pix.postman_collection.json) 提供的 JSON 覆盖全部 48 个 `/v1` 路由。文件夹按路由路径组织，每段路径一个文件夹：`POST /user/callbacks/resend/webhook` 位于 `user › callbacks › resend › webhook`。每个 request 都按状态码附有已保存的响应示例。

## 导入 collection [#导入-collection]

<PostmanButton />

或在 Postman 中通过 URL 导入：**Import → Link**：

```
https://docs.payzu.com.br/payzu-pix.postman_collection.json
```

## 三步配置 [#三步配置]

<Steps>
  <Step>
    ### 导入到你的 workspace [#导入到你的-workspace]

    点击上方的 **Run in Postman**。collection 会被 fork 到你的个人 workspace，包含完整结构：folders、认证、示例。
  </Step>

  <Step>
    ### 配置 token [#配置-token]

    在 PayZu Pix collection → **Variables** 标签页：

    | 变量        | 值                                            |
    | --------- | -------------------------------------------- |
    | `baseUrl` | `https://api.payzu.processamento.com/v1`（默认） |
    | `token`   | 你的 PayZu Bearer token                        |

    `baseUrl` 与 `token` 是这个 collection 仅有的两个变量：鉴权配置在 collection 级别，每个请求都继承 `Authorization: Bearer {{token}}` 请求头，自身不带 token。以上描述的是 [docs.payzu.com.br](https://docs.payzu.com.br/payzu-pix.postman_collection.json) 提供的 JSON；如果你 fork 的副本里某个请求自带 token，说明它来自旧版本，用该链接重新导入即可解决。
  </Step>

  <Step>
    ### 测试一次调用 [#测试一次调用]

    发送任何请求之前，先把 `baseUrl` 改为 sandbox（`https://pix.sandbox.payzu.dev/v1`），或选择 **Sandbox** environment。

    <Callout type="warn">
      使用默认的 `baseUrl` 时你处于**生产环境**。创建的收款是真实的，扫码支付会动用真实资金。
    </Callout>

    然后再打开 &#x2A;*pix → Create Charge (Pix deposit)** → **Send**。示例已填好 `amount` 和 `clientReference`，并返回 `qrCodeText`。
  </Step>
</Steps>

## Sandbox：不用生产环境也能测的推荐方式 [#sandbox不用生产环境也能测的推荐方式]

把 `baseUrl` 指向 sandbox，用 24 小时凭证、无需注册，即可对着真实 API 跑完整个 collection：

```
https://pix.sandbox.payzu.dev/v1
```

路由与生产的 `/v1` 完全一致，这里能跑通的代码，换个 host 就能在生产跑通。与 mock 不同，sandbox **会保存状态**：创建的收款可以被支付，提现会变更状态，webhook 也会真正送达你的接口。

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/sandbox/credencial" title="获取 sandbox 凭证" />

  <QuickLink href="/docs/pix-processamento/sandbox/cenarios" title="测试场景" />

  <QuickLink href="/docs/pix-processamento/sandbox/webhooks" title="sandbox 中的 webhook" />
</QuickLinks>

## Mock Server [#mock-server]

mock 适用于你连 sandbox 凭证都还不想申请，或者需要在 web 工具里**绕过 CORS** 的场景。它返回固定示例，不保存状态。

```
https://a8aa4f94-6b53-4994-bc60-7b2347f008e1.mock.pstmn.io/v1
```

<Callout type="warn">
  URL 末尾的 `/v1` 必须保留。少了它，mock 对所有请求都返回 404。
</Callout>

| 请求                                | Mock 响应                                                                                   |
| --------------------------------- | ----------------------------------------------------------------------------------------- |
| `POST /v1/pix`                    | `{ id, status: "PENDING", amount, type: "DEPOSIT", qrCodeText, qrCodeBase64, qrCodeUrl }` |
| `GET /v1/pix?clientReference=...` | 同一个对象，始终为 `PENDING`                                                                       |
| `GET /v1/user/balance`            | `{ balanceAvailable: 231.46, balanceBlocked: 0 }`                                         |

<Callout type="info">
  无论你发送什么，mock 都返回同一个示例：响应里的 `amount` 不会跟随请求，状态也永远不会推进。要看交易状态变化，请使用 sandbox。
</Callout>

## 最佳实践 [#最佳实践]

* **fork** 官方 collection，而不是直接编辑原件。fork 会收到上游更新。
* **使用 environments** 在 sandbox 与生产之间切换 `baseUrl`（`https://pix.sandbox.payzu.dev/v1` 与 `https://api.payzu.processamento.com/v1`）。
* **代码片段**：点击任意请求右侧的 `</>`，导出为 curl、Node、Python、Go、PHP 等。
* **Monitor**：启用 Postman Monitor，每 5 分钟测试一次 API，宕机时告警。

## 与其他查看器的对比 [#与其他查看器的对比]

| 功能              | Postman          | [Scalar](/api-scalar) | [Swagger](/api-swagger) |
| --------------- | ---------------- | --------------------- | ----------------------- |
| 带 CORS 的 Try-it | **是（无需浏览器）**     | 否（CORS 拦截）            | 否（CORS 拦截）              |
| 公开 mock server  | **是**            | 否                     | 否                       |
| Environments    | **是**            | 否                     | 否                       |
| 定时 monitor      | **是**            | 否                     | 否                       |
| 代码片段            | 是                | 是                     | 是                       |
| 浏览器内 Try-it     | 否（Postman Web 可） | 是                     | 是                       |
| 免安装             | Postman Web      | **是**                 | **是**                   |