Idempotência

Todo POST que cria recurso ou trabalho exige o cabeçalho Idempotency-Key. Ele garante que repetir a chamada (por queda de rede, por timeout, por 429) não cria duas vezes a mesma coisa.

Regra de uso: gere um UUID por operação lógica e repita o mesmo UUID em todas as retentativas dela. Operação nova, UUID novo.

POST /v1/relatorios HTTP/1.1
Authorization: Bearer rmf_test_...
Idempotency-Key: 7f3c1b52-9d4e-4a86-b0c1-2e5d8f6a9b13
Content-Type: application/json

Como funciona

• A chave é por conta e por operação: a impressão digital inclui a conta, o método, o caminho e o corpo. A chave de outra conta nunca colide com a sua.
• É guardada por 24 horas.
• Mesma chave e mesma impressão digital: a resposta original é devolvida, sem criar de novo.
• No envio de arquivo (multipart/form-data), a impressão digital é o conteúdo do arquivo e dos demais campos, não o corpo multipart.

Erros

Situação	Resposta
Faltou o cabeçalho	400 cabecalho_ausente
Mesma chave com outro corpo	422 idempotencia_conflito
Mesma chave ainda em processamento	409 idempotencia_em_andamento: espere e repita com a mesma chave

Reenviar o mesmo conteúdo de arquivo pela mesma conta, mesmo com outra Idempotency-Key, devolve o arquivo existente com duplicado: true (200).