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

# Ottieni risultati di laboratorio

> Recupera i risultati di laboratorio clinici e genetici per un ordine di kit domiciliare

Recupera i risultati di laboratorio clinici e genetici per un ordine di kit domiciliare, insieme ai riferimenti ai documenti per i PDF dei referti di laboratorio.

Ogni biomarcatore ordinato per il kit appare nella risposta, così puoi monitorare l'intero ordine invece che solo ciò che è già arrivato. I risultati vengono registrati sotto il `lab_code` dell'ordine — l'ordine al laboratorio viene effettuato all'[attivazione](https://docs.anivahealth.com/it/api/home-kit-orders/activate-home-kit.md), e il laboratorio comunica i marcatori singolarmente man mano che vengono analizzati, quindi un payload parziale è normale e lo `status` di primo livello resta `in_progress` fino al referto finale. Leggi `status` su ogni risultato prima di usare il relativo `value`:

* Gli esami ancora in sospeso appaiono con stato `planned` mentre l'ordine è `in_progress`. Puoi chiamare questo endpoint prima dell'attivazione — in quel caso ogni marcatore ordinato è `planned`.
* I risultati consegnati dal laboratorio ma che **non** devono essere usati clinicamente appaiono con stato `fault` o `undeliverable` e includono un `status_reason` che spiega il motivo. Un risultato `fault` ha comunque il proprio `value` compilato — quel valore è errato. Non presentarlo mai come un esito.
* I risultati su cui Aniva o il membro ha dubbi appaiono con stato `likely_wrong` e un `status_reason`. Il valore non è confermato. Non mostrarlo come un esito senza verifica.

Usa [Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md) per scaricare i PDF dei referti di laboratorio referenziati nell'array `documents`.

Non hai bisogno di fare polling su questo endpoint. Iscriviti ai [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md) `home_kit_order.results.updated` o `home_kit_order.results.completed` e chiamalo quando arriva un evento. Il polling funziona comunque come fallback.

Richiede lo scope `results_view` — i risultati di laboratorio e i documenti sono sempre protetti da questo scope, proprio come i risultati dell'appuntamento e [Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md) — più lo scope `home_kit_orders_view` o `home_kit_orders_manage` per accedere all'ordine del kit stesso.

## Richiesta

### Parametri di percorso

**id** `string` *required*

Identificatore univoco (UUID) dell'ordine di kit domiciliare di cui recuperare i risultati.

## Risposta

In caso di successo, l'API restituisce `200 OK` con l'oggetto dei risultati.

**status** `string` *required*

Stato complessivo dei risultati. Uno tra:

* `in_progress` — alcune richieste sono ancora in laboratorio.
* `completed` — ogni richiesta si è chiusa e almeno una ha prodotto un referto.
* `fault` — ogni richiesta è fallita senza produrre un referto. Non è dovuto nulla.

**submissions** `object[]` *required*

Una voce per ogni richiesta di laboratorio — un prelievo di sangue su più provette o laboratori ne ha
diverse. Lo `status` di primo livello è `completed` quando ogni voce si è chiusa e una ha prodotto un referto.

**oggetto submission**

**lab\_code** `string`

Codice di laboratorio (codice a barre della provetta) con cui è stata registrata questa richiesta. Può essere `null` quando il laboratorio non ne ha registrato
alcuno.

**status** `string` *required*

`in_progress` mentre il laboratorio ci sta ancora lavorando, `completed` quando il referto è
definitivo oppure `fault` quando la richiesta è stata rifiutata o abbandonata e non produrrà mai un referto — il
campione viene spesso spostato in un altro laboratorio, che poi registra una propria voce.

**clinical\_results** `object[]` *required*

Array di risultati di biomarcatori clinici.

**oggetto risultato clinico**

**id** `string`

Identificatore della riga di risultato di laboratorio (UUID). Resta uguale quando il laboratorio corregge quella riga, quindi usalo per l'upsert. `null` per un risultato `planned`.

**status** `string` *required*

Stato del risultato. Uno tra:

* `planned` — ordinato, non ancora restituito dal laboratorio. `value` è `null`.
* `received` — consegnato dal laboratorio.
* `corrected` — consegnato, poi rivisto da una persona. `value` è il valore corretto.
* `likely_wrong` — il controllo automatico di Aniva o il membro dubita del valore. Non confermato: non mostrarlo come esito senza revisione. Vedi `status_reason`.
* `fault` — consegnato ma confermato errato; **non usare clinicamente**. `value` contiene il dato errato. Vedi `status_reason`.
* `undeliverable` — il laboratorio non ha potuto produrre un valore. `value` è `null`. Vedi `status_reason`.

**status\_reason** `string` *required*

Motivo per cui il risultato è dubbio o inutilizzabile. Valorizzato per `likely_wrong`, `fault` e `undeliverable`, `null` per ogni altro stato.

Distinto da `comment`, che è la nota del laboratorio sul referto — `comment` è vuoto nella maggior parte dei risultati errati, quindi considera `status_reason` come la spiegazione autorevole.

**lab\_code** `string`

Codice di laboratorio (codice a barre della provetta) sotto cui è stato archiviato il risultato — uno dei codici di laboratorio dell'ordine. `null` per un risultato `planned` e per i risultati riportati dal laboratorio senza codice.

**biomarker\_id** `integer` *required*

Identificatore del biomarcatore.

**biomarker\_name** `string` *required*

Nome visualizzato del biomarcatore.

**category** `string`

Categoria del biomarcatore (es. Ormoni, Vitamine). Può essere `null`.

**value** `number`

Valore effettivo del risultato (corretto se disponibile, altrimenti grezzo). Può essere `null`.

**value\_operator** `string`

Operatore di confronto per il valore: `eq` (uguale a), `lt` (minore di) o `gt` (maggiore di). Può essere `null`.

**unit\_id** `integer`

Identificatore dell'unità di misura. Può essere `null`.

**unit** `string`

Nome visualizzato dell'unità di misura. Può essere `null`.

**reference\_range\_lab** `object`

Intervalli di riferimento riportati dal laboratorio per **questo** risultato, convertiti nella stessa unità di `value`. `null` quando il laboratorio non ha riportato alcun intervallo.

Un limite lasciato aperto dal laboratorio resta `null`, quindi un intervallo unilaterale valorizza solo il proprio estremo — una soglia superiore arriva come `normal_min: null, normal_max: 50`, una inferiore come `normal_min: 55, normal_max: null`. Non interpretare un limite `null` come zero o illimitato per impostazione predefinita; leggilo come "il laboratorio non ha impostato alcun limite da quel lato".

Ogni risultato riporta l'intervallo rispetto al quale è stato misurato, così un paziente i cui risultati coprono più prelievi di sangue o più laboratori ottiene l'intervallo corretto per ciascun risultato anziché quello più recente.

**intervallo di riferimento**

**normal\_min** `number`

Limite inferiore dell'intervallo normale. Può essere `null`.

**normal\_max** `number`

Limite superiore dell'intervallo normale. Può essere `null`.

**optimal\_min** `number`

Limite inferiore dell'intervallo ottimale. Può essere `null`.

**optimal\_max** `number`

Limite superiore dell'intervallo ottimale. Può essere `null`.

**reference\_range\_lab\_absent\_reason** `string`

Motivo per cui `reference_range_lab` è `null`. `null` quando `reference_range_lab` è presente e su un risultato `planned`.

* `not_provided`: non esiste alcun intervallo. Il laboratorio non ne ha inviato nessuno. Mostra "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. Mostra `lab_reported.reference_range`.
* `not_measured`: il risultato è `undeliverable`, quindi non c'è alcun valore da confrontare. Mostra `status_reason`.

**aniva\_range** `object`

Valori di confronto raccolti da Aniva, sulla stessa scala di `value`. Variano per 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, una diagnosi o una valutazione del risultato. Aniva non imposta alcun flag rispetto a essi. Usa `reference_range_lab` come standard per il risultato. `null` quando la tua chiave non ha lo scope `aniva_ranges_view` o quando Aniva non ha valori per questo biomarcatore.

**intervallo di riferimento**

**normal\_min** `number`

Limite inferiore dell'intervallo normale. Può essere `null`.

**normal\_max** `number`

Limite superiore dell'intervallo normale. Può essere `null`.

**optimal\_min** `number`

Limite inferiore dell'intervallo ottimale. Può essere `null`.

**optimal\_max** `number`

Limite superiore dell'intervallo più ristretto. Può essere `null`.

**sources** `object[]`

Fonti pubblicate che Aniva ha registrato per questi valori. Ogni voce ha un `title` e un `url`. L'`url` può essere `null`. L'elenco è vuoto quando Aniva non ha registrato alcuna fonte.

**tested\_at** `string`

Data di esecuzione del test nel formato `YYYY-MM-DD`. Può essere `null`.

**comment** `string`

Commento facoltativo sul risultato. Può essere `null`.

**origin** `string`

Chi ha consegnato il documento da cui proviene questo valore, come `origin` sul documento. Un valore da un documento caricato deriva dalla lettura del file da parte di Aniva, non da un referto di laboratorio. `null` per un risultato `planned`.

**lab\_reported** `object`

La riga del referto del laboratorio che ha eseguito l'analisi, alla lettera — per confrontare questo payload con il PDF del laboratorio. Può essere `null` quando non abbiamo alcun record grezzo per il risultato.

Ogni altro campo di un risultato è normalizzato: `value` e `unit` sono convertiti nell'unità predefinita del biomarcatore e `biomarker_name` è il nostro nome per l'analita, non quello del laboratorio. I campi seguenti non lo sono. Considerali come riferimento così come stampato e i campi canonici come controllo incrociato di coerenza.

I numeri qui sono i limiti del laboratorio sulla sua stessa scala — `reference_range_min` e `reference_range_max` **non** sono convertiti di unità e differiranno da `reference_range_lab` ogni volta che le due scale differiscono. Un limite lasciato aperto dal laboratorio resta `null`; nulla viene dedotto o impostato come valore predefinito.

**riportato dal laboratorio**

**name** `string`

Nome dell'analita così come stampato dal laboratorio. Può essere `null`.

**code** `string`

Codice analita del laboratorio. Può essere `null`.

**category** `string`

Titolo della sezione del referto, es. `Klinische Chemie`. Può essere `null`.

**value** `string`

Valore così come stampato. È una stringa, così i risultati non numerici restano intatti (`<0.04`, `negativ`, `1:100`). Può essere `null`.

**unit** `string`

Unità così come stampata, es. `U/l`. Può essere `null`.

**reference\_range** `string`

Intervallo di riferimento così come stampato, incluse le soglie unilaterali: `40 - 129`, `< 50`, `> 55`. Può essere `null`.

**reference\_range\_min** `number`

Limite inferiore del laboratorio, non convertito. `null` per un intervallo lasciato aperto in basso dal laboratorio.

**reference\_range\_max** `number`

Limite superiore del laboratorio, non convertito. `null` per un intervallo lasciato aperto in alto dal laboratorio.

**flag** `string`

Flag di anomalia del laboratorio per questa riga: `normal`, `high`, `low`, `critical_high`, `critical_low`, `abnormal`. Un codice che non riconosciamo viene passato così come lo ha inviato il laboratorio. Può essere `null`.

**result\_status** `string`

Stato del risultato del laboratorio: `final`, `preliminary`, `correction`, `incomplete`, `partial`, `deleted`, `cannot_be_obtained`. Un valore `preliminary` può ancora essere rivisto. Un successivo [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md)`results.updated` ti avvisa quando recuperare di nuovo i dati. Può essere `null`.

**comment** `string`

Nota del laboratorio su questa riga. La spaziatura delle colonne viene compressa; il testo resta invariato. Può essere `null`.

**genetic\_results** `object[]` *required*

Array di risultati di biomarcatori genetici.

**oggetto risultato genetico**

**id** `string`

Identificatore della riga di risultato di laboratorio (UUID). Resta uguale quando il laboratorio corregge quella riga, quindi usalo per l'upsert. `null` per un risultato `planned`.

**status** `string` *required*

Stato del risultato. Uno tra:

* `planned` — ordinato, non ancora restituito dal laboratorio.
* `received` — consegnato dal laboratorio.
* `likely_wrong` — il controllo automatico di Aniva o il membro dubita del genotipo. Non confermato. Vedi `status_reason`.
* `fault` — consegnato ma confermato errato; **non usare clinicamente**. Vedi `status_reason`.
* `undeliverable` — il laboratorio non ha potuto produrre un genotipo. Vedi `status_reason`.

**status\_reason** `string` *required*

Motivo per cui il risultato è dubbio o inutilizzabile. Valorizzato per `likely_wrong`, `fault` e `undeliverable`, `null` per ogni altro stato.

**lab\_code** `string`

Codice di laboratorio (codice a barre della provetta) sotto cui è stato archiviato il risultato. `null` per un risultato `planned` e per i risultati riportati dal laboratorio senza codice.

**biomarker\_id** `integer` *required*

Identificatore del biomarcatore (gene).

**gene** `string` *required*

Simbolo del gene (es. APOE, MTHFR).

**genotype** `string`

Visualizzazione del genotipo (es. E3/E4). Può essere `null`.

**clinical\_significance** `string`

Significato clinico complessivo. Uno tra `pathogenic`, `likely_pathogenic`, `uncertain`, `likely_benign`, `benign`, `high_risk`, `moderate_risk`, `low_risk`, `protective`, `drug_response`, `poor_metabolizer` o `rapid_metabolizer`. Può essere `null`.

**risk\_description** `string`

Descrizione del rischio per questo genotipo. Può essere `null`.

**tested\_at** `string`

Data di esecuzione del test nel formato `YYYY-MM-DD`. Può essere `null`.

**comment** `string`

Commento facoltativo sul risultato. Può essere `null`.

**origin** `string`

Chi ha consegnato il documento da cui proviene questo valore, come `origin` sul documento. Un valore da un documento caricato deriva dalla lettura del file da parte di Aniva, non da un referto di laboratorio. `null` per un risultato `planned`.

**variants** `object[]` *required*

Varianti genetiche rilevate.

**oggetto variante**

**name** `string` *required*

Nome comune della variante (es. APOE E4).

**clinical\_significance** `string`

Significato clinico a livello di variante. Può essere `null`.

**description** `string`

Descrizione della variante. Può essere `null`.

**hgvs\_c** `string`

Notazione HGVS del DNA codificante. Può essere `null`.

**hgvs\_p** `string`

Notazione HGVS della proteina. Può essere `null`.

**conditions** `object[]` *required*

Condizioni associate.

**oggetto condizione**

**condition** `string` *required*

Nome della condizione/malattia.

**association\_description** `string`

Descrizione dell'associazione tra variante e condizione. Può essere `null`.

**badge** `string`

Testo breve del badge da mostrare. Può essere `null`.

**snvs** `object[]` *required*

Varianti a singolo nucleotide che definiscono questa variante.

**oggetto SNV**

**rs\_id** `string` *required*

Identificativo dbSNP (es. rs429358).

**allele** `string` *required*

Allele della variante (`A`, `C`, `G`, `T`, `del`, `ins` o `undetermined`).

**reference\_allele** `string` *required*

Allele di riferimento della popolazione.

**hgvs\_c** `string`

Notazione HGVS del DNA codificante. Può essere `null`.

**hgvs\_p** `string`

Notazione HGVS della proteina. Può essere `null`.

**documents** `object[]` *required*

Documenti dei referti di laboratorio. Usa `GET /api/v1/documents/{id}` per scaricare ogni file.

**oggetto documento**

**id** `string` *required*

Identificativo del file (UUID). Passalo a [Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md) per recuperare il file.

**file\_name** `string` *required*

Nome del file. [Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md) invia lo stesso nome in `Content-Disposition`. Contiene una data, il titolo del documento e il codice di laboratorio, es. `20260405 - Quade Befund - 7642001234.pdf`. Usalo solo per la visualizzazione. Leggi il codice di laboratorio da `lab_code`, non dal nome.

**original\_file\_name** `string` *required*

Nome del file esattamente come ricevuto dalla fonte, es. `7642100312_B0012_FA_V.pdf` dal laboratorio o il nome scelto dal membro per un caricamento. Aniva non lo modifica.

**origin** `string` *required*

Chi ha fornito il file. Uno tra `lab` (inviato dal laboratorio), `member_upload` (caricato dal membro), `staff_upload` (caricato dallo staff di Aniva) o `partner_upload` (caricato da te con [Carica documento](https://docs.anivahealth.com/it/api/documents/upload-document.md)).

**content\_type** `string` *required*

Tipo media del file, es. `application/pdf`, `image/jpeg` o `text/csv`. La maggior parte dei referti di laboratorio è in PDF.

**etag** `string`

Versione del contenuto del file. Cambia ogni volta che cambiano i byte, quindi confrontala con il valore salvato per capire se scaricarlo di nuovo. [Scarica documento](https://docs.anivahealth.com/it/api/documents/download-document.md) la invia tra virgolette come header HTTP standard `ETag`. Può essere `null` quando il file salvato manca.

**size\_bytes** `integer`

Dimensione del file in byte. Può essere `null` quando il file salvato manca.

**lab\_code** `string`

Codice di laboratorio (codice a barre della provetta) a cui appartiene il referto. Può essere `null` se il laboratorio non ne ha indicato alcuno.

## Chiamate ripetute

Aniva memorizza la risposta di questo endpoint per 60 minuti per ogni chiave API. Una chiamata ripetuta entro
questo intervallo riceve la risposta memorizzata finché l'ordine di kit domiciliare e i suoi risultati non cambiano. Dopo una modifica, ricevi una risposta
aggiornata. Gli header `Cache-Status` e `Age` mostrano che la risposta è
memorizzata e quanto è vecchia.

Per sapere subito di una modifica, iscriviti agli eventi webhook `home_kit_order.results.updated`, `home_kit_order.results.completed` e `home_kit_order.results.fault`.
Vedi [Letture ripetute](https://docs.anivahealth.com/it/concepts/webhooks.md#letture-ripetute).

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Formato ID non valido — il valore fornito non è un UUID valido. |
| `403` | Accesso negato — alla tua chiave API manca lo scope `results_view`, mancano sia `home_kit_orders_view` sia `home_kit_orders_manage`, oppure l'ordine di kit domiciliare è fuori dal tuo contesto di accesso. |
| `404` | Ordine di kit domiciliare non trovato. |
| `500` | Errore interno del server. |

```bash cURL theme={null}
curl --request GET \
  --url https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "status": "in_progress",
  "submissions": [
    {
      "lab_code": "7642001234",
      "status": "in_progress"
    }
  ],
  "clinical_results": [
    {
      "id": "e9f1a3c5-6b7d-4c2e-8a4f-1d3b5c7e9f02",
      "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": "1b3d5f7a-9c2e-4a6b-8d0f-2e4a6c8b0d13",
      "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"
    }
  ]
}
```

```json 404 theme={null}
{
  "error": "Home kit order not found"
}
```


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