Vai al contenuto principale
Un appuntamento è un prelievo di sangue programmato per un profilo paziente in una sede fisica per i test, eseguito da un operatore sanitario. I kit spediti al paziente non sono appuntamenti — vedi Ordini di kit domiciliari.

Campi

string
obbligatorio
UUID generato automaticamente da Aniva. Usalo per aggiungere pannelli, confermare il prelievo e recuperare i risultati.
string
obbligatorio
L’UUID del profilo a cui appartiene questo appuntamento.
string
L’UUID della sede per i test in cui avverrà il prelievo. I kit domiciliari non sono appuntamenti — vedi Ordini di kit domiciliari.
string
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).
string
obbligatorio
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.
string
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.
string[]
obbligatorio
Indirizzi che ricevono ciascuno un’email quando tutti i risultati di laboratorio sono definitivi, in minuscolo. Vuoto se disattivato. Vedi Email di risultati pronti.
string
obbligatorio
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.
string
obbligatorio
Timestamp ISO 8601 della creazione dell’appuntamento.
string
Timestamp ISO 8601 dell’aggiornamento più recente. Nullo se l’appuntamento non è mai stato aggiornato.
string[]
obbligatorio
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.
object[]
obbligatorio
Pannelli associati a questo appuntamento, come voci { panel_id, added_at }. Vedi Aggiungere pannelli.
object[]
obbligatorio
Biomarcatori singoli associati a questo appuntamento, come voci { biomarker_id, added_at }. Vedi Biomarcatori singoli.
object[]
obbligatorio
Spedizioni collegate a questo appuntamento, come voci { id, added_at }, dal collegamento meno recente al più recente. Vedi Collegare spedizioni.
object
obbligatorio
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 status di primo livello è in_progress o completed.
  • Avanzamento della spedizione (in transito, consegnata ecc.) → segui ogni voce dell’array shipments incorporato nell’appuntamento verso Ottieni spedizione — ogni spedizione ha il proprio status e un registro eventi status_updates.
Ogni cambio di stato invia un webhook appointment.*, ad esempio appointment.confirmed. Un nuovo orario o una nuova sede invia appointment.rescheduled.
Confermare un appuntamento (portarlo a blood_drawn) è irreversibile. Una volta inviati il codice o i codici di laboratorio, il flusso dell’ordine di laboratorio viene avviato e non può essere annullato. Aggiornamenti e annullamenti sono consentiti solo finché l’appuntamento è in stato pending o confirmed.

Elencare gli appuntamenti

Recupera tutti gli appuntamenti accessibili alla tua chiave API:
Facoltativamente passa ?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:
Passa qualsiasi combinazione di 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 un draw_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ù:
Questo imposta lo stato dell’appuntamento su 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:
Passa un array di UUID dei pannelli nel campo 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:
Passa un array di UUID dei pannelli nel campo 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 array individual_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):
Rimuovi biomarcatori (idempotente — i biomarcatori non associati vengono ignorati):
Entrambi gli endpoint accettano un array 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:
L’array 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:
Invia 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

POST /api/v1/appointments/pickup è stato rimosso, insieme allo stato dell’appuntamento shipment_picked_up. Ora risponde 405 Method Not Allowed, perché il percorso ricade sulla rotta dell’appuntamento per ID. Nella sua fase finale l’endpoint era un no-op che accettava la chiamata senza fare nulla, quindi la sua rimozione non cambia alcun comportamento su cui facevi affidamento.
Per seguire l’avanzamento dopo il prelievo di sangue, segui ogni voce dell’array inline shipments 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 shipments di voci { id, added_at };
  • sulla spedizione, come array appointments di voci { id, added_at }.
Entrambi gli array sono ordinati dal collegamento più vecchio al più recente. Ogni 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.
Al di fuori di questa finestra il collegamento è bloccato così i dati storici restano stabili.

Recuperare i risultati di laboratorio

Una volta che il laboratorio ha elaborato i campioni di sangue, recupera i risultati clinici e genetici:
La risposta include gli esami pianificati (stato 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.

Esempio di appuntamento