Saltar al contenido principal
Cuando se confirma la extracción de sangre y el laboratorio procesa las muestras, los resultados quedan disponibles en la cita. Los resultados se obtienen mediante GET /api/v1/appointments/{id}/results e incluyen resultados de biomarcadores clínicos, resultados de biomarcadores genéticos y documentos de informes de laboratorio descargables.

Estado de los resultados

El campo status de nivel superior en la respuesta de resultados indica el progreso general del procesamiento: Los resultados individuales dentro de la respuesta tienen su propio estado por resultado (ver más abajo), así que puedes mostrar resultados parciales mientras el estado general sigue en in_progress. Para saber cuándo cambian los resultados, suscríbete a los webhooks. appointment.results.updated se dispara con cada cambio en el cuerpo de los resultados y appointment.results.completed se dispara cuando el estado de nivel superior pasa a completed. Los pedidos de kit de prueba en casa envían los mismos eventos con el prefijo home_kit_order.. Cada evento incluye la URL de resultados para consultar. Puedes seguir consultando periódicamente este endpoint para conciliar. El array submissions desglosa el estado de nivel superior por solicitud de laboratorio. Una extracción de sangre que abarca varios tubos o varios laboratorios tiene varias entradas, cada una con el lab_code (código de barras del tubo) con el que se registró y su propio estado in_progress / completed / fault. Una entrada fault fue rechazada o abandonada en el laboratorio y nunca enviará resultados: a menudo la muestra se trasladó a otro laboratorio, que registra su propia entrada. El estado de nivel superior es completed cuando todas las entradas se han cerrado y al menos una ha enviado resultados. Cada resultado recibido y cada documento llevan el mismo lab_code, así que puedes saber de qué tubo procede cada valor.

Resultados clínicos

Los resultados clínicos representan mediciones estándar de biomarcadores en sangre, como niveles de vitamina D, colesterol, hormonas tiroideas, etc. Cada resultado clínico incluye:
  • id — el identificador de la fila del resultado de laboratorio. Se mantiene igual cuando el laboratorio corrige esa fila, así que úsalo para hacer upsert. null para un resultado planned.
  • biomarker_name y category — qué se ha medido y su categoría (p. ej., Vitaminas, Hormonas).
  • lab_code — el código de laboratorio (código de barras del tubo) con el que se registró el resultado, uno de los códigos de laboratorio del pedido. null para un resultado planned y para resultados que el laboratorio envió sin código.
  • value y value_operator — la medición efectiva. El operador es eq (igual) para valores exactos, o lt/gt cuando el laboratorio informa de un valor por debajo o por encima del rango medible.
  • unit — la unidad de medida (p. ej., ng/mL, µIU/mL).
  • reference_range_lab — límites mínimos y máximos normales y óptimos informados por el laboratorio para este resultado, convertidos a la misma escala que value. Un límite que el laboratorio deja abierto es null, de modo que un intervalo unilateral como < 50 llega como normal_min: null, normal_max: 50. Cada resultado lleva el intervalo con el que se midió, así que un paciente con resultados de varias extracciones de sangre o laboratorios recibe el adecuado para cada resultado.
  • reference_range_lab_absent_reason — por qué reference_range_lab es null. null cuando el intervalo está presente y en un resultado planned. Consulta Cuando no hay intervalo de laboratorio.
  • aniva_range — valores de comparación que Aniva ha recopilado, en la misma escala que value. Varían según la edad, el sexo y la semana de embarazo. normal_* es el intervalo general. optimal_* es un intervalo más estrecho. Los valores son solo informativos. No son asesoramiento médico, ni un diagnóstico, ni una valoración del resultado. Aniva no establece ningún indicador respecto a ellos. Usa reference_range_lab como referencia para el resultado. null cuando tu clave no tiene el scope aniva_ranges_view o cuando Aniva no tiene valores para este biomarcador.
  • tested_at — la fecha en que se realizó la prueba.
  • comment — anotación en texto libre del laboratorio sobre este resultado concreto (p. ej., orientación sobre el intervalo de referencia, avisos sobre la calidad de la muestra). null cuando el laboratorio no adjuntó ninguna.
  • status_reason — por qué un resultado likely_wrong es dudoso, o por qué un resultado fault o undeliverable no se puede usar. null para cualquier otro estado. Es distinto de comment, que es la nota propia del laboratorio y suele estar vacía en los resultados con error.
  • origin — quién entregó el documento del que procede el valor, con los mismos valores que el campo origin del documento más abajo. Un valor de un documento subido (member_upload, staff_upload, partner_upload) procede de la lectura del archivo por parte de Aniva, no de un informe de laboratorio: compruébalo con el archivo antes de darle uso clínico. null para un resultado planned.
  • lab_reported — la línea propia del informe del laboratorio que realizó la prueba, literal y sin convertir. Ver más abajo.

Intervalos de Aniva

aniva_range contiene valores de comparación que Aniva ha recopilado de fuentes publicadas y de su propia selección. Los intervalos varían según la edad, el sexo y la semana de embarazo. sources enumera las fuentes publicadas que Aniva ha registrado para los valores. La lista puede estar vacía.
Los valores son información general. No son asesoramiento médico, ni un diagnóstico, ni un hallazgo médico, ni una valoración de un resultado. Aniva no los proporciona como producto sanitario. Aniva no compara ningún resultado con ellos ni establece indicadores respecto a ellos. reference_range_lab y la valoración de un médico siguen siendo la referencia para un resultado.
Reglas para tu producto:
  • Muestra el intervalo de Aniva solo junto al intervalo del laboratorio, nunca en su lugar.
  • Si derivas un indicador, un aviso o una recomendación a partir del intervalo de Aniva, lo haces en tu propio nombre y bajo tu propia responsabilidad.
  • Muestra el aviso de tu acuerdo con Aniva siempre que muestres el intervalo de Aniva.
Para obtener acceso, firma el breve acuerdo sobre los intervalos de Aniva. Después añadimos el scope aniva_ranges_view a tu clave. Los valores pueden cambiar sin previo aviso.

Valores normalizados frente a la línea del laboratorio

value, unit y reference_range_lab están normalizados: convertimos cada medición a la unidad canónica del biomarcador y la presentamos con nuestro propio nombre de biomarcador, para que el mismo analito sea comparable entre laboratorios y a lo largo del tiempo. Eso es lo que necesitas para ver tendencias y comparar entre laboratorios, y no es lo que ve un médico al revisar el PDF del laboratorio: la fosfatasa alcalina impresa como 48 U/l (40 - 129) te llega como 0.8 µkat/L. lab_reported incluye junto a ello esa línea impresa: el nombre y el código del analito del laboratorio, el valor y la unidad tal como aparecen impresos, el intervalo de referencia tanto en texto (< 50, > 55, 40 - 129) como con los límites propios del laboratorio sin convertir, además de su indicador de anomalía, el estado del resultado y la nota. Usa lab_reported cuando una persona esté conciliando tus datos con el informe del laboratorio, y los campos canónicos para todo lo calculado. Solo se rellenan los campos que el laboratorio envió realmente; nada en lab_reported se infiere, se asigna por defecto ni se convierte, y todo el objeto es null cuando no tenemos ningún registro sin procesar para un resultado.

Cuando no hay intervalo de laboratorio

Cuando reference_range_lab es null, reference_range_lab_absent_reason te indica por qué: Algunos laboratorios imprimen un objetivo o un nivel de riesgo en lugar de un intervalo de referencia, por ejemplo Ziel: <200. >240 hoch o <5.7 neg >=6.5 pos. Estos textos no van en reference_range_lab, así que sus límites son null y el motivo es lab_text_only. Muestra el texto impreso tal cual. Un intervalo unilateral como < 20 sí es un intervalo. Llega en reference_range_lab con un límite en null y el motivo es null. Mantén abierto el extremo abierto cuando lo muestres.

Estados de los resultados clínicos

Al mostrar resultados a los pacientes, usa directamente el campo value, ya que refleja el valor corregido cuando existe.
Nunca presentes un resultado fault como un hallazgo: su campo value tiene un valor, pero está confirmado como incorrecto.

Resultados genéticos

Los resultados genéticos representan hallazgos a nivel génico procedentes de análisis de ADN. Cada resultado corresponde a un gen (p. ej., APOE, MTHFR) e incluye:
  • id — el identificador de la fila del resultado de laboratorio. Se mantiene igual cuando el laboratorio corrige esa fila, así que úsalo para hacer upsert. null para un resultado planned.
  • gene — el símbolo del gen.
  • lab_code — el código de laboratorio (código de barras del tubo) con el que se registró el resultado. null para un resultado planned y para resultados que el laboratorio envió sin código.
  • genotype — el genotipo detectado (p. ej., E3/E4).
  • clinical_significance — una clasificación del hallazgo basada en los criterios ACMG.
  • risk_description — una explicación legible para personas de lo que significa el genotipo.
  • comment — anotación en texto libre del laboratorio sobre este resultado concreto. null cuando el laboratorio no adjuntó ninguna.
  • status_reason — por qué un resultado likely_wrong es dudoso, o por qué un resultado fault o undeliverable no se puede usar. null para cualquier otro estado.
  • origin — quién entregó el documento del que procede el valor, igual que en los resultados clínicos.
  • variants — las variantes genéticas concretas detectadas, cada una con detalle a nivel de SNV.

Valores de significación clínica

Estados de los resultados genéticos

Estructura de las variantes

Cada resultado genético contiene un array variants. Cada variante incluye:
  • name — nombre común (p. ej., APOE E4).
  • clinical_significance — significado a nivel de variante (puede diferir del significado a nivel de gen).
  • conditions — enfermedades o afecciones asociadas con descripciones.
  • snvs — las variantes de un solo nucleótido subyacentes, cada una con rs_id, allele, reference_allele y notación HGVS opcional.

Documentos

El array documents en la respuesta de resultados contiene referencias a archivos descargables de informes de laboratorio. Cada documento tiene:
  • id — un UUID de archivo. Pásalo a GET /api/v1/documents/{id} para descargar el archivo.
  • file_name — el nombre del archivo, el mismo que envía la descarga (p. ej., 20260405 - Quade Befund - 7642001234.pdf).
  • original_file_name — el nombre del archivo exactamente como lo entregó el laboratorio o quien lo subió (p. ej., 7642001234_B0012_FA_E.pdf).
  • origin — quién entregó el archivo: lab, member_upload, staff_upload o partner_upload (lo subiste con Subir documento).
  • content_type — el tipo de medio del archivo (p. ej., application/pdf). La mayoría de los informes son PDF. Los documentos escaneados subidos pueden ser imágenes o archivos CSV.
  • etag — la versión del contenido del archivo; cambia cada vez que cambian los bytes. Guárdalo y vuelve a descargarlo solo cuando cambie. Es la etiqueta de entidad HTTP estándar, tal como la usan S3 o Google Cloud Storage.
  • size_bytes — el tamaño del archivo en bytes.
  • lab_code — el código de laboratorio (código de barras del tubo) al que pertenece el informe; null si el laboratorio no registró ninguno.
El acceso a los documentos se valida con el perfil propietario del documento.

Enviar resultados por correo al cliente

Puedes avisar al cliente por correo electrónico de que sus resultados están listos. Llama a Enviar resultados por correo para una cita o a Enviar resultados por correo para un pedido de kit de prueba en casa. Cada llamada envía un correo electrónico. Las llamadas no se deduplican.
  • El correo se envía al email del perfil. Las direcciones provisionales @aniva.email se rechazan.
  • El correo muestra el nombre y el logo del grupo de perfiles principal del perfil.
  • El correo está en el language del perfil, inglés por defecto.
  • Establece with_reports en true para adjuntar los informes de laboratorio.
  • Añade note para mostrar una nota personal en el correo, de como máximo 1.000 caracteres.
Si el perfil ha desactivado los correos transaccionales, la llamada devuelve 409 con el motivo unsubscribed. Para volver a activarlos, establece transactional_emails_enabled en true con Actualizar perfil.

Correos de resultados listos

Puedes recibir un correo electrónico cuando los resultados de una reserva estén listos. Configura results_ready_emails con hasta 5 direcciones en Crear cita o Crear pedido de kit de prueba en casa. Cambia la lista más adelante con Actualizar cita o Actualizar pedido de kit de prueba en casa; [] desactiva los correos.
  • Pídenos que configuremos direcciones de correo predeterminadas para tu grupo de perfiles. Cualquier reserva creada sin results_ready_emails las recibe. Una lista las sustituye para esa reserva, así que incluye tu dirección predeterminada para conservarla. [] no envía ningún correo.
  • Cada dirección recibe un correo una vez que todos los resultados de laboratorio de la reserva son definitivos.
  • Una dirección añadida después de que los resultados sean definitivos recibe el correo de inmediato.
  • El correo enlaza a la página de resultados en el panel de administración de Aniva. El cliente no lo recibe.
  • Tu clave necesita acceso results_view para el paciente. Sin él, la solicitud devuelve 403.

Mostrar resultados en tu app

Crear sesión integrada devuelve una URL de un solo uso para una página de resultados de solo lectura. Ábrela en un WebView de tu app para que el paciente vea los resultados sin iniciar sesión.
  • Tu clave necesita los scopes embed y results_view para el paciente. Solicita a Aniva el scope embed.
  • Llámala desde tu servidor cada vez que el paciente abra los resultados. La URL funciona una vez y durante 5 minutos, y después la página mantiene una sesión de 60 minutos.
  • route abre una de las páginas que publicamos: la lista de biomarcadores, un biomarcador o el Twin 3D.
  • appearance define el tema, el color de los botones y enlaces, y si se muestra tu logotipo.
  • report limita la página a una cita, un pedido de kit de prueba en casa o un informe de laboratorio que hayas subido con POST /api/v1/documents. El paciente solo verá entonces los resultados de ese informe.
  • La página muestra solo resultados de laboratorio, igual que esta API. No muestra archivos, chat ni ajustes.

Ejemplo de respuesta de resultados