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

# Risultati

> Come funzionano i risultati di laboratorio e i documenti nell'API di Aniva: valori dei biomarcatori, intervalli di riferimento, referti di laboratorio e webhook per i risultati.

Dopo che un prelievo di sangue viene confermato e il laboratorio elabora i campioni, i risultati diventano disponibili sull'appuntamento. I risultati si recuperano tramite `GET /api/v1/appointments/{id}/results` e includono risultati di biomarcatori clinici, risultati di biomarcatori genetici e referti di laboratorio scaricabili.

## Stato dei risultati

Il campo `status` di primo livello nella risposta dei risultati indica l'avanzamento complessivo dell'elaborazione:

| Stato | Significato |
| - | - |
| `in_progress` | Alcuni invii sono ancora in fase di elaborazione in laboratorio. |
| `completed` | Tutti gli invii sono chiusi e almeno uno ha prodotto risultati. |
| `fault` | Ogni invio si è interrotto senza produrre risultati. Non sono più attesi risultati. |

I singoli risultati nella risposta hanno un proprio stato (vedi sotto), così puoi mostrare risultati parziali mentre lo stato complessivo è ancora `in_progress`.

Per sapere quando i risultati cambiano, iscriviti ai [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md). `appointment.results.updated` si attiva a ogni modifica del corpo dei risultati, mentre `appointment.results.completed` si attiva quando lo stato di primo livello passa a `completed`. Gli ordini di kit domiciliari inviano gli stessi eventi con il prefisso `home_kit_order.`. Ogni evento contiene l'URL dei risultati da recuperare. Puoi comunque fare polling su questo endpoint per riconciliare i dati.

L'array `submissions` suddivide lo stato di primo livello per richiesta di laboratorio. Un prelievo di sangue che coinvolge più provette o più laboratori ha più voci, ciascuna con il `lab_code` (codice a barre della provetta) con cui è stata registrata e il proprio stato `in_progress` / `completed` / `fault`. Una voce `fault` è stata respinta o abbandonata dal laboratorio e non produrrà mai risultati: spesso il campione è stato spostato in un altro laboratorio, che registra poi una propria voce. Lo stato di primo livello è `completed` quando tutte le voci sono chiuse e almeno una ha prodotto risultati. Ogni risultato ricevuto e ogni documento riporta lo stesso `lab_code`, così puoi sapere da quale provetta proviene un valore.

## Risultati clinici

I risultati clinici rappresentano le misurazioni standard dei biomarcatori del sangue — come i livelli di vitamina D, il colesterolo, gli ormoni tiroidei e così via.

Ogni risultato clinico include:

* **`id`** — l'identificativo della riga del risultato di laboratorio. Resta invariato quando il laboratorio corregge quella riga, quindi usalo per l'upsert. `null` per un risultato `planned`.
* **`biomarker_name`** e **`category`** — cosa è stato misurato e il relativo gruppo (es. Vitamine, Ormoni).
* **`lab_code`** — il codice di laboratorio (codice a barre della provetta) con cui è stato registrato il risultato, uno dei codici di laboratorio dell'ordine. `null` per un risultato `planned` e per i risultati refertati dal laboratorio senza codice.
* **`value`** e **`value_operator`** — la misurazione effettiva. L'operatore è `eq` (uguale) per i valori esatti, oppure `lt`/`gt` quando il laboratorio riporta un valore inferiore o superiore all'intervallo misurabile.
* **`unit`** — l'unità di misura (es. ng/mL, µIU/mL).
* **`reference_range_lab`** — i limiti min/max normali e ottimali riportati dal laboratorio per questo risultato, convertiti sulla stessa scala di `value`. Un limite lasciato aperto dal laboratorio è `null`, quindi un intervallo unilaterale come `< 50` arriva come `normal_min: null, normal_max: 50`. Ogni risultato include l'intervallo rispetto al quale è stato misurato, così un paziente con risultati provenienti da più prelievi o laboratori riceve quello corretto per ogni risultato.
* **`reference_range_lab_absent_reason`** — il motivo per cui `reference_range_lab` è `null`. `null` quando l'intervallo è presente e per un risultato `planned`. Vedi [Quando non c'è un intervallo di laboratorio](#quando-manca-l-intervallo-del-laboratorio).
* **`aniva_range`** — Valori di confronto raccolti da Aniva, sulla stessa scala di `value`. Variano in base a età, sesso e settimana di gravidanza. `normal_*` è l'intervallo generale. `optimal_*` è un intervallo più ristretto. I valori hanno solo scopo informativo. Non sono un parere medico, né una diagnosi, né una valutazione del risultato. Aniva non imposta alcun flag rispetto a essi. Usa `reference_range_lab` come riferimento per il risultato. `null` quando la tua chiave non dispone dello scope `aniva_ranges_view` o quando Aniva non ha valori per questo biomarcatore.
* **`tested_at`** — la data in cui è stato eseguito il test.
* **`comment`** — annotazione in testo libero del laboratorio su questo risultato specifico (es. indicazioni sull'intervallo di riferimento, avvisi sulla qualità del campione). `null` quando il laboratorio non ne ha allegata alcuna.
* **`status_reason`** — il motivo per cui un risultato `likely_wrong` è dubbio, oppure un risultato `fault` o `undeliverable` è inutilizzabile. `null` per ogni altro stato. Distinto da `comment`, che è la nota del laboratorio stesso ed è spesso vuota nei risultati con errore.
* **`origin`** — chi ha fornito il documento da cui proviene il valore, con gli stessi valori del campo `origin` del documento qui sotto. Un valore proveniente da un documento caricato (`member_upload`, `staff_upload`, `partner_upload`) deriva dalla lettura del file da parte di Aniva, non da un referto di laboratorio: verificalo sul file prima dell'uso clinico. `null` per un risultato `planned`.
* **`lab_reported`** — la riga di referto del laboratorio esecutore, testuale e non convertita. Vedi sotto.

### Intervalli Aniva

`aniva_range` contiene valori di confronto che Aniva ha compilato da fonti pubblicate e
dalla propria elaborazione. Gli intervalli variano per età, sesso e settimana di gravidanza.
`sources` elenca le fonti pubblicate che Aniva ha registrato per i valori. L'elenco può essere vuoto.

> [!WARNING]
>
> I valori sono informazioni generali. Non sono un parere medico, né una diagnosi, né un
> reperto medico né una valutazione di un risultato. Aniva non li fornisce come dispositivo
> medico. Aniva non confronta alcun risultato con essi e non imposta alcun flag in base a essi.
> `reference_range_lab` e la valutazione di un medico restano il riferimento per un risultato.

Regole per il tuo prodotto:

* Mostra l'intervallo Aniva solo in aggiunta all'intervallo del laboratorio, mai al suo posto.
* Se ricavi un flag, un avviso o una raccomandazione dall'intervallo Aniva, lo fai a tuo
  nome e sotto la tua responsabilità.
* Mostra l'avviso previsto dal tuo accordo con Aniva ovunque mostri l'intervallo Aniva.

Per ottenere l'accesso, firma il breve accordo sugli intervalli Aniva. Aggiungeremo poi lo
scope `aniva_ranges_view` alla tua chiave. I valori possono cambiare senza preavviso.

### Valori normalizzati e riga originale del laboratorio

`value`, `unit` e `reference_range_lab` sono normalizzati: convertiamo ogni misurazione nell'unità canonica del biomarcatore e la riportiamo sotto il nostro nome del biomarcatore, così lo stesso analita è confrontabile tra laboratori diversi e nel tempo. È ciò che ti serve per i trend e il confronto tra laboratori, ma non è ciò che un medico vede sul PDF del laboratorio — la fosfatasi alcalina stampata come `48 U/l (40 - 129)` ti arriva come `0.8 µkat/L`.

`lab_reported` affianca quella riga stampata: il nome e il codice dell'analita usati dal laboratorio, il valore e l'unità così come stampati, l'intervallo di riferimento sia come testo (`< 50`, `> 55`, `40 - 129`) sia come limiti non convertiti del laboratorio, oltre al flag di anomalia, allo stato del risultato e alla nota.

Usa `lab_reported` quando una persona riconcilia i tuoi dati con il referto del laboratorio, e i campi canonici per tutto ciò che viene calcolato. Sono popolati solo i campi effettivamente inviati dal laboratorio; nulla in `lab_reported` viene dedotto, impostato per default o convertito, e l'intero oggetto è `null` quando non disponiamo di alcun record grezzo per un risultato.

### Quando manca l'intervallo del laboratorio

Quando `reference_range_lab` è `null`, `reference_range_lab_absent_reason` ti dice perché:

| Valore | Significato | Mostra |
| - | - | - |
| `not_provided` | Non esiste alcun intervallo. Il laboratorio non ne ha inviato uno. | "Non applicabile" |
| `lab_text_only` | Il laboratorio ha stampato solo testo, come un obiettivo, una fascia di rischio o un intervallo legato alla fase della vita. | Il testo in `lab_reported.reference_range` |
| `not_measured` | Il risultato è `undeliverable`, quindi non c'è alcun valore da confrontare. | Il campo `status_reason` |

Alcuni laboratori stampano un obiettivo o una fascia di rischio al posto di un intervallo di riferimento, ad esempio
`Ziel: <200. >240 hoch` o `<5.7 neg >=6.5 pos`. Questi non vanno in `reference_range_lab`, quindi i suoi
limiti sono `null` e il motivo è `lab_text_only`. Mostra il testo stampato così com'è.

Un intervallo unilaterale come `< 20` è un intervallo. Arriva in `reference_range_lab` con un limite
`null`, e il motivo è `null`. Lascia aperto il lato aperto quando lo mostri.

### Stati dei risultati clinici

| Stato | Significato |
| - | - |
| `planned` | Il test è ordinato ma i risultati non sono ancora arrivati dal laboratorio. |
| `received` | Il laboratorio ha restituito un risultato. |
| `corrected` | Un revisore umano ha corretto il valore riportato dal laboratorio. |
| `likely_wrong` | Il controllo automatico di Aniva o il membro dubita del valore. Non confermato: non mostrarlo come reperto senza verifica. Vedi `status_reason`. |
| `fault` | Il laboratorio ha consegnato un risultato confermato errato — **non usare a fini clinici**. `value` contiene ancora il valore errato; vedi `status_reason`. |
| `undeliverable` | Il laboratorio non ha potuto produrre un valore. `value` è `null`; vedi `status_reason`. |

> [!TIP]
>
> Quando mostri i risultati ai pazienti, usa direttamente il campo `value` — riflette già il
> valore corretto quando esiste.

> [!WARNING]
>
> Non presentare mai un risultato `fault` come reperto — il suo `value` è popolato ma confermato errato.

## Risultati genetici

I risultati genetici rappresentano i riscontri a livello genico dell'analisi del DNA. Ogni risultato corrisponde a un gene (es. APOE, MTHFR) e include:

* **`id`** — l'identificatore della riga del risultato di laboratorio. Rimane invariato quando il laboratorio corregge quella riga, quindi usalo per l'upsert. `null` per un risultato `planned`.
* **`gene`** — il simbolo del gene.
* **`lab_code`** — il codice di laboratorio (codice a barre della provetta) con cui è stato registrato il risultato. `null` per un risultato `planned` e per i risultati refertati dal laboratorio senza codice.
* **`genotype`** — il genotipo rilevato (es. E3/E4).
* **`clinical_significance`** — una classificazione del riscontro basata sui criteri ACMG.
* **`risk_description`** — una spiegazione leggibile di cosa significa il genotipo.
* **`comment`** — annotazione in testo libero del laboratorio su questo specifico risultato. `null` quando il laboratorio non ne ha allegata alcuna.
* **`status_reason`** — perché un risultato `likely_wrong` è dubbio, oppure un risultato `fault` o `undeliverable` è inutilizzabile. `null` per tutti gli altri stati.
* **`origin`** — chi ha consegnato il documento da cui proviene il valore, come nei risultati clinici.
* **`variants`** — le specifiche varianti genetiche rilevate, ciascuna con dettagli a livello di SNV.

### Valori di significatività clinica

| Valore | Categoria |
| - | - |
| `pathogenic`, `likely_pathogenic` | Causa di malattia o probabile causa di malattia |
| `uncertain` | Variante di significato incerto (VUS) |
| `likely_benign`, `benign` | Non causa malattia |
| `high_risk`, `moderate_risk`, `low_risk` | Classificazione del livello di rischio |
| `protective` | Variante protettiva |
| `drug_response`, `poor_metabolizer`, `rapid_metabolizer` | Risultati farmacogenomici |

### Stati dei risultati genetici

| Stato | Significato |
| - | - |
| `planned` | L'esame è stato ordinato ma i risultati non sono ancora arrivati. |
| `received` | Il laboratorio ha restituito un risultato. |
| `likely_wrong` | Il controllo automatico di Aniva o il membro dubita del genotipo. Non confermato. Vedi `status_reason`. |
| `fault` | Il laboratorio ha fornito un risultato confermato come errato — **non usare clinicamente**. Vedi `status_reason`. |
| `undeliverable` | Il laboratorio non è riuscito a produrre un genotipo. Vedi `status_reason`. |

### Struttura della variante

Ogni risultato genetico contiene un array `variants`. Ogni variante include:

* **`name`** — nome comune (ad es. APOE E4).
* **`clinical_significance`** — significatività a livello di variante (può differire dalla significatività a livello di gene).
* **`conditions`** — malattie/condizioni associate con descrizioni.
* **`snvs`** — le varianti a singolo nucleotide sottostanti, ciascuna con `rs_id`, `allele`, `reference_allele` e notazione HGVS opzionale.

## Documenti

L'array `documents` nella risposta dei risultati contiene i riferimenti ai file scaricabili dei referti di laboratorio. Ogni documento ha:

* **`id`** — un UUID del file. Passalo a `GET /api/v1/documents/{id}` per scaricare il file.
* **`file_name`** — il nome del file, lo stesso inviato dal download (ad es. `20260405 - Quade Befund - 7642001234.pdf`).
* **`original_file_name`** — il nome del file esattamente come fornito dal laboratorio o da chi lo ha caricato (ad es. `7642001234_B0012_FA_E.pdf`).
* **`origin`** — chi ha fornito il file: `lab`, `member_upload`, `staff_upload` o `partner_upload` (lo hai caricato con [Carica documento](https://docs.anivahealth.com/it/api/documents/upload-document.md)).
* **`content_type`** — il media type del file (ad es. `application/pdf`). La maggior parte dei referti è in PDF. Le scansioni caricate possono essere immagini o file CSV.
* **`etag`** — la versione del contenuto del file; cambia ogni volta che cambiano i byte. Salvalo e scarica di nuovo solo quando cambia. È lo standard HTTP entity tag, usato da S3 o Google Cloud Storage.
* **`size_bytes`** — la dimensione del file in byte.
* **`lab_code`** — il codice laboratorio (codice a barre della provetta) a cui appartiene il referto; `null` se il laboratorio non ne ha indicato nessuno.

> [!NOTE]
>
> L'accesso ai documenti viene verificato rispetto al profilo proprietario del documento.

## Invio dei risultati via email al cliente

Puoi avvisare il cliente via email che i suoi risultati sono pronti. Chiama
[Invia risultati via email](https://docs.anivahealth.com/it/api/appointments/email-results.md) per un appuntamento, oppure
[Invia risultati via email](https://docs.anivahealth.com/it/api/home-kit-orders/email-results.md) per un ordine di kit domiciliare. Ogni chiamata invia una email.
Le chiamate non vengono deduplicate.

* L'email viene inviata all'`email` del profilo. Un indirizzo segnaposto `@aniva.email` viene rifiutato.
* L'email mostra il nome e il logo del gruppo di profili principale del profilo.
* L'email è nella `language` del profilo, inglese di default.
* Imposta `with_reports` su `true` per allegare i referti di laboratorio.
* Aggiungi `note` per mostrare una nota personale nell'email, al massimo 1.000 caratteri.

Se il profilo ha disattivato le email transazionali, la chiamata restituisce `409` con il motivo
`unsubscribed`. Per riattivarle, imposta `transactional_emails_enabled` su `true` con
[Aggiorna profilo](https://docs.anivahealth.com/it/api/profiles/update-profile.md).

## Email di risultati pronti

Puoi ricevere un'email quando i risultati di una prenotazione sono pronti. Imposta `results_ready_emails` con fino a 5
indirizzi in [Crea appuntamento](https://docs.anivahealth.com/it/api/appointments/create-appointment.md) o
[Crea ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/create-home-kit.md). Modifica l'elenco in seguito con
[Aggiorna appuntamento](https://docs.anivahealth.com/it/api/appointments/update-appointment.md) o
[Aggiorna ordine kit domiciliare](https://docs.anivahealth.com/it/api/home-kit-orders/update-home-kit.md); `[]` disattiva le email.

* Chiedici di impostare indirizzi email predefiniti per il tuo gruppo di profili. Una prenotazione creata senza
  `results_ready_emails` li riceve. Un elenco li sostituisce per quella prenotazione, quindi includi il tuo
  indirizzo email predefinito per mantenerlo. `[]` non invia alcuna email.
* Ogni indirizzo riceve una email, una volta che tutti i risultati di laboratorio della prenotazione sono definitivi.
* Un indirizzo aggiunto dopo che i risultati sono definitivi riceve subito l'email.
* L'email rimanda alla pagina dei risultati nel pannello di amministrazione Aniva. Il cliente non la riceve.
* La tua chiave necessita dell'accesso `results_view` per il paziente. Senza di esso, la richiesta restituisce `403`.

## Mostra i risultati nella tua app

[Crea sessione embed](https://docs.anivahealth.com/it/api/profiles/create-embed-session.md) restituisce un URL monouso per una pagina di risultati
in sola lettura. Aprilo in una WebView della tua app, così il paziente vede i risultati senza effettuare il login.

* La tua chiave necessita degli scope `embed` e `results_view` per il paziente. Chiedi ad Aniva lo scope
  `embed`.
* Chiamalo dal tuo server ogni volta che il paziente apre i risultati. L'URL funziona una sola volta e per
  5 minuti, e la pagina mantiene poi una sessione di 60 minuti.
* `route` apre una delle pagine che rilasciamo: l'elenco dei biomarcatori, un singolo biomarcatore o il Twin 3D.
* `appearance` imposta il tema, il colore di pulsanti e link e se mostrare il tuo logo.
* `report` limita la pagina a un appuntamento, un ordine di kit domiciliare o un referto di laboratorio che hai
  caricato con `POST /api/v1/documents`. Il paziente vede quindi solo i risultati di quel referto.
* La pagina mostra solo i risultati di laboratorio, come questa API. Non mostra file, chat né impostazioni.

## Esempio di risposta dei risultati

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