> ## 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.

# Visão geral

> Papel da clearpago, modelo assíncrono e o porquê de IDs, webhooks e reconciliação.

## Papel da plataforma

A **clearpago** atua como camada entre o **seu sistema** e o **parceiro bancário (BaaS)**. Você consome somente a **API REST** e as **notificações HTTP** assinadas; diferenças de instituição, transporte e mapeamento de eventos permanecem encapsuladas.

Este portal é a documentação **ClearPago** dessa integração: contrato técnico, fluxos e boas práticas para o time de integração.

## Modelo assíncrono (padrão)

* **Criação rápida:** `POST` de cash-in, cash-out e refund costuma retornar com estado ainda em evolução (`PENDING`, reserva, etc.).
* **Conclusão fora do request/response primário:** a liquidação e falhas finais chegam via **webhook do parceiro** processado internamente e/ou **reconciliação** quando a rede ou o parceiro responde de forma **ambígua** (timeout, 5xx, atraso).
* **Não** trate o corpo de resposta de criação como estado terminal salvo o que o documento de status explicitar para o seu caso.

## Por que `id`, webhooks e reconciliação importam

| Tema                        | Motivo prático                                                                                                                                      |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`id` (UUID)**             | Chave primária do recurso na plataforma: consultas, `POST /api/pix/refund-in/{id}` com **UUID do cash-in**, auditoria.                              |
| **`externalId`**            | Sua chave de negócio: idempotência e correlação com ERP; deve ser **única** onde a API exigir.                                                      |
| **Webhooks ao comerciante** | Sinal principal de término relevante (ex.: `PAID`, `CONFIRMED`, `FAILED`, `REVERSED`) de forma assinada.                                            |
| **Reconciliação**           | Destrava estados como `PROVIDER_RESULT_UNKNOWN` e `RECONCILIATION_REQUIRED` com consulta autoritativa no BaaS, deduplicando com webhooks atrasados. |

## Componentes que afetam sua integração

| Componente                          | Função                                                                                                                |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| API `/api/pix/*`                    | Criar e consultar cash-in, cash-out, refund-in, ledger.                                                               |
| Webhooks `POST /api/webhooks/pix/*` | Entrada de eventos do parceiro (não implementados no seu sistema). Resposta **200** rápida; processamento assíncrono. |
| Workers de reconciliação            | Consultam status no parceiro em estados intermediários ou ambíguos.                                                   |
| Outbox de notificações              | Entrega durável de notificações ao comerciante após commit (cash-in e refund-in usam este caminho).                   |
| **Ledger**                          | Registro de créditos e débitos por operação Pix **confirmada**.                                                       |

## Leitura recomendada

* [Convenções e headers](/getting-started/environments-and-headers)
* [Modelo de identidade](/core-concepts/identity-model)
* [Ciclo de vida](/core-concepts/transaction-lifecycle)
* [Reconciliação](/ledger-and-reconciliation/reconciliation)