Gli endpoint per gli ordini di kit domiciliare richiedono lo scope
home_kit_orders_view
(lettura) o home_kit_orders_manage (scrittura). Attiva
accetta anche lo scope più ristretto home_kit_orders_activate.
Ottieni risultati e
Invia risultati via email richiedono inoltre
results_view — i risultati di laboratorio e i documenti sono sempre protetti da questo scope.Campi
UUID generato automaticamente da Aniva. Usalo per aggiornare l’ordine, sostituire il pannello,
attivarlo, annullarlo e recuperare i risultati.
Stato attuale del ciclo di vita. Uno tra
pending, dispatched, activated o cancelled. Vedi
Ciclo di vita sotto. Il dettaglio sul completamento dei risultati di laboratorio
(in_progress o completed) si ricava da
Ottieni risultati.L’indirizzo a cui spedire il kit — in uno di due formati:
{location_id} che fa riferimento a
una sede di analisi nota, oppure i campi di indirizzo inline (name, street, city,
postal_code, country_code; company_name / house_number / address_line_2 / state /
phone / email opzionali — lo stesso vocabolario dell’API locations). Fornisci esattamente uno
dei due — un riferimento alla sede o un indirizzo inline, non entrambi.Packstation o Postfiliale (solo Germania): imposta
street su Packstation o Postfiliale,
house_number sul numero a tre cifre della stazione e address_line_2 sul DHL Postnummer del
destinatario (6–10 cifre, spazi ammessi). Senza il Postnummer, il pacco non può essere prenotato.
Il Postfach non è supportato.Timestamp ISO 8601 dell’aggiornamento più recente. Nullo se l’ordine di kit domiciliare non è mai
stato aggiornato.
L’oggetto profilo completo del paziente, incluso in ogni risposta di un ordine di kit domiciliare.
Il pannello associato all’ordine di kit domiciliare — sempre esattamente una voce
{ panel_id, added_at }, perché un kit domiciliare corrisponde 1:1 a un kit fisico. Confronta il
panel_id con Elenca pannelli.Biomarcatori associati all’ordine di kit domiciliare al di fuori del suo pannello. Ogni voce è
{ biomarker_id, added_at }. Confronta ogni biomarker_id con
Elenca biomarcatori con home_kit=true. In un ordine normale
sono analisi à la carte in aggiunta al pannello; in un kit sostitutivo sono
ciò che il laboratorio riesegue.L’ordine di kit domiciliare che questo sostituisce, quando si tratta di un
kit sostitutivo.
null in un ordine normale.Indirizzi in minuscolo che ricevono ciascuno un’email quando tutti i risultati di laboratorio sono
definitivi. Sempre presente — vuoto quando disattivato. Impostalo in
Crea o
Aggiorna. Vedi
Email per risultati pronti.
Le tue coppie chiave/valore, restituite tali e quali e mai interpretate da Aniva. Sempre presente
in lettura —
{} quando non ne imposti nessuna. Al massimo 20 chiavi; le chiavi rispettano
[A-Za-z0-9_-] e hanno al massimo 40 caratteri; i valori sono stringhe, numeri o booleani, con
stringhe di al massimo 500 caratteri; 16.384 byte serializzati in totale. Le chiavi che iniziano
con aniva_ sono riservate. In Aggiorna, i metadati
vengono uniti: le chiavi che ometti restano, una chiave inviata come null viene eliminata e
{} cancella tutto. La validazione è tutto-o-niente. Non inserire mai dati personali o clinici in
metadata — non sono trattati come dati del paziente.Il codice campione di laboratorio. Un solo codice, tre ruoli: quello con cui vengono riportati i
risultati di laboratorio, quello stampato sul kit fisico e quello che il paziente legge sulla
scatola come codice di attivazione. Assegnato quando il kit viene imballato —
null finché
l’ordine è pending, tranne dopo che Aniva rispedisce un kit (vedi Ciclo di vita).
Sempre di sola lettura. Risali dal kit fisico al relativo ordine con
GET /api/v1/home-kit-orders?lab_code=….Il timestamp di raccolta comunicato tramite Attiva —
quando il paziente ha effettivamente raccolto il campione, come istante UTC.
null finché il kit
non viene attivato. È l’orario di raccolta riportato sul referto di laboratorio.I pacchi collegati a questo ordine, dal collegamento più vecchio, ciascuno
{ id, added_at } —
il kit in viaggio verso il paziente e, per i kit con tratta di ritorno tracciata, il campione in
viaggio verso il laboratorio, che compaiono nel momento in cui vengono stampate le etichette.
Vuoto finché l’ordine è pending, tranne dopo che Aniva rispedisce un kit. Leggi i pacchi
completi in una sola chiamata con GET /api/v1/shipments?home_kit_order_id={id} — vedi
Spedizioni.Ciclo di vita
Gli ordini di kit domiciliare espongono quattro stati del ciclo di vita:
Quando Aniva rispedisce un kit perso, l’ordine torna in
pending, ma mantiene il suo lab_code e i
pacchi precedenti in shipments. Il nuovo kit riporta lo stesso codice. Un’etichetta di reso inutilizzata
viene inserita nella nuova scatola. Solo Aniva esegue questi due passaggi; l’API non li offre. Ogni passaggio
invia un webhook home_kit_order.pending o home_kit_order.cancelled.
Gli stati dell’ordine di kit domiciliare sono volutamente essenziali. L’avanzamento della consegna da
e verso il paziente è tracciato sulle spedizioni dell’ordine:
dispatched
significa che il kit ha un’etichetta e un codice di laboratorio, non che è partito; lo status della
spedizione in uscita indica se lo è. L’elaborazione dei risultati di laboratorio risiede negli invii.
Il completamento dei risultati di laboratorio (in_progress o completed) è esposto tramite
Ottieni i risultati: il campo status di primo livello rimane
in_progress finché tutti gli invii non si chiudono, poi passa a completed, oppure a fault
quando tutti gli invii si sono interrotti senza riportare risultati.Tracciare i pacchi
destination è il laboratorio), collegati tramite paired_with. Il pacco di ritorno resta
pending, con il numero di tracciamento già noto, finché il paziente non lo spedisce. Un kit per il
microbioma intestinale viene restituito come una sola spedizione: il kit verso il paziente. La sua busta
di reso è prepagata e non tracciata, quindi non viene prenotato nulla per il ritorno. booked_by indica
chi ha prenotato l’etichetta: "aniva" o "external". Qui puoi modificare solo un pacco "aniva",
e solo il campo notes una volta stampata l’etichetta. Ogni pacco include tutti gli status_updates
del corriere, incluso il detail_code di DHL per il reindirizzamento a un ufficio postale.
home_kit_orders sulla spedizione elenca solo gli ordini nel tuo contesto di accesso. Vedi
Accesso.
Elencare gli ordini di kit domiciliari
Recupera tutti gli ordini di kit domiciliari accessibili con la tua chiave API:?profile_id={uuid} per filtrare per un profilo specifico, oppure ?lab_code={code} per
risalire all’ordine a partire da un kit fisico che hai in mano: il primo passo naturale di un flusso di attivazione.
Creare un ordine di kit domiciliare
Richiedi un ordine di kit domiciliare per un profilo paziente:profile_id, un delivery_address e un singolo panel_id. L’ordine viene creato nello stato pending.
Passa un header facoltativo Idempotency-Key così un nuovo tentativo non ordina un secondo kit: vedi Idempotenza.
Esattamente un pannello, perché un kit domiciliare corrisponde 1:1 a un kit fisico: il pannello è il kit. Sono ordinabili solo i pannelli configurati da Aniva come kit domiciliari; qualsiasi altro pannello viene rifiutato con 422. È obbligatorio alla creazione perché l’ordine entra subito nella coda di confezionamento e il confezionamento può iniziare immediatamente. Finché l’ordine è in pending, puoi cambiare il pannello tramite Aggiorna.
Per inviare un secondo kit in sostituzione di uno che non ha potuto fornire i risultati, passa replaces_home_kit_order_id invece di scegliere un pannello: vedi Kit sostitutivi.
Kit sostitutivi
A volte un kit non riesce a fornire i risultati: il paziente non è riuscito a riempire la provetta, il campione è arrivato con troppo poco materiale o il laboratorio non è riuscito ad analizzarne una parte. Ordina una sostituzione:replaces_home_kit_order_id.
L’ordine che sostituisci non viene toccato. Mantiene il suo stato, il suo codice di laboratorio ed eventuali risultati già registrati, così un paziente che spedisce comunque il primo kit ottiene tutto ciò che il laboratorio riesce a leggere.
Il pannello viene ereditato. Ometti panel_id e la sostituzione manterrà il pannello dell’ordine che sostituisce: è ciò che il paziente ha acquistato e corrisponde al marchio sulla scatola. Invia un pannello diverso solo per sostituire l’intero pannello; un pannello e un sottoinsieme di marcatori insieme vengono rifiutati con 422, perché un sottoinsieme ha senso solo all’interno del pannello da cui è stato scelto. Anche il pannello di una sostituzione non può essere cambiato in seguito.
Scegli tu cosa ripetere. Invia biomarker_ids con i marcatori non riusciti e il laboratorio ripete solo quelli, così il kit contiene solo le provette necessarie. Omettilo per ripetere l’intero pannello: la scelta giusta quando non è stato analizzato nulla. Non serve nessuno scope aggiuntivo: ripetere marcatori che il paziente ha già pagato non è una selezione à la carte. Questi marcatori non possono essere rimossi in seguito, perché costituiscono l’intera richiesta.
I marcatori vengono ripetuti per gruppi del pannello, non uno per uno. Indicare un marcatore di
un gruppo ripete l’intero gruppo, perché non è possibile inviare un ordine di laboratorio che riporti
più di quanto richiesto. Una sostituzione per un singolo marcatore può quindi restituire più di un
risultato, e il numero di provette può essere maggiore di quanto suggerisca l’elenco dei marcatori.
pending o dispatched, una seconda creazione per lo stesso ordine restituisce 409 indicandola. I risultati arrivano con il lab_code della sostituzione, tramite il suo Ottieni i risultati.
Una sostituzione non è il modo per gestire un pacco mai arrivato. Avvisa invece Aniva: si tratta di una nuova spedizione dello stesso ordine con lo stesso codice di laboratorio, non di un nuovo ordine.
Aggiornare un ordine di kit domiciliare
Modifica l’indirizzo di consegna, cambia il pannello, aggiorna i metadati o sostituisci le email di notifica dei risultati pronti:panel_id sostituisce il pannello associato: con esattamente un pannello per kit, il cambio è l’unica operazione sensata sul pannello, motivo per cui non esistono endpoint per aggiungere o rimuovere pannelli. L’indirizzo e il pannello sono modificabili solo finché l’ordine è pending; metadata resta modificabile per l’intero ciclo di vita dell’ordine. results_ready_emails resta modificabile finché l’ordine non è cancelled.
Annullare un ordine di kit domiciliare
Annulla un ordine di kit domiciliare che non serve più:cancelled. L’ordine di kit domiciliare annullato viene restituito nella risposta.
Solo un ordine in pending può essere annullato. Da dispatched in poi il kit è già stato confezionato ed etichettato, non esiste un richiamo automatico e la chiamata restituisce 409. Se devi bloccare un kit già spedito, contatta direttamente Aniva.
Annullare un ordine pending il cui kit è già stato richiesto alla logistica lo annulla anche lì, e la chiamata ha successo solo se la logistica accetta:
409— il kit era già stato confezionato ed etichettato, quindi non può più essere richiamato, anche se l’ordine risulta ancorapending.502— la logistica ha rifiutato l’annullamento (l’errore ne riporta il motivo) o non è stato possibile raggiungerla. Non è stato modificato nulla: l’ordine è ancora attivo e può essere annullato di nuovo.
200 è l’unica conferma che non arriverà nessun kit.
Annullare un ordine già cancelled restituisce lo stesso 200, indipendentemente dallo stato da cui era stato annullato.
Attivare un ordine di kit domiciliare
Quando il paziente ha raccolto il campione, segnalalo:activated_at, cioè il momento in cui il paziente ha effettivamente raccolto il campione, come istante UTC. È l’orario di raccolta che verrà riportato nel referto di laboratorio, quindi invia il momento reale della raccolta, non l’orario di elaborazione. L’attivazione è definitiva: l’ordine passa a activated e non può più essere annullato né modificato. È l’equivalente per i kit domiciliari di Conferma prelievo di sangue, senza codice a barre: il codice del kit viene applicato al momento del confezionamento, quindi non hai mai bisogno di conoscerlo. A quel punto l’ordine deve avere il proprio lab_code; un ordine che ne è privo restituisce 409.
L’attivazione è anche ciò che inoltra l’ordine al laboratorio: il pannello del kit viene ordinato presso il laboratorio con il suo lab_code, così il campione spedito indietro è atteso e i risultati si collegano man mano che il laboratorio li trasmette. Questa operazione avviene dopo la risposta e un eventuale problema lato laboratorio viene gestito da Aniva, senza emergere nella tua richiesta.
Singoli biomarcatori
Puoi aggiungere singoli biomarcatori a un ordine di kit domiciliare come esami à la carte, al di fuori del pannello. È utile quando vuoi una selezione su misura in aggiunta al kit. I biomarcatori aggiunti compaiono nella risposta dell’ordine di kit domiciliare come arrayindividual_biomarkers (allo stesso livello di panels).
Entrambi gli endpoint dei biomarcatori richiedono lo scope di funzionalità home_kit_orders_individual_biomarker_selection in aggiunta a home_kit_orders_manage — i kit domiciliari si ordinano per pannello, quindi i marcatori singoli vengono abilitati per partner. Chiedi ad Aniva se la tua integrazione ne ha bisogno.
Aggiungi biomarcatori (idempotente — i biomarcatori già associati vengono mantenuti):
biomarker_ids. Usa Elenca biomarcatori con home_kit=true per scoprire gli ID dei biomarcatori. I biomarcatori possono essere modificati solo finché il kit è pending (vedi Ciclo di vita).
Recuperare i risultati di laboratorio
Una volta che il laboratorio ha analizzato il campione restituito, recupera i risultati clinici e genetici:planned) accanto ai risultati ricevuti, così puoi monitorare cosa è ancora in sospeso. I risultati vengono registrati sotto il lab_code dell’ordine e arrivano marcatore per marcatore man mano che il laboratorio li analizza, quindi i payload parziali sono normali. Il campo status di primo livello è in_progress fino al referto finale, poi completed (o fault se tutti gli ordini di laboratorio sono falliti senza referto) — usalo per stabilire se il lavoro di laboratorio dell’ordine di kit domiciliare è concluso. Un webhook home_kit_order.results.completed ti avvisa quando succede, così non devi fare polling. I PDF dei referti di laboratorio sono indicati nell’array documents — usa GET /api/v1/documents/{id} per scaricarli.