Saltar al contenido principal
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.

Campos

string
requerido
UUID generado automáticamente por Aniva. Úsalo para añadir paneles, confirmar la extracción de sangre y obtener los resultados.
string
requerido
El UUID del perfil al que pertenece esta cita.
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.
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).
string
requerido
Estado actual del ciclo de vida. Puede ser pending, confirmed, blood_drawn o cancelled. Consulta 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; el progreso detallado del envío (en tránsito, entregado, etc.) se obtiene siguiendo cada entrada del array shipments incluido hasta 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ó.
string
requerido
Marca de tiempo ISO 8601 de cuándo se creó la cita.
string
Marca de tiempo ISO 8601 de la última actualización. Nulo si la cita nunca se ha actualizado.
string[]
requerido
Códigos de laboratorio (códigos de barras de los tubos) registrados en Confirmar extracción de sangre, 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.
object[]
requerido
Paneles asociados a esta cita, como entradas { panel_id, added_at }. Consulta Añadir paneles.
object[]
requerido
Biomarcadores a la carta asociados a esta cita, como entradas { biomarker_id, added_at }. Consulta Biomarcadores individuales.
object[]
requerido
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.
object
requerido
El objeto de perfil completo del paciente, incluido en cada respuesta de cita. Los campos siguientes son un subconjunto. Obtener cita los enumera todos.

Ciclo de vida

Las citas tienen cuatro estados de ciclo de vida:
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: 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: cada envío tiene su propio status y un registro de eventos status_updates.
Cada cambio de estado envía un webhook appointment.*, por ejemplo appointment.confirmed. Una nueva hora o ubicación envía appointment.rescheduled.
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:
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:
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 como Actualizar cita 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.
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:
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.
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:
Pasa un array de UUID de paneles en el campo panel_ids. Aniva proporciona los ID de panel para tu cuenta de socio.
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:
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.
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):
Elimina biomarcadores (idempotente: los biomarcadores que no están asociados se ignoran):
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 para consultar los ID de biomarcadores.
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:
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), 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.
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:
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

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: 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 / Obtener cita) 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. Tras la creación, gestiona los vínculos desde el envío con Vincular citas a un envío y Desvincular citas de un envío; cada uno devuelve la lista de citas resultante para ese envío. Para consultar todos los paquetes de una cita, usa Listar envíos 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:
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 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