# ADR-003 — Idempotência de comandos e integrações

- Estado: Aceite como padrão para operações repetíveis com efeitos.
- Data: 2026-10-01
- Contexto: há recibos idempotentes territoriais, chaves em outbox e `insertOrIgnore` localizados, mas não contrato uniforme.

## Decisão

Comandos repetíveis com efeitos aceitam `Idempotency-Key` opaca, limitada em tamanho e escopo por actor/cliente, operação e recurso. Persistir chave, hash canónico dos parâmetros relevantes, estado e resultado mínimo por janela de retenção aprovada; a mesma chave e mesmo pedido reproduzem a resposta, a mesma chave com payload diferente produz conflito. A criação do recibo e a mutação de negócio pertencem à mesma transacção. Jobs e consumidores deduplicam por identificador de evento e guardam progresso sem reexecutar efeitos já confirmados. Não registar a chave em claro em logs; guardar apenas referência/hash adequado. Retenção não é fixada aqui.

## Alternativas e consequências

Deduplicar só na memória falha em reinícios e múltiplos workers. Usar só UUID do recurso não cobre criação repetida. Integrações externas exigem reconciliação e chave do destinatário; não se promete exactly-once, mas entrega pelo menos uma vez com consumidor idempotente. Cada API define respostas de replay e conflito.