# 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 个环境**（Mock、Sandbox、Production）。

## 导入 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                        |

    token 会**自动**出现在每个请求的 `Authorization: Bearer {{token}}` 请求头中。
  </Step>

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

    打开 **Pix Charges → POST /pix** → **Send**。示例已填好 `amount`、`clientReference`、`callbackUrl`，会返回 `qrCodeText`，可用任意支持 Pix 的银行测试。
  </Step>
</Steps>

## Mock Server [#mock-server]

无需真实 token 即可开发：collection 自带一个**公开 mock server**，用 OpenAPI 示例作答，还可用于在 web 工具中**绕过 CORS**。

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

开发前端时用它替代 `https://api.payzu.processamento.com/v1`。

| 请求                                 | Mock 响应                                      |
| ---------------------------------- | -------------------------------------------- |
| `POST /pix`                        | `{ id, qrCodeText, status: "PENDING", ... }` |
| `GET /pix?clientReference=order-1` | `{ status: "COMPLETED", ... }`               |
| `GET /user/balance`                | `{ available: 12450.75, blocked: 0, ... }`   |

<Callout type="info">
  mock 基于 OpenAPI 的 `examples` 作答。调用之间不保存状态，但格式与真实 API 完全一致。
</Callout>

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

* **fork** 官方 collection，而不是直接编辑原件。fork 会收到上游更新。
* **使用 environments** 在 dev/prod 之间切换 `baseUrl`（`api.payzu.processamento.com/v1` 与 mock）。
* **代码片段**：点击任意请求右侧的 `</>`，导出为 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      | **是**                 | **是**                   |