Skip to main content
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.

​
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