# EvoPay API — Documentação Completa para IAs

Este arquivo contém toda a documentação do guia (em português) seguida da especificação OpenAPI 3.1.0 completa.
Gerado automaticamente. Versão em índice leve: /llms.txt

---

# Introdução

A EvoPay API é uma infraestrutura Pix para alto volume, projetada para processamento em massa. Atende gateways de pagamento, marketplaces e casas de apostas que precisam de depósitos e saques Pix com baixa latência e alta disponibilidade.

## Base URL

```
https://api.evopay.cash/v1
```

Todos os endpoints descritos nesta documentação são relativos a essa base. Exemplo:

```
POST https://api.evopay.cash/v1/pix/
```

## Formato das respostas

- Respostas em **JSON**
- Datas em **ISO 8601** (ex: `2024-01-01T12:00:00.000Z`)
- Valores monetários em **reais (BRL)**, representados como `number` com duas casas decimais (ex: `150.00`)

## Formato dos IDs de transação

Transações geradas pela API usam um ID próprio com o seguinte formato:

```
EPB1694C2C35E94053874D53B1
```

Estrutura: prefixo `EP` + 24 caracteres hexadecimais em maiúsculas = **26 caracteres no total**.

Use esse ID para consultar o status de uma transação, referenciar callbacks e correlacionar com os registros do seu sistema.

---

# Autenticação

## Header obrigatório

Todas as requisições autenticadas devem incluir o token no header:

```
Authorization: Bearer <token>
```

Requisições sem esse header ou com token inválido retornam `401 Unauthorized`.

## Como obter um token

Acesse **Tokens** na sidebar do painel, sob a seção **DESENVOLVEDOR**:

https://processamento.evopay.cash/settings/tokens

A criação de um novo token exige confirmação via **2FA (TOTP)**. Certifique-se de ter o autenticador configurado antes de gerar tokens para produção.

## Limite de tokens ativos

Cada conta suporta no máximo **5 tokens ativos simultâneos**. Um deles é reservado para uso web (painel), deixando **4 disponíveis para integração via API**.

## Token de primeiro acesso

Ao criar sua conta, você recebe um token inicial no formato **UUID** (ex: `550e8400-e29b-41d4-a716-446655440000`), enviado pelo seu gerente de contas. Esse token é desativado automaticamente após o primeiro login no painel — use-o apenas para autenticar pela primeira vez e gerar seus tokens de API.

## Permissões

Cada token é criado com um conjunto de permissões. Os endpoints desta documentação indicam qual permissão é necessária.

| Permissão | O que libera |
|---|---|
| `DEPOSIT` | Criar e consultar cobranças Pix |
| `WITHDRAW` | Criar e consultar saques Pix |

Um token pode ter uma ou ambas as permissões. Para operações de leitura da conta (`GET /v1/user/`, `GET /v1/user/balance`, etc.), qualquer token válido é suficiente — não há permissão específica exigida.

## Boas práticas

- Nunca exponha o token no frontend — guarde-o exclusivamente no backend
- Não use em variáveis de ambiente prefixadas com `NEXT_PUBLIC_` ou equivalentes de outros frameworks
- Rotacione os tokens a cada **90 dias**
- Em caso de suspeita de vazamento, revogue imediatamente pelo painel e gere um novo

## Exemplos de uso

### cURL

```bash
curl -X POST https://api.evopay.cash/v1/pix/ \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100.00, "clientReference": "pedido-123"}'
```

### Node.js (Axios)

```js
import axios from 'axios';

const client = axios.create({
  baseURL: 'https://api.evopay.cash/v1',
  headers: {
    Authorization: `Bearer ${process.env.EVOPAY_TOKEN}`,
  },
});

const { data } = await client.post('/pix/', {
  amount: 100.00,
  clientReference: 'pedido-123',
});

console.log(data.id); // EPB1694C2C35E94053874D53B1
```

---

# Webhooks

A EvoPay envia uma notificação HTTP POST para a `callbackUrl` informada na criação da transação sempre que o status é atualizado.

## Configuração

A `callbackUrl` é opcional e informada nos endpoints de criação:

- `POST /v1/pix/` — campo `callbackUrl`
- `POST /v1/withdraw/` — campo `callbackUrl`
- `POST /v1/withdraw/qrcode` — campo `callbackUrl`

Seu servidor deve responder com qualquer status HTTP `2xx` para confirmar o recebimento.

## Política de entrega

| Parâmetro | Valor |
|---|---|
| Tentativas máximas | 5 |
| Backoff | Exponencial, base 2 minutos + 50% de jitter |
| Timeout por tentativa | 10 segundos |

Após 5 falhas consecutivas o reenvio para. Use POST /v1/user/callbacks/resend (Reenvio de callbacks em lote) ou POST /v1/user/callbacks/resend/{transactionId} (Reenvio de callback por transação) para reenviar manualmente.

## Headers enviados

```
Content-Type: application/json
User-Agent: Callback-Service/1.0
X-Callback-Attempt: <n>
```

`X-Callback-Attempt` começa em `0` na primeira tentativa e vai até `4` na quinta.

## Payload

DEPOSIT e WITHDRAW recebem o mesmo schema. Os campos `null` variam conforme o status e o tipo da transação.

```json
{
  "id": "EPB1694C2C35E94053874D53B1",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "amount": 100.00,
  "serviceFeeCharged": 2.50,
  "clientReference": "pedido-123",
  "qrCodeText": "00020101...",
  "qrCodeUrl": "https://...",
  "qrCodeBase64": "iVBORw0KGgo...",
  "generatedName": "João Silva",
  "generatedDocument": "12345678901",
  "generatedEmail": "joao@email.com",
  "payerName": "João Silva",
  "payerDocument": "12345678901",
  "payerInstitutionIspb": "60746948",
  "payerInstitutionName": "Itaú",
  "receiverName": null,
  "receiverDocument": null,
  "receiverInstitutionIspb": null,
  "receiverInstitutionName": null,
  "withdrawPixKey": null,
  "withdrawPixType": null,
  "withdrawQrCodeText": null,
  "endToEndId": "E60746948...",
  "cancellationReason": null,
  "paidAt": "2024-01-01T12:05:00.000Z",
  "refundEndToEndId": null,
  "refundAmount": null,
  "refundStatus": null,
  "refundReason": null,
  "refundDescription": null,
  "refundedAt": null,
  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-01T12:05:00.000Z"
}
```

### Campos principais

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | ID da transação |
| `type` | TransactionType | DEPOSIT ou WITHDRAW |
| `status` | TransactionStatus | Status atual |
| `amount` | number | Valor em reais |
| `serviceFeeCharged` | number ou null | Taxa cobrada |
| `clientReference` | string ou null | Referência externa enviada na criação |
| `cancellationReason` | string ou null | Motivo do cancelamento |
| `endToEndId` | string ou null | ID fim a fim Pix |
| `paidAt` | string ou null | Timestamp do pagamento (ISO 8601) |

### Campos típicos por tipo

| Campo | DEPOSIT | WITHDRAW |
|---|---|---|
| `qrCodeText / qrCodeUrl / qrCodeBase64` | Preenchido | null |
| `generatedName / generatedDocument / generatedEmail` | Preenchido se informado na criação | null |
| `payerName / payerDocument / payerInstitutionIspb / payerInstitutionName` | Fornecido pelo provedor | Fornecido pelo provedor |
| `receiverName / receiverDocument / receiverInstitutionIspb / receiverInstitutionName` | null | Preenchido após liquidação |
| `withdrawPixKey / withdrawPixType` | null | Preenchido (saque via chave) |
| `withdrawQrCodeText` | null | Preenchido (saque via QR Code) |

### Campos de estorno (quando status é WAITING_FOR_REFUND ou REFUNDED)

| Campo | Tipo | Descrição |
|---|---|---|
| `refundStatus` | RefundStatus ou null | Status do estorno |
| `refundReason` | RefundReason ou null | Motivo do estorno |
| `refundAmount` | number ou null | Valor estornado |
| `refundEndToEndId` | string ou null | ID fim a fim do estorno |
| `refundDescription` | string ou null | Descrição livre |
| `refundedAt` | string ou null | Timestamp do estorno (ISO 8601) |

### Campo infraction (opcional)

Presente apenas quando o webhook é disparado por uma atualização de infração Pix. Campos: id, protocol, status (InfractionStatus), type (InfractionType), reportDetails, reportedBy (ReportedType), analysisResult (AnalysisResult ou null), analysisDetails, reportedAt, expiresAt, createdAt, updatedAt.

---

# Motivos de Cancelamento (cancellationReason)

Lista de todas as mensagens possíveis no campo `cancellationReason` de uma transação.

## Formato de resposta da API

Erros chegam em dois formatos:

### Erro síncrono (HTTP direto)
```json
{ "statusCode": 422, "message": "Saldo insuficiente para realizar a transação", "error": "Unprocessable Entity" }
```

### Erro assíncrono (transação cancelada)
```json
{ "id": "txn_abc123", "status": "CANCELED", "cancellationReason": "Chave Pix informada inválida" }
```

## Mensagens de cancelamento

| Mensagem (cancellationReason) |
|---|
| A ordem foi rejeitada pelo banco (por razões que dizem respeito ao conteúdo) |
| Bloqueio de depósitos para CNPJ |
| Chave Pix informada inválida |
| Chave Pix informada não corresponde ao documento do destinatário |
| Chave Pix informada não encontrada |
| Chave Pix inválida |
| Chave Pix não corresponde ao documento do destinatario |
| Chave Pix não encontrada |
| Conta do beneficiário está fechada |
| Conta especificada está bloqueada |
| Erro ao gerar QRCode na instituição financeira |
| Erro no processamento com a instituição financeira. Tente novamente. |
| Existe uma transação pendente identica. Por favor tente novamente mais tarde. |
| Instituição: Tipo de transação não suportado/autorizado nesta conta |
| Não é possível enviar PIX para conta salário |
| O JDPI após alguns minutos de espera não obteve retorno sobre o envio da transação ao SPI. A transação foi rejeitada automaticamente. |
| Pagamento expirado por timeout |
| Pagamento rejeitado pelo PSP do recebedor |
| Participante não está autorizado a receber Pix |
| Participante recebedor encerrado no SPI |
| Pix QR Code não encontrado |
| QrCode não encontrado |
| Saldo insuficiente para realizar a transação |
| Saque cancelado |
| Tipo de QR Code (estático) inválido para este endpoint. |
| Transação cancelada por timeout |
| Transação interrompida devido a erro no agente do beneficiário |
| Transação interrompida devido a timeout no agente do pagador |
| TxId não encontrado |
| Valor da transação é maior que o máximo permitido |

---

# Schemas

Referência completa de todos os tipos e objetos usados na API EvoPay.

## Enums

### TransactionStatus
PENDING — aguardando processamento ou pagamento
COMPLETED — concluída com sucesso
CANCELED — cancelada (ver cancellationReason)
WAITING_FOR_REFUND — aguardando estorno
REFUNDED — estornada com sucesso
EXPIRED — cobrança Pix expirou sem pagamento
ERROR — erro interno

### TransactionType
DEPOSIT — entrada via cobrança Pix (cash-in)
WITHDRAW — saída para chave Pix (cash-out)
COMMISSION — comissão interna da plataforma

### PixType
cpf — CPF (11 dígitos)
cnpj — CNPJ (14 dígitos)
email — endereço de e-mail
phone — telefone com DDD e código do país (ex: +5511999999999)
evp — chave aleatória (EVP)

### RefundStatus
PENDING — estorno solicitado
COMPLETED — estorno concluído
CANCELED — estorno cancelado

### RefundReason
CUSTOMER_REQUEST — solicitação do cliente
DENY_COMPANY_DEPOSIT — depósito recusado pela empresa
INFRACTION — infração Pix identificada pelo Banco Central

### InfractionStatus
WAITING_PSP — aguardando PSP participante
OPEN — infração em análise
ACKNOWLEDGED — participante concordou com estorno
DEFENDED — defesa apresentada
ANSWERED — infração respondida
WAITING_ADJUSTMENTS — aguardando ajustes
CLOSED — infração encerrada
CANCELLED — infração cancelada

### InfractionType
FRAUD — fraude detectada
REFUND_REQUEST — solicitação de devolução
REFUND_CANCELLED — cancelamento de solicitação de devolução

### AnalysisResult
AGREED — participante concordou com estorno
DISAGREED — participante contestou a infração

### ReportedType
DEBITED_PARTICIPANT — participante debitado (enviou o Pix) reportou
CREDITED_PARTICIPANT — participante creditado (recebeu o Pix) reportou

## Objetos

### Transaction
id: string — ID da transação (EP + 24 hex)
type: TransactionType
status: TransactionStatus
amount: number — valor em BRL
serviceFeeCharged: number | null
clientReference: string | null
qrCodeText: string | null — payload Pix Copia e Cola (DEPOSIT)
qrCodeUrl: string | null — URL do QR Code (DEPOSIT)
qrCodeBase64: string | null — QR Code em base64 (DEPOSIT)
generatedName: string | null — nome do pagador esperado (DEPOSIT)
generatedDocument: string | null — CPF/CNPJ esperado (DEPOSIT)
generatedEmail: string | null — e-mail esperado (DEPOSIT)
payerName: string | null — nome do pagador real (DEPOSIT, pós-pagamento)
payerDocument: string | null — CPF/CNPJ do pagador real (DEPOSIT, pós-pagamento)
payerInstitutionIspb: string | null
payerInstitutionName: string | null
receiverName: string | null — nome do recebedor (WITHDRAW, pós-liquidação)
receiverDocument: string | null — CPF/CNPJ do recebedor (WITHDRAW, pós-liquidação)
receiverInstitutionIspb: string | null
receiverInstitutionName: string | null
withdrawPixKey: string | null — chave Pix de destino (WITHDRAW via chave)
withdrawPixType: PixType | null — tipo da chave (WITHDRAW via chave)
withdrawQrCodeText: string | null — QR Code EMV de destino (WITHDRAW via QR Code)
endToEndId: string | null — E2EID Pix
cancellationReason: string | null
paidAt: string | null — ISO 8601
refundEndToEndId: string | null
refundAmount: number | null
refundStatus: RefundStatus | null
refundReason: RefundReason | null
refundDescription: string | null
refundedAt: string | null — ISO 8601
createdAt: string — ISO 8601
updatedAt: string — ISO 8601

### Infraction
id: string
protocol: string — protocolo do Banco Central
status: InfractionStatus
type: InfractionType
reportedBy: ReportedType
reportDetails: string
analysisResult: AnalysisResult | null
analysisDetails: string | null
reportedAt: string — ISO 8601
expiresAt: string | null — ISO 8601
createdAt: string — ISO 8601
updatedAt: string — ISO 8601
transaction: object — dados resumidos da transação vinculada
defenseHistory: array — histórico de defesas apresentadas

### AutoWithdraw (dentro de GET /v1/user/)
amount: number — saldo mínimo para disparar saque automático
pixKey: string
pixType: PixType
active: boolean

### DailyWithdrawLimit (dentro de GET /v1/user/)
limit: number — limite diário em BRL
used: number — valor já sacado hoje
updatedAt: string — ISO 8601
lastReset: string | null — ISO 8601

---

# OpenAPI 3.1.0 — Especificação Completa

openapi: 3.1.0

info:
  title: EvoPay Processamento
  description: >-
    Infraestrutura Pix para alto volume, projetada para processamento em massa.
    Atende gateways de pagamento, marketplaces e casas de apostas que precisam de
    depósitos e saques Pix com baixa latência e alta disponibilidade.
  version: "1.0"

tags:
  - name: Conta
  - name: Depósito
  - name: Saque
  - name: Callbacks
  - name: Extratos
  - name: Infrações

servers:
  - url: https://api.evopay.cash/v1
    description: Produção

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Token de API obtido em https://processamento.evopay.cash/settings/tokens.
        Cada token carrega permissões DEPOSIT e/ou WITHDRAW.

  schemas:
    TransactionStatus:
      type: string
      enum: [PENDING, COMPLETED, CANCELED, WAITING_FOR_REFUND, REFUNDED, EXPIRED, ERROR]

    TransactionType:
      type: string
      enum: [DEPOSIT, WITHDRAW, COMMISSION]

    PixType:
      type: string
      enum: [cpf, cnpj, email, phone, evp]

    RefundStatus:
      type: string
      enum: [PENDING, COMPLETED, CANCELED]

    RefundReason:
      type: string
      enum: [CUSTOMER_REQUEST, DENY_COMPANY_DEPOSIT, INFRACTION]

    InfractionStatus:
      type: string
      enum: [WAITING_PSP, CLOSED, OPEN, CANCELLED, ACKNOWLEDGED, DEFENDED, ANSWERED, WAITING_ADJUSTMENTS]

    InfractionType:
      type: string
      enum: [REFUND_REQUEST, FRAUD, REFUND_CANCELLED]

    AnalysisResult:
      type: string
      enum: [AGREED, DISAGREED]

    ReportedType:
      type: string
      enum: [DEBITED_PARTICIPANT, CREDITED_PARTICIPANT]

    Error:
      type: object
      properties:
        statusCode: { type: integer }
        error: { type: string }
        message: { type: string }

    Transaction:
      type: object
      properties:
        id: { type: string, example: EPB1694C2C35E94053874D53B1 }
        type: { $ref: "#/components/schemas/TransactionType" }
        status: { $ref: "#/components/schemas/TransactionStatus" }
        amount: { type: number }
        serviceFeeCharged: { type: [number, "null"] }
        clientReference: { type: [string, "null"] }
        qrCodeText: { type: [string, "null"] }
        qrCodeUrl: { type: [string, "null"] }
        qrCodeBase64: { type: [string, "null"] }
        generatedName: { type: [string, "null"] }
        generatedDocument: { type: [string, "null"] }
        generatedEmail: { type: [string, "null"] }
        payerName: { type: [string, "null"] }
        payerDocument: { type: [string, "null"] }
        payerInstitutionIspb: { type: [string, "null"] }
        payerInstitutionName: { type: [string, "null"] }
        receiverName: { type: [string, "null"] }
        receiverDocument: { type: [string, "null"] }
        receiverInstitutionIspb: { type: [string, "null"] }
        receiverInstitutionName: { type: [string, "null"] }
        withdrawPixKey: { type: [string, "null"] }
        withdrawPixType:
          oneOf:
            - $ref: "#/components/schemas/PixType"
            - type: "null"
        withdrawQrCodeText: { type: [string, "null"] }
        endToEndId: { type: [string, "null"] }
        cancellationReason: { type: [string, "null"] }
        paidAt: { type: [string, "null"], format: date-time }
        refundEndToEndId: { type: [string, "null"] }
        refundAmount: { type: [number, "null"] }
        refundStatus:
          oneOf:
            - $ref: "#/components/schemas/RefundStatus"
            - type: "null"
        refundReason:
          oneOf:
            - $ref: "#/components/schemas/RefundReason"
            - type: "null"
        refundDescription: { type: [string, "null"] }
        refundedAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    Infraction:
      type: object
      properties:
        id: { type: string }
        protocol: { type: string }
        status: { $ref: "#/components/schemas/InfractionStatus" }
        type: { $ref: "#/components/schemas/InfractionType" }
        reportedBy: { $ref: "#/components/schemas/ReportedType" }
        reportDetails: { type: string }
        analysisResult:
          oneOf:
            - $ref: "#/components/schemas/AnalysisResult"
            - type: "null"
        analysisDetails: { type: [string, "null"] }
        reportedAt: { type: string, format: date-time }
        expiresAt: { type: [string, "null"], format: date-time }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        transaction:
          type: object
          properties:
            id: { type: string }
            amount: { type: number }
            payerName: { type: [string, "null"] }
            payerDocument: { type: [string, "null"] }
            receiverName: { type: [string, "null"] }
            receiverDocument: { type: [string, "null"] }
            endToEndId: { type: [string, "null"] }
        defenseHistory:
          type: array
          items:
            $ref: "#/components/schemas/InfractionDefense"

    InfractionDefense:
      type: object
      properties:
        id: { type: string }
        defense: { type: string }
        status: { type: string, enum: [PENDING, DEFENDED] }
        infractionId: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        files:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              mimeType: { type: string }
              size: { type: integer }
              url: { type: string }

    CallbackLog:
      type: object
      properties:
        id: { type: string }
        url: { type: string }
        status: { type: integer }
        transactionId: { type: [string, "null"] }
        body: { type: object }
        responseBody: { type: string }
        responseHeaders: { type: object }
        responseTime: { type: integer }
        createdAt: { type: string, format: date-time }

    BankStatement:
      type: object
      properties:
        id: { type: string }
        amount: { type: number }
        operation: { type: string, enum: [INCREMENT, DECREMENT] }
        balanceType: { type: string, enum: [AVAILABLE, BLOCKED] }
        reason: { type: string }
        previousBalanceAvailable: { type: number }
        previousBalanceBlocked: { type: number }
        newBalanceAvailable: { type: number }
        newBalanceBlocked: { type: number }
        transactionId: { type: [string, "null"] }
        infractionId: { type: [string, "null"] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

paths:

  /user/:
    get:
      summary: Dados da conta
      tags: [Conta]
      description: Retorna dados completos da conta: saldos, limites, AutoWithdraw, DailyWithdrawLimit.
      responses:
        "200":
          description: Dados da conta
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }
                  balanceAvailable: { type: number }
                  balanceBlocked: { type: number }
                  status: { type: string, enum: [ACTIVE, BLOCKED, DELETED] }
                  allowWithdraw: { type: boolean }
                  allowDeposit: { type: boolean }
                  allowInfraction: { type: boolean }
                  cashInTicketMin: { type: number }
                  cashInTicketMax: { type: number }
                  cashOutTicketMin: { type: number }
                  cashOutTicketMax: { type: number }
                  createdAt: { type: string, format: date-time }
                  updatedAt: { type: string, format: date-time }
                  AutoWithdraw:
                    type: [object, "null"]
                    properties:
                      amount: { type: number }
                      pixKey: { type: string }
                      pixType: { $ref: "#/components/schemas/PixType" }
                      active: { type: boolean }
                  DailyWithdrawLimit:
                    type: [object, "null"]
                    properties:
                      limit: { type: number }
                      used: { type: number }
                      updatedAt: { type: string, format: date-time }
                      lastReset: { type: [string, "null"], format: date-time }
        "401":
          description: Token ausente ou inválido

  /user/balance:
    get:
      summary: Saldo da conta
      tags: [Conta]
      description: Retorna balanceAvailable (disponível para saque/cobranças) e balanceBlocked (em processamento ou disputa).
      responses:
        "200":
          description: Saldos da conta
          content:
            application/json:
              schema:
                type: object
                properties:
                  balanceAvailable: { type: number }
                  balanceBlocked: { type: number }
        "401":
          description: Token ausente ou inválido

  /user/transactions/:
    get:
      summary: Listar transações
      tags: [Conta]
      description: Lista transações com paginação. Filtros opcionais: page, limit, dateFrom, dateTo, id, status (vírgula-separado), type (DEPOSIT/WITHDRAW), amount, document, name, endToEndId, clientReference.
      parameters:
        - { name: page, in: query, schema: { type: integer, default: 1 } }
        - { name: limit, in: query, schema: { type: integer, maximum: 1000, default: 10 } }
        - { name: dateFrom, in: query, schema: { type: string, format: date-time } }
        - { name: dateTo, in: query, schema: { type: string, format: date-time } }
        - { name: id, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string } }
        - { name: type, in: query, schema: { type: string } }
        - { name: amount, in: query, schema: { type: number } }
        - { name: document, in: query, schema: { type: string } }
        - { name: name, in: query, schema: { type: string } }
        - { name: endToEndId, in: query, schema: { type: string } }
        - { name: clientReference, in: query, schema: { type: string } }
      responses:
        "200":
          description: Lista paginada
          content:
            application/json:
              schema:
                type: object
                properties:
                  total: { type: integer }
                  pages: { type: integer }
                  transactions:
                    type: array
                    items: { $ref: "#/components/schemas/Transaction" }

  /user/transactions/{id}:
    get:
      summary: Detalhe de uma transação
      tags: [Conta]
      description: Retorna detalhe completo incluindo CallbackLog (histórico de webhooks) e Infraction (infrações associadas).
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Detalhe da transação (Transaction + CallbackLog[] + Infraction[])
        "404":
          description: Transação não encontrada

  /pix/:
    post:
      summary: Criar cobrança Pix
      tags: [Depósito]
      description: |
        Requer permissão DEPOSIT. Cria cobrança Pix (cash-in). Retorna QR Code.
        Campos obrigatórios: amount.
        Campos opcionais: callbackUrl, generatedName, generatedDocument, generatedEmail, expiresIn (máx. 172000s), clientReference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount: { type: number }
                callbackUrl: { type: string, format: uri }
                generatedName: { type: string }
                generatedDocument: { type: string }
                generatedEmail: { type: string }
                expiresIn: { type: integer, maximum: 172000 }
                clientReference: { type: string }
      responses:
        "200":
          description: Cobrança criada
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transaction" }
        "400": { description: Campo inválido }
        "401": { description: Token inválido }
        "403": { description: Sem permissão DEPOSIT ou depósito bloqueado }

    get:
      summary: Consultar cobrança Pix
      tags: [Depósito]
      description: Requer permissão DEPOSIT. Ao menos um de id, clientReference ou endToEndId deve ser informado.
      parameters:
        - { name: id, in: query, schema: { type: string } }
        - { name: clientReference, in: query, schema: { type: string } }
        - { name: endToEndId, in: query, schema: { type: string } }
      responses:
        "200":
          description: Dados da transação
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transaction" }

  /pix/qr-code/read:
    post:
      summary: Ler QR Code Pix
      tags: [Depósito]
      description: Decodifica QR Code Pix externo. Retorna qrCodeType (DYNAMIC/STATIC), amount, name, document, additionalInfo, expiresIn, txid, createdAt.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [qrCode]
              properties:
                qrCode: { type: string, minLength: 20 }
      responses:
        "200": { description: QR Code decodificado }
        "400": { description: QR Code inválido ou expirado }

  /proof/{id}:
    get:
      summary: Comprovante de transação
      tags: [Depósito]
      description: Não requer autenticação. Retorna PDF (padrão) ou base64 (type=base64).
      security: []
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        - { name: type, in: query, schema: { type: string, enum: [pdf, base64], default: pdf } }
      responses:
        "200": { description: Comprovante gerado }
        "404": { description: Transação não encontrada }

  /withdraw/:
    post:
      summary: Criar saque
      tags: [Saque]
      description: |
        Requer permissão WITHDRAW.
        Campos obrigatórios: amount, pixKey, pixType.
        Campos opcionais: callbackUrl, description, clientReference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount, pixKey, pixType]
              properties:
                amount: { type: number }
                pixKey: { type: string }
                pixType: { $ref: "#/components/schemas/PixType" }
                callbackUrl: { type: string, format: uri }
                description: { type: string }
                clientReference: { type: string }
      responses:
        "200":
          description: Saque criado
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transaction" }
        "401": { description: Token inválido }
        "403": { description: Sem permissão WITHDRAW ou IP não autorizado }
        "422": { description: Saldo insuficiente, conta sem permissão ou limite diário excedido }

    get:
      summary: Consultar saque
      tags: [Saque]
      description: Requer permissão WITHDRAW. Ao menos um de id, clientReference ou endToEndId deve ser informado.
      parameters:
        - { name: id, in: query, schema: { type: string } }
        - { name: clientReference, in: query, schema: { type: string } }
        - { name: endToEndId, in: query, schema: { type: string } }
      responses:
        "200":
          description: Dados do saque
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transaction" }

  /withdraw/qrcode:
    post:
      summary: Saque via QR Code
      tags: [Saque]
      description: |
        Requer permissão WITHDRAW.
        QR dinâmico (com valor): amount ignorado.
        QR estático (sem valor): amount obrigatório.
        Campos: qrCode (obrigatório), amount, callbackUrl, description, clientReference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [qrCode]
              properties:
                qrCode: { type: string }
                amount: { type: number }
                callbackUrl: { type: string, format: uri }
                description: { type: string }
                clientReference: { type: string }
      responses:
        "200":
          description: Saque criado
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Transaction" }

  /user/callbacks/:
    get:
      summary: Listar callbacks
      tags: [Callbacks]
      description: Lista histórico de webhooks. Filtros: page, limit, sortBy (createdAt/status), sortDirection, id, url, status (HTTP), transactionId, transactionType, transactionStatus, transactionEndToEndId, hasError, createdAtFrom, createdAtTo.
      responses:
        "200":
          description: Lista paginada (pagination + callbacks[])

  /user/callbacks/{id}:
    get:
      summary: Detalhe de um callback
      tags: [Callbacks]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Detalhe do callback
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CallbackLog" }

  /user/callbacks/resend:
    post:
      summary: Reenviar callbacks em lote
      tags: [Callbacks]
      description: |
        Rate limit: 5 reenvios em 60 segundos.
        Campos obrigatórios: createdAtFrom, createdAtTo (máx. 30 dias atrás, intervalo máx. 7 dias).
        Campos opcionais: transactionIds[], transactionTypes[], transactionStatus[], transactionEndToEndIds[].
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [createdAtFrom, createdAtTo]
              properties:
                createdAtFrom: { type: string, format: date-time }
                createdAtTo: { type: string, format: date-time }
                transactionIds: { type: array, items: { type: string } }
                transactionTypes: { type: array, items: { type: string, enum: [DEPOSIT, WITHDRAW] } }
                transactionStatus: { type: array, items: { type: string } }
                transactionEndToEndIds: { type: array, items: { type: string } }
      responses:
        "200": { description: "{ message, total }" }
        "429": { description: Rate limit excedido }

  /user/callbacks/resend/{transactionId}:
    post:
      summary: Reenviar callback de uma transação
      tags: [Callbacks]
      description: Rate limit: 5 reenvios em 60 segundos.
      parameters:
        - { name: transactionId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { description: "{ message }" }
        "404": { description: Transação inexistente, não pertence à conta ou sem callbackUrl }
        "429": { description: Rate limit excedido }

  /user/bank-statements/:
    get:
      summary: Listar extratos bancários
      tags: [Extratos]
      description: |
        createdAtFrom e createdAtTo são obrigatórios.
        Filtros opcionais: page, limit, sortBy (createdAt/amount), sortDirection, id, operation (INCREMENT/DECREMENT), reason, transactionId, amountFrom, amountTo.
      responses:
        "200":
          description: Lista paginada (pagination + bankStatements[])

  /user/bank-statements/{id}:
    get:
      summary: Detalhe de um extrato
      tags: [Extratos]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Detalhe do extrato
          content:
            application/json:
              schema: { $ref: "#/components/schemas/BankStatement" }

  /user/infractions/:
    get:
      summary: Listar infrações
      tags: [Infrações]
      description: |
        Filtros: page, limit, sortBy, sortDirection, id, protocol, endToEndId, transactionId,
        amountMin, amountMax, status[] (InfractionStatus), type[] (InfractionType),
        analysisResult[] (AnalysisResult), reportedBy[] (ReportedType),
        participantDocument, participantName, reportDetails, analysisDetails,
        reportedAtFrom, reportedAtTo, createdAtFrom, createdAtTo,
        expiresAtFrom, expiresAtTo, updatedAtFrom, updatedAtTo.
      responses:
        "200":
          description: Lista paginada (infractions[] + pagination com totalItems/totalPages)

  /user/infractions/{id}:
    get:
      summary: Detalhe de uma infração
      tags: [Infrações]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Detalhe da infração
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Infraction" }

  /user/infractions/{id}/defenses:
    post:
      summary: Criar defesa para uma infração
      tags: [Infrações]
      description: |
        A infração deve estar com status OPEN.
        Extensões bloqueadas: .exe, .msi, .bat, .sh, .cmd.
        Tamanho máximo total: 10MB.
        Campos: defense (string, obrigatório, máx. 1000 chars), files (array de binários, opcional).
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [defense]
              properties:
                defense: { type: string, maxLength: 1000 }
                files: { type: array, items: { type: string, format: binary } }
      responses:
        "201":
          description: Defesa criada
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InfractionDefense" }
        "413": { description: Anexos excedem 10MB }
        "422": { description: Não é possível defender esta infração }

    get:
      summary: Listar defesas de uma infração
      tags: [Infrações]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Lista de defesas
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/InfractionDefense" }

  /user/infractions/{infractionId}/defenses/{defenseId}:
    get:
      summary: Detalhe de uma defesa
      tags: [Infrações]
      parameters:
        - { name: infractionId, in: path, required: true, schema: { type: string } }
        - { name: defenseId, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Detalhe da defesa
          content:
            application/json:
              schema: { $ref: "#/components/schemas/InfractionDefense" }
        "404": { description: Defesa não encontrada }