Campos
UUID generado automáticamente por Aniva. Úsalo para añadir paneles, confirmar la extracción de sangre y obtener los resultados.
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.
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).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.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.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.
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ó.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.Paneles asociados a esta cita, como entradas
{ panel_id, added_at }. Consulta
Añadir paneles.Biomarcadores a la carta asociados a esta cita, como entradas
{ biomarker_id, added_at }. Consulta
Biomarcadores individuales.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.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
statusde nivel superior esin_progressocompleted. - Progreso del envío (en tránsito, entregado, etc.) → sigue cada entrada del array
shipmentsincluido en la cita hasta Obtener envío: cada envío tiene su propiostatusy un registro de eventosstatus_updates.
appointment.*, por ejemplo
appointment.confirmed. Una nueva hora o ubicación envía appointment.rescheduled.Listar citas
Obtén todas las citas accesibles para tu clave API:?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: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 undraw_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: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: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: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 arrayindividual_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):
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: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: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
Para seguir el progreso tras la extracción de sangre, consulta cada entrada del arrayshipments 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
shipmentsde entradas{ id, added_at }; - en el envío, como un array
appointmentsde entradas{ id, added_at }.
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.
Obtener resultados de laboratorio
Cuando el laboratorio haya procesado las muestras de sangre, obtén los resultados clínicos y genéticos: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.