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

# Ottieni disponibilità

> Recupera gli orari di inizio degli slot prenotabili per una singola sede

Restituisce gli orari di inizio degli slot prenotabili per una singola sede nell'intervallo richiesto. Gli slot vengono
generati a partire da `open_hours` della sede, saltando le date bloccate globali / per sede e
sottraendo gli appuntamenti Aniva già prenotati, così il risultato rispecchia ciò che i tuoi pazienti possono
effettivamente prenotare lato client.

Richiede lo scope `appointments_schedule`. La sede deve inoltre rientrare nel contesto di accesso ai gruppi di sedi della tua chiave API.

> [!NOTE]
>
> Usa questo endpoint invece di dedurre la disponibilità dagli orari statici `open_hours` restituiti da [Elenca
> sedi](https://docs.anivahealth.com/it/api/locations/list-locations.md) — solo questo endpoint tiene conto delle prenotazioni in tempo reale,
> delle eccezioni di orario per singola data e del [preavviso
> minimo](https://docs.anivahealth.com/it/api/appointments/create-appointment.md#preavviso-minimo) di 12 ore presso le sedi gestite da Aniva. Ogni
> slot restituito qui è prenotabile così com'è.

Le risposte includono `Cache-Control: private, max-age=30, stale-while-revalidate=60`, quindi un browser può
servire un payload in cache fino a \~30 secondi — uno slot prenotato in quella finestra può risultare ancora
prenotabile fino al successivo aggiornamento. Mostra eventuali conflitti anche al momento della prenotazione.

## Parametri di percorso

**id** `string` *required*

Identificativo della sede (UUID). Usa l'`id` di [Elenca sedi](https://docs.anivahealth.com/it/api/locations/list-locations.md).

## Parametri di query

**start\_date** `string`

Inizio inclusivo dell'intervallo in formato `YYYY-MM-DD` (interpretato in `timezone`). Facoltativo. Il valore predefinito è
**oggi** quando non viene fornita nessuna data, oppure **`end_date − 30 days`** quando viene fornita solo `end_date`.
Le date passate vengono automaticamente riportate a oggi.

**end\_date** `string`

Fine inclusiva dell'intervallo in formato `YYYY-MM-DD` (interpretata in `timezone`). Facoltativo. Il valore predefinito è
**oggi + 30 giorni** quando non viene fornita nessuna data, oppure **`start_date + 30 days`** quando viene fornita solo
`start_date`. Deve essere uguale o successiva a `start_date` ed entro 90 giorni da oggi.

**timezone** `string`

Fuso orario IANA (es. `Europe/Berlin`) usato per interpretare `start_date` / `end_date` e per raggruppare
gli slot per data di calendario. Facoltativo — il valore predefinito è il fuso orario della sede. Gli orari di inizio degli slot
vengono sempre restituiti come istanti UTC (`Z`) e non cambiano con questo parametro — la
griglia degli slot è sempre calcolata nel fuso orario della sede; il parametro influisce solo sul
giorno di calendario in cui viene raggruppato uno slot. Le voci giornaliere nella risposta coprono esattamente
`start_date`..`end_date` come giorni di calendario in questo fuso orario. Omettilo a meno che tu non mostri il selettore
in un altro fuso orario.

## Risposta

In caso di successo, l'API restituisce `200 OK` con un singolo oggetto disponibilità.

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

Identificativo della sede ripetuto dalla richiesta.

**timezone** `string` *required*

Fuso orario IANA usato nella risposta (es. `Europe/Berlin`) — ripete il parametro query `timezone`
se fornito, altrimenti il fuso orario della sede.

**slot\_interval\_minutes** `integer`

Intervallo in minuti tra gli orari di inizio di slot prenotabili consecutivi. È il passo della griglia configurato per la sede —
ogni slot in `availability` cade su questa griglia. È `null` solo quando la sede non ha una configurazione
di pianificazione. **Non indica la durata dell'appuntamento:** le prenotazioni sovrapposte con orari di inizio diversi non
vanno in conflitto; solo le collisioni sullo stesso identico orario di inizio contano ai fini della concorrenza.

**availability** `array` *required*

Slot prenotabili per giorno. I giorni senza slot prenotabili vengono omessi per mantenere il payload leggero.
Ogni voce contiene:

**voce giornaliera**

**date** `string` *required*

Data di calendario nel `timezone` della risposta (`YYYY-MM-DD`).

**slots** `array` *required*

Orari di inizio degli slot come istanti UTC (ISO 8601 con suffisso `Z`), in ordine crescente.

## Risposte di errore

| Stato | Descrizione |
| - | - |
| `400` | ID sede non valido, formato data o fuso orario non valido, `end_date` precedente a `start_date` oppure `end_date` oltre 90 giorni nel futuro. |
| `403` | Accesso negato — manca lo scope `appointments_schedule` oppure la sede è fuori dal tuo contesto di accesso. |
| `404` | Sede non trovata o inattiva. |
| `500` | Errore interno del server. |

```bash cURL theme={null}
curl --request GET \
  --url 'https://anivahealth.com/api/v1/locations/b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b/availability?start_date=2026-05-01&end_date=2026-05-07' \
  --header 'x-api-key: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "location_id": "b7e2d1f5-3c4a-4e8b-a2f1-9d0c1e2f3a4b",
  "timezone": "Europe/Berlin",
  "slot_interval_minutes": 15,
  "availability": [
    {
      "date": "2026-05-04",
      "slots": ["2026-05-04T07:00:00Z", "2026-05-04T07:15:00Z", "2026-05-04T07:30:00Z"]
    },
    {
      "date": "2026-05-05",
      "slots": ["2026-05-05T06:00:00Z", "2026-05-05T06:15:00Z"]
    }
  ]
}
```


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