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

# Resultados

> Cómo funcionan los resultados de laboratorio y los documentos en la API de Aniva: valores de biomarcadores, intervalos de referencia, informes de laboratorio y webhooks de resultados.

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:

| Estado | Significado |
| - | - |
| `in_progress` | El laboratorio todavía está procesando algunos envíos. |
| `completed` | Todos los envíos se han cerrado y al menos uno ha enviado resultados. |
| `fault` | Todos los envíos fallaron sin enviar resultados. Ya no quedan resultados pendientes. |

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](https://docs.anivahealth.com/es/concepts/webhooks.md). `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](#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.

> [!WARNING]
>
> 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é:

| Valor | Significado | Mostrar |
| - | - | - |
| `not_provided` | No existe intervalo. El laboratorio no envió ninguno. | "No aplicable" |
| `lab_text_only` | El laboratorio imprimió solo texto, como un objetivo, un nivel de riesgo o un intervalo según la etapa vital. | El texto en `lab_reported.reference_range` |
| `not_measured` | El resultado es `undeliverable`, así que no hay valor que comparar. | El campo `status_reason` |

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

| Estado | Significado |
| - | - |
| `planned` | La prueba está solicitada, pero los resultados aún no han llegado del laboratorio. |
| `received` | El laboratorio ha devuelto un resultado. |
| `corrected` | Un revisor humano ha corregido el valor informado por el laboratorio. |
| `likely_wrong` | La comprobación automática de Aniva o el miembro dudan del valor. Sin confirmar: no lo muestres como un hallazgo sin revisión. Consulta `status_reason`. |
| `fault` | El laboratorio entregó un resultado confirmado como erróneo — **no usar clínicamente**. `value` sigue conteniendo la cifra errónea; consulta `status_reason`. |
| `undeliverable` | El laboratorio no pudo obtener un valor. `value` es `null`; consulta `status_reason`. |

> [!TIP]
>
> Al mostrar resultados a los pacientes, usa directamente el campo `value`, ya que refleja el
> valor corregido cuando existe.

> [!WARNING]
>
> 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

| Valor | Categoría |
| - | - |
| `pathogenic`, `likely_pathogenic` | Causante de enfermedad o probablemente causante de enfermedad |
| `uncertain` | Variante de significado incierto (VUS) |
| `likely_benign`, `benign` | No causante de enfermedad |
| `high_risk`, `moderate_risk`, `low_risk` | Clasificación del nivel de riesgo |
| `protective` | Variante protectora |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Hallazgos farmacogenómicos |

### Estados de los resultados genéticos

| Estado | Significado |
| - | - |
| `planned` | El análisis está solicitado, pero los resultados aún no han llegado. |
| `received` | El laboratorio ha devuelto un resultado. |
| `likely_wrong` | La comprobación automática de Aniva o el miembro duda del genotipo. Sin confirmar. Consulta `status_reason`. |
| `fault` | El laboratorio entregó un resultado confirmado como erróneo — **no usar clínicamente**. Consulta `status_reason`. |
| `undeliverable` | El laboratorio no pudo generar un genotipo. Consulta `status_reason`. |

### 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](https://docs.anivahealth.com/es/api/documents/upload-document.md)).
* **`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.

> [!NOTE]
>
> 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](https://docs.anivahealth.com/es/api/appointments/email-results.md) para una cita o a
[Enviar resultados por correo](https://docs.anivahealth.com/es/api/home-kit-orders/email-results.md) 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](https://docs.anivahealth.com/es/api/profiles/update-profile.md).

## 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](https://docs.anivahealth.com/es/api/appointments/create-appointment.md) o
[Crear pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/create-home-kit.md). Cambia la lista más adelante con
[Actualizar cita](https://docs.anivahealth.com/es/api/appointments/update-appointment.md) o
[Actualizar pedido de kit de prueba en casa](https://docs.anivahealth.com/es/api/home-kit-orders/update-home-kit.md); `[]` 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](https://docs.anivahealth.com/es/api/profiles/create-embed-session.md) 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

```json theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "3f2b8c1e-5d4a-4e7b-9a6c-2d1f0e8b7a54",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 104,
      "biomarker_name": "Vitamin D",
      "category": "Vitamins",
      "value": 38.5,
      "value_operator": "eq",
      "unit_id": 1,
      "unit": "ng/mL",
      "reference_range_lab": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": null,
        "optimal_max": null
      },
      "reference_range_lab_absent_reason": null,
      "aniva_range": {
        "normal_min": 30,
        "normal_max": 100,
        "optimal_min": 30,
        "optimal_max": 60,
        "sources": [
          {
            "title": "Example source title",
            "url": "https://example.com/source"
          }
        ]
      },
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "lab_reported": {
        "name": "Vitamin D (25-OH)",
        "code": "vitd",
        "category": "Endokrinologie",
        "value": "38.5",
        "unit": "ng/ml",
        "reference_range": "30 - 100",
        "reference_range_min": 30,
        "reference_range_max": 100,
        "flag": "normal",
        "result_status": "final",
        "comment": null
      }
    },
    {
      "id": null,
      "status": "planned",
      "status_reason": null,
      "lab_code": null,
      "biomarker_id": 79,
      "biomarker_name": "Thyroid-Stimulating Hormone (TSH)",
      "category": "Hormones",
      "value": null,
      "value_operator": null,
      "unit_id": null,
      "unit": null,
      "reference_range_lab": null,
      "reference_range_lab_absent_reason": null,
      "aniva_range": null,
      "tested_at": null,
      "comment": null,
      "origin": null,
      "lab_reported": null
    }
  ],
  "genetic_results": [
    {
      "id": "b7e41d09-2c6f-4a83-8f15-6e9d3a0c4b21",
      "status": "received",
      "status_reason": null,
      "lab_code": "7642001234",
      "biomarker_id": 348,
      "gene": "APOE",
      "genotype": "E3/E4",
      "clinical_significance": "moderate_risk",
      "risk_description": "Carriers of one APOE E4 allele have a moderately increased risk of Alzheimer's disease.",
      "tested_at": "2026-04-05",
      "comment": null,
      "origin": "lab",
      "variants": [
        {
          "name": "APOE E4",
          "clinical_significance": "moderate_risk",
          "description": "The E4 allele is associated with increased Alzheimer's risk.",
          "hgvs_c": "c.388T>C",
          "hgvs_p": "p.Cys130Arg",
          "conditions": [
            {
              "condition": "Alzheimer's disease",
              "association_description": "Increased risk with one E4 allele",
              "badge": "Moderate Risk"
            }
          ],
          "snvs": [
            {
              "rs_id": "rs429358",
              "allele": "C",
              "reference_allele": "T",
              "hgvs_c": "c.388T>C",
              "hgvs_p": "p.Cys130Arg"
            }
          ]
        }
      ]
    }
  ],
  "documents": [
    {
      "id": "f8a1b2c3-d4e5-4f6a-7b8c-9d0e1f2a3b4c",
      "file_name": "20260405 - Quade Befund - 7642001234.pdf",
      "original_file_name": "7642001234_B0012_FA_E.pdf",
      "origin": "lab",
      "content_type": "application/pdf",
      "etag": "56104b36f860cfd5b41efc716fdf7b6f",
      "size_bytes": 258341,
      "lab_code": "7642001234"
    }
  ]
}
```


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