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

# Checklist de primeira integração

> Lista de verificação para ter a primeira integração ClearPago funcionando corretamente em ambiente de teste.

Use este checklist antes de submeter a integração para revisão ou de solicitar acesso ao ambiente de produção.

## Credenciais e ambiente

<Check>Token Bearer gerado via `POST /api-key/generate` e armazenado em variável de ambiente (não no repositório).</Check>
<Check>Base URL configurada corretamente: `https://api.clearpago.com.br`.</Check>
<Check>Header `Authorization: Bearer <token>` presente em todas as chamadas autenticadas.</Check>
<Check>Header `Content-Type: application/json` presente em todos os `POST` com corpo.</Check>
<Check>`X-Correlation-ID` sendo gerado e enviado em cada requisição para rastreabilidade.</Check>

## Cash-in

<Check>Criação de cash-in retorna `201` com `id` (UUID) e `status: PENDING`.</Check>
<Check>UUID do cash-in persistido na base do seu sistema imediatamente após o `201`.</Check>
<Check>`externalId` único por cobrança; colisões retornam `409` e estão sendo tratadas.</Check>
<Check>QR Code EMV (`pixCode`) presente na resposta quando `generateQrCode: true`.</Check>
<Check>`expirationDate` lido e exibido corretamente ao usuário/sistema.</Check>
<Check>`GET /api/pix/cash-in/{id}` funcionando e retornando o status atual.</Check>

## Webhook do comerciante

<Check>Endpoint `POST` público configurado e acessível via HTTPS.</Check>
<Check>URL registrada via `POST /webhook` com os eventos `pix_cash_in`, `pix_cash_out`, `pix_cash_in_reversal`, `pix_cash_out_reversal`.</Check>
<Check>Chave pública obtida de `GET /public-key` e armazenada (com TTL de cache definido).</Check>
<Check>Verificação de `Digital-Signature` implementada: ECDSA P-256 + SHA-256 sobre o **corpo bruto**.</Check>
<Check>Handler de webhook retorna **2xx** em menos de 5 segundos.</Check>
<Check>Lógica de negócio executada **após** a resposta HTTP (fila ou processamento assíncrono).</Check>
<Check>Handler idempotente: o mesmo evento entregue duas vezes não duplica efeito colateral.</Check>
<Check>Chave de idempotência definida: pelo menos `event_type` + `event.id` + transição de status.</Check>

## Cash-out (se aplicável)

<Check>`POST /api/pix/cash-out` retorna `201` com `id` e estado de reserva.</Check>
<Check>UUID do cash-out persistido imediatamente.</Check>
<Check>Webhook `pix_cash_out` processado corretamente ao receber status `CONFIRMED`.</Check>
<Check>Estado `PROVIDER_RESULT_UNKNOWN` e `RECONCILIATION_REQUIRED` não tratados como terminais.</Check>

## Refund-in (se aplicável)

<Check>`POST /api/pix/refund-in/{id}` usando o UUID do **cash-in** (não o `transactionId` do parceiro).</Check>
<Check>`refundValue` em BRL (não em centavos) no request.</Check>
<Check>UUID do refund-in retornado no `201` persistido para auditoria.</Check>
<Check>Webhook `pix_cash_in_reversal` deduplicando por `transaction_id` + `end_to_end_id` do estorno (não só por `event.id`).</Check>

## Valores monetários

<Check>Requests enviados com valores em **BRL** (ex.: `150.75`).</Check>
<Check>Responses com campos `*_cents` convertidos corretamente antes de comparação ou exibição.</Check>
<Check>Nenhuma comparação direta entre campo BRL e campo centavos no seu código.</Check>

## Estados e erros

<Check>HTTP `4xx` com corpo de erro lido e logado (nunca silenciado).</Check>
<Check>`409` em `externalId` duplicado capturado e tratado (não gera novo recurso sem intenção).</Check>
<Check>`PROVIDER_RESULT_UNKNOWN` e `RECONCILIATION_REQUIRED` monitorados e não marcados como sucesso/falha prematuramente.</Check>

## Próximo passo

Após validar todos os itens, revise o [Checklist de produção](/go-live/production-checklist) para a virada de ambiente.