Idempotencia

Toda operacao financeira (POST) deve incluir o header Idempotency-Key para evitar duplicidade em caso de timeout ou retentativa.

Como funciona

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

1. Na primeira chamada, a API processa e armazena a resposta
2. Em chamadas subsequentes com a mesma chave, retorna a resposta armazenada sem reprocessar
3. Se o body mudar com a mesma chave, retorna 409 idempotency_key_reused_with_different_body

Regras

Regra	Valor
Formato	UUIDv7 recomendado (qualquer string 16-80 chars aceita)
TTL	24 horas
Escopo	Por originator_id + key
Metodos	POST, PUT, PATCH, DELETE
Rotas	Apenas /v1/*

Exemplo

# Primeira chamada — processa normalmente
curl -X POST https://receivables-api.zemocapital.com/v1/stock \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "NF-001", ...}'
# -> 201 Created

# Segunda chamada (retry) — retorna resposta cacheada
curl -X POST https://receivables-api.zemocapital.com/v1/stock \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "NF-001", ...}'
# -> 201 Created (mesma resposta, sem reprocessar)

Erro: chave reutilizada com body diferente

// 409
{"detail": "idempotency_key_reused_with_different_body"}

Gere UUIDs unicos

Use uuidgen (Linux/Mac), uuid.uuid4() (Python) ou crypto.randomUUID() (Node.js).