Saltar al contenido principal
POST
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 para asociar paneles de análisis de sangre antes de confirmar la extracción de sangre.
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.
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. Requiere el scope appointments_schedule.

Solicitud

Parámetros del cuerpo

string
requerido
UUID del perfil de paciente para el que se crea la cita.
string
requerido
UUID de la ubicación de pruebas donde tendrá lugar la extracción de sangre. Usa Listar ubicaciones para encontrar los ID de ubicación disponibles.
string
requerido
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. 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.
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.
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.
string
requerido
Identificador único de la cita (UUID).
string
requerido
UUID del perfil al que pertenece esta cita.
string
UUID del centro de análisis donde se realiza la extracción de sangre.
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.
string
requerido
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; 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.
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.
string[]
requerido
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.
string
requerido
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. Después de la extracción de sangre, es el método que se utilizó.
object
requerido
El perfil del paciente asociado a esta cita.
AppointmentPanel[]
requerido
Paneles asociados actualmente a esta cita. Vacío en citas recién creadas; asócialos mediante Añadir paneles. Consulta los detalles del panel (nombre, biomarcadores) mediante Listar paneles.
AppointmentIndividualBiomarker[]
requerido
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. Cruza cada biomarker_id con Listar biomarcadores para obtener los datos de visualización.
AppointmentShipmentLink[]
requerido
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 (con appointment_id) o Asociar citas a un envío.
string[]
requerido
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 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 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:
Gestiónalo tratando la solicitud como ya aplicada: obtén la cita con Obtener cita, muévela con Actualizar cita o anúlala con Cancelar cita. 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.
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.

Respuestas de error