Skip to main content
Timeout de rede acontece. Quando acontece no meio de um POST /v1/attendances, o integrador não sabe se o atendimento foi criado ou não — e a resposta errada para essa dúvida é tentar de novo sem proteção, arriscando abrir dois atendimentos para o mesmo caso. POST /v1/attendances é o único endpoint de criação da API pública, e é o único que exige o cabeçalho Idempotency-Key.

​
Como usar

Gere um identificador único para cada tentativa lógica de abertura de atendimento — um UUID serve bem — e envie no cabeçalho Idempotency-Key:
A mesma chave é reaproveitada só quando a chamada anterior falhou de um jeito que deixa dúvida sobre o resultado (timeout, erro de conexão, 5xx). Uma nova tentativa lógica — outro atendimento, outro cliente — sempre usa uma chave nova.

​
O que acontece ao repetir

A chave de idempotência é única por contratante (duas contratantes podem usar o mesmo valor sem conflito). Repetir a chamada com a mesma chave e o mesmo corpo:
  • Não cria um segundo atendimento.
  • Devolve 200 (em vez do 201 da criação original) com o mesmo atendimento já criado.
  • É seguro repetir quantas vezes precisar — inclusive em paralelo, uma corrida entre duas requisições simultâneas com a mesma chave sempre resolve para um único atendimento.
Repetir a mesma chave com um corpo diferente é tratado como um erro do integrador, não como uma segunda tentativa: a API devolve 409 IDEMPOTENCY_CONFLICT e não altera nada. Isso normalmente significa que a chave foi reaproveitada por engano entre duas tentativas lógicas diferentes — gere uma chave nova para o novo atendimento.

​
O que a chave não faz

A chave de idempotência não substitui a checagem de elegibilidade nem valida o corpo da requisição — ela só decide se uma tentativa de criação é uma repetição ou uma tentativa nova. Uma chamada inválida (documento inexistente, cliente sem cobertura) continua devolvendo o erro correspondente mesmo com uma chave de idempotência válida, e essa chave só passa a “significar” alguma coisa depois que um atendimento é de fato criado com sucesso.

​
Retenção

A chave fica associada ao atendimento enquanto ele existir — não há uma janela de expiração curta depois da qual o mesmo valor passa a criar um atendimento novo. Trate cada chave como permanentemente ligada à tentativa que ela representa, e nunca a reutilize para outra coisa.