Idempotência

Numa integração que cria empréstimos e move dinheiro, um retry após um timeout de rede não pode duplicar a operação. Para isso, os POST sensíveis exigem o header Idempotency-Key.

Como funciona

Você gera uma chave única (ex.: um UUID) por operação lógica e a envia no header. Se a mesma chave chegar de novo, a API retorna a resposta original sem reexecutar nada — seguro para reenviar quantas vezes precisar.


curl -X POST https://api.socinal.com.br/v1/emprestimos \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Idempotency-Key: 7b3e2c10-4f5a-4c8d-9a1b-2e6f0a9c1d34' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Na repetição, a resposta vem com o header X-Idempotency-Replayed: true.

Quais endpoints exigem

Endpoint	Por quê
`POST /v1/emprestimos`	Não duplicar emissão de CCB
`POST /v1/emprestimos/{id}/documentos`	Não reprocessar pacote assinado
`POST /v1/emprestimos/{id}/averbacao`	Não averbar em duplicidade
`POST /v1/emprestimos/{id}/desembolso`	Não duplicar PIX
`POST /v1/emprestimos/{id}/cancelamento`	Não cancelar em duplicidade

Chamar esses endpoints sem o header resulta em 400 IDEMPOTENCY_KEY_OBRIGATORIA.

Uma chave por operação lógica. Reutilizar a mesma chave para uma operação diferente devolve a resposta antiga. Gere uma chave nova para cada nova intenção.

Boas práticas

Use um UUID v4 por tentativa de operação e persista-o do seu lado antes de chamar — assim o retry reusa a mesma chave.
A janela de deduplicação tem TTL (≈24h). Retries dentro desse período são seguros; depois disso, a chave pode não estar mais em cache.
Combine idempotência com webhooks: mesmo que sua chamada dê timeout, o evento assíncrono confirma o resultado real.