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

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

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

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

把下面的某个 URL 粘贴到聊天中，或把文件加载到 AI 的上下文里。

<CopyAIPrompt />

<Callout type="warn">
  本文档对应**数字账户** API（`https://api.hub.payzu.com.br/api/v1`，`client_id` + `client_secret` 凭证在 `POST /oauth/token` 换取令牌，金额以**分**为单位）。**Pix** API（`https://api.payzu.processamento.com/v1`，金额以雷亚尔为单位）和**银行卡** API（`https://api.payzu.io/v1`，mTLS）是其他系统，有各自的凭证。不要在同一个集成中混用这些 API。
</Callout>

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

| URL                                                                                     | 内容                                    |
| --------------------------------------------------------------------------------------- | ------------------------------------- |
| [`/conta-digital/llms.txt`](https://docs.payzu.com.br/conta-digital/llms.txt)           | 索引，包含数字账户每个页面的链接和说明。                  |
| [`/conta-digital/llms-full.txt`](https://docs.payzu.com.br/conta-digital/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 产品的全部文档。                     |
| [`/conta-digital-openapi.json`](https://docs.payzu.com.br/conta-digital-openapi.json)   | 数字账户的 OpenAPI 3.1 规范：路由、作用域、字段、示例和拒绝。 |
| [`/api-scalar-conta-digital`](https://docs.payzu.com.br/api-scalar-conta-digital)       | 交互式的 Scalar 版 OpenAPI。                |
| [`/api-swagger-conta-digital`](https://docs.payzu.com.br/api-swagger-conta-digital)     | Swagger UI 中的 OpenAPI。                |

## 按页面 [#按页面]

每个页面都有 Markdown 版本。把 `/docs/...` 替换为 `/llms.mdx/docs/.../content.md`：

| 页面                                | Markdown                                              |
| --------------------------------- | ----------------------------------------------------- |
| `/docs/conta-digital`             | `/llms.mdx/docs/conta-digital/content.md`             |
| `/docs/conta-digital/webhooks`    | `/llms.mdx/docs/conta-digital/webhooks/content.md`    |
| `/docs/conta-digital/withdrawals` | `/llms.mdx/docs/conta-digital/withdrawals/content.md` |

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

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

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

```text
PayZu 数字账户 API 文档：https://docs.payzu.com.br/conta-digital/llms-full.txt
Base URL：https://api.hub.payzu.com.br/api/v1
令牌：POST /oauth/token，使用 Basic（client_id:client_secret）和
grant_type=client_credentials。access_token 有效期 15 分钟，放在
Authorization: Bearer 中。金额以分为单位。

请给我一个 Node.js 示例，要求：
1. 获取令牌，并在 API 返回 401 TOKEN_INVALID 时重新获取。
2. 创建一笔 R$ 15,00（"amount": 1500）的 Pix 收款，把订单号放在
   externalRef 中。
3. 接收 PAYMENT_PAID Webhook 并校验 X-Payzu-Signature header：它是用端点密钥对
   "<X-Payzu-Timestamp>.<raw body>" 计算的 HMAC-SHA256，与 "sha256=" 之后的值
   比较。拒绝超过 5 分钟的时间戳（单位毫秒）。
4. 按 X-Payzu-Delivery header 忽略重复的 Webhook。
```

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

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

```text
你正在对接 PayZu 的数字账户 API。

规则：
- Base URL：https://api.hub.payzu.com.br/api/v1
- 令牌：POST /oauth/token，使用 Basic（client_id:client_secret）和
  grant_type=client_credentials。有效期 15 分钟；遇到 401 TOKEN_INVALID 时重新获取。
- 账户就是凭证所属的账户。没有任何路由接收 accountId。
- 金额以分为单位，为整数（1500 = R$ 15,00）。百分比：150 = 1.5%。
  日期为 ISO 8601，UTC。
- 列表：把响应中的 nextCursor 放入下一次调用的 cursor 参数；
  最后一页不返回它。limit 为 1 到 100。
- 错误：{ message, code, details }。根据 code 判断，绝不根据 message。
- 收款：用同一个 externalRef 和相同数据重复请求，会返回同一笔收款（200）；
  有数据不同时，返回 409 PAYMENT_EXTERNAL_REF_MISMATCH。
- 提现、Pix 复制粘贴码付款和转账：发送 Idempotency-Key。
  遇到 502 时，用同一个键重试，或先查询。
- 退款和退回存款不接受 Idempotency-Key：遇到 502 时，重试前先查询
  收款或存款。
- 在 PAYMENT_PAID Webhook 中放行订单。提现只有在
  WITHDRAW_COMPLETED（状态 CONFIRMED）时才算到达目的地。
- Webhook：校验 X-Payzu-Signature（"<timestamp>.<raw body>" 的 HMAC-SHA256），
  在 10 秒内返回 2xx，并按 X-Payzu-Delivery 忽略重复的 Webhook。
- 不要编造路由或字段：以 https://docs.payzu.com.br/conta-digital-openapi.json 为准。
```

### 使用 OpenAPI 的助手 [#使用-openapi-的助手]

带 Actions 的 GPTs、智能体和客户端生成器可以直接使用 `https://docs.payzu.com.br/conta-digital-openapi.json`。该规范包含每个路由的作用域、请求和响应示例，以及各项拒绝及其 `code`。