> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Arquitetura

> Visão lógica da integração ClearPago: componentes, fluxos e responsabilidades de cada parte.

## Visão geral

A integração ClearPago envolve três camadas principais: o **seu sistema**, a **plataforma ClearPago** e o **parceiro BaaS**. Cada camada tem responsabilidades bem definidas.

```mermaid theme={null}
flowchart TB
  subgraph cliente[Seu sistema]
    CLI[Cliente HTTP REST]
    WH_RCV[Endpoint de webhook\nPOST /webhooks/pix]
    DB_CLI[(Banco de dados\ndo integrador)]
  end

  subgraph clearpago[Plataforma ClearPago]
    REST[API REST\n/api/pix/*]
    WH_IN[Webhooks de entrada\nPOST /api/webhooks/pix/*]
    Q[Fila de eventos\nSQS]
    W[Workers de processamento\ne reconciliação]
    DB_OTP[(PostgreSQL\nledger + transações)]
    OUT[Outbox de notificações]
    RECON[Worker de reconciliação]
  end

  subgraph baas[Parceiro BaaS]
    PIX[Pix / Liquidação]
  end

  CLI -->|POST /api/pix/cash-in\nPOST /api/pix/cash-out\netc.| REST
  REST -->|Criação / consulta| DB_OTP
  REST -->|Despacho Pix| PIX
  PIX -->|CashIn, CashOut\nCashInReversal, CashOutReversal| WH_IN
  WH_IN --> Q
  Q --> W
  W --> DB_OTP
  W --> OUT
  OUT -->|Digital-Signature ECDSA| WH_RCV
  RECON -->|Consulta periódica| PIX
  RECON --> DB_OTP
  CLI -->|GET /api/pix/cash-in/{id}| REST
  DB_OTP -.-> WH_RCV
```

## Responsabilidades por camada

### Seu sistema

| Componente              | Responsabilidade                                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| **Cliente HTTP**        | Chama `POST` e `GET` na API REST. Inclui `Authorization`, `Content-Type` e `X-Correlation-ID`. |
| **Endpoint de webhook** | Recebe `POST` com `Digital-Signature`, valida a assinatura e responde `2xx` rapidamente.       |
| **Banco de dados**      | Persiste `id`, `externalId`, `transactionId`, `endToEndId` e status de cada recurso.           |

### Plataforma ClearPago

| Componente              | Responsabilidade                                                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **API REST**            | Valida, cria e persiste recursos Pix. Faz despacho inicial ao BaaS em operações de cash-out.                                    |
| **Webhooks de entrada** | Recebe eventos `CashIn`, `CashOut`, `CashInReversal`, `CashOutReversal` do parceiro. **Não são implementados pelo integrador.** |
| **Fila de eventos**     | Desacopla recebimento de eventos do processamento. Garante durabilidade.                                                        |
| **Workers**             | Aplicam transições de status, gravam ledger e enfileiram notificações ao comerciante.                                           |
| **Outbox**              | Garante entrega durável de notificações ao comerciante com retry e backoff.                                                     |
| **Reconciliação**       | Consulta o BaaS periodicamente em estados intermediários ou ambíguos (`PROVIDER_RESULT_UNKNOWN`, `RECONCILIATION_REQUIRED`).    |

### Parceiro BaaS

| Componente           | Responsabilidade                                                          |
| -------------------- | ------------------------------------------------------------------------- |
| **Pix / Liquidação** | Processa pagamentos Pix, confirma ou rejeita, emite eventos de resultado. |

## Fluxo de um cash-in

1. Seu sistema chama `POST /api/pix/cash-in` → plataforma retorna `201` com `id`, `status: PENDING` e `pixCode`.
2. O pagador escaneia o QR e liquida no BaaS.
3. O BaaS notifica a plataforma via `POST /api/webhooks/pix/cash-in` (interno).
4. Worker transiciona o status para `PAID`, grava lançamento no ledger, enfileira notificação ao comerciante.
5. Outbox entrega `POST` com `event_type: pix_cash_in` e `Digital-Signature` ao seu endpoint.
6. Você valida a assinatura e executa a lógica de negócio (ex.: liberar pedido).

## Fluxo de um cash-out

1. `POST /api/pix/cash-out` → reserva criada, estado inicial.
2. Plataforma despacha para o BaaS; resultado pode ser **imediato** ou **assíncrono**.
3. Resposta ambígua (timeout, 5xx) → estado `PROVIDER_RESULT_UNKNOWN` → reconciliação resolve.
4. BaaS confirma → `CONFIRMED`; BaaS falha → `FAILED` e reserva liberada.
5. Comerciante recebe `pix_cash_out` com resultado final.

## Modelo de entrega de notificações

| Tipo de operação   | Canal de notificação                      | Latência esperada                   |
| ------------------ | ----------------------------------------- | ----------------------------------- |
| Cash-in, refund-in | **Outbox** (durável, commit-first)        | Baixa a moderada                    |
| Cash-out, reversão | **Pool de goroutines** + **fallback SQS** | Geralmente baixa; SQS em alta carga |

<Warning>
  Não conte com **ordem garantida** entre eventos de canais diferentes. Deduplicação e ordenação por identificadores de negócio são sua responsabilidade.
</Warning>

## Implicações para o integrador

* **Não trate o `POST` de criação como terminal.** O status retornado é o estado no momento do commit; o estado final chega via webhook ou consulta.
* **Implemente idempotência.** Webhooks podem reentrar; seu handler deve ser seguro para execução múltipla.
* **Persista `id` cedo.** Antes de qualquer lógica de negócio, grave o UUID retornado.
* **Monitore estados ambíguos.** `PROVIDER_RESULT_UNKNOWN` e `RECONCILIATION_REQUIRED` não são terminais — monitore a idade e consulte via `GET` antes de escalar.

## Referências

* [Ciclo de vida das operações](/core-concepts/transaction-lifecycle)
* [Modelo de status](/core-concepts/status-model)
* [Ledger e saldo](/core-concepts/ledger-and-balance)
* [Webhooks: ClearPago → comerciante](/webhooks/clearpago-to-merchant)