Pular para o conteúdo principal
Rede cai, servidor reinicia, o seu job roda duas vezes. Para que um POST repetido não crie duas fichas nem mande duas mensagens à paciente, envie Idempotency-Key com um uuid novo por operação:
  • A chave é opcional e vale nos POST que criam ou mandam algo: criar paciente, enviar e reenviar a anamnese, gerar documentos, enviar e reenviar para assinatura, criar webhook.
  • A mesma chave, na mesma rota, nas 24 horas seguintes devolve a mesma resposta, sem repetir o efeito. A resposta repetida traz o cabeçalho Idempotent-Replayed: true.
  • A mesma chave com outro corpo responde 409 conflict: “Esta Idempotency-Key já foi usada com outro corpo nas últimas 24 horas. Gere uma chave nova para outra operação.”
  • A mesma chave enquanto a primeira chamada ainda roda (o seu job repetiu porque a geração dos PDFs demorou) responde 409 conflict: “Esta chave está em uso por uma chamada que ainda não terminou. Espere e repita.” A chave é reservada antes de executar, então duas chamadas ao mesmo tempo nunca fazem o efeito duas vezes. Uma reserva de chamada que caiu no meio vale 5 minutos.
  • Só a resposta de sucesso fica guardada. Se a chamada falhou (um 422, um 409 de regra), a reserva é liberada: corrija e repita com a mesma chave.
  • A resposta repetida de POST /v1/webhooks vem com secret: null. O segredo sai uma vez só, na primeira resposta; depois, GET /v1/webhooks/{id}/secret.
  • A chave precisa ser um uuid; outro formato responde 422 com fields["Idempotency-Key"].
  • A chave é de quem chama: dois apps podem usar o mesmo uuid sem conflito.
O 503 de POST /v1/anamneses é a exceção: a anamnese já foi criada e só a mensagem não saiu. Repetir a chamada responde 409 com o id da anamnese aberta. Reenvie por POST /v1/anamneses/{id} /resend.
Use sempre em tudo que manda mensagem à paciente: enviar a anamnese, enviar para assinatura, reenviar. Gere a chave quando a operação nasce no seu sistema e guarde junto dela, para que a nova tentativa use a mesma.
Última modificação em 16 de outubro de 2026