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

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

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

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

银行卡文档也以纯文本形式提供给 AI 助手。你可以把固定 URL 粘贴到聊天里，或者把整个文件加载到上下文中。

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

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

| URL                                                                       | 内容                                     |
| ------------------------------------------------------------------------- | -------------------------------------- |
| [`/cartao/llms.txt`](https://docs.payzu.com.br/cartao/llms.txt)           | markdown 格式的索引，包含**仅银行卡**所有页面的链接和描述。   |
| [`/cartao/llms-full.txt`](https://docs.payzu.com.br/cartao/llms-full.txt) | **完整**银行卡文档拼接为单一文件。                    |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                         | 全局索引（所有 PayZu 产品合并）。                   |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)               | 全局转储（所有 PayZu 产品合并）。                   |
| [`/cartao-openapi.json`](https://docs.payzu.com.br/cartao-openapi.json)   | 银行卡 API 的 OpenAPI 3 规范：端点、schemas 和错误。 |
| [`/api-scalar-cartao`](https://docs.payzu.com.br/api-scalar-cartao)       | OpenAPI 的 Scalar 交互式渲染。                |
| [`/api-swagger-cartao`](https://docs.payzu.com.br/api-swagger-cartao)     | OpenAPI 的 Swagger UI 渲染。               |

<Callout type="info">
  专用转储 `/cartao/llms-full.txt` 只包含银行卡。全局转储 `/llms-full.txt` 把银行卡和 Pix 放在同一文件里，二者的 base URL、认证方式（mTLS × Bearer）和金额单位（分 × 雷亚尔）都不同。
</Callout>

## 按页面 [#按页面]

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

| HTML 页面                          | 原始 markdown                                          |
| -------------------------------- | ---------------------------------------------------- |
| `/zh/docs/cartao`                | `/llms.mdx/docs/zh/cartao/content.md`                |
| `/zh/docs/cartao/webhooks`       | `/llms.mdx/docs/zh/cartao/webhooks/content.md`       |
| `/zh/docs/cartao/three-d-secure` | `/llms.mdx/docs/zh/cartao/three-d-secure/content.md` |

每个页面顶部都有 **问 AI**、**复制给 LLM**（复制页面的 markdown）和 **查看 Markdown**（打开页面的 markdown）按钮。

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

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

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

```text
PayZu 银行卡 API 文档：https://docs.payzu.com.br/cartao/llms-full.txt
Base URL：https://api.payzu.io/v1（sandbox：https://api.sandbox.payzu.io/v1）。
认证：每次调用都使用客户端证书（mTLS）+ Bearer token，token 通过 POST /token 获取，
使用 Basic Auth（client_id:client_secret）和 grant_type client_credentials。
金额以分为单位。

给我一个 Node.js 示例：
1. 使用 mTLS 证书通过 POST /token 获取 token。
2. 在 POST /charges 创建一笔 R$ 100,00 的收款（"amount": 10000），并带上 postbackUrl。
3. 接收 webhook，并在处理前校验签名：用 webhook secret 对
   "<X-Webhook-Timestamp>.<X-Webhook-Nonce>.<原始请求体>" 计算 HMAC-SHA256，
   与 X-Webhook-Signature 比对；时间戳（毫秒）超过 5 分钟则拒绝。
4. 按收款 id + 状态变化去重。
```

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

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

```text
你正在对接 PayZu 银行卡 API。它是独立于 Pix API 的系统。

不可违反的规则：
- Base URL：https://api.payzu.io/v1（sandbox：https://api.sandbox.payzu.io/v1）
- 每次调用都使用 PayZu 提供的客户端证书（mTLS）
- Token：POST /token，使用 Basic Auth（client_id:client_secret）和 {"grant_type": "client_credentials"}；
  其他路由携带 Authorization: Bearer <access_token>
- 金额（amount、unitPrice）以分为单位（R$ 10,90 = 1090）；汇率（rate.bid、rate.ask）为小数
- Webhook：POST 到收款的 postbackUrl。校验 X-Webhook-Signature（用 webhook secret 对
  "timestamp.nonce.payload" 计算的十六进制 HMAC-SHA256），并拒绝超过 5 分钟的
  X-Webhook-Timestamp（毫秒）
- 在 5 秒内以 2xx 响应 webhook；投递失败后最多重试 5 次
- 按收款 id + 状态变化对 webhook 去重，切勿使用 X-Webhook-Nonce
- POST /charges 不是幂等的：遇到超时时，先在 GET /charges（startDate 和 endDate）中查找您的 externalId
  再决定是否重试，否则会重复扣款
- 退款（PUT /charges/{chargeId}/reverse）始终全额，每笔收款只能退一次；不要传 amount
- 切勿使用 api.payzu.processamento.com（那是 Pix API：Bearer，金额以雷亚尔为单位）

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

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

`/cartao/llms-full.txt` 是将银行卡文档索引到向量库（Pinecone、Qdrant、Supabase pgvector）的文件。每个 `## 章节` 可作为一个 chunk。

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

要生成 HTTP 客户端，让 AI 指向 `/cartao-openapi.json`：

```text
为这个银行卡 API 生成一个带类型的 TypeScript 客户端：
https://docs.payzu.com.br/cartao-openapi.json
Base URL https://api.payzu.io/v1，mTLS + 通过 POST /token 获取的 Bearer token，金额以分为单位。
使用 Zod 做运行时校验，并用 undici 携带客户端证书。
```

## 更新 [#更新]

文档中发布的每一次变更，都会在下一次部署时更新 `/cartao/llms.txt`、`/cartao/llms-full.txt` 以及每个页面的 markdown。API 新增端点或 schema 变更时，`/cartao-openapi.json` 也会随之更新。