Guia 7/12

Idempotência

As redes falham. Com uma Idempotency-Key, um POST repetido nunca cria um segundo registo.

• Envie uma chave única (8–120 caracteres; um UUID é o ideal) por operação.
• Durante 24 h, a mesma chave com o mesmo corpo devolve a resposta guardada, com Idempotency-Replayed: true.
• Mesma chave com outro corpo → 409 idempotencia_conflito; mesma chave ainda em curso → 409 idempotencia_em_curso.
• As chaves são por credencial: duas integrações nunca colidem.

curl -X POST "https://anagen.pt/api/v1/tarefas" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1d9a42-2b1f-4f7e-9a51-1b2d3c4e5f60" \
  -d '{"titulo":"Ligar à Rita Matos","prazo":"2026-10-29T10:00:00+00:00","prioridade":"alta"}'

# A mesma chave e o mesmo corpo devolvem a mesma resposta (cabeçalho Idempotency-Replayed: true).
# A mesma chave com outro corpo devolve 409 idempotencia_conflito.