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

# Citas

> Cómo funcionan las citas de extracción de sangre en la API de análisis de laboratorio de Aniva: reserva, paneles, biomarcadores, cambios de estado y cancelación.

Una cita es una extracción de sangre programada para un perfil de paciente en una ubicación física de pruebas, realizada por un profesional sanitario. Los kits enviados por correo a un paciente no son citas; consulta [Pedidos de kits de prueba en casa](https://docs.anivahealth.com/es/concepts/home-kit-orders.md).

## Campos

**id** `string` *required*

UUID generado automáticamente por Aniva. Úsalo para añadir paneles, confirmar la extracción de sangre y obtener los resultados.

**profile\_id** `string` *required*

El UUID del perfil al que pertenece esta cita.

**location\_id** `string`

El UUID de la ubicación de pruebas donde tendrá lugar la extracción de sangre. Los kits de prueba en casa no son citas; consulta
[Pedidos de kits de prueba en casa](https://docs.anivahealth.com/es/concepts/home-kit-orders.md).

**scheduled\_at** `string`

Fecha y hora programada de la extracción de sangre en formato ISO 8601. Siempre se devuelve como un instante UTC con el sufijo `Z`
(p. ej., `2026-04-15T08:30:00Z`). Al crear o actualizar, el valor **debe incluir un indicador de zona
horaria** (`Z` o un desplazamiento explícito como `+02:00`); se rechazan las fechas y horas sin zona horaria. Debe
estar en el futuro y, en ubicaciones gestionadas por Aniva, con al menos 12 horas de antelación ([antelación
mínima](https://docs.anivahealth.com/es/api/appointments/create-appointment.md#antelacion-minima)).

**status** `string` *required*

Estado actual del ciclo de vida. Puede ser `pending`, `confirmed`, `blood_drawn` o `cancelled`. Consulta
[Ciclo de vida](#ciclo-de-vida) más abajo. El nivel de avance de los resultados de laboratorio (`in_progress` frente a `completed`) se
obtiene en [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md); el progreso detallado del envío (en
tránsito, entregado, etc.) se obtiene siguiendo cada entrada del array `shipments` incluido hasta
[Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md).

**cancellation\_reason** `string`

Motivo en texto libre registrado al cancelar la cita (p. ej., no presentado, cancelación tardía,
'Fallida. Repetición necesaria'). `null` salvo que `status` sea `cancelled`.

**results\_ready\_emails** `string[]` *required*

Direcciones que reciben un correo cada una cuando todos los resultados de laboratorio son definitivos, en minúsculas. Vacío cuando está desactivado. Consulta
[Correos de resultados listos](https://docs.anivahealth.com/es/concepts/results.md#correos-de-resultados-listos).

**draw\_method** `string` *required*

Cómo se realiza la extracción de sangre: `capillary` (en la yema del dedo o en la parte superior del brazo, en microtubos) o `venous` (de la vena,
en tubos). Es el método definido en la cita o, en su defecto, el `default_draw_method` de su
[ubicación](https://docs.anivahealth.com/es/concepts/locations.md). Después de la extracción de sangre, es el método que se utilizó.

**created\_at** `string` *required*

Marca de tiempo ISO 8601 de cuándo se creó la cita.

**updated\_at** `string`

Marca de tiempo ISO 8601 de la última actualización. Nulo si la cita nunca se ha actualizado.

**lab\_codes** `string[]` *required*

Códigos de laboratorio (códigos de barras de los tubos) registrados en [Confirmar extracción de sangre](https://docs.anivahealth.com/es/api/appointments/confirm-blood-draw.md),
en orden de escaneo. Vacío hasta que se confirme la extracción. Una extracción venosa tiene un único código impreso en todos los
tubos; una extracción capilar tiene un código por microtainer. Los resultados y documentos hacen referencia a ellos mediante
`lab_code`.

**panels** `object[]` *required*

Paneles asociados a esta cita, como entradas `{ panel_id, added_at }`. Consulta
[Añadir paneles](#anadir-paneles).

**individual\_biomarkers** `object[]` *required*

Biomarcadores a la carta asociados a esta cita, como entradas `{ biomarker_id, added_at }`. Consulta
[Biomarcadores individuales](#biomarcadores-individuales).

**shipments** `object[]` *required*

Envíos vinculados a esta cita, como entradas `{ id, added_at }`, del vínculo más antiguo al más reciente. Consulta
[Vincular envíos](#vincular-envios).

**profile** `object` *required*

El objeto de perfil completo del paciente, incluido en cada respuesta de cita. Los campos siguientes
son un subconjunto. [Obtener cita](https://docs.anivahealth.com/es/api/appointments/get-appointment.md) los enumera todos.

**propiedades**

**id** `string`

UUID del perfil asociado.

**first\_name** `string`

Nombre del paciente.

**last\_name** `string`

Apellido del paciente.

**email** `string`

Dirección de correo electrónico del paciente.

**date\_of\_birth** `string`

Fecha de nacimiento en formato `YYYY-MM-DD`.

**sex** `integer`

Sexo biológico según ISO/IEC 5218.

## Ciclo de vida

Las citas tienen cuatro estados de ciclo de vida:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Estado | Significado |
| - | - |
| `pending` | La cita está programada y pendiente de confirmación. Se puede [actualizar](https://docs.anivahealth.com/es/api/appointments/update-appointment.md) o [cancelar](https://docs.anivahealth.com/es/api/appointments/cancel-appointment.md). |
| `confirmed` | La cita se ha confirmado (p. ej., por la consulta), pero aún no se ha realizado la extracción de sangre. Todavía se puede actualizar o cancelar. |
| `blood_drawn` | Los códigos de laboratorio se han enviado mediante [Confirmar extracción de sangre](https://docs.anivahealth.com/es/api/appointments/confirm-blood-draw.md) y se ha iniciado el proceso de pedido al laboratorio. Los paneles quedan bloqueados y la cita no se puede reprogramar ni cancelar. |
| `cancelled` | La cita se ha cancelado. Estado final, sin más transiciones. |

> [!NOTE]
>
> El estado de la cita es general a propósito; el progreso más detallado se consulta
> mediante endpoints específicos:
>
> * **Estado de los resultados de laboratorio** →
>   [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md): el campo `status` de nivel superior es `in_progress` o
>   `completed`.
> * **Progreso del envío** (en tránsito, entregado, etc.) → sigue cada entrada del array
>   `shipments` incluido en la cita hasta [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md): cada
>   envío tiene su propio `status` y un registro de eventos `status_updates`.
>
> Cada cambio de estado envía un [webhook](https://docs.anivahealth.com/es/concepts/webhooks.md) `appointment.*`, por ejemplo
> `appointment.confirmed`. Una nueva hora o ubicación envía `appointment.rescheduled`.

> [!WARNING]
>
> Confirmar una cita (pasarla a `blood_drawn`) es **irreversible**. Una vez que envíes el código o
> códigos de laboratorio, se inicia el proceso de pedido al laboratorio y no se puede deshacer. Las actualizaciones y cancelaciones
> solo se permiten mientras la cita está en estado `pending` o `confirmed`.

## Listar citas

Obtén todas las citas accesibles para tu clave API:

```
GET /api/v1/appointments
```

Opcionalmente, pasa `?profile_id={uuid}` para filtrar por un perfil concreto. Sin este parámetro, se aplica un margen de tiempo predeterminado (de los últimos 2 meses al próximo mes).

## Actualizar una cita

Antes de confirmar la extracción de sangre, puedes reprogramar la cita o cambiar la ubicación de pruebas:

```
PATCH /api/v1/appointments/{id}
```

Pasa cualquier combinación de `scheduled_at`, `location_id`, `draw_method` y `results_ready_emails` para actualizar. Incluye solo los campos que quieras cambiar.

## Método de extracción

Cada cita tiene un `draw_method`: `capillary` (en la yema del dedo o en la parte superior del brazo, en microtainers) o
`venous` (de la vena, en tubos). Solo se aplica a la extracción de sangre. Las muestras de orina, hisopo y otras
muestras que no son de sangre se recogen igual con cualquiera de los dos métodos.

Por defecto, es el `default_draw_method` de la ubicación. Define `draw_method` al crear o actualizar para
usar otro método, o establécelo en `null` para volver al valor predeterminado de la ubicación. La ubicación debe incluir
el método en su `draw_methods` y las pruebas reservadas deben ser posibles con él; de lo contrario, la solicitud
devuelve `400`. No puedes cambiarlo después de la extracción de sangre. Tras la extracción, `draw_method` es el
método que se utilizó.

## Una cita por perfil, ubicación y hora

Un perfil tiene como máximo una cita no cancelada por par `(location_id, scheduled_at)`: una
persona no puede someterse a dos extracciones de sangre a la vez en el mismo lugar, independientemente de cuántas reservas en paralelo
acepte la ubicación.

Tanto [Crear cita](https://docs.anivahealth.com/es/api/appointments/create-appointment.md) como
[Actualizar cita](https://docs.anivahealth.com/es/api/appointments/update-appointment.md) aplican esta regla y devuelven `409` con un
`appointment_id` que apunta a la cita ya existente. Trata esa respuesta como ya
reservada en lugar de un error que reintentar: consulta, reprograma o cancela la cita que indica.

El efecto práctico es que las creaciones repetidas son seguras. Una creación que reenvíes tras un tiempo de espera de red,
o que un usuario active dos veces, se resuelve en una sola cita en lugar de dos, lo que también significa que
nunca necesitas conciliar reservas duplicadas para el mismo paciente después.

> [!NOTE]
>
> Las actualizaciones solo se permiten antes de la extracción de sangre, es decir, mientras la cita está en estado `pending` o
> `confirmed`. Una vez que la cita pasa a `blood_drawn` o está en `cancelled`, no se puede
> modificar. La única excepción es `results_ready_emails`: puedes seguir cambiándolo por sí solo después de la
> extracción de sangre.

## Cancelar una cita

Cancela una cita que ya no sea necesaria:

```
DELETE /api/v1/appointments/{id}
```

Esto establece el estado de la cita en `cancelled`. La cita cancelada se devuelve en la respuesta.

De forma opcional, envía `cancellation_reason` (hasta 500 caracteres) en el cuerpo para registrar el motivo. Se
guarda en la cita y se devuelve como `cancellation_reason` en lecturas posteriores.

> [!NOTE]
>
> La cancelación solo se permite antes de la extracción de sangre, es decir, mientras la cita está en estado `pending` o
> `confirmed`. Las citas que ya han pasado a `blood_drawn` no se pueden cancelar.

## Añadir paneles

Antes de confirmar la extracción de sangre, añade los paneles de análisis de sangre que quieras realizar llamando a:

```
POST /api/v1/appointments/{id}/panels
```

Pasa un array de UUID de paneles en el campo `panel_ids`. Aniva proporciona los ID de panel para tu cuenta de socio.

> [!NOTE]
>
> Los paneles deben añadirse antes de la extracción de sangre, es decir, mientras la cita está en estado `pending` o
> `confirmed`. No puedes añadir ni cambiar paneles una vez que la cita ha pasado a
> `blood_drawn`.

## Eliminar paneles

Si necesitas eliminar paneles antes de la extracción de sangre, llama a:

```
DELETE /api/v1/appointments/{id}/panels
```

Pasa un array de UUID de paneles en el campo `panel_ids`. La eliminación es idempotente: cualquier panel que no esté asociado se ignora.

> [!NOTE]
>
> Al igual que añadir paneles, la eliminación solo se permite antes de la extracción de sangre, es decir, mientras la cita está
> en estado `pending` o `confirmed`. No se pueden eliminar paneles una vez que la cita ha pasado a
> `blood_drawn`.

## Biomarcadores individuales

Puedes asociar biomarcadores individuales a una cita como pruebas a la carta, fuera de cualquier panel preconfigurado. Esto resulta útil cuando un profesional quiere una selección a medida en lugar de un paquete predefinido. Los biomarcadores asociados aparecen en la respuesta de la cita como un array `individual_biomarkers` (al mismo nivel que `panels`). Las decisiones de enrutamiento se toman más adelante en el flujo de logística de pedidos según las asignaciones por laboratorio de cada biomarcador.

Añade biomarcadores (idempotente: los biomarcadores ya asociados se conservan):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Elimina biomarcadores (idempotente: los biomarcadores que no están asociados se ignoran):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

Ambos endpoints aceptan un array `biomarker_ids` y validan el conjunto resultante según las reglas de cierre de cada laboratorio: un pedido que no pueda tramitarse correctamente (p. ej., un cociente CRP/HDL sin CRP y HDL) devuelve `400` con los biomarcadores que tendrías que añadir y no guarda nada. Usa [Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) para consultar los ID de biomarcadores.

> [!NOTE]
>
> Al igual que las modificaciones de paneles, los biomarcadores individuales solo se pueden añadir o eliminar antes de la extracción de sangre,
> es decir, mientras la cita está en estado `pending` o `confirmed`. Una vez que la cita pasa a
> `blood_drawn`, la instantánea personalizada queda congelada.

## Previsualizar los requisitos de recipientes

Después de añadir paneles o biomarcadores individuales, previsualiza los recipientes físicos de recogida de muestras que se necesitarán para la toma de muestras:

```
GET /api/v1/appointments/{id}/preview
```

El array `containers` de la respuesta incluye el tipo, el nombre, el color del tapón, el volumen, el número de artículo del fabricante y la cantidad de cada recipiente necesario. Esto ayuda a los profesionales a preparar el material correcto antes de la extracción de sangre. La respuesta también incluye un objeto `pricing`: el desglose completo de la cita (las partidas aplicadas, los paneles asociados y una fila por cada biomarcador entregado, con el precio según tu tarifa junto al precio de venta al público; consulta [Precios](https://docs.anivahealth.com/es/concepts/pricing.md)), que se rellena cuando la cita tiene pruebas asociadas y tu clave tiene el scope `prices_view`; en caso contrario, es `null`. `routing` no se expone nunca de forma intencionada y siempre es `null`.

> [!NOTE]
>
> La previsualización refleja los paneles y biomarcadores asociados en ese momento. Si añades o eliminas paneles
> después de previsualizar, vuelve a llamar al endpoint de previsualización para obtener los requisitos de recipientes actualizados.

## Confirmar la extracción de sangre

Después de la extracción de sangre, envía los códigos de laboratorio (códigos de barras de los tubos) para iniciar el flujo de pedidos de laboratorio:

```
POST /api/v1/appointments/{id}/confirm
```

Envía `lab_code` cuando se imprime un único código en todos los tubos (extracción venosa), o `lab_codes` con una entrada
por código —cada una con los `panel_ids` que cubre— cuando cada panel se extrae en sus propios tubos con
su propio código (extracción capilar). En ese caso, cada panel constituye su propia solicitud de laboratorio con su código. Los
códigos se devuelven como `lab_codes` en la cita.

En una extracción capilar, la muestra se reparte en microtainers. Los paneles van primero, por orden de reserva. Los biomarcadores
individuales llenan después el espacio libre de los microtainers de los paneles. Cuando necesitan más espacio, abren
nuevos microtainers. Los repartimos de forma uniforme. Cada microtainer admite como máximo 150 µl de biomarcadores
individuales. Las llamadas que modifican paneles o biomarcadores devuelven `400` cuando el conjunto resultante incumple
esta regla.

Esto cambia el estado de la cita a `blood_drawn` e inicia el procesamiento en el laboratorio. Esta acción es irreversible.

## Recogida del envío

> [!WARNING]
>
> Se ha **eliminado** `POST /api/v1/appointments/pickup`, junto con el estado de cita
> `shipment_picked_up`. Ahora devuelve `405 Method Not Allowed`, porque la ruta pasa a la
> ruta de cita por ID. En su última fase, el endpoint era un no-op que aceptaba la llamada y
> no hacía nada, por lo que eliminarlo no cambia ningún comportamiento del que dependieras.

Para seguir el progreso tras la extracción de sangre, consulta cada entrada del array `shipments` incluido en la cita
mediante [Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md): cada envío tiene su propio `status`
y un historial `status_updates`.

## Vincular envíos

Una cita puede vincularse a uno o más envíos (y viceversa: la relación es
de muchos a muchos). El conjunto actual de vínculos aparece directamente en ambos lados:

* en la cita, como un array `shipments` de entradas `{ id, added_at }`;
* en el envío, como un array `appointments` de entradas `{ id, added_at }`.

Ambos arrays están ordenados del vínculo más antiguo al más reciente. Cada `id` remite al endpoint canónico de detalle
([Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md) /
[Obtener cita](https://docs.anivahealth.com/es/api/appointments/get-appointment.md)) para obtener el payload completo.

Los envíos se vinculan en el momento de su creación mediante el campo `appointment_id` en
[Crear envío](https://docs.anivahealth.com/es/api/shipments/create-shipment.md). Tras la creación, gestiona los vínculos desde el envío
con [Vincular citas a un envío](https://docs.anivahealth.com/es/api/shipments/attach-appointments-to-shipment.md) y
[Desvincular citas de un envío](https://docs.anivahealth.com/es/api/shipments/detach-appointments-from-shipment.md); cada uno devuelve
la lista de citas resultante para ese envío. Para consultar todos los paquetes de una cita,
usa [Listar envíos](https://docs.anivahealth.com/es/api/shipments/list-shipments.md) con `?appointment_id=`.

La regla de modificación es: los vínculos pueden crearse o eliminarse cuando O BIEN

* la cita ya ha pasado la extracción de sangre (`blood_drawn`), o
* el envío se creó hace menos de 24 horas.

Fuera de ese plazo, el vínculo queda bloqueado para que los registros históricos permanezcan estables.

## Obtener resultados de laboratorio

Cuando el laboratorio haya procesado las muestras de sangre, obtén los resultados clínicos y genéticos:

```
GET /api/v1/appointments/{id}/results
```

La respuesta incluye las pruebas planificadas (estado `planned`) junto con los resultados recibidos, para que puedas
hacer seguimiento de lo que aún está pendiente. El campo `status` de nivel superior es `in_progress` hasta que se cierra
cada envío, momento en el que pasa a `completed` (o a `fault` cuando ninguno devuelve resultados); úsalo para saber si el
trabajo de laboratorio de la cita ha terminado. Un [webhook](https://docs.anivahealth.com/es/concepts/webhooks.md) `appointment.results.completed`
te avisa cuando eso ocurre, así que no necesitas hacer consultas periódicas. El
array `submissions` lo desglosa por solicitud de laboratorio, cada una con su `lab_code`. Cada
resultado recibido y cada documento llevan el `lab_code` con el que se registraron. Los informes de laboratorio en PDF se
referencian en el array `documents`: usa `GET /api/v1/documents/{id}` para descargarlos.

## Ejemplo de cita

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


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