Idempotência
Idempotency-Key é obrigatório no POST /v1/admissoes. Gere um valor novo (um UUID serve) para cada admissão e reuse-o em todo reenvio dela. Ausente ou fora da forma (8 a 100 caracteres: letras, dígitos e . _ : -): 400 IDEMPOTENCY_KEY_INVALIDA, sem nada gravado nem consumido.
| situação | resposta |
|---|---|
| primeira vez | 202 |
| mesma chave, mesmo corpo (timeout, fila reenviando, dúvida se chegou) | 202 idêntico ao primeiro, com X-Motor-Repetido: true; nada é criado de novo |
| mesma chave, mesmo corpo, enviado por outra chave de integração ativa da mesma empresa | o mesmo 202 guardado — a Idempotency-Key é da empresa, não da chave de integração |
| mesma chave, corpo diferente | 409 IDEMPOTENCIA_CONFLITO |
| mesma chave enquanto o primeiro pedido ainda roda | 409 IDEMPOTENCIA_EM_CURSO — repita em alguns segundos |
o pedido anterior foi recusado (4xx) ou deu 503 | a chave não ficou presa: corrija e reenvie com a mesma chave, ou com outra |
"Mesmo corpo" é o mesmo JSON: ordem das chaves e espaços não contam, e 2150.00 e 2150 são o mesmo número. A Idempotency-Key é lembrada sem prazo.
Exemplo
O primeiro POST estourou o tempo do seu lado e você não sabe se chegou: reenvie exatamente o mesmo corpo com a mesma Idempotency-Key. Se tinha chegado, você recebe a mesma matrícula; se não, a admissão é criada agora.
Nunca gere chave nova para "tentar de novo": com chave nova, o mesmo CPF volta como 409 TRABALHADOR_JA_ADMITIDO.