Idempotencia

Chaves de idempotencia garantem que uma operação seja executada apenas uma vez, mesmo que a requisição seja enviada múltiplas vezes. Isso e essencial para prevenir duplicações em cenários de falha de rede ou timeout.

Por que usar idempotencia?

Considere o cenário: sua aplicação envia uma requisição para criar uma importação, mas ocorre um timeout de rede. Você não sabe se a requisição foi processada ou não. Sem idempotencia, reenviar a requisição poderia criar uma importação duplicada.

Com uma chave de idempotencia, a API reconhece que a requisição já foi processada e retorna o mesmo resultado da primeira execução, sem criar duplicatas.

Como funciona

Inclua o header Idempotency-Key com um UUID v4 único em qualquer requisição POST. A API armazena o resultado associado a essa chave por 24 horas.

Primeira requisição: a operação e executada normalmente e o resultado e armazenado
Requisições subsequentes com a mesma chave: a API retorna o resultado armazenado sem executar a operação novamente
Após 24 horas: a chave expira e pode ser reutilizada

Exemplo prático

Requisição com idempotenciabash

# Gere uma chave única 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 requisição retorna o mesmo resultado da primeira

Regras importantes

Uma chave por operação

Cada operação lógica deve usar uma chave única. Nunca reutilize a mesma chave para operações diferentes -- isso retornaria o resultado da primeira operação em vez de executar a nova.

Formato da chave

A chave deve ser um UUID v4 valido. Exemplos de geração:

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 cenário

Cenário	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 operação
Sem header Idempotency-Key	Executa normalmente (sem proteção)

Boas práticas

Gere a chave de idempotencia antes do loop de retentativas. Se gerar uma nova chave a cada tentativa, a proteção contra duplicação será 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