# Para IAs (LLMs) (/docs/pix-processamento/for-ai)



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

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

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

Esta documentação foi pensada para ser consumida tanto por humanos quanto por assistentes de IA. Você pode copiar o conteúdo direto pro chat ou apontar a IA para uma URL fixa.

<CopyAIPrompt />

A partir daí, qualquer pergunta sobre cobrança Pix, webhooks, MED, autenticação ou tratamento de erros vem respondida com base na doc real.

<Callout type="warn">
  Esta doc é da API **Pix Processamento** (`https://api.payzu.processamento.com/v1`, Bearer, valores em **reais**). A API de **Cartão** é outro sistema (`https://api.payzu.io/v1`, mTLS + `client_credentials`, valores em **centavos**) e tem doc própria. Nunca misture as duas na mesma integração, e não existe `pix.payzu.io`.
</Callout>

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

| URL                                                                                                 | O que tem                                                                                   |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`/pix-processamento/llms.txt`](https://docs.payzu.com.br/pix-processamento/llms.txt)               | Índice em formato markdown com link e descrição de toda página **só de Pix Processamento**. |
| [`/pix-processamento/llms-full.txt`](https://docs.payzu.com.br/pix-processamento/llms-full.txt)     | **Toda** Pix Processamento concatenada em um arquivo. Cabe no contexto da maioria dos LLMs. |
| [`/llms.txt`](https://docs.payzu.com.br/llms.txt)                                                   | Índice global (todos os produtos PayZu juntos).                                             |
| [`/llms-full.txt`](https://docs.payzu.com.br/llms-full.txt)                                         | Dump global (todos os produtos PayZu juntos).                                               |
| [`/openapi.json`](https://docs.payzu.com.br/openapi.json)                                           | Especificação OpenAPI 3 da API V1. Source-of-truth dos endpoints, schemas, erros.           |
| [`/api-scalar`](https://docs.payzu.com.br/api-scalar)                                               | Renderização Scalar interativa do OpenAPI.                                                  |
| [`/api-swagger`](https://docs.payzu.com.br/api-swagger)                                             | Renderização Swagger UI do OpenAPI.                                                         |
| [`/payzu-pix.postman_collection.json`](https://docs.payzu.com.br/payzu-pix.postman_collection.json) | Coleção Postman pronta para importar.                                                       |

<Callout type="info">
  Para uma integração **só de Pix**, prefira o dump específico `/pix-processamento/llms-full.txt`. O dump global `/llms-full.txt` mistura Pix e Cartão no mesmo arquivo e pode induzir a IA a confundir base URL, autenticação (Bearer × mTLS) e unidade de valor (reais × centavos).
</Callout>

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

Toda página da doc tem o conteúdo equivalente em markdown puro. Substitua `/docs/...` por `/llms.mdx/docs/.../content.md`:

| Página HTML                                          | Markdown bruto                                                           |
| ---------------------------------------------------- | ------------------------------------------------------------------------ |
| `/docs/pix-processamento`                            | `/llms.mdx/docs/pix-processamento/content.md`                            |
| `/docs/pix-processamento/webhooks`                   | `/llms.mdx/docs/pix-processamento/webhooks/content.md`                   |
| `/docs/pix-processamento/best-practices/idempotency` | `/llms.mdx/docs/pix-processamento/best-practices/idempotency/content.md` |

E em toda página da doc tem um botão &#x2A;*"Copy Markdown"** no topo, que copia direto pra área de transferência.

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

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

Cole a URL `https://docs.payzu.com.br/pix-processamento/llms-full.txt` na conversa e peça algo concreto:

```text
Doc da API Pix PayZu (Processamento): https://docs.payzu.com.br/pix-processamento/llms-full.txt
Base URL: https://api.payzu.processamento.com/v1, auth Bearer token, valores em reais.

Me mostre um exemplo em Node.js que:
1. Cria uma cobrança Pix de R$ 100 (POST /pix) com clientReference idempotente.
2. Recebe o webhook e valida a assinatura antes de processar:
   x-webhook-signature = HMAC-SHA256(segredo, "timestamp.nonce.payload"),
   usando os headers x-webhook-timestamp e x-webhook-nonce.
3. Só marca o pedido como pago quando o status for COMPLETED, deduplicando por id + status.
```

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

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

```text
Você está integrando com a API PayZu Pix Processamento. É um sistema independente da API de Cartão.

Regras invioláveis:
- Base URL: https://api.payzu.processamento.com/v1
- Toda chamada usa Authorization: Bearer <token> + Content-Type: application/json
- Valores em reais (BRL) decimais, nunca centavos (R$ 10,90 = "amount": 10.90)
- clientReference único e determinístico garante a idempotência da requisição
- Listagens (GET) paginam com page + limit (máx 100 na maioria; /user/transactions aceita até 1000), sem count total
- Webhook: valide a assinatura HMAC-SHA256 do header x-webhook-signature sobre
  "timestamp.nonce.payload" (headers x-webhook-timestamp e x-webhook-nonce); responda 2xx em até 5s
- Deduplique callbacks por id + status
- NUNCA use api.payzu.io (essa é a API de Cartão: mTLS, client_credentials, centavos)
  nem pix.payzu.io (não existe)

Referência completa: https://docs.payzu.com.br/pix-processamento/llms-full.txt
OpenAPI: https://docs.payzu.com.br/openapi.json
```

### RAG / vector store [#rag--vector-store]

O `/pix-processamento/llms-full.txt` é o input ideal para indexar a doc de Pix em um vector store (Pinecone, Qdrant, Supabase pgvector). Chunk por `## seção` e cada chunk fica com 500-2000 tokens, granularidade boa para retrieval. Indexe o dump de Pix separado do de Cartão para o retriever nunca cruzar convenções dos dois sistemas.

### Code generation [#code-generation]

Para gerar SDK ou cliente HTTP, aponte a IA para o `/openapi.json`:

```text
Gere um cliente TypeScript tipado para esta API Pix:
https://docs.payzu.com.br/openapi.json
Base URL https://api.payzu.processamento.com/v1, auth Bearer, valores em reais.
Use Zod para validação de runtime e fetch nativo.
```

## Atualização [#atualização]

Toda mudança publicada na doc atualiza automaticamente:

* `/llms.txt` e `/llms-full.txt` no próximo deploy.
* `/openapi.json` quando a API ganha endpoints novos ou mudanças de schema.
* O botão "Copy Markdown" sempre serve a versão renderizada da página atual.

<Callout type="info">
  Se sua IA der uma resposta que parece desatualizada, peça pra ela re-buscar `https://docs.payzu.com.br/pix-processamento/llms-full.txt`. O timestamp da publicação está no final do arquivo.
</Callout>