# EvoPay API

> Infraestrutura Pix para alto volume. REST API para depósitos, saques e gestão financeira via Pix.
> Base URL: https://api.evopay.cash/v1
> Autenticação: Bearer token — Authorization: Bearer <token>
> Tokens: https://processamento.evopay.cash/settings/tokens

## Guia

- [Introdução](/guide/introduction): URL base, formato de resposta (JSON, ISO 8601, BRL), formato dos IDs (EP + 24 hex = 26 chars)
- [Autenticação](/guide/authentication): Bearer token, como obter, permissões DEPOSIT/WITHDRAW, boas práticas de segurança
- [Webhooks](/guide/webhook): Notificações HTTP POST via callbackUrl, política de entrega (5 tentativas, backoff exponencial), payload completo
- [Motivos de Cancelamento](/guide/cancellation-reasons): Todos os valores possíveis de cancellationReason (erros síncronos e assíncronos)
- [Schemas](/guide/schemas): Referência completa de enums e objetos: TransactionStatus, TransactionType, PixType, RefundStatus, RefundReason, InfractionStatus, InfractionType, AnalysisResult, ReportedType, Transaction, Infraction, AutoWithdraw, ServiceFee, DailyWithdrawLimit

## Endpoints

**Conta**
- GET /v1/user/ — Dados da conta: saldos, limites, AutoWithdraw, DailyWithdrawLimit
- GET /v1/user/balance — Saldo disponível (balanceAvailable) e bloqueado (balanceBlocked)
- GET /v1/user/transactions/ — Listar transações (page, limit, dateFrom, dateTo, status, type, amount, document, endToEndId, clientReference)
- GET /v1/user/transactions/{id} — Detalhe de transação com histórico de callbacks e infrações associadas

**Depósito (requer permissão DEPOSIT)**
- POST /v1/pix/ — Criar cobrança Pix: amount (obrigatório), callbackUrl, generatedName, generatedDocument, generatedEmail, expiresIn (máx. 172000s), clientReference
- GET /v1/pix/ — Consultar cobrança por id, clientReference ou endToEndId (ao menos um obrigatório)
- POST /v1/pix/qr-code/read — Decodificar QR Code Pix externo (campo qrCode obrigatório)
- GET /v1/proof/{id} — Comprovante em PDF ou base64 (não requer autenticação)

**Saque (requer permissão WITHDRAW)**
- POST /v1/withdraw/ — Criar saque: amount, pixKey, pixType (obrigatórios), callbackUrl, description, clientReference
- GET /v1/withdraw/ — Consultar saque por id, clientReference ou endToEndId
- POST /v1/withdraw/qrcode — Saque via QR Code: qrCode obrigatório, amount obrigatório se QR estático

**Callbacks**
- GET /v1/user/callbacks/ — Listar histórico de callbacks (paginado, filtros: url, status, transactionId, hasError, datas)
- GET /v1/user/callbacks/{id} — Detalhe de um callback
- POST /v1/user/callbacks/resend — Reenviar em lote (createdAtFrom/To obrigatórios, máx. 30 dias atrás, intervalo máx. 7 dias; rate limit: 5/60s)
- POST /v1/user/callbacks/resend/{transactionId} — Reenviar callback de uma transação específica (rate limit: 5/60s)

**Extratos**
- GET /v1/user/bank-statements/ — Listar extratos (createdAtFrom e createdAtTo obrigatórios)
- GET /v1/user/bank-statements/{id} — Detalhe de um extrato

**Infrações**
- GET /v1/user/infractions/ — Listar infrações (filtros: status[], type[], analysisResult[], reportedBy[], datas)
- GET /v1/user/infractions/{id} — Detalhe de uma infração
- POST /v1/user/infractions/{id}/defenses — Criar defesa (multipart/form-data: defense obrigatório, files opcional, máx. 10MB)
- GET /v1/user/infractions/{id}/defenses — Listar defesas de uma infração
- GET /v1/user/infractions/{infractionId}/defenses/{defenseId} — Detalhe de uma defesa

## Optional

- [Para IAs](/guide/for-ais): Como usar este arquivo com Cursor, Claude e GitHub Copilot
- [llms-full.txt](/llms-full.txt): Conteúdo completo do guia + OpenAPI YAML 3.1.0