Vai al contenuto principale
POST
Prenota un appuntamento per un prelievo di sangue per il profilo di un paziente in una specifica sede del test. Una volta creato, l’appuntamento entra per impostazione predefinita nello stato confirmed (alcune sedi possono invece partire da pending — è un’impostazione specifica della sede). Usa Aggiungi pannelli per associare i pannelli di esami del sangue prima di confermare il prelievo di sangue.
Un profilo può avere al massimo un appuntamento per sede e orario. Creare un appuntamento per uno slot già occupato dal profilo restituisce 409 con l’appointment_id esistente invece di un secondo appuntamento — così una richiesta ripetuta o inviata di nuovo per errore non può mai duplicare una prenotazione. Vedi Appuntamenti duplicati.
Invia un header opzionale Idempotency-Key per poter ripetere questa creazione in sicurezza — ripetere la stessa chiave restituisce la risposta originale invece di crearne una seconda. Vedi Idempotenza. Richiede lo scope appointments_schedule.

Richiesta

Parametri del body

string
obbligatorio
UUID del profilo paziente per cui creare l’appuntamento.
string
obbligatorio
UUID della sede del test in cui si svolgerà il prelievo di sangue. Usa Elenca sedi per trovare gli ID delle sedi disponibili.
string
obbligatorio
Data e ora dell’appuntamento in formato ISO 8601 (ad es. 2026-05-15T10:30:00Z o 2026-05-15T12:30:00+02:00). Deve includere un indicatore di fuso orario — Z oppure un offset esplicito come +02:00; le date e ore senza fuso orario vengono rifiutate. Deve essere nel futuro.Deve corrispondere all’inizio esatto di uno slot nella griglia della sede e lo slot deve avere ancora disponibilità — consulta prima Ottieni disponibilità. Gli orari fuori griglia restituiscono 400; uno slot già pieno restituisce 409. Nelle sedi gestite da Aniva deve inoltre essere ad almeno 12 ore di distanza — vedi Preavviso minimo.
string[]
Fino a 5 indirizzi che ricevono ciascuno un’email quando tutti i risultati di laboratorio sono definitivi. L’email rimanda alla pagina dei risultati nel pannello di amministrazione Aniva. La tua chiave richiede l’accesso results_view per il paziente, altrimenti 403. Omettilo per usare gli indirizzi predefiniti impostati per il gruppo del paziente. Una lista vuota disattiva le email. Vedi Email di risultati pronti.
string
Come viene effettuato il prelievo di sangue: capillary o venous. Omettilo per usare il default_draw_method della sede. La sede deve includere il metodo in draw_methods, altrimenti 400.

Risposta

In caso di successo, l’API restituisce 201 Created con il nuovo appuntamento.
string
obbligatorio
Identificatore univoco dell’appuntamento (UUID).
string
obbligatorio
UUID del profilo a cui appartiene questo appuntamento.
string
UUID della sede del test in cui avviene il prelievo di sangue.
string
Data e ora programmate dell’appuntamento come istante UTC (ISO 8601 con suffisso Z, es. 2026-05-15T10:30:00Z). Può essere null.
string
obbligatorio
Stato attuale dell’appuntamento. Uno tra pending, confirmed, blood_drawn o cancelled. Il dettaglio di completamento dei risultati di laboratorio si ricava da Ottieni risultati; l’avanzamento più dettagliato delle spedizioni da ciascuna voce nell’array inline shipments (vedi sotto), da consultare su 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.
object
obbligatorio
Il profilo del paziente associato a questo appuntamento.
AppointmentPanel[]
obbligatorio
Pannelli attualmente associati a questo appuntamento. Vuoto per gli appuntamenti appena creati — associali tramite Aggiungi pannelli. Consulta i dettagli dei pannelli (nome, biomarcatori) tramite Elenca pannelli.
AppointmentIndividualBiomarker[]
obbligatorio
Biomarcatori singoli associati a questo appuntamento al di fuori di qualsiasi pannello. Vuoto per gli appuntamenti appena creati — associali tramite Aggiungi biomarcatori singoli. Confronta ogni biomarker_id con Elenca biomarcatori per i dati di visualizzazione.
AppointmentShipmentLink[]
obbligatorio
Spedizioni collegate a questo appuntamento, a partire dal collegamento più vecchio. Vuoto per gli appuntamenti appena creati — collegale tramite Crea spedizione (con appointment_id) o Associa appuntamenti a una spedizione.
string[]
obbligatorio
Codici di laboratorio (codici a barre delle provette) registrati per questo appuntamento, in ordine di scansione. Vuoto finché il prelievo di sangue non viene confermato. Un prelievo venoso ha un unico codice stampato su ogni provetta; un prelievo capillare ha un codice per ogni microprovetta. Risultati e documenti in Ottieni risultati fanno riferimento a questi codici tramite lab_code.

Preavviso minimo

Gli appuntamenti nelle sedi gestite da Aniva devono essere prenotati con almeno 12 ore di anticipo; prenotare in quella finestra restituisce 400. Ottieni disponibilità esclude già quegli slot, quindi tutto ciò che leggi da quella griglia è prenotabile. Le sedi che gestisci in autonomia non hanno alcun preavviso minimo — le prenotazioni in giornata e senza appuntamento restano invariate.

Appuntamenti duplicati

Un profilo può avere al massimo un appuntamento non annullato per sede e istante — una persona non può fare due prelievi nello stesso luogo e nello stesso momento, indipendentemente da quante poltrone abbia la sede. Creare un appuntamento per uno slot già occupato dal profilo restituisce 409 con un appointment_id che indica l’appuntamento già esistente:
Gestiscilo considerando la richiesta già applicata: recupera l’appuntamento con Ottieni appuntamento, spostalo con Aggiorna appuntamento o eliminalo con Annulla appuntamento. Non riprovare la creazione — continuerà a restituire 409. Questo rende sicure le creazioni ripetute: una richiesta che invii di nuovo dopo un timeout, o un modulo inviato due volte, non può generare due appuntamenti per lo stesso paziente allo stesso orario.
appointment_id è presente solo nel 409 per duplicato. Il 409 per capacità esaurita — lo slot è pieno perché occupato da altri pazienti — restituisce solo error, e la soluzione corretta in quel caso è scegliere uno slot diverso da Ottieni disponibilità.

Risposte di errore