Idempotência
Uma tentativa repetida deve recuperar a operação anterior, não duplicar uma cobrança.
Chave por ação de negócio
Envie Idempotency-Key com 16 a 128 caracteres alfanuméricos, hífen, sublinhado, ponto ou dois-pontos. Reutilize a chave para repetir a mesma solicitação. Gere outra apenas para uma ação nova.
A criação de sessão grava a combinação organização/chave como única no PostgreSQL e armazena um hash canônico do corpo. Duas requisições concorrentes convergem para a mesma sessão.
| Repetição | Resultado |
|---|---|
| Mesma chave e mesmo corpo | Mesma sessão e URL |
| Mesma chave e corpo diferente | 409 IDEMPOTENCY_CONFLICT |
| Chave em outra organização | Namespace independente |
Campos opcionais normalizados seguem o schema antes de calcular o hash. Trate também e-mail/documento pré-preenchidos como parte da solicitação.
Pagamentos
Existe uma restrição única por checkout. Repetir criação de pagamento com a mesma chave e dados retorna o pagamento. Outra chave ou outro corpo retorna CHECKOUT_USED.
Eventos
Cada evento tem uma chave de deduplicação. A entrega pode se repetir após timeout ou perda de conexão, mesmo com assinatura válida. Seu consumidor deve manter event.id como chave única.