Idempotencia

Chaves de idempotencia garantem que uma operacao seja executada apenas uma vez, mesmo que a requisicao seja enviada multiplas vezes. Isso e essencial para prevenir duplicacoes em cenarios de falha de rede ou timeout.

Por que usar idempotencia?

Considere o cenario: sua aplicacao envia uma requisicao para criar uma importacao, mas ocorre um timeout de rede. Voce nao sabe se a requisicao foi processada ou nao. Sem idempotencia, reenviar a requisicao poderia criar uma importacao duplicada.

Com uma chave de idempotencia, a API reconhece que a requisicao ja foi processada e retorna o mesmo resultado da primeira execucao, sem criar duplicatas.

Como funciona

Inclua o header Idempotency-Key com um UUID v4 unico em qualquer requisicao POST. A API armazena o resultado associado a essa chave por 24 horas.

Primeira requisicao: a operacao e executada normalmente e o resultado e armazenado
Requisicoes subsequentes com a mesma chave: a API retorna o resultado armazenado sem executar a operacao novamente
Apos 24 horas: a chave expira e pode ser reutilizada

Exemplo pratico

Requisicao com idempotenciabash

# Gere uma chave unica ANTES de enviar
IDEMPOTENCY_KEY=$(uuidgen)

# Primeira tentativa
curl -X POST https://api.topocontabil.com.br/v1/imports \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F "type=trial_balance" \
  -F "companyId=550e8400-e29b-41d4-a716-446655440000" \
  -F "period=2026-01" \
  -F "file=@balancete.xlsx"

# Se houve timeout, reenvie com a MESMA chave
curl -X POST https://api.topocontabil.com.br/v1/imports \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -F "type=trial_balance" \
  -F "companyId=550e8400-e29b-41d4-a716-446655440000" \
  -F "period=2026-01" \
  -F "file=@balancete.xlsx"

# A segunda requisicao retorna o mesmo resultado da primeira

Regras importantes

Uma chave por operacao

Cada operacao logica deve usar uma chave unica. Nunca reutilize a mesma chave para operacoes diferentes -- isso retornaria o resultado da primeira operacao em vez de executar a nova.

Formato da chave

A chave deve ser um UUID v4 valido. Exemplos de geracao:

Gerando UUID em diferentes ambientesbash

# Linux/macOS
uuidgen

# Node.js
node -e "console.log(crypto.randomUUID())"

# Python
python3 -c "import uuid; print(uuid.uuid4())"

Comportamento por cenario

Cenario	Comportamento
Mesma chave, mesmo corpo	Retorna resultado armazenado (sem re-execucao)
Mesma chave, corpo diferente	Retorna erro 422 Unprocessable Entity
Chave expirada (> 24h)	Executa como nova operacao
Sem header Idempotency-Key	Executa normalmente (sem protecao)

Boas praticas

Gere a chave de idempotencia antes do loop de retentativas. Se gerar uma nova chave a cada tentativa, a protecao contra duplicacao sera perdida.

Endpoints que aceitam idempotencia

Todos os endpoints POST aceitam o header Idempotency-Key:

POST /v1/tenants
POST /v1/connections
POST /v1/imports
POST /v1/webhooks