Guia

Idempotência

Repetir uma escrita sem criar duas vezes.

A rede cai no meio de um “criar veículo” e você não sabe se ele foi criado. Repetir sem cuidado cria dois. Para isso existe o cabeçalho Idempotency-Key: obrigatório em POST e aceito em PATCH.

curl

curl -X POST https://frotasimples.com/api/v1/... \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: 4f1c9a1e-0b7e-4c1a-9f3e-2d5b8a6c7e90" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Como funciona

Gere um valor único por operação (um UUID serve) e guarde junto da operação no seu sistema.
Repetiu com a mesma chave e o mesmo corpo: a API devolve a resposta original, sem executar de novo, com o cabeçalho Idempotent-Replayed: true.
Mesma chave com outro corpo: 422 idempotencia_divergente.
Mesma chave enquanto a primeira ainda roda: 409 conflito — espere e repita.
Erro 5xx não fica gravado: repita com a mesma chave.
A chave vale por 24 horas.

O corpo é comparado como texto exato. Reformatar o JSON entre as tentativas (espaços, ordem dos campos) conta como corpo diferente — serialize uma vez e reenvie o mesmo texto.

Guia

Idempotência

Repetir uma escrita sem criar duas vezes.

curl

curl -X POST https://frotasimples.com/api/v1/... \
  -H "Authorization: Bearer $FROTASIMPLES_CHAVE" \
  -H "Idempotency-Key: 4f1c9a1e-0b7e-4c1a-9f3e-2d5b8a6c7e90" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Como funciona

Gere um valor único por operação (um UUID serve) e guarde junto da operação no seu sistema.
Repetiu com a mesma chave e o mesmo corpo: a API devolve a resposta original, sem executar de novo, com o cabeçalho Idempotent-Replayed: true.
Mesma chave com outro corpo: 422 idempotencia_divergente.
Mesma chave enquanto a primeira ainda roda: 409 conflito — espere e repita.
Erro 5xx não fica gravado: repita com a mesma chave.
A chave vale por 24 horas.

O corpo é comparado como texto exato. Reformatar o JSON entre as tentativas (espaços, ordem dos campos) conta como corpo diferente — serialize uma vez e reenvie o mesmo texto.