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

# Idempotência e correlação

> externalId, X-Correlation-ID, deduplicação de webhooks e armazenamento do lado do integrador.

A API de origem enfatiza **idempotência** de eventos e notificações: webhooks e outbox **podem reentregar**; a plataforma deduplica por **identificadores e hash de payload** (lado deles). Do **seu** lado, trate tudo como **pelo menos uma vez (at-least-once)**.

## `externalId` (sua chave de negócio)

* Deve ser **único** por operação quando a regra de criação assim exigir. Duplicidade costuma resultar em **`409` Conflito** (conforme convenções gerais do documento).
* Use o mesmo `externalId` enquanto quiser mapear 1:1 com pedido, saque, estorno, etc. — mas **não** reutilize o mesmo `externalId` para operações financeiras distintas que a API considera conflitantes.
* Não confunda com `id` (UUID da plataforma). Refund: path usa o **`id` do cash-in**; a consulta de refund usa o `id` do **refund-in**.

`TODO: regra formal de unicidade` — tamanho máximo, charset e escopo (global vs. organização) se precisar para certificação.

## `X-Correlation-ID`

* Envie em **toda** chamada (recomendado): UUID ou string rastreável.
* Deve ser ecoado na resposta **quando aplicável**, facilitando rastreio com suporte e logs cruzados.

## Deduplicação de webhooks (comerciante)

Após verificar a assinatura, considere idempotente por **combinação** mínima coerente com o evento, por exemplo:

* Base geral: `event_type` + `event.id` + **transição lógica de status** (o mesmo “evento de negócio” pode replicar o mesmo `status` em reentregas).
* `pix_cash_in_reversal`: a documentação de origem recomenda compor com `transaction_id` e `end_to_end_id` do estorno, porém `event.id` nesse evento aponta para o **UUID do cash-in original**; veja tabela em [Referência de eventos](/webhooks/webhook-event-reference).

## Estratégia de armazenamento (integrador)

1. Tabela/ledger de **entregas processadas** com chave de idempotência (hash do body canônico ou chave composta acordada, **além** da assinatura).
2. Resposta HTTP **2xx** rápida; processamento longo em fila interna.
3. Correlação de logs com `X-Correlation-ID` (suas saídas) e `event.correlation_id` (quando presente no webhook de saída).
4. Para refund parcial, persistir o **`id` do refund-in** retornado no `201` e reconciliar com `GET /api/pix/refund/{id}`.

## O que a API **não** documenta formalmente

`TODO: header de idempotência` — ex.: `Idempotency-Key` em criação — o documento de origem **não** descreve header HTTP de idempotência além de `externalId` e boas práticas; confirme com a equipe se existir suporte a `Idempotency-Key` no gateway.

## Referência

* [Registro de webhooks](/guides/register-merchant-webhooks)
* [Verificar assinaturas](/guides/verify-webhook-signatures)