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

# Resultats

> Com funcionen els resultats i documents de laboratori a l'API d'Aniva: valors de biomarcadors, intervals de referència, informes de laboratori i webhooks de resultats.

Un cop es confirma una extracció de sang i el laboratori processa les mostres, els resultats queden disponibles a la cita. Els resultats s'obtenen mitjançant `GET /api/v1/appointments/{id}/results` i inclouen resultats de biomarcadors clínics, resultats de biomarcadors genètics i documents d'informe de laboratori descarregables.

## Estat dels resultats

El camp `status` de nivell superior de la resposta dels resultats indica el progrés general del processament:

| Estat | Significat |
| - | - |
| `in_progress` | El laboratori encara està processant alguns enviaments. |
| `completed` | Tots els enviaments s'han tancat i almenys un ha emès resultats. |
| `fault` | Tots els enviaments han fallat sense emetre resultats. No queda cap resultat pendent. |

Els resultats individuals dins de la resposta tenen el seu propi estat per resultat (consulta més avall), de manera que pots mostrar resultats parcials mentre l'estat general encara és `in_progress`.

Per saber quan canvien els resultats, subscriu-te als [webhooks](https://docs.anivahealth.com/ca/concepts/webhooks.md). `appointment.results.updated` s'activa amb cada canvi del cos dels resultats, i `appointment.results.completed` s'activa quan l'estat de nivell superior passa a `completed`. Les comandes de kits de prova a casa envien els mateixos esdeveniments amb el prefix `home_kit_order.`. Cada esdeveniment inclou l'URL dels resultats per consultar-lo. Pots continuar fent consultes periòdiques a aquest endpoint per reconciliar les dades.

La matriu `submissions` desglossa l'estat de nivell superior per petició de laboratori. Una extracció de sang que inclou diversos tubs o diversos laboratoris té diverses entrades, cadascuna amb el `lab_code` (codi de barres del tub) amb què es va registrar i el seu propi estat `in_progress` / `completed` / `fault`. Una entrada `fault` ha estat rebutjada o abandonada al laboratori i no emetrà mai resultats: sovint la mostra s'ha traslladat a un altre laboratori, que aleshores registra la seva pròpia entrada. L'estat de nivell superior és `completed` quan totes les entrades s'han tancat i almenys una ha emès resultats. Cada resultat rebut i cada document porta el mateix `lab_code`, així que pots saber de quin tub prové un valor.

## Resultats clínics

Els resultats clínics representen mesures estàndard de biomarcadors en sang, com ara els nivells de vitamina D, el colesterol, les hormones tiroidals, etc.

Cada resultat clínic inclou:

* **`id`** — l'identificador de fila del resultat de laboratori. Es manté igual quan el laboratori corregeix aquesta fila, així que fes-lo servir per fer un upsert. `null` per a un resultat `planned`.
* **`biomarker_name`** i **`category`** — què s'ha mesurat i la seva agrupació (p. ex., vitamines, hormones).
* **`lab_code`** — el codi de laboratori (codi de barres del tub) amb què es va registrar el resultat, un dels codis de laboratori de la comanda. `null` per a un resultat `planned` i per als resultats que el laboratori ha informat sense codi.
* **`value`** i **`value_operator`** — la mesura efectiva. L'operador és `eq` (igual) per a valors exactes, o `lt`/`gt` quan el laboratori informa un valor per sota o per sobre de l'interval mesurable.
* **`unit`** — la unitat de mesura (p. ex., ng/mL, µIU/mL).
* **`reference_range_lab`** — els límits mínim i màxim normals i òptims informats pel laboratori per a aquest resultat, convertits a la mateixa escala que `value`. Un límit que el laboratori deixa obert és `null`, de manera que un interval unilateral com `< 50` arriba com `normal_min: null, normal_max: 50`. Cada resultat porta l'interval amb què es va mesurar, així que un pacient amb resultats de diverses extraccions de sang o laboratoris rep l'interval adequat per a cada resultat.
* **`reference_range_lab_absent_reason`** — per què `reference_range_lab` és `null`. `null` quan hi ha interval, i en un resultat `planned`. Consulta [Quan no hi ha interval de laboratori](#quan-no-hi-ha-interval-de-laboratori).
* **`aniva_range`** — Valors de comparació recopilats per Aniva, a la mateixa escala que `value`. Varien segons l'edat, el sexe i la setmana d'embaràs. `normal_*` és l'interval general. `optimal_*` és un interval més estret. Els valors són només informatius. No són consell mèdic, ni un diagnòstic ni una valoració del resultat. Aniva no hi assigna cap indicador. Fes servir `reference_range_lab` com a estàndard per al resultat. `null` quan la teva clau no té l'àmbit `aniva_ranges_view` o quan Aniva no té valors per a aquest biomarcador.
* **`tested_at`** — la data en què es va fer la prova.
* **`comment`** — anotació de text lliure del laboratori sobre aquest resultat concret (p. ex., orientació sobre l'interval de referència, avisos sobre la qualitat de la mostra). `null` quan el laboratori no n'ha adjuntat cap.
* **`status_reason`** — per què un resultat `likely_wrong` és dubtós, o per què un resultat `fault` o `undeliverable` no és utilitzable. `null` per a qualsevol altre estat. És diferent de `comment`, que és la nota pròpia del laboratori i sovint és buida en els resultats amb error.
* **`origin`** — qui ha lliurat el document d'on prové el valor, amb els mateixos valors que l'`origin` del document més avall. Un valor d'un document pujat (`member_upload`, `staff_upload`, `partner_upload`) prové de la lectura que fa Aniva del fitxer, no d'un informe de laboratori: comprova'l amb el fitxer abans de fer-ne un ús clínic. `null` per a un resultat `planned`.
* **`lab_reported`** — la línia pròpia de l'informe del laboratori que ha fet l'anàlisi, literal i sense convertir. Consulta més avall.

### Intervals d'Aniva

`aniva_range` conté valors de comparació que Aniva ha recopilat a partir de fonts publicades i
de la seva pròpia selecció. Els intervals varien segons l'edat, el sexe i la setmana d'embaràs.
`sources` enumera les fonts publicades que Aniva ha registrat per als valors. La llista pot estar buida.

> [!WARNING]
>
> Els valors són informació general. No són consell mèdic, ni un diagnòstic, ni una
> troballa mèdica ni una valoració d'un resultat. Aniva no els proporciona com a producte
> sanitari. Aniva no hi compara cap resultat ni hi assigna cap indicador.
> `reference_range_lab` i la valoració d'un metge continuen sent l'estàndard per a un resultat.

Normes per al teu producte:

* Mostra l'interval d'Aniva només com a complement de l'interval del laboratori, mai en el seu lloc.
* Si derives un indicador, un avís o una recomanació de l'interval d'Aniva, ho fas en nom
  propi i sota la teva pròpia responsabilitat.
* Mostra l'avís del teu acord amb Aniva allà on mostris l'interval d'Aniva.

Per obtenir-hi accés, signa l'acord breu sobre els intervals d'Aniva. Aleshores afegim l'àmbit
`aniva_ranges_view` a la teva clau. Els valors poden canviar sense avís previ.

### Valors normalitzats enfront de la línia pròpia del laboratori

`value`, `unit` i `reference_range_lab` estan normalitzats: convertim cada mesura a la unitat canònica del biomarcador i l'informem amb el nostre propi nom de biomarcador, de manera que el mateix analit és comparable entre laboratoris i al llarg del temps. Això és el que vols per seguir tendències i comparar entre laboratoris, i no és el que veu un metge quan revisa el PDF del laboratori: una fosfatasa alcalina impresa com `48 U/l (40 - 129)` t'arriba com `0.8 µkat/L`.

`lab_reported` inclou aquesta línia impresa al costat: el nom i el codi de l'analit del laboratori, el valor i la unitat tal com s'han imprès, l'interval de referència tant en format de text (`< 50`, `> 55`, `40 - 129`) com amb els límits propis del laboratori sense convertir, a més del seu indicador d'anormalitat, l'estat del resultat i la nota.

Fes servir `lab_reported` quan una persona estigui reconciliant les teves dades amb l'informe del laboratori, i els camps canònics per a tot el que sigui calculat. Només s'emplenen els camps que el laboratori ha enviat realment; a `lab_reported` no s'infereix, no s'assigna per defecte ni es converteix res, i tot l'objecte és `null` quan no tenim cap registre en brut per a un resultat.

### Quan no hi ha interval de laboratori

Quan `reference_range_lab` és `null`, `reference_range_lab_absent_reason` t'indica per què:

| Valor | Significat | Mostra |
| - | - | - |
| `not_provided` | No existeix cap interval. El laboratori no n'ha enviat cap. | "No aplicable" |
| `lab_text_only` | El laboratori només ha imprès text, com un objectiu, un nivell de risc o un interval per etapa vital. | El text de `lab_reported.reference_range` |
| `not_measured` | El resultat és `undeliverable`, així que no hi ha cap valor per comparar. | El camp `status_reason` |

Alguns laboratoris imprimeixen un objectiu o un nivell de risc en lloc d'un interval de referència, per exemple
`Ziel: <200. >240 hoch` o `<5.7 neg >=6.5 pos`. Aquests valors no van a `reference_range_lab`, així que els seus
límits són `null` i el motiu és `lab_text_only`. Mostra el text imprès literalment.

Un interval unilateral com `< 20` és un interval. Arriba a `reference_range_lab` amb un límit
`null`, i el motiu és `null`. Mantén obert l'extrem obert quan el mostris.

### Estats dels resultats clínics

| Estat | Significat |
| - | - |
| `planned` | La prova s'ha sol·licitat, però els resultats encara no han arribat del laboratori. |
| `received` | El laboratori ha retornat un resultat. |
| `corrected` | Un revisor humà ha modificat el valor informat pel laboratori. |
| `likely_wrong` | La comprovació automàtica d'Aniva o el membre dubta del valor. No està confirmat: no el mostris com una troballa sense revisió. Consulta `status_reason`. |
| `fault` | El laboratori ha lliurat un resultat confirmat com a erroni — **no el facis servir clínicament**. `value` encara conté la xifra errònia; consulta `status_reason`. |
| `undeliverable` | El laboratori no ha pogut obtenir un valor. `value` és `null`; consulta `status_reason`. |

> [!TIP]
>
> Quan mostris resultats als pacients, fes servir el camp `value` directament — ja reflecteix el
> valor corregit quan n'hi ha un.

> [!WARNING]
>
> No presentis mai un resultat `fault` com una troballa — el seu `value` està emplenat, però s'ha confirmat que és incorrecte.

## Resultats genètics

Els resultats genètics representen troballes a nivell de gen a partir d'una anàlisi d'ADN. Cada resultat correspon a un gen (p. ex., APOE, MTHFR) i inclou:

* **`id`** — l'identificador de fila del resultat de laboratori. Es manté igual quan el laboratori corregeix aquesta fila, així que fes-lo servir per fer un upsert. `null` per a un resultat `planned`.
* **`gene`** — el símbol del gen.
* **`lab_code`** — el codi de laboratori (codi de barres del tub) amb què es va registrar el resultat. `null` per a un resultat `planned` i per als resultats que el laboratori ha informat sense codi.
* **`genotype`** — el genotip detectat (p. ex., E3/E4).
* **`clinical_significance`** — una classificació de la troballa basada en l'ACMG.
* **`risk_description`** — una explicació llegible per a persones del que significa el genotip.
* **`comment`** — anotació de text lliure del laboratori sobre aquest resultat concret. `null` quan el laboratori no n'ha adjuntat cap.
* **`status_reason`** — per què un resultat `likely_wrong` és dubtós, o per què un resultat `fault` o `undeliverable` no és utilitzable. `null` per a qualsevol altre estat.
* **`origin`** — qui ha lliurat el document d'on prové el valor, igual que als resultats clínics.
* **`variants`** — les variants genètiques específiques detectades, cadascuna amb detall a nivell d'SNV.

### Valors de significació clínica

| Valor | Categoria |
| - | - |
| `pathogenic`, `likely_pathogenic` | Causant o probablement causant de malaltia |
| `uncertain` | Variant de significat incert (VUS) |
| `likely_benign`, `benign` | No causant de malaltia |
| `high_risk`, `moderate_risk`, `low_risk` | Classificació del nivell de risc |
| `protective` | Variant protectora |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Troballes farmacogenòmiques |

### Estats dels resultats genètics

| Estat | Significat |
| - | - |
| `planned` | La prova s'ha sol·licitat, però els resultats encara no han arribat. |
| `received` | El laboratori ha retornat un resultat. |
| `likely_wrong` | La comprovació automàtica d'Aniva o el membre dubta del genotip. No confirmat. Consulta `status_reason`. |
| `fault` | El laboratori ha lliurat un resultat confirmat com a erroni — **no el facis servir clínicament**. Consulta `status_reason`. |
| `undeliverable` | El laboratori no ha pogut obtenir un genotip. Consulta `status_reason`. |

### Estructura de les variants

Cada resultat genètic conté una matriu `variants`. Cada variant inclou:

* **`name`** — nom comú (p. ex., APOE E4).
* **`clinical_significance`** — significat a nivell de variant (pot diferir del significat a nivell de gen).
* **`conditions`** — malalties o afeccions associades amb descripcions.
* **`snvs`** — les variants d'un sol nucleòtid subjacents, cadascuna amb `rs_id`, `allele`, `reference_allele` i notació HGVS opcional.

## Documents

La matriu `documents` de la resposta dels resultats conté referències a fitxers d'informes de laboratori descarregables. Cada document té:

* **`id`** — un UUID de fitxer. Passa'l a `GET /api/v1/documents/{id}` per descarregar el fitxer.
* **`file_name`** — el nom del fitxer, el mateix que envia la descàrrega (p. ex., `20260405 - Quade Befund - 7642001234.pdf`).
* **`original_file_name`** — el nom del fitxer exactament tal com el va lliurar el laboratori o qui el va pujar (p. ex., `7642001234_B0012_FA_E.pdf`).
* **`origin`** — qui ha lliurat el fitxer: `lab`, `member_upload`, `staff_upload` o `partner_upload` (el vas pujar amb [Pujar un document](https://docs.anivahealth.com/ca/api/documents/upload-document.md)).
* **`content_type`** — el tipus de medi del fitxer (p. ex., `application/pdf`). La majoria d'informes són PDF. Els escanejos pujats poden ser imatges o fitxers CSV.
* **`etag`** — la versió del contingut del fitxer; canvia cada vegada que canvien els bytes. Desa'l i torna a descarregar el fitxer només quan canviï. És l'etiqueta d'entitat HTTP estàndard, com la que fan servir S3 o Google Cloud Storage.
* **`size_bytes`** — la mida del fitxer en bytes.
* **`lab_code`** — el codi de laboratori (codi de barres del tub) al qual pertany l'informe; `null` quan el laboratori no n'ha registrat cap.

> [!NOTE]
>
> L'accés als documents es valida segons el perfil propietari del document.

## Enviar els resultats per correu al client

Pots avisar el client per correu electrònic que els seus resultats estan a punt. Crida
[Enviar resultats per correu](https://docs.anivahealth.com/ca/api/appointments/email-results.md) per a una cita, o
[Enviar resultats per correu](https://docs.anivahealth.com/ca/api/home-kit-orders/email-results.md) per a una comanda de kit de prova a casa. Cada crida envia un correu.
Les crides no es dedupliquen.

* El correu electrònic s'envia a l'`email` del perfil. Una adreça `@aniva.email` provisional es rebutja.
* El correu electrònic mostra el nom i el logotip del grup de perfils principal del perfil.
* El correu electrònic és en el `language` del perfil, en anglès per defecte.
* Defineix `with_reports` com a `true` per adjuntar els informes de laboratori.
* Afegeix `note` per mostrar una nota personal al correu electrònic, de com a màxim 1.000 caràcters.

Si el perfil té desactivats els correus transaccionals, la crida retorna `409` amb el motiu
`unsubscribed`. Per tornar-los a activar, defineix `transactional_emails_enabled` com a `true` amb
[Actualitzar el perfil](https://docs.anivahealth.com/ca/api/profiles/update-profile.md).

## Correus d'avís de resultats a punt

Pots rebre un correu electrònic quan els resultats d'una reserva estiguin a punt. Defineix `results_ready_emails` amb fins a 5
adreces a [Crear una cita](https://docs.anivahealth.com/ca/api/appointments/create-appointment.md) o
[Crear una comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/create-home-kit.md). Canvia la llista més endavant amb
[Actualitzar una cita](https://docs.anivahealth.com/ca/api/appointments/update-appointment.md) o
[Actualitzar una comanda de kit de prova a casa](https://docs.anivahealth.com/ca/api/home-kit-orders/update-home-kit.md); `[]` desactiva els correus.

* Demana'ns que configurem adreces de correu predeterminades per al teu grup de perfils. Una reserva creada sense
  `results_ready_emails` les rep. Una llista les substitueix per a aquella reserva, així que inclou la teva
  adreça de correu predeterminada per mantenir-la. `[]` no envia cap correu.
* Cada adreça rep un sol correu un cop tots els resultats de laboratori de la reserva són definitius.
* Una adreça afegida després que els resultats siguin definitius rep el correu de seguida.
* El correu enllaça a la pàgina de resultats del panell d'administració d'Aniva. El client no el rep.
* La teva clau necessita accés `results_view` al pacient. Sense aquest accés, la sol·licitud retorna `403`.

## Mostra els resultats a la teva aplicació

[Crear una sessió incrustada](https://docs.anivahealth.com/ca/api/profiles/create-embed-session.md) retorna un URL d'un sol ús per a una pàgina de resultats
només de lectura. Obre'l en un WebView de la teva aplicació perquè el pacient vegi els resultats sense iniciar sessió.

* La teva clau necessita els àmbits `embed` i `results_view` per al pacient. Demana a Aniva l'àmbit
  `embed`.
* Fes la crida des del teu servidor cada vegada que el pacient obri els resultats. L'URL funciona una sola vegada i durant
  5 minuts, i després la pàgina manté una sessió de 60 minuts.
* `route` obre una de les pàgines que publiquem: la llista de biomarcadors, un biomarcador o el Twin 3D.
* `appearance` defineix el tema, el color dels botons i dels enllaços, i si es mostra el teu logotip.
* `report` limita la pàgina a una cita, una comanda de kit de prova a casa o un informe de laboratori que hagis
  pujat amb `POST /api/v1/documents`. Aleshores el pacient només veu els resultats d'aquell informe.
* La pàgina mostra només els resultats de laboratori, igual que aquesta API. No mostra cap fitxer, cap xat ni cap configuració.

## Exemple de resposta de resultats

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