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

# Idempotencia

> Reintenta cualquier operación de escritura de forma segura, sin crear nada dos veces

## Escrituras que modifican un recurso existente

No interviene ninguna cabecera. Donde antes una repetición devolvía un error, ahora devuelve el estado actual:

| Endpoint | Una llamada repetida devuelve |
| - | - |
| [Cancelar cita](https://docs.anivahealth.com/es/api/appointments/cancel-appointment.md) | `200` con la cita cancelada |
| [Cancelar envío](https://docs.anivahealth.com/es/api/shipments/cancel-shipment.md) | `200` con el envío cancelado |
| [Cancelar pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/cancel-home-kit.md) | `200` con el pedido cancelado |
| [Activar pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/activate-home-kit.md) | `200`, si la hora de recogida es la misma |
| Eliminar paneles o biomarcadores | `200`, estuvieran o no todavía asociados |

Una repetición no escribe nada y su respuesta incluye `Idempotent-Replayed: true`: esa cabecera es la que te permite distinguir entre "lo cancelé yo" y "ya estaba cancelado".

Tres excepciones devuelven `409` en su lugar:

* **Activar con un `activated_at` *distinto*.** La hora de recogida es la que figura en el informe del laboratorio, así que un reintento no debe sobrescribirla silenciosamente.
* **Cancelar una cita ya cancelada con un `cancellation_reason` *distinto*.** Mismo razonamiento: el motivo registrado puede haberse corregido desde entonces y un reintento no debe sobrescribirlo. Vuelve a enviar el motivo registrado u omítelo.
* **Cancelar pasado el punto de no retorno** — una extracción de sangre confirmada, un envío recogido, un kit enviado o activado.

Tres endpoints no son seguros para reintentos de forma deliberada:

* [Confirmar extracción de sangre](https://docs.anivahealth.com/es/api/appointments/confirm-blood-draw.md) — una segunda llamada devuelve `409`.
* [Enviar resultados por email](https://docs.anivahealth.com/es/api/appointments/email-results.md) (`POST /v1/appointments/{id}/results/email`) y [Enviar resultados por email](https://docs.anivahealth.com/es/api/home-kit-orders/email-results.md) (`POST /v1/home-kit-orders/{id}/results/email`) — cada llamada envía un email. Un reintento tras un timeout o un `5xx` puede enviar un duplicado al cliente.

## Escrituras que crean algo

Cinco endpoints aceptan una cabecera opcional `Idempotency-Key`, de 255 caracteres como máximo:

* [Crear perfil](https://docs.anivahealth.com/es/api/profiles/create-profile.md)
* [Crear cita](https://docs.anivahealth.com/es/api/appointments/create-appointment.md)
* [Crear pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/create-home-kit.md)
* [Crear envío](https://docs.anivahealth.com/es/api/shipments/create-shipment.md)
* [Subir documento](https://docs.anivahealth.com/es/api/documents/upload-document.md)

Una clave, cuatro intentos, un pedido: lo que recibes depende de cuándo reintentas y de si el cuerpo coincide:

![Diagrama de secuencia: una solicitud duplicada enviada 350 ms después de la primera recibe un 409 mientras esa primera sigue en curso, la primera devuelve 201, un reintento posterior con la misma clave devuelve el mismo pedido marcado como Idempotent-Replayed y la misma clave con un cuerpo modificado devuelve 409.](https://mintcdn.com/anivahealth/8KTut54iIoaIFYY2/images/idempotency-retry.svg?fit=max\&auto=format\&n=8KTut54iIoaIFYY2\&q=85\&s=617f6b19f473ee0fed9243004f932c19)

Las claves están acotadas a tu API key **y** al endpoint, así que nunca colisionan con las de otro partner ni con la misma clave usada en otro sitio.

* **Misma clave, mismo cuerpo** → durante 24 horas recibes de vuelta la respuesta original, marcada con `Idempotent-Replayed: true`. El orden de los campos y los espacios en blanco no importan.
* **Misma clave, cuerpo distinto** → `409`.
* **Un `Idempotency-Key` vacío** → `400`, en lugar de ignorarse.

### Cuándo se libera la clave

La creación **no es atómica**: un `5xx` no significa que no se haya escrito nada.

* **La solicitud falló antes de crear nada** → la clave se libera, así que puedes reintentar con ella.
* **La solicitud falló después de crear algo**, o **nunca devolvió respuesta** → la clave sigue reservada y los reintentos reciben `409`. Consulta el recurso para comprobar si existe y, si no existe, usa una clave nueva.

> [!NOTE]
>
> Una repetición devuelve el cuerpo de la respuesta registrado cuando se creó el recurso: una
> instantánea, no una lectura en tiempo real. Si el recurso ha cambiado desde entonces, consúltalo
> directamente.

### Algunas creaciones también tienen una clave natural

Dos endpoints rechazan duplicados por sí solos, independientemente de cualquier cabecera:

* [Crear cita](https://docs.anivahealth.com/es/api/appointments/create-appointment.md) permite una cita por perfil, ubicación e instante. Una repetición devuelve `409` con el `appointment_id` existente.
* [Crear perfil](https://docs.anivahealth.com/es/api/profiles/create-profile.md) devuelve `409` cuando `email` ya tiene un perfil. Si omites `email`, se genera un valor provisional único por solicitud, por lo que las repeticiones *sí* crean perfiles distintos.

Cuando se aplican ambos, el `409` que verás es el de la clave natural, y solo ese incluye el campo adicional (`appointment_id` o un discriminador `error_name`): un `409` de idempotencia solo incluye `error`, así que lee esos campos de forma defensiva.


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