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 campostatus 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.nullper un risultatoplanned.biomarker_nameecategory— 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.nullper un risultatoplannede per i risultati refertati dal laboratorio senza codice.valueevalue_operator— la misurazione effettiva. L’operatore èeq(uguale) per i valori esatti, oppurelt/gtquando 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 divalue. Un limite lasciato aperto dal laboratorio ènull, quindi un intervallo unilaterale come< 50arriva comenormal_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 cuireference_range_labènull.nullquando l’intervallo è presente e per un risultatoplanned. Vedi Quando non c’è un intervallo di laboratorio.aniva_range— Valori di confronto raccolti da Aniva, sulla stessa scala divalue. 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. Usareference_range_labcome riferimento per il risultato.nullquando la tua chiave non dispone dello scopeaniva_ranges_viewo 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).nullquando il laboratorio non ne ha allegata alcuna.status_reason— il motivo per cui un risultatolikely_wrongè dubbio, oppure un risultatofaultoundeliverableè inutilizzabile.nullper ogni altro stato. Distinto dacomment, 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 campoorigindel 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.nullper un risultatoplanned.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.
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.
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
Quandoreference_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
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.nullper un risultatoplanned.gene— il simbolo del gene.lab_code— il codice di laboratorio (codice a barre della provetta) con cui è stato registrato il risultato.nullper un risultatoplannede 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.nullquando il laboratorio non ne ha allegata alcuna.status_reason— perché un risultatolikely_wrongè dubbio, oppure un risultatofaultoundeliverableè inutilizzabile.nullper 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 arrayvariants. 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 conrs_id,allele,reference_allelee notazione HGVS opzionale.
Documenti
L’arraydocuments nella risposta dei risultati contiene i riferimenti ai file scaricabili dei referti di laboratorio. Ogni documento ha:
id— un UUID del file. Passalo aGET /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_uploadopartner_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;nullse 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’
emaildel profilo. Un indirizzo segnaposto@aniva.emailviene rifiutato. - L’email mostra il nome e il logo del gruppo di profili principale del profilo.
- L’email è nella
languagedel profilo, inglese di default. - Imposta
with_reportssutrueper allegare i referti di laboratorio. - Aggiungi
noteper mostrare una nota personale nell’email, al massimo 1.000 caratteri.
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. Impostaresults_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_emailsli 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_viewper il paziente. Senza di esso, la richiesta restituisce403.
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
embederesults_viewper il paziente. Chiedi ad Aniva lo scopeembed. - 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.
routeapre una delle pagine che rilasciamo: l’elenco dei biomarcatori, un singolo biomarcatore o il Twin 3D.appearanceimposta il tema, il colore di pulsanti e link e se mostrare il tuo logo.reportlimita la pagina a un appuntamento, un ordine di kit domiciliare o un referto di laboratorio che hai caricato conPOST /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.