Operações de escrita que alteram um recurso existente
Não envolve qualquer cabeçalho. Onde antes uma repetição devolvia um erro, agora devolve o estado atual:
Uma repetição não escreve nada e a sua resposta inclui
Idempotent-Replayed: true — esse cabeçalho permite-te distinguir “eu cancelei-o” de “já estava cancelado”.
Três exceções devolvem 409 em vez disso:
- Ativar com um
activated_atdiferente. A hora de colheita é a que consta no relatório laboratorial, pelo que uma nova tentativa não deve substituí-la silenciosamente. - Cancelar uma marcação já cancelada com um
cancellation_reasondiferente. O mesmo raciocínio: o motivo registado pode entretanto ter sido corrigido e uma nova tentativa não deve substituí-lo. Volta a enviar o motivo registado ou omite-o. - Cancelar após o ponto sem retorno — uma colheita de sangue confirmada, um envio recolhido, um kit expedido ou ativado.
- Confirmar colheita de sangue — uma segunda chamada devolve
409. - Enviar resultados por e-mail (
POST /v1/appointments/{id}/results/email) e Enviar resultados por e-mail (POST /v1/home-kit-orders/{id}/results/email) — cada chamada envia um e-mail. Uma nova tentativa após um timeout ou um5xxpode enviar um duplicado ao cliente.
Operações de escrita que criam algo
Cinco endpoints aceitam um cabeçalhoIdempotency-Key opcional, com no máximo 255 caracteres:
Uma chave, quatro tentativas, uma encomenda — o que recebes depende de quando voltas a tentar e de o corpo coincidir ou não:
- Mesma chave, mesmo corpo → durante 24 horas recebes de volta a resposta original, marcada com
Idempotent-Replayed: true. A ordem dos campos e os espaços em branco não importam. - Mesma chave, corpo diferente →
409. - Um
Idempotency-Keyvazio →400, em vez de ser ignorado.
Quando a chave é libertada
A criação não é atómica — um5xx não significa que nada foi escrito.
- O pedido falhou antes de algo ser criado → a chave é libertada, pelo que podes voltar a tentar com ela.
- O pedido falhou depois de algo ser criado, ou nunca devolveu resposta → a chave permanece ocupada e as novas tentativas recebem
409. Obtém o recurso para verificar se existe e depois usa uma nova chave se não existir.
Uma repetição devolve o corpo da resposta registado quando o recurso foi criado — um snapshot, não
uma leitura em tempo real. Se o recurso mudou entretanto, obtém-no diretamente.
Algumas criações também têm uma chave natural
Dois endpoints rejeitam duplicados por conta própria, independentemente de qualquer cabeçalho:- Criar marcação permite uma marcação por perfil, local e instante. Uma repetição devolve
409com oappointment_idexistente. - Criar perfil devolve
409quandoemailjá tem um perfil. Omiteemaile é gerado um placeholder único por pedido, pelo que as repetições criam mesmo perfis separados.
409 da chave natural e só ele inclui o campo extra (appointment_id ou um discriminador error_name) — um 409 de idempotência traz apenas error, pelo que deves ler esses campos de forma defensiva.