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

# Quickstart

> Fluxo mínimo: token, cash-in, webhook, consulta e registro de webhook do comerciante.

## Pré-requisitos

* URL base: `https://api.clearpago.com.br`
* Token (Bearer) obtido conforme [Autenticação](/getting-started/authentication)
* `X-Correlation-ID` (string ou UUID) em cada chamada — recomendado

<Steps>
  <Step title="1. Obter token de API">
    Use `POST /api-key/generate` com o token administrativo. Guarde o `apiKey` retornado.
  </Step>

  <Step title="2. Criar cash-in">
    `POST /api/pix/cash-in` com valor em reais, `externalId` único e, se desejar QR, `generateQrCode: true`.

    ```bash theme={null}
    curl -X POST https://api.clearpago.com.br/api/pix/cash-in \
      -H "Authorization: Bearer <seu_api_token>" \
      -H "Content-Type: application/json" \
      -H "X-Correlation-ID: req-001" \
      -d '{
        "transaction": {
          "value": 150.75,
          "externalId": "pedido-12345",
          "description": "Pagamento Pedido #12345",
          "expirationTime": 3600,
          "generateQrCode": true
        },
        "payer": {
          "fullName": "João da Silva",
          "document": "123.456.789-00"
        }
      }'
    ```

    Resposta **201** com `id` (UUID do cash-in) e, em geral, `status` `PENDING`. **Persista** `id` e `externalId`.
  </Step>

  <Step title="3. Receber webhook (comerciante)">
    Efetue o pagamento no ambiente de teste ou produção. A plataforma notificará a URL que você [registrar com POST /webhook](/api-reference/register-webhook) (evento `pix_cash_in`).

    Valide a assinatura `Digital-Signature` sobre o **corpo bruto** (ver [Verificar assinaturas](/guides/verify-webhook-signatures)). Responda **2xx** em poucos segundos; processe o negócio de forma assíncrona se necessário.
  </Step>

  <Step title="4. Consultar transação">
    Use o UUID do passo 2: `GET /api/pix/cash-in/{id}`. O sucesso financeiro para “liberar” o pedido em integração comum ocorre quando o status de domínio for **`PAID`** (e webhooks/ledger alinhados à sua política). Veja [Receber cash-in](/guides/receive-pix-cash-in).
  </Step>

  <Step title="5. Registrar webhook do comerciante (se ainda não fez)">
    `POST /webhook` com a URL pública e a lista de eventos necessários. Detalhe de payload: [clearpago → comerciante](/webhooks/clearpago-to-merchant).

    `TODO: corpo exato (JSON) de POST /webhook` — não consta o exemplo no documento de origem; alinhar com o suporte ou especificação OpenAPI interna.
  </Step>
</Steps>

## O que acompanhar em seguida

* [Modelo de identidade](/core-concepts/identity-model) — `refund-in` usa o **UUID do cash-in** no path.
* [Semântica de `event.id`](/webhooks/webhook-event-reference) nos webhooks ao comerciante.
* [Checklist de go-live](/go-live/checklist)