# 面向 AI（LLMs） (/zh/docs/pix-processamento/for-ai)

<QuickLinks>
  <QuickLink href="https://docs.payzu.com.br/pix-processamento/llms.txt" title="llms.txt（索引）" />

  <QuickLink href="https://docs.payzu.com.br/pix-processamento/llms-full.txt" title="llms-full.txt（全部）" />

  <QuickLink href="https://docs.payzu.com.br/openapi.json" title="OpenAPI JSON" />
</QuickLinks>

本文档既面向人类阅读，也面向 AI 助手使用。你可以把内容直接复制到聊天里，或者让 AI 指向一个固定 URL。

<CopyAIPrompt />

之后，任何关于 Pix 收款、webhooks、MED、认证或错误处理的问题，都会基于真实文档得到解答。

<Callout type="warn">
  本文档针对 **Pix Processamento** API（`https://api.payzu.processamento.com/v1`，Bearer，金额以**巴西雷亚尔**为单位）。**Cartão** API 是另一套系统（`https://api.payzu.io/v1`，mTLS + `client_credentials`，金额以**分**为单位），有独立文档。切勿在同一集成中混用这两者，也不存在 `pix.payzu.io`。
</Callout>

## 面向 AI 的端点 [#面向-ai-的端点]

| URL                                                                                                 | 内容                                                   |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [`/pix-processamento/llms.txt`](https://docs.payzu.com.br/pix-processamento/llms.txt)               | markdown 格式的索引，包含**仅 Pix Processamento** 所有页面的链接和描述。 |
| [`/pix-processamento/llms-full.txt`](https://docs.payzu.com.br/pix-processamento/llms-full.txt)     | **完整** Pix Processamento 内容拼接为单一文件。可容纳于大多数 LLM 的上下文。 |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                                                   | 全局索引（所有 PayZu 产品合并）。                                 |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)                                         | 全局转储（所有 PayZu 产品合并）。                                 |
| [`/openapi.json`](https://docs.payzu.com.br/openapi.json)                                           | V1 API 的 OpenAPI 3 规范。端点、schemas 和错误的唯一权威来源。         |
| [`/api-scalar`](https://docs.payzu.com.br/api-scalar)                                               | OpenAPI 的 Scalar 交互式渲染。                              |
| [`/api-swagger`](https://docs.payzu.com.br/api-swagger)                                             | OpenAPI 的 Swagger UI 渲染。                             |
| [`/payzu-pix.postman_collection.json`](https://docs.payzu.com.br/payzu-pix.postman_collection.json) | 可直接导入的 Postman 集合。                                   |

<Callout type="info">
  如果你只做 **Pix** 集成，请优先使用专用转储 `/pix-processamento/llms-full.txt`。全局转储 `/llms-full.txt` 把 Pix 和 Cartão 混在同一文件里，可能会让 AI 混淆 base URL、认证方式（Bearer × mTLS）以及金额单位（雷亚尔 × 分）。
</Callout>

## 按页面 [#按页面]

文档的每个页面都有对应的纯 markdown 内容。将 `/docs/...` 替换为 `/llms.mdx/docs/.../content.md`：

| HTML 页面                                              | 原始 markdown                                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------ |
| `/docs/pix-processamento`                            | `/llms.mdx/docs/pix-processamento/content.md`                            |
| `/docs/pix-processamento/webhooks`                   | `/llms.mdx/docs/pix-processamento/webhooks/content.md`                   |
| `/docs/pix-processamento/best-practices/idempotency` | `/llms.mdx/docs/pix-processamento/best-practices/idempotency/content.md` |

并且文档的每个页面顶部都有一个 &#x2A;*"Copy Markdown"** 按钮，可直接把内容复制到剪贴板。

## 使用场景 [#使用场景]

### 在 ChatGPT/Claude 里快速提问 [#在-chatgptclaude-里快速提问]

把 URL `https://docs.payzu.com.br/pix-processamento/llms-full.txt` 贴入对话，然后提出具体问题：

```text
PayZu Pix API 文档（Processamento）：https://docs.payzu.com.br/pix-processamento/llms-full.txt
Base URL：https://api.payzu.processamento.com/v1，认证使用 Bearer token，金额以雷亚尔为单位。

请给我一个 Node.js 示例，实现以下功能：
1. 创建一笔 R$ 100 的 Pix 收款（POST /pix），使用幂等的 clientReference。
2. 接收 webhook 并在处理前校验签名：
   X-Callback-Signature 头形如 "t=<unix>, v1=<hex>"，HMAC-SHA256 计算对象为
   "<t>.<原始请求体>"，密钥为 webhook secret。不存在 nonce。
3. 只有当 status 为 COMPLETED 时才把订单标记为已支付，并按 id + 事件 去重。
```

### 编辑器里的 Cursor / Copilot [#编辑器里的-cursor--copilot]

在你的仓库中创建 `.cursorrules` 或 `.github/copilot-instructions.md` 文件：

```text
你正在集成 PayZu Pix Processamento API。这是独立于 Cartão API 的系统。

不可违反的规则：
- Base URL：https://api.payzu.processamento.com/v1
- 每个调用都需带上 Authorization: Bearer <token> + Content-Type: application/json
- 金额以雷亚尔（BRL）小数表示，绝不能用分（R$ 10,90 = "amount": 10.90）
- 唯一且确定性的 clientReference 保证请求的幂等性
- 列表（GET）使用 page + limit 分页（大多数最多 100；/user/transactions 最多接受 1000），无总数计数
- Webhook：校验 X-Callback-Signature 头，它形如 "t=<unix>, v1=<hex>"；
  HMAC-SHA256 计算对象为 "<t>.<原始请求体>"，密钥为 webhook secret，不存在 nonce。
  注册的 webhook 使用 webhook secret 签名；发往交易 callbackUrl 的投递则使用账户的 callback secret 签名（若已配置）。
  需在 5s 内返回 2xx
- 按 id + 事件（X-Callback-Event 头）对 callback 去重：三个事件不会改变 status
- 绝不使用 api.payzu.io（那是 Cartão API：mTLS、client_credentials、分为单位）
  也不使用 pix.payzu.io（不存在）

完整参考：https://docs.payzu.com.br/pix-processamento/llms-full.txt
OpenAPI：https://docs.payzu.com.br/openapi.json
```

### RAG / 向量库 [#rag--向量库]

`/pix-processamento/llms-full.txt` 是把 Pix 文档索引到向量库（Pinecone、Qdrant、Supabase pgvector）的理想输入。按 `## section` 分块，每块约 500-2000 tokens，检索粒度合适。请把 Pix 与 Cartão 的转储分开索引，以免检索器混淆两套系统的约定。

### 代码生成 [#代码生成]

要生成 SDK 或 HTTP 客户端，请让 AI 指向 `/openapi.json`：

```text
请为这个 Pix API 生成一个带类型的 TypeScript 客户端：
https://docs.payzu.com.br/openapi.json
Base URL 为 https://api.payzu.processamento.com/v1，认证 Bearer，金额以雷亚尔为单位。
使用 Zod 做运行时校验，使用原生 fetch。
```

## 更新 [#更新]

文档中发布的每个改动都会自动更新：

* `/llms.txt` 和 `/llms-full.txt` 会在下一次部署时更新。
* `/openapi.json` 会在 API 新增端点或 schema 变更时更新。
* "Copy Markdown" 按钮始终提供当前页面已渲染的版本。

<Callout type="info">
  如果你的 AI 给出的回答看起来已过时，请让它重新拉取 `https://docs.payzu.com.br/pix-processamento/llms-full.txt`。发布时间戳位于文件末尾。
</Callout>