> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Appuntamenti

> Come funzionano gli appuntamenti per il prelievo di sangue nell'API di Aniva per gli esami di laboratorio: prenotazione, pannelli, biomarcatori, cambi di stato e cancellazione.

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](https://docs.anivahealth.com/it/concepts/home-kit-orders.md).

## Campi

**id** `string` *required*

UUID generato automaticamente da Aniva. Usalo per aggiungere pannelli, confermare il prelievo e recuperare i risultati.

**profile\_id** `string` *required*

L'UUID del profilo a cui appartiene questo appuntamento.

**location\_id** `string`

L'UUID della sede per i test in cui avverrà il prelievo. I kit domiciliari non sono appuntamenti — vedi
[Ordini di kit domiciliari](https://docs.anivahealth.com/it/concepts/home-kit-orders.md).

**scheduled\_at** `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](https://docs.anivahealth.com/it/api/appointments/create-appointment.md#preavviso-minimo)).

**status** `string` *required*

Stato attuale del ciclo di vita. Uno tra `pending`, `confirmed`, `blood_drawn` o `cancelled`. Vedi
[Ciclo di vita](#ciclo-di-vita) sotto. Il livello di completamento dei risultati di laboratorio (`in_progress` o `completed`)
si ricava da [Ottieni risultati](https://docs.anivahealth.com/it/api/appointments/get-results.md); l'avanzamento più dettagliato della spedizione (in
transito, consegnata ecc.) si ricava seguendo ogni voce dell'array `shipments` incorporato verso
[Ottieni spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md).

**cancellation\_reason** `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`.

**results\_ready\_emails** `string[]` *required*

Indirizzi che ricevono ciascuno un'email quando tutti i risultati di laboratorio sono definitivi, in minuscolo. Vuoto se disattivato. Vedi
[Email di risultati pronti](https://docs.anivahealth.com/it/concepts/results.md#email-di-risultati-pronti).

**draw\_method** `string` *required*

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](https://docs.anivahealth.com/it/concepts/locations.md). Dopo il prelievo di sangue, è il metodo utilizzato.

**created\_at** `string` *required*

Timestamp ISO 8601 della creazione dell'appuntamento.

**updated\_at** `string`

Timestamp ISO 8601 dell'aggiornamento più recente. Nullo se l'appuntamento non è mai stato aggiornato.

**lab\_codes** `string[]` *required*

Codici di laboratorio (codici a barre delle provette) registrati con [Conferma prelievo di sangue](https://docs.anivahealth.com/it/api/appointments/confirm-blood-draw.md),
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`.

**panels** `object[]` *required*

Pannelli associati a questo appuntamento, come voci `{ panel_id, added_at }`. Vedi
[Aggiungere pannelli](#aggiungere-pannelli).

**individual\_biomarkers** `object[]` *required*

Biomarcatori singoli associati a questo appuntamento, come voci `{ biomarker_id, added_at }`. Vedi
[Biomarcatori singoli](#singoli-biomarcatori).

**shipments** `object[]` *required*

Spedizioni collegate a questo appuntamento, come voci `{ id, added_at }`, dal collegamento meno recente al più recente. Vedi
[Collegare spedizioni](#collegare-spedizioni).

**profile** `object` *required*

L'oggetto profilo completo del paziente, incorporato in ogni risposta di appuntamento. I campi sotto
sono un sottoinsieme. [Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md) li elenca tutti.

**proprietà**

**id** `string`

UUID del profilo associato.

**first\_name** `string`

Nome del paziente.

**last\_name** `string`

Cognome del paziente.

**email** `string`

Indirizzo email del paziente.

**date\_of\_birth** `string`

Data di nascita in formato `YYYY-MM-DD`.

**sex** `integer`

Sesso biologico secondo ISO/IEC 5218.

## Ciclo di vita

Gli appuntamenti espongono quattro stati del ciclo di vita:

```
pending → confirmed → blood_drawn
   │          │             │
   └──────────┴─────────────┴──→ cancelled
```

| Stato | Significato |
| - | - |
| `pending` | L'appuntamento è programmato e in attesa di conferma. Può essere [aggiornato](https://docs.anivahealth.com/it/api/appointments/update-appointment.md) o [annullato](https://docs.anivahealth.com/it/api/appointments/cancel-appointment.md). |
| `confirmed` | La programmazione è stata confermata (ad es. dallo studio), ma il prelievo di sangue non è ancora stato effettuato. Può ancora essere aggiornato o annullato. |
| `blood_drawn` | I codici di laboratorio sono stati inviati tramite [Conferma prelievo di sangue](https://docs.anivahealth.com/it/api/appointments/confirm-blood-draw.md) e il flusso dell'ordine di laboratorio è stato avviato. I pannelli sono bloccati e l'appuntamento non può essere riprogrammato né annullato. |
| `cancelled` | L'appuntamento è stato annullato. Stato finale — nessuna ulteriore transizione. |

> [!NOTE]
>
> Lo stato dell'appuntamento è intenzionalmente sintetico — l'avanzamento più dettagliato è esposto
> tramite endpoint dedicati:
>
> * **Completamento dei risultati di laboratorio** →
>   [Ottieni risultati](https://docs.anivahealth.com/it/api/appointments/get-results.md) — 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](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) — ogni
>   spedizione ha il proprio `status` e un registro eventi `status_updates`.
>
> Ogni cambio di stato invia un [webhook](https://docs.anivahealth.com/it/concepts/webhooks.md) `appointment.*`, ad esempio
> `appointment.confirmed`. Un nuovo orario o una nuova sede invia `appointment.rescheduled`.

> [!WARNING]
>
> 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:

```
GET /api/v1/appointments
```

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:

```
PATCH /api/v1/appointments/{id}
```

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](https://docs.anivahealth.com/it/api/appointments/create-appointment.md) che
[Aggiorna appuntamento](https://docs.anivahealth.com/it/api/appointments/update-appointment.md) 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.

> [!NOTE]
>
> 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ù:

```
DELETE /api/v1/appointments/{id}
```

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.

> [!NOTE]
>
> 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:

```
POST /api/v1/appointments/{id}/panels
```

Passa un array di UUID dei pannelli nel campo `panel_ids`. Gli ID dei pannelli vengono forniti da Aniva per il tuo account partner.

> [!NOTE]
>
> 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:

```
DELETE /api/v1/appointments/{id}/panels
```

Passa un array di UUID dei pannelli nel campo `panel_ids`. La rimozione è idempotente: un pannello non associato viene ignorato.

> [!NOTE]
>
> 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):

```
PATCH /api/v1/appointments/{id}/biomarkers
```

Rimuovi biomarcatori (idempotente — i biomarcatori non associati vengono ignorati):

```
DELETE /api/v1/appointments/{id}/biomarkers
```

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](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md) per trovare gli ID dei biomarcatori.

> [!NOTE]
>
> 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:

```
GET /api/v1/appointments/{id}/preview
```

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](https://docs.anivahealth.com/it/concepts/pricing.md)), 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`.

> [!NOTE]
>
> 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:

```
POST /api/v1/appointments/{id}/confirm
```

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

> [!WARNING]
>
> `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](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) — 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](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) /
[Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md)) per il payload completo.

Le spedizioni vengono collegate al momento della creazione tramite il campo `appointment_id` in
[Crea spedizione](https://docs.anivahealth.com/it/api/shipments/create-shipment.md). Dopo la creazione, gestisci i collegamenti dalla
spedizione con [Collega appuntamenti alla spedizione](https://docs.anivahealth.com/it/api/shipments/attach-appointments-to-shipment.md)
e [Scollega appuntamenti dalla spedizione](https://docs.anivahealth.com/it/api/shipments/detach-appointments-from-shipment.md); ciascuno
restituisce l'elenco degli appuntamenti aggiornato per quella spedizione. Per leggere per intero i
colli di un appuntamento, usa [Elenca spedizioni](https://docs.anivahealth.com/it/api/shipments/list-shipments.md) 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:

```
GET /api/v1/appointments/{id}/results
```

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](https://docs.anivahealth.com/it/concepts/webhooks.md) `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

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "profile_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "location_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_at": "2026-04-15T08:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": null,
  "profile": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "handle": null,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1990-06-15",
    "height": 170,
    "weight": 62,
    "language": "en",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:55:00Z",
    "updated_at": null
  },
  "panels": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T10:05:00Z"
    }
  ],
  "individual_biomarkers": [
    {
      "biomarker_id": 42,
      "added_at": "2026-04-01T10:07:00Z"
    }
  ],
  "shipments": [
    {
      "id": "P2611194821",
      "added_at": "2026-04-15T07:00:00Z"
    }
  ],
  "lab_codes": []
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.