> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência

> Volta a tentar qualquer escrita em segurança, sem criar nada duas vezes

## 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:

| Endpoint | Uma chamada repetida devolve |
| - | - |
| [Cancelar marcação](https://docs.anivahealth.com/pt/api/appointments/cancel-appointment.md) | `200` com a marcação cancelada |
| [Cancelar envio](https://docs.anivahealth.com/pt/api/shipments/cancel-shipment.md) | `200` com o envio cancelado |
| [Cancelar encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/cancel-home-kit.md) | `200` com a encomenda cancelada |
| [Ativar encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/activate-home-kit.md) | `200`, se a hora de colheita for a mesma |
| Remover painéis ou biomarcadores | `200`, estivessem ou não ainda associados |

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_at` *diferente*.** 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_reason` *diferente*.** 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.

Três endpoints não são deliberadamente seguros para repetição:

* [Confirmar colheita de sangue](https://docs.anivahealth.com/pt/api/appointments/confirm-blood-draw.md) — uma segunda chamada devolve `409`.
* [Enviar resultados por e-mail](https://docs.anivahealth.com/pt/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) e [Enviar resultados por e-mail](https://docs.anivahealth.com/pt/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — cada chamada envia um e-mail. Uma nova tentativa após um timeout ou um `5xx` pode enviar um duplicado ao cliente.

## Operações de escrita que criam algo

Cinco endpoints aceitam um cabeçalho `Idempotency-Key` opcional, com no máximo 255 caracteres:

* [Criar perfil](https://docs.anivahealth.com/pt/api/profiles/create-profile.md)
* [Criar marcação](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md)
* [Criar encomenda de kit de teste em casa](https://docs.anivahealth.com/pt/api/home-kit-orders/create-home-kit.md)
* [Criar envio](https://docs.anivahealth.com/pt/api/shipments/create-shipment.md)
* [Carregar documento](https://docs.anivahealth.com/pt/api/documents/upload-document.md)

Uma chave, quatro tentativas, uma encomenda — o que recebes depende de quando voltas a tentar e de o corpo coincidir ou não:

![Diagrama de sequência: um pedido duplicado disparado 350 ms após o primeiro recebe 409 enquanto esse pedido ainda está em execução, o primeiro devolve 201, uma nova tentativa posterior com a mesma chave devolve a mesma encomenda marcada como Idempotent-Replayed e a mesma chave com o corpo alterado devolve 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

As chaves estão associadas à tua chave API **e** ao endpoint, pelo que nunca colidem com as de outro parceiro nem com a mesma chave usada noutro local.

* **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-Key` vazio** → `400`, em vez de ser ignorado.

### Quando a chave é libertada

A criação **não é atómica** — um `5xx` 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.

> [!NOTE]
>
> 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](https://docs.anivahealth.com/pt/api/appointments/create-appointment.md) permite uma marcação por perfil, local e instante. Uma repetição devolve `409` com o `appointment_id` existente.
* [Criar perfil](https://docs.anivahealth.com/pt/api/profiles/create-profile.md) devolve `409` quando `email` já tem um perfil. Omite `email` e é gerado um placeholder único por pedido, pelo que as repetições criam *mesmo* perfis separados.

Quando ambos se aplicam, vês o `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.