Vai al contenuto principale
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: 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. 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.
  • 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.
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é: 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

Quando mostri i risultati ai pazienti, usa direttamente il campo value — riflette già il valore corretto quando esiste.
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

Stati dei risultati genetici

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).
  • 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.
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 per un appuntamento, oppure Invia risultati via email 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.

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 o Crea ordine kit domiciliare. Modifica l’elenco in seguito con Aggiorna appuntamento o Aggiorna ordine kit domiciliare; [] 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 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