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

# Aggiorna appuntamento

> Modifica i dettagli dell'appuntamento prima del prelievo di sangue

Aggiorna i dettagli dell'appuntamento, come l'orario programmato o la sede dell'esame. È possibile modificare solo gli appuntamenti per cui il prelievo di sangue non è ancora stato confermato.

> [!WARNING]
>
> Gli appuntamenti non possono essere modificati dopo la conferma del prelievo di sangue o se sono
> già stati annullati. Tentare di aggiornare un appuntamento di questo tipo restituisce
> `409 Conflict`. L'unica eccezione è `results_ready_emails`, che puoi ancora modificare dopo il
> prelievo di sangue.

Richiede lo scope `appointments_schedule` o `appointments_manage`.

## Richiesta

### Parametri di percorso

**id** `string` *required*

Identificatore univoco (UUID) dell'appuntamento da aggiornare.

### Parametri del body

Tutti i parametri del body sono facoltativi — includi solo i campi che vuoi modificare.

**scheduled\_at** `string`

Nuova data e ora dell'appuntamento in formato ISO 8601 (ad es., `2026-05-20T14:00:00Z` o
`2026-05-20T16:00:00+02:00`). **Deve includere un indicatore di fuso orario** — `Z` oppure un
offset esplicito come `+02:00`; le date senza fuso orario vengono rifiutate. Deve essere nel futuro.

Deve corrispondere esattamente all'inizio di uno slot con capacità residua — consulta
[Ottieni disponibilità](https://docs.anivahealth.com/it/api/locations/get-availability.md). L'appuntamento riprogrammato non viene
mai conteggiato nel proprio slot di destinazione, ma spostarlo in uno slot in cui lo stesso profilo
ha già un *altro* appuntamento restituisce `409` con l'`appointment_id` di quell'appuntamento.

Se la sede *di destinazione* è gestita da Aniva, il nuovo orario deve essere anche ad almeno 12 ore
di distanza — consulta [Preavviso minimo](https://docs.anivahealth.com/it/api/appointments/create-appointment.md#preavviso-minimo).

**location\_id** `string`

UUID della nuova sede dell'esame. La sede deve esistere ed essere attiva. Usa [Elenca
sedi](https://docs.anivahealth.com/it/api/locations/list-locations.md) per trovare gli ID delle sedi disponibili.

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

Sostituisce l'elenco di massimo 5 indirizzi che ricevono ciascuno un'email quando tutti i
risultati di laboratorio sono definitivi. Invia `[]` per disattivare le email. Questo campo resta
modificabile dopo il prelievo di sangue; solo un appuntamento annullato lo rifiuta. Dopo il
prelievo di sangue, invialo da solo: con `scheduled_at` o `location_id` nello stesso body, la
richiesta restituisce `409`. La tua chiave necessita dell'accesso `results_view` al paziente,
altrimenti `403`. Consulta [Email per risultati pronti](https://docs.anivahealth.com/it/concepts/results.md#email-di-risultati-pronti).

**draw\_method** `string | null`

Nuovo metodo di prelievo: `capillary` o `venous`, oppure `null` per usare nuovamente il
`default_draw_method` della sede. La sede deve elencare il metodo in `draw_methods` e gli esami
prenotati devono essere compatibili, altrimenti `400`. Quando sposti un appuntamento in un'altra
sede, lo stesso controllo viene eseguito lì: sul proprio `draw_method`, oppure sul
`default_draw_method` della nuova sede.

## Risposta

In caso di successo, l'API restituisce `200 OK` con l'appuntamento aggiornato e il relativo profilo incorporato.

**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`, ad es.
`2026-05-20T14:00: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.

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

Timestamp ISO 8601 della creazione dell'appuntamento.

**updated\_at** `string`

Timestamp ISO 8601 dell'ultimo aggiornamento. Può essere `null`.

**profile** `object` *required*

Il profilo del paziente associato a questo appuntamento.

**profilo**

**id** `string`

Identificatore 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`.

**created\_at** `string`

Timestamp ISO 8601 della creazione del profilo.

**updated\_at** `string`

Timestamp ISO 8601 dell'ultimo aggiornamento del profilo. Può essere `null`.

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

Pannelli attualmente associati a questo appuntamento. Esclude le associazioni annullate. Consulta i dettagli del pannello
(nome, biomarcatori) tramite [Elenco 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 collegati a questo appuntamento al di fuori dei pannelli (vedi [Aggiungi biomarcatori
personalizzati](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 meno recente. Array vuoto
quando non ci sono spedizioni collegate. Confronta ciascun `id` con [Ottieni
spedizione](https://docs.anivahealth.com/it/api/shipments/get-shipment.md) per il payload completo della spedizione.

**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`.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | Errore di convalida — ad es. `scheduled_at` è nel passato, è a meno di 12 ore di distanza presso una sede gestita da Aniva, formato UUID non valido, la sede non dispone di contenitori per il `draw_method`, oppure gli esami prenotati non sono possibili con il `draw_method`. |
| `403` | Vietato — la tua chiave API non ha accesso a questa operazione, l'appuntamento o la sede è fuori dal tuo contesto di accesso, oppure `results_ready_emails` è impostato senza accesso `results_view` al paziente. |
| `404` | Appuntamento o sede non trovati. |
| `409` | Impossibile modificare l'appuntamento (prelievo di sangue già confermato o appuntamento annullato), la fascia oraria richiesta è al completo, la sede è chiusa in quella data, oppure questo profilo ha già un altro appuntamento nella sede e all'orario richiesti (include `appointment_id`). |
| `500` | Errore interno del server. |

```bash cURL theme={null}
curl --request PATCH \
  --url https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "scheduled_at": "2026-05-20T14:00:00Z",
    "location_id": "d8f3e1a2-4c5b-6d7e-8f9a-0b1c2d3e4f5a"
  }'
```

```json 200 theme={null}
{
  "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
  "profile_id": "a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d",
  "location_id": "d8f3e1a2-4c5b-6d7e-8f9a-0b1c2d3e4f5a",
  "scheduled_at": "2026-05-20T14:00:00Z",
  "status": "confirmed",
  "cancellation_reason": null,
  "results_ready_emails": [],
  "draw_method": "venous",
  "created_at": "2026-04-01T09:45:00Z",
  "updated_at": "2026-04-10T11:30:00Z",
  "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": [
    {
      "panel_id": "f1c2d4a3-7b8e-4f2a-9c1d-2e3f4a5b6c7d",
      "added_at": "2026-04-01T09:50:00Z"
    }
  ],
  "individual_biomarkers": [],
  "shipments": [],
  "lab_codes": []
}
```

```json 409 theme={null}
{
  "error": "Appointment cannot be modified after blood draw has been confirmed"
}
```

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


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