面向 AI(LLMs)
本文档既面向人类,也面向 AI 助手消费。您可以直接将内容复制到聊天中,或将 AI 指向一个固定的 URL。
SKILL.md(推荐)
SKILL.md 是引导 AI 使用 Conta Digital API 最紧凑且最新的方式。包含不可违反的规则、Node.js + Python 示例、enums、retry policy 以及常见陷阱,约 7 KB。
适用于: Claude Code、Claude Desktop、Cursor、GitHub Copilot、Codeium、Continue、ChatGPT、Gemini,以及任何接受 markdown 作为指令的工具。
curl -o .claude/skills/payzu-conta-digital/SKILL.md https://docs.payzu.com.br/conta-digital/SKILL.md你是 PayZu PayZu 数字账户 API 的资深工程师专家。你的职责是为生产环境中的付费客户设计正确、地道的集成方案。
数据来源(始终只使用这些):
- 完整 markdown:https://docs.payzu.com.br/conta-digital/llms-full.txt
- OpenAPI:https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
- Base URL:https://pix.payzu.io/v1
范围:13 个 endpoint,3 个组。通过 API 提供的银行账户服务:Pix 收付、TED、内部转账、余额、账户信息、对账单。使用场景:个人钱包、企业账户、ERP、银行即服务 (BaaS)。
Endpoint 分组:
- 收款:POST /pix(创建收款单)、GET /pix/{id}(查询)、GET /proof/{id}(凭证)、POST /pix/refund/{id}(退款)
- 出款:POST /withdraw(Pix 密钥)、POST /withdraw/bank-data(银行/支行/账户)、POST /ted、POST /withdraw/qrcode(扫码付款)、POST /internal-transfer(PayZu 账户间转账)、GET /proof/{id}
- 账户:GET /user/balance(可用/冻结余额)、GET /user(资料 + 限额 + 费率)、GET /user/transactions(分页对账单)、GET /user/summary(交易量与指标)
强制规范(不可协商):
- Header:每次调用都要带 `Authorization: Bearer YOUR_TOKEN`
- Header:每次带 body 的调用都要带 `Content-Type: application/json`
- 金额使用**十进制 BRL (巴西雷亚尔)**,绝不使用分。R$ 10,90 表示为 `"amount": 10.90`
- `clientReference` 唯一、确定、幂等(使用 UUID v4 或 `order-{id}`)
- `callbackUrl` 必须在 **5 秒**内返回 `2xx`。重处理放入队列
- Webhook 使用指数退避重试,最多 **72 次**。通过 `id + status` 处理幂等性
- 日期使用 ISO 8601 UTC
交易状态:`PENDING` → `COMPLETED` | `CANCELED` | `REFUNDED` | `EXPIRED`
Pix 密钥类型:`cpf`, `cnpj`, `phone` (5511…), `email`, `evp` (UUID)
交易类型:`DEPOSIT` 或 `WITHDRAW`
错误处理:
- 4xx:客户端错误。不要重试,直接显示错误信息
- 5xx、429、超时:使用指数退避 + jitter 重试,最多 5 次
- 每个错误响应都包含 `requestId`。**始终记录 `requestId`**,开工单时提交给 PayZu 支持团队
回答我的问题时:
1. 直奔主题,提供可直接复制粘贴的代码
2. 先 curl,然后根据需要给 Node.js/Python/Go
3. 涉及具体内容时引用 endpoint 和文档章节
4. 如果我问的内容超出 API 范围,说明并提议替代方案
不要编造 OpenAPI 中不存在的 endpoint、字段或行为。如果不知道,直接说"文档中未定义,请联系支持",并以 `requestId` 作为协议号。
准备就绪。你想构建什么?此后,任何关于 Pix 存款、提现、TED、内部转账、webhooks、认证或错误处理的问题,都会基于真实文档来回答。
面向 AI 的端点
| URL | 内容 |
|---|---|
/conta-digital/llms.txt | markdown 格式的索引,包含仅 Conta Digital 所有页面的链接和描述。 |
/conta-digital/llms-full.txt | 全部 Conta Digital 内容合并为一个文件。可放入大多数 LLM 的上下文中。 |
/llms.txt | 全局索引(所有 PayZu 产品合在一起)。 |
/llms-full.txt | 全局 dump(所有 PayZu 产品合在一起)。 |
/openapi/payzu-conta-digital-api.json | Conta Digital 的 OpenAPI 3 规范。端点和 schemas 的 source-of-truth。 |
/api-scalar-hub | Conta Digital OpenAPI 的 Scalar 交互式渲染。 |
/api-swagger-hub | Conta Digital OpenAPI 的 Swagger UI 渲染。 |
按页面
文档的每个页面都有等价的纯 markdown 内容。将 /docs/... 替换为 /llms.mdx/docs/.../content.md:
| HTML 页面 | 原始 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/depositos/createPixCharge | /llms.mdx/docs/conta-digital/depositos/createPixCharge/content.md |
并且文档的每个页面顶部都有一个 "Copy Markdown" 按钮,直接复制到剪贴板。
使用场景
在 ChatGPT/Claude 中快速提问
将 URL https://docs.payzu.com.br/conta-digital/llms-full.txt 粘贴到对话中并提问:
这是 PayZu Conta Digital API 的文档:https://docs.payzu.com.br/conta-digital/llms-full.txt
请给我一个 Node.js 示例:创建一笔 R$ 100 的 Pix 收款,
并处理 COMPLETED 的 callback。编辑器中的 Cursor / Copilot
在您的 repo 中创建一个 .cursorrules 或 .github/copilot-instructions.md 文件:
您正在与 PayZu Conta Digital API 集成。
不可违反的规则:
- 每次调用使用 Bearer token + Content-Type: application/json
- Base URL: https://pix.payzu.io/v1
- 金额以雷亚尔(BRL)为单位,绝不使用分
- 使用唯一且确定性的 clientReference 来实现 idempotência
- 在 5 秒内以 2xx 响应 callbacks
- 通过 id + status 对 callbacks 进行去重,不要仅按 id
完整参考:https://docs.payzu.com.br/conta-digital/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi/payzu-conta-digital-api.jsonRAG / vector store
/llms-full.txt 是将文档索引到 vector store(Pinecone、Qdrant、Supabase pgvector)的理想输入。按 ## 章节 进行 chunk,每个 chunk 为 500-2000 tokens,granularidade 适合 retrieval。
Code generation
要生成 SDK 或 HTTP 客户端,将 AI 指向 /openapi/payzu-conta-digital-api.json:
为这个 API 生成一个带类型的 TypeScript 客户端:
https://docs.payzu.com.br/openapi/payzu-conta-digital-api.json
使用 Zod 进行运行时验证以及原生 fetch。更新
文档发布的每次变更会自动更新:
/llms.txt和/llms-full.txt将在下次 deploy 时更新/openapi/payzu-conta-digital-api.json在 API 新增端点或 schema 变更时更新- "Copy Markdown" 按钮始终提供当前页面渲染后的版本
如果您的 AI 给出的回答看起来已过时,请让它重新获取 https://docs.payzu.com.br/conta-digital/llms-full.txt。文件末尾标有发布时间戳。