# Para IAs (LLMs) (/docs/conta-digital/for-ai)

<QuickLinks>
  <QuickLink href="https://docs.payzu.com.br/conta-digital/llms.txt" title="llms.txt (índice)" />

  <QuickLink href="https://docs.payzu.com.br/conta-digital/llms-full.txt" title="llms-full.txt (tudo)" />

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

Cole uma das URLs abaixo no chat ou carregue o arquivo no contexto da IA.

<CopyAIPrompt />

<Callout type="warn">
  Esta doc é da API **Conta Digital** (`https://api.hub.payzu.com.br/api/v1`, credencial `client_id` + `client_secret` trocada por token em `POST /oauth/token`, valores em **centavos**). A API **Pix** (`https://api.payzu.processamento.com/v1`, valores em reais) e a API **Cartões** (`https://api.payzu.io/v1`, mTLS) são outros sistemas, com credenciais próprias. Não misture as APIs na mesma integração.
</Callout>

## Endpoints para IAs [#endpoints-para-ias]

| URL                                                                                     | O que tem                                                                               |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| [`/conta-digital/llms.txt`](https://docs.payzu.com.br/conta-digital/llms.txt)           | Índice com o link e a descrição de cada página da Conta Digital.                        |
| [`/conta-digital/llms-full.txt`](https://docs.payzu.com.br/conta-digital/llms-full.txt) | Toda a doc da Conta Digital num arquivo só.                                             |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                                       | Índice de todos os produtos PayZu.                                                      |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)                             | Toda a doc de todos os produtos PayZu.                                                  |
| [`/conta-digital-openapi.json`](https://docs.payzu.com.br/conta-digital-openapi.json)   | Especificação OpenAPI 3.1 da Conta Digital: rotas, escopos, campos, exemplos e recusas. |
| [`/api-scalar-conta-digital`](https://docs.payzu.com.br/api-scalar-conta-digital)       | A OpenAPI no Scalar, em versão interativa.                                              |
| [`/api-swagger-conta-digital`](https://docs.payzu.com.br/api-swagger-conta-digital)     | A OpenAPI no Swagger UI.                                                                |

## Por página [#por-página]

Cada página tem uma versão em Markdown. Troque `/docs/...` por `/llms.mdx/docs/.../content.md`:

| Página                            | 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` |

No topo de cada página ficam os botões **Perguntar à IA**, **Copiar para LLM** (copia o markdown da página) e **Ver como Markdown** (abre o markdown da página).

## Casos de uso [#casos-de-uso]

### Pergunta rápida no ChatGPT/Claude [#pergunta-rápida-no-chatgptclaude]

```text
Doc da API Conta Digital PayZu: https://docs.payzu.com.br/conta-digital/llms-full.txt
Base URL: https://api.hub.payzu.com.br/api/v1
Token: POST /oauth/token com Basic (client_id:client_secret) e
grant_type=client_credentials. O access_token vale 15 minutos e vai em
Authorization: Bearer. Valores em centavos.

Me mostre um exemplo em Node.js que:
1. Pega o token e pede outro quando a API responde 401 TOKEN_INVALID.
2. Cria uma cobrança Pix de R$ 15,00 ("amount": 1500) com o número do pedido
   em externalRef.
3. Recebe o webhook PAYMENT_PAID e confere o header X-Payzu-Signature: é o
   HMAC-SHA256 de "<X-Payzu-Timestamp>.<corpo cru>" com o segredo do endpoint,
   comparado com o valor depois de "sha256=". Recusa timestamp (em
   milissegundos) com mais de 5 minutos.
4. Ignora webhook repetido pelo header X-Payzu-Delivery.
```

### Cursor / Copilot no editor [#cursor--copilot-no-editor]

Crie um arquivo `.cursorrules` ou `.github/copilot-instructions.md` no seu repositório:

```text
Você está integrando com a API Conta Digital da PayZu.

Regras:
- Base URL: https://api.hub.payzu.com.br/api/v1
- Token: POST /oauth/token com Basic (client_id:client_secret) e
  grant_type=client_credentials. Vale 15 minutos; peça outro no 401 TOKEN_INVALID.
- A conta é a da credencial. Nenhuma rota recebe accountId.
- Valores em centavos, inteiros (1500 = R$ 15,00). Percentuais: 150 = 1,5%.
  Datas em ISO 8601, UTC.
- Listagens: mande o nextCursor da resposta no parâmetro cursor da próxima
  chamada; na última página ele não vem. limit vai de 1 a 100.
- Erro: { message, code, details }. Decida pelo code, nunca pela message.
- Cobrança: repetir com o mesmo externalRef e os mesmos dados devolve a mesma
  cobrança (200); com algum dado diferente, 409 PAYMENT_EXTERNAL_REF_MISMATCH.
- Saque, pagamento de Pix copia e cola e transferência: mande Idempotency-Key.
  Num 502, repita com a mesma chave ou consulte antes.
- Estorno e devolução de depósito não aceitam Idempotency-Key: num 502, consulte
  a cobrança ou o depósito antes de repetir.
- Libere o pedido no webhook PAYMENT_PAID. Saque só chegou ao destino em
  WITHDRAW_COMPLETED (status CONFIRMED).
- Webhook: confira X-Payzu-Signature (HMAC-SHA256 de "<timestamp>.<corpo cru>"),
  responda 2xx em até 10 segundos e ignore repetidos por X-Payzu-Delivery.
- Não invente rotas nem campos: a fonte é https://docs.payzu.com.br/conta-digital-openapi.json
```

### Assistente com a OpenAPI [#assistente-com-a-openapi]

GPTs com Actions, agentes e geradores de cliente usam `https://docs.payzu.com.br/conta-digital-openapi.json` direto. A spec traz o escopo de cada rota, exemplos de requisição e resposta e as recusas, com o `code` de cada uma.