> ## 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.

# Crea appuntamento

> Programma un appuntamento per il prelievo di sangue per un profilo in una sede d'esame

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](https://docs.anivahealth.com/it/api/appointments/add-panels.md) per associare i pannelli di esami del sangue prima di [confermare il prelievo di sangue](https://docs.anivahealth.com/it/api/appointments/confirm-blood-draw.md).

> [!NOTE]
>
> 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](#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](https://docs.anivahealth.com/it/concepts/idempotency.md).

Richiede lo scope `appointments_schedule`.

## Richiesta

### Parametri del body

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

UUID del profilo paziente per cui creare l'appuntamento.

**location\_id** `string` *required*

UUID della sede del test in cui si svolgerà il prelievo di sangue. Usa [Elenca
sedi](https://docs.anivahealth.com/it/api/locations/list-locations.md) per trovare gli ID delle sedi disponibili.

**scheduled\_at** `string` *required*

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à](https://docs.anivahealth.com/it/api/locations/get-availability.md). 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](#preavviso-minimo).

**results\_ready\_emails** `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](https://docs.anivahealth.com/it/concepts/results.md#email-di-risultati-pronti).

**draw\_method** `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.

**id** `string` *required*

Identificatore univoco dell'appuntamento (UUID).

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

UUID del profilo a cui appartiene questo appuntamento.

**location\_id** `string`

UUID della sede del test in cui avviene il prelievo di sangue.

**scheduled\_at** `string`

Data e ora programmate dell'appuntamento come istante UTC (ISO 8601 con suffisso `Z`, es.
`2026-05-15T10:30:00Z`). Può essere `null`.

**status** `string` *required*

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](https://docs.anivahealth.com/it/api/appointments/get-results.md);
l'avanzamento più dettagliato delle spedizioni da ciascuna voce nell'array inline `shipments` (vedi sotto),
da consultare su [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.

**profile** `object` *required*

Il profilo del paziente associato a questo appuntamento.

**profile**

**id** `string`

Identificativo univoco del profilo (UUID).

**handle** `string`

Handle o nome utente del profilo. Può essere `null`.

**first\_name** `string`

Nome. Può essere `null`.

**last\_name** `string`

Cognome. Può essere `null`.

**email** `string`

Indirizzo email. Può essere `null`.

**phone** `string`

Numero di telefono in formato E.164. Può essere `null`.

**sex** `integer`

Sesso biologico secondo ISO/IEC 5218. Può essere `null`.

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

Data di nascita in formato `YYYY-MM-DD`. Può essere `null`.

**height** `number`

Altezza in centimetri. Può essere `null`.

**weight** `number`

Peso in chilogrammi. Può essere `null`.

**language** `string`

Lingua preferita: uno dei 32 codici in [Crea profilo](https://docs.anivahealth.com/it/api/profiles/create-profile.md).

**transactional\_emails\_enabled** `boolean`

Indica se questo profilo riceve email transazionali (programmatiche). Può essere `null`.

**panels** `AppointmentPanel[]` *required*

Pannelli attualmente associati a questo appuntamento. Vuoto per gli appuntamenti appena creati — associali tramite
[Aggiungi pannelli](https://docs.anivahealth.com/it/api/appointments/add-panels.md). Consulta i dettagli dei pannelli (nome, biomarcatori) tramite
[Elenca pannelli](https://docs.anivahealth.com/it/api/panels/list-panels.md).

**Campi del pannello collegato**

**panel\_id** `string`

UUID del pannello — confrontalo con [Elenca pannelli](https://docs.anivahealth.com/it/api/panels/list-panels.md).

**added\_at** `string`

Timestamp ISO 8601 del momento in cui il pannello è stato collegato per la prima volta a questo appuntamento.

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

Biomarcatori singoli associati a questo appuntamento al di fuori di qualsiasi pannello. Vuoto per gli appuntamenti appena
creati — associali tramite [Aggiungi biomarcatori singoli](https://docs.anivahealth.com/it/api/appointments/add-individual-biomarkers.md).
Confronta ogni `biomarker_id` con [Elenca biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md)
per i dati di visualizzazione.

**Campi del biomarcatore singolo**

**biomarker\_id** `integer`

Identificatore del biomarcatore — confrontalo con
[Elenca biomarcatori](https://docs.anivahealth.com/it/api/biomarkers/list-biomarkers.md).

**added\_at** `string`

Timestamp ISO 8601 del momento in cui il biomarcatore è stato collegato per la prima volta a questo appuntamento.

**shipments** `AppointmentShipmentLink[]` *required*

Spedizioni collegate a questo appuntamento, a partire dal collegamento più vecchio. Vuoto per gli appuntamenti appena creati —
collegale tramite [Crea spedizione](https://docs.anivahealth.com/it/api/shipments/create-shipment.md) (con `appointment_id`) o
[Associa appuntamenti a una spedizione](https://docs.anivahealth.com/it/api/shipments/attach-appointments-to-shipment.md).

**Campi del collegamento della spedizione**

**id** `string`

Identificatore di riferimento della spedizione — confrontalo con
[Ottieni spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md).

**added\_at** `string`

Timestamp ISO 8601 del momento in cui la spedizione è stata collegata per la prima volta a questo appuntamento.

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

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](https://docs.anivahealth.com/it/api/appointments/get-results.md) 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à](https://docs.anivahealth.com/it/api/locations/get-availability.md) 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:

```json theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```

Gestiscilo considerando la richiesta già applicata: recupera l'appuntamento con
[Ottieni appuntamento](https://docs.anivahealth.com/it/api/appointments/get-appointment.md), spostalo con
[Aggiorna appuntamento](https://docs.anivahealth.com/it/api/appointments/update-appointment.md) o eliminalo con
[Annulla appuntamento](https://docs.anivahealth.com/it/api/appointments/cancel-appointment.md). 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.

> [!NOTE]
>
> `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à](https://docs.anivahealth.com/it/api/locations/get-availability.md).

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di validazione — ad es., `scheduled_at` è nel passato, è a meno di 12 ore di distanza in una sede gestita da Aniva o non corrisponde all'inizio esatto di uno slot nella griglia della sede, oppure la sede non dispone di contenitori per `draw_method`. |
| `403` | Accesso negato — la tua chiave API non ha accesso a questa operazione, oppure `results_ready_emails` è impostato senza accesso `results_view` per il paziente. |
| `404` | Profilo o sede non trovati, oppure la sede non è attiva. |
| `409` | Questo profilo ha già un appuntamento in questa sede e a quest'ora (include `appointment_id`), lo slot è al completo, la sede è chiusa in quella data, oppure `Idempotency-Key` è stata riutilizzata con un corpo diverso o la sua richiesta originale non è ancora stata completata. |
| `500` | Errore interno del server. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/appointments \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
    "scheduled_at": "2026-05-15T10:30:00Z"
  }'
```

```json 201 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "scheduled_at": "2026-05-15T10:30:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": null,
  "profile": {
    "id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
    "handle": null,
    "first_name": "Maria",
    "last_name": "Schmidt",
    "email": "maria.schmidt@example.com",
    "phone": "+4930123456789",
    "sex": 2,
    "date_of_birth": "1985-03-22",
    "height": 168,
    "weight": 65,
    "language": "de",
    "transactional_emails_enabled": true,
    "created_at": "2026-04-01T09:14:32Z",
    "updated_at": null
  },
  "panels": [],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 400 theme={null}
{
  "error": "Appointments must be booked at least 12 hours in advance. Please pick a later time."
}
```

```json 404 theme={null}
{
  "error": "Location not found or inactive"
}
```

```json 409 theme={null}
{
  "error": "This profile already has an appointment at this location and time. Reschedule or cancel the existing appointment instead of creating a second one.",
  "appointment_id": "03e916d2-7fd6-4414-8276-8532a105edc3"
}
```


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