Campi
UUID generato automaticamente da Aniva. Usalo per aggiungere pannelli, confermare il prelievo e recuperare i risultati.
L’UUID della sede per i test in cui avverrà il prelievo. I kit domiciliari non sono appuntamenti — vedi
Ordini di kit domiciliari.
Data e ora programmate per il prelievo di sangue in formato ISO 8601. Sempre restituite come istante UTC con suffisso
Z
(ad es. 2026-04-15T08:30:00Z). In fase di creazione o aggiornamento il valore deve includere l’indicazione del fuso
orario (Z oppure un offset esplicito come +02:00) — data e ora senza fuso orario vengono rifiutate. Deve
essere nel futuro e, nelle sedi gestite da Aniva, con almeno 12 ore di anticipo (preavviso
minimo).Stato attuale del ciclo di vita. Uno tra
pending, confirmed, blood_drawn o cancelled. Vedi
Ciclo di vita sotto. Il livello di completamento dei risultati di laboratorio (in_progress o completed)
si ricava da Ottieni risultati; l’avanzamento più dettagliato della spedizione (in
transito, consegnata ecc.) si ricava seguendo ogni voce dell’array shipments incorporato verso
Ottieni spedizione.Motivo in testo libero registrato al momento dell’annullamento dell’appuntamento (es. mancata
presentazione, annullamento tardivo, ‘Non riuscito. Ripetizione necessaria’).
null a meno che status non sia cancelled.Indirizzi che ricevono ciascuno un’email quando tutti i risultati di laboratorio sono definitivi, in minuscolo. Vuoto se disattivato. Vedi
Email di risultati pronti.
Come viene effettuato il prelievo di sangue:
capillary (dal polpastrello o dalla parte superiore del braccio, in microprovette) o venous (dalla vena,
in provette). È il metodo impostato dall’appuntamento, altrimenti il default_draw_method della sua
sede. Dopo il prelievo di sangue, è il metodo utilizzato.Timestamp ISO 8601 dell’aggiornamento più recente. Nullo se l’appuntamento non è mai stato aggiornato.
Codici di laboratorio (codici a barre delle provette) registrati con Conferma prelievo di sangue,
in ordine di scansione. Vuoto finché il prelievo non viene confermato. Un prelievo venoso ha un codice stampato su ogni
provetta; un prelievo capillare ha un codice per ogni microtainer. Risultati e documenti vi fanno riferimento tramite
lab_code.Pannelli associati a questo appuntamento, come voci
{ panel_id, added_at }. Vedi
Aggiungere pannelli.Biomarcatori singoli associati a questo appuntamento, come voci
{ biomarker_id, added_at }. Vedi
Biomarcatori singoli.Spedizioni collegate a questo appuntamento, come voci
{ id, added_at }, dal collegamento meno recente al più recente. Vedi
Collegare spedizioni.L’oggetto profilo completo del paziente, incorporato in ogni risposta di appuntamento. I campi sotto
sono un sottoinsieme. Ottieni appuntamento li elenca tutti.
Ciclo di vita
Gli appuntamenti espongono quattro stati del ciclo di vita:Lo stato dell’appuntamento è intenzionalmente sintetico — l’avanzamento più dettagliato è esposto
tramite endpoint dedicati:
- Completamento dei risultati di laboratorio →
Ottieni risultati — il campo
statusdi primo livello èin_progressocompleted. - Avanzamento della spedizione (in transito, consegnata ecc.) → segui ogni voce dell’array
shipmentsincorporato nell’appuntamento verso Ottieni spedizione — ogni spedizione ha il propriostatuse un registro eventistatus_updates.
appointment.*, ad esempio
appointment.confirmed. Un nuovo orario o una nuova sede invia appointment.rescheduled.Elencare gli appuntamenti
Recupera tutti gli appuntamenti accessibili alla tua chiave API:?profile_id={uuid} per filtrare per un profilo specifico. Senza questo parametro, viene applicata una finestra temporale predefinita (da 2 mesi fa a 1 mese nel futuro).
Aggiornare un appuntamento
Prima che il prelievo di sangue venga confermato, puoi riprogrammare l’appuntamento o cambiare la sede per i test:scheduled_at, location_id, draw_method e results_ready_emails per aggiornare. Includi solo i campi che vuoi modificare.
Metodo di prelievo
Ogni appuntamento ha undraw_method: capillary (polpastrello o parte superiore del braccio, in microtainer) o
venous (dalla vena, in provette). Si applica solo al prelievo di sangue. Urine, tamponi e altri
campioni non ematici vengono raccolti allo stesso modo con entrambi i metodi.
Per impostazione predefinita è il default_draw_method della sede. Imposta draw_method in fase di creazione o aggiornamento per
usare un altro metodo, oppure impostalo su null per tornare al valore predefinito della sede. La sede deve elencare
il metodo nei propri draw_methods e i test prenotati devono essere possibili con quel metodo, altrimenti la richiesta
restituisce 400. Non puoi modificarlo dopo il prelievo di sangue. Dopo il prelievo, draw_method è il
metodo che è stato utilizzato.
Un appuntamento per profilo, sede e orario
Un profilo può avere al massimo un appuntamento non annullato per coppia(location_id, scheduled_at) — una
persona non può fare due prelievi di sangue nello stesso posto e nello stesso momento, indipendentemente da quante prenotazioni parallele la
sede accetti.
Sia Crea appuntamento che
Aggiorna appuntamento applicano questa regola, restituendo 409 con un
appointment_id che punta all’appuntamento già esistente. Tratta quella risposta come prenotazione già
effettuata anziché come errore da ritentare: recupera, riprogramma o annulla l’appuntamento indicato.
L’effetto pratico è che le creazioni ripetute sono sicure. Una creazione che reinvii dopo un timeout di rete,
o che un utente avvia due volte, produce un solo appuntamento anziché due — il che significa anche che
non devi mai riconciliare prenotazioni duplicate per lo stesso paziente a posteriori.
Le modifiche sono consentite solo prima del prelievo di sangue — cioè finché l’appuntamento è nello
stato
pending o confirmed. Una volta che l’appuntamento passa a blood_drawn o cancelled,
non può più essere modificato. L’unica eccezione è results_ready_emails: puoi comunque cambiarlo
da solo dopo il prelievo di sangue.Annullare un appuntamento
Annulla un appuntamento che non serve più:cancelled. L’appuntamento annullato viene restituito nella risposta.
Puoi inviare facoltativamente un cancellation_reason (fino a 500 caratteri) nel body per
registrarne il motivo. Viene salvato sull’appuntamento e restituito come cancellation_reason nelle
letture successive.
L’annullamento è consentito solo prima del prelievo di sangue — cioè finché l’appuntamento è nello
stato
pending o confirmed. Gli appuntamenti già passati a blood_drawn non possono essere
annullati.Aggiungere pannelli
Prima di confermare il prelievo di sangue, aggiungi i pannelli di esami del sangue che vuoi eseguire chiamando:panel_ids. Gli ID dei pannelli vengono forniti da Aniva per il tuo account partner.
I pannelli devono essere aggiunti prima del prelievo di sangue — cioè finché l’appuntamento è
nello stato
pending o confirmed. Non puoi aggiungere o modificare pannelli una volta che
l’appuntamento è passato a blood_drawn.Rimuovere pannelli
Se devi rimuovere pannelli prima del prelievo di sangue, chiama:panel_ids. La rimozione è idempotente: un pannello non associato viene ignorato.
Come l’aggiunta di pannelli, la rimozione è consentita solo prima del prelievo di sangue — cioè
finché l’appuntamento è nello stato
pending o confirmed. I pannelli non possono essere rimossi
una volta che l’appuntamento è passato a blood_drawn.Singoli biomarcatori
Puoi associare singoli biomarcatori a un appuntamento come esami à la carte, al di fuori di qualsiasi pannello preconfigurato. È utile quando un professionista desidera una selezione su misura invece di un pacchetto predefinito. I biomarcatori associati compaiono nella risposta dell’appuntamento come arrayindividual_biomarkers (allo stesso livello di panels). Le decisioni di instradamento vengono prese a valle dalla pipeline logistica degli ordini in base alle mappature per laboratorio di ciascun biomarcatore.
Aggiungi biomarcatori (idempotente — i biomarcatori già associati vengono mantenuti):
biomarker_ids e validano l’insieme risultante rispetto alle regole di chiusura di ciascun laboratorio — un ordine che non può essere inoltrato in modo valido (ad es. un rapporto CRP/HDL senza CRP e HDL) restituisce 400 con i biomarcatori da aggiungere e non salva nulla. Usa Elenca biomarcatori per trovare gli ID dei biomarcatori.
Come le modifiche ai pannelli, i singoli biomarcatori possono essere aggiunti o rimossi solo prima
del prelievo di sangue — cioè finché l’appuntamento è nello stato
pending o confirmed. Una
volta che l’appuntamento passa a blood_drawn, lo snapshot personalizzato viene bloccato.Anteprima dei contenitori necessari
Dopo aver aggiunto pannelli o singoli biomarcatori, visualizza in anteprima i contenitori fisici necessari per la raccolta dei campioni:containers della risposta include tipo, nome, colore del tappo, volume, codice articolo del produttore e quantità per ciascun contenitore richiesto. Questo aiuta i professionisti a preparare il materiale corretto prima del prelievo di sangue. La risposta contiene anche un oggetto pricing — il conto complessivo dell’appuntamento (le voci applicate, i pannelli associati e una riga per ciascun biomarcatore fornito, al tuo listino con accanto il prezzo al pubblico; vedi Prezzi), valorizzato quando l’appuntamento ha esami associati e la tua chiave ha lo scope prices_view, altrimenti null. routing non viene intenzionalmente mai esposto ed è sempre null.
L’anteprima riflette i pannelli e i biomarcatori attualmente associati. Se aggiungi o rimuovi
pannelli dopo l’anteprima, richiama l’endpoint di anteprima per ottenere i contenitori aggiornati.
Confermare il prelievo di sangue
Dopo il prelievo di sangue, invia i codici di laboratorio (i codici a barre delle provette) per avviare la pipeline degli ordini di laboratorio:lab_code quando su tutte le provette è stampato un unico codice (prelievo venoso), oppure
lab_codes con una voce per codice — ciascuna con i panel_ids che copre — quando ogni pannello
viene raccolto nelle proprie provette con il proprio codice (prelievo capillare). Ogni pannello
diventa quindi una richiesta di laboratorio distinta con il proprio codice. I codici vengono
restituiti come lab_codes sull’appuntamento.
In un prelievo capillare, il sangue prelevato viene suddiviso in microtainer. I pannelli vanno per
primi, in ordine di prenotazione. I singoli biomarcatori riempiono poi lo spazio libero dei
microtainer dei pannelli. Quando serve più spazio, aprono nuovi microtainer. Li distribuiamo in modo
uniforme. Ogni microtainer contiene al massimo 150 µl di singoli biomarcatori. Le chiamate che
modificano pannelli o biomarcatori rispondono 400 quando l’insieme risultante viola questa regola.
Questo porta lo stato dell’appuntamento a blood_drawn e avvia l’elaborazione in laboratorio. Questa azione è irreversibile.
Ritiro della spedizione
Per seguire l’avanzamento dopo il prelievo di sangue, segui ogni voce dell’array inlineshipments
dell’appuntamento verso Ottieni spedizione — ogni spedizione ha il
proprio status e una cronologia status_updates.
Collegare spedizioni
Un appuntamento può essere collegato a una o più spedizioni (e viceversa — la relazione è molti-a-molti). L’insieme dei collegamenti attuali compare inline su entrambi i lati:- sull’appuntamento, come array
shipmentsdi voci{ id, added_at }; - sulla spedizione, come array
appointmentsdi voci{ id, added_at }.
id rimanda
all’endpoint di dettaglio canonico (Ottieni spedizione /
Ottieni appuntamento) per il payload completo.
Le spedizioni vengono collegate al momento della creazione tramite il campo appointment_id in
Crea spedizione. Dopo la creazione, gestisci i collegamenti dalla
spedizione con Collega appuntamenti alla spedizione
e Scollega appuntamenti dalla spedizione; ciascuno
restituisce l’elenco degli appuntamenti aggiornato per quella spedizione. Per leggere per intero i
colli di un appuntamento, usa Elenca spedizioni con ?appointment_id=.
La regola di modifica è: i collegamenti possono essere creati o rimossi quando O
- l’appuntamento ha superato il prelievo di sangue (
blood_drawn), oppure - la spedizione è stata creata meno di 24 ore fa.
Recuperare i risultati di laboratorio
Una volta che il laboratorio ha elaborato i campioni di sangue, recupera i risultati clinici e genetici:planned) accanto ai risultati ricevuti, così puoi
monitorare cosa è ancora in sospeso. Il campo status di primo livello è in_progress finché ogni
invio non si chiude, poi completed (o fault se nessuno ha restituito risultati) — usalo per
sapere se le analisi di laboratorio dell’appuntamento sono terminate. Un
webhook appointment.results.completed ti avvisa quando succede, così non
devi fare polling. L’array submissions suddivide questo stato per singola richiesta di
laboratorio, ciascuna con il proprio lab_code. Ogni risultato ricevuto e ogni documento riporta
il lab_code con cui è stato registrato. I PDF dei referti di laboratorio sono indicati
nell’array documents — usa GET /api/v1/documents/{id} per scaricarli.