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

# Crear cita

> Programar una cita de extracción de sangre para un perfil en un centro de análisis

Programa una cita para una extracción de sangre de un perfil de paciente en una ubicación de pruebas concreta. Una vez creada, la cita pasa al estado `confirmed` por defecto (algunas ubicaciones pueden usar `pending` por defecto; es un ajuste por ubicación). Usa [Añadir paneles](https://docs.anivahealth.com/es/api/appointments/add-panels.md) para asociar paneles de análisis de sangre antes de [confirmar la extracción de sangre](https://docs.anivahealth.com/es/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> Un perfil puede tener como máximo **una** cita por ubicación y hora. Crear una cita para una
> franja que el perfil ya ocupa devuelve `409` con el `appointment_id` existente en lugar de una
> segunda cita, de modo que una solicitud reintentada o repetida por error nunca puede duplicar una
> reserva. Consulta [Citas duplicadas](#citas-duplicadas).

Envía una cabecera opcional `Idempotency-Key` para que esta creación se pueda reintentar con seguridad: repetir la misma clave devuelve la respuesta original en lugar de crear otra. Consulta [Idempotencia](https://docs.anivahealth.com/es/concepts/idempotency.md).

Requiere el scope `appointments_schedule`.

## Solicitud

### Parámetros del cuerpo

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

UUID del perfil de paciente para el que se crea la cita.

**location\_id** `string` *required*

UUID de la ubicación de pruebas donde tendrá lugar la extracción de sangre. Usa [Listar
ubicaciones](https://docs.anivahealth.com/es/api/locations/list-locations.md) para encontrar los ID de ubicación disponibles.

**scheduled\_at** `string` *required*

Fecha y hora de la cita en formato ISO 8601 (p. ej., `2026-05-15T10:30:00Z` o
`2026-05-15T12:30:00+02:00`). **Debe incluir un indicador de zona horaria**, ya sea `Z` o un
desplazamiento explícito como `+02:00`; las fechas y horas sin zona horaria se rechazan. Debe
estar en el futuro.

Debe ser el inicio exacto de una franja en la cuadrícula de la ubicación, y la franja debe seguir
teniendo capacidad; consulta primero [Obtener disponibilidad](https://docs.anivahealth.com/es/api/locations/get-availability.md). Las
horas fuera de la cuadrícula devuelven `400`; una franja que ya se ha llenado devuelve `409`. En
las ubicaciones gestionadas por Aniva también debe ser con al menos 12 horas de antelación; consulta
[Antelación mínima](#antelacion-minima).

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

Hasta 5 direcciones que reciben un correo cada una cuando todos los resultados de laboratorio son
definitivos. El correo enlaza a la página de resultados en el panel de administración de Aniva. Tu
clave necesita acceso `results_view` al paciente; si no, devuelve `403`. Omítelo para usar las
direcciones predeterminadas del grupo del paciente. Una lista vacía desactiva los correos.
Consulta [Correos de resultados listos](https://docs.anivahealth.com/es/concepts/results.md#correos-de-resultados-listos).

**draw\_method** `string`

Cómo se realiza la extracción de sangre: `capillary` o `venous`. Omítelo para usar el
`default_draw_method` de la ubicación. La ubicación debe incluir el método en sus `draw_methods`;
si no, devuelve `400`.

## Respuesta

Si la solicitud tiene éxito, la API devuelve `201 Created` con la nueva cita.

**id** `string` *required*

Identificador único de la cita (UUID).

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

UUID del perfil al que pertenece esta cita.

**location\_id** `string`

UUID del centro de análisis donde se realiza la extracción de sangre.

**scheduled\_at** `string`

Fecha y hora programadas de la cita como instante UTC (ISO 8601 con sufijo `Z`, p. ej.,
`2026-05-15T10:30:00Z`). Puede ser `null`.

**status** `string` *required*

Estado actual de la cita. Puede ser `pending`, `confirmed`, `blood_drawn` o `cancelled`. El grado
de avance de los resultados de laboratorio se obtiene en [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md);
el progreso detallado de los envíos, a partir de cada entrada del array `shipments` integrado (ver
más abajo) consultándolo en [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ó.

**profile** `object` *required*

El perfil del paciente asociado a esta cita.

**perfil**

**id** `string`

Identificador único del perfil (UUID).

**handle** `string`

Alias o nombre de usuario del perfil. Puede ser `null`.

**first\_name** `string`

Nombre. Puede ser `null`.

**last\_name** `string`

Apellido. Puede ser `null`.

**email** `string`

Dirección de correo electrónico. Puede ser `null`.

**phone** `string`

Número de teléfono en formato E.164. Puede ser `null`.

**sex** `integer`

Sexo biológico según ISO/IEC 5218. Puede ser `null`.

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

Fecha de nacimiento en formato `YYYY-MM-DD`. Puede ser `null`.

**height** `number`

Altura en centímetros. Puede ser `null`.

**weight** `number`

Peso en kilogramos. Puede ser `null`.

**language** `string`

Idioma preferido: uno de los 32 códigos de [Crear perfil](https://docs.anivahealth.com/es/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Indica si este perfil recibe correos transaccionales (programáticos). Puede ser `null`.

**panels** `AppointmentPanel[]` *required*

Paneles asociados actualmente a esta cita. Vacío en citas recién creadas; asócialos mediante
[Añadir paneles](https://docs.anivahealth.com/es/api/appointments/add-panels.md). Consulta los detalles del panel (nombre,
biomarcadores) mediante [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md).

**Campos de asociación de panel**

**panel\_id** `string`

UUID del panel: contrástalo con [Listar paneles](https://docs.anivahealth.com/es/api/panels/list-panels.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que el panel se asoció por primera vez a esta cita.

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

Biomarcadores a la carta asociados a esta cita fuera de cualquier panel. Vacío en citas recién
creadas; asócialos mediante [Añadir biomarcadores individuales](https://docs.anivahealth.com/es/api/appointments/add-individual-biomarkers.md).
Cruza cada `biomarker_id` con [Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md) para obtener
los datos de visualización.

**Campos de biomarcador individual**

**biomarker\_id** `integer`

Identificador del biomarcador: contrástalo con
[Listar biomarcadores](https://docs.anivahealth.com/es/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que el biomarcador se asoció por primera vez a esta cita.

**shipments** `AppointmentShipmentLink[]` *required*

Envíos vinculados a esta cita, ordenados del vínculo más antiguo al más reciente. Vacío en citas
recién creadas; vincúlalos mediante [Crear envío](https://docs.anivahealth.com/es/api/shipments/create-shipment.md) (con
`appointment_id`) o [Asociar citas a un envío](https://docs.anivahealth.com/es/api/shipments/attach-appointments-to-shipment.md).

**Campos de vínculo de envío**

**id** `string`

Identificador de referencia del envío: contrástalo con
[Obtener envío](https://docs.anivahealth.com/es/api/shipments/get-shipment.md).

**added\_at** `string`

Marca de tiempo ISO 8601 en la que el envío se vinculó por primera vez a esta cita.

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

Códigos de laboratorio (códigos de barras de los tubos) registrados para esta cita, en orden de escaneo. Vacío hasta que se confirme
la extracción de sangre. Una extracción venosa lleva un único código impreso en todos los tubos; una extracción capilar lleva un
código por microtubo. Los resultados y documentos de [Obtener resultados](https://docs.anivahealth.com/es/api/appointments/get-results.md) hacen referencia
a estos códigos mediante `lab_code`.

## Antelación mínima

Las citas en ubicaciones gestionadas por Aniva deben reservarse con al menos **12 horas** de
antelación; reservar dentro de ese margen devuelve `400`. [Obtener disponibilidad](https://docs.anivahealth.com/es/api/locations/get-availability.md)
ya omite esas franjas, así que todo lo que aparezca en esa cuadrícula se puede reservar.

Las ubicaciones que gestionas tú mismo no tienen antelación mínima: las reservas para el mismo día y sin cita previa siguen funcionando igual.

## Citas duplicadas

Un perfil puede tener como máximo una cita no cancelada por ubicación e instante: no se puede hacer
una extracción de sangre dos veces a una misma persona en el mismo lugar y momento, por muchas
sillas que tenga la ubicación.

Crear una cita para una franja que el perfil ya ocupa devuelve `409` con un `appointment_id` que
indica la cita que ya existe:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Gestiónalo tratando la solicitud como ya aplicada: obtén la cita con
[Obtener cita](https://docs.anivahealth.com/es/api/appointments/get-appointment.md), muévela con
[Actualizar cita](https://docs.anivahealth.com/es/api/appointments/update-appointment.md) o anúlala con
[Cancelar cita](https://docs.anivahealth.com/es/api/appointments/cancel-appointment.md). No reintentes la creación: seguirá devolviendo
`409`.

Esto hace que las creaciones repetidas sean seguras: una solicitud que reenvíes tras un tiempo de
espera agotado, o un formulario enviado dos veces, no puede generar dos citas para el mismo paciente
a la misma hora.

> [!NOTE]
>
> `appointment_id` solo aparece en el `409` por duplicado. El `409` por capacidad —cuando la franja
> está llena porque la ocupan *otros* pacientes— devuelve solo `error`, y en ese caso lo adecuado es
> elegir otra franja en [Obtener disponibilidad](https://docs.anivahealth.com/es/api/locations/get-availability.md).

## Respuestas de error

| Estado | Descripción |
| - | - |
| `400` | Error de validación — por ejemplo, `scheduled_at` está en el pasado, faltan menos de 12 horas en una ubicación operada por Aniva, no coincide con el inicio exacto de una franja de la cuadrícula de la ubicación o la ubicación no dispone de recipientes para `draw_method`. |
| `403` | Prohibido — tu clave de API no tiene acceso a esta operación, o `results_ready_emails` está configurado sin acceso `results_view` al paciente. |
| `404` | Perfil o ubicación no encontrados, o la ubicación está inactiva. |
| `409` | Este perfil ya tiene una cita en esta ubicación y a esta hora (incluye `appointment_id`), la franja está completa, la ubicación cierra en esa fecha, se ha reutilizado `Idempotency-Key` con un cuerpo distinto o su solicitud original aún no ha finalizado. |
| `500` | Error interno del servidor. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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