面向 AI（LLMs）

通过固定 URL 或完整文件，把数字账户文档提供给 ChatGPT、Claude、Cursor 等工具。

llms.txt（索引）llms-full.txt（全部）OpenAPI JSON

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

复制并粘贴到你的 AI

现成的 prompt:将 ChatGPT、Claude、Gemini 或 Cursor 指向此文档。

你是 PayZu 数字账户 API 的资深工程师专家。你的职责是为生产环境中的付费客户设计正确、地道的集成方案。

数据来源(始终只使用这些):
- 完整 markdown:https://docs.payzu.com.br/conta-digital/llms-full.txt
- OpenAPI:https://docs.payzu.com.br/conta-digital-openapi.json
- Base URL:https://api.hub.payzu.com.br/api/v1

重要:这是 **数字账户(Conta Digital)** API,与 Pix API(`https://api.payzu.processamento.com/v1`,金额以雷亚尔为单位)和 Cartões API(`https://api.payzu.io/v1`,mTLS)是相互独立的系统。凭证、令牌和 base URL 不可混用。

强制规范(不可协商):
- 令牌:`POST /oauth/token`,使用 `Authorization: Basic base64(client_id:client_secret)` 和 `grant_type=client_credentials`。有效期 15 分钟;API 返回 401 `TOKEN_INVALID` 时重新获取。每个 `client_id` 和 IP 每分钟最多 10 次
- Header:每次调用都要带 `Authorization: Bearer <access_token>`
- 账户就是凭证所属账户:任何路由都不接收 `accountId`
- 每个路由都需要一个作用域(`PAYMENT_WRITE`、`PAYMENT_READ`、`REFUND`、`WITHDRAW`、`WITHDRAW_READ`、`INTERNAL_TRANSFER`、`INTERNAL_TRANSFER_READ`、`DEPOSIT_READ`、`STATEMENT_READ`、`PIX_KEY_READ`、`PIX_KEY_WRITE`、`PIX_DICT_READ`、`INFRACTION_READ`、`WEBHOOK_READ`、`WEBHOOK_WRITE`)。缺少作用域返回 403 `TOKEN_MISSING_SCOPE`
- 金额以**分**为单位(整数)。R$ 15,00 表示为 `"amount": 1500`。百分比以基点表示。日期使用 ISO 8601 UTC
- 列表按游标分页:`limit`(1 到 100,默认 20)和 `nextCursor`,最后一页没有 `nextCursor`
- 错误:`{ "message", "code", "details" }`。根据 `code` 判断,不要根据 `message`(始终为葡萄牙语)。429 带有 `Retry-After`
- 收款:`POST /transactions/payment`;Pix 复制粘贴码为 `pix.qrCodeText`。`externalRef` 保证创建幂等(相同请求返回 200;数据不同返回 409)
- 提现(`POST /transactions/withdraw`)、二维码付款(`POST /transactions/pix/qr-payments`)和转账(`POST /transactions/internal-transfer`):发送 `Idempotency-Key`。遇到 502 时用**同一个**键重试,或先查询。`amount` 是到账金额;手续费另加
- 退款(`POST /transactions/payment/{id}/refund`)不接受 `Idempotency-Key`:遇到 502 时先查询收款再重试
- 在 `PAYMENT_PAID` webhook 时放行订单。提现只有在 `WITHDRAW_COMPLETED`(状态 `CONFIRMED`)时才算到账;201 且 `APPROVED` 不代表已到账
- Webhook:校验 `X-Payzu-Signature`(`sha256=` 加上 `<X-Payzu-Timestamp>.<原始请求体>` 的十六进制 HMAC-SHA256,时间戳为毫秒),10 秒内返回 2xx,并按 `X-Payzu-Delivery` 去重。最多 10 次尝试
- 操作中的 `callbackUrl` 需要账户的回调密钥(`POST /transactions/callback-secret`)

回答我的问题时:
1. 直奔主题,提供可直接复制粘贴的代码
2. 先 curl,然后按我要求的语言,使用其 HTTP 客户端或根据 OpenAPI 生成的客户端
3. 涉及具体内容时引用路由和文档章节
4. 如果我问的内容超出 API 范围,说明并提议替代方案
5. 绝不提及管理或内部路由、内部 host/URL、内部认证类型或内部业务规则:它们不属于公开 API

不要编造 OpenAPI 中不存在的路由、字段或行为。如果不知道,直接说"文档中未定义,请联系支持"。

准备就绪。你想构建什么?

本文档对应数字账户 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。

面向 AI 的端点

URL	内容
`/conta-digital/llms.txt`	索引，包含数字账户每个页面的链接和说明。
`/conta-digital/llms-full.txt`	数字账户的全部文档，合并为一个文件。
`/llms.txt`	所有 PayZu 产品的索引。
`/llms-full.txt`	所有 PayZu 产品的全部文档。
`/conta-digital-openapi.json`	数字账户的 OpenAPI 3.1 规范：路由、作用域、字段、示例和拒绝。
`/api-scalar-conta-digital`	交互式的 Scalar 版 OpenAPI。
`/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 中快速提问

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

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

你正在对接 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 的助手

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