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

# Récupérer les disponibilités

> Récupérer les heures de début des créneaux réservables pour un seul lieu

Renvoie les heures de début des créneaux réservables pour un seul lieu sur la période demandée.
Les créneaux sont générés à partir de `open_hours` du lieu, en excluant les dates bloquées
globales ou propres au lieu et en soustrayant les rendez-vous Aniva déjà réservés, afin que le
résultat reflète ce que tes patients peuvent réellement réserver côté client.

Nécessite le scope `appointments_schedule`. Le lieu doit également relever du contexte d'accès par groupe de lieux de ta clé API.

> [!NOTE]
>
> Utilise cet endpoint plutôt que de déduire les disponibilités à partir des horaires statiques
> `open_hours` renvoyés par [Lister les lieux](https://docs.anivahealth.com/fr/api/locations/list-locations.md) — seul cet endpoint
> tient compte des réservations en temps réel, des exceptions d'horaires par date et du [préavis
> minimum](https://docs.anivahealth.com/fr/api/appointments/create-appointment.md#delai-minimum) de 12 heures dans les lieux gérés
> par Aniva. Chaque créneau renvoyé ici est réservable tel quel.

Les réponses incluent `Cache-Control: private, max-age=30, stale-while-revalidate=60`, donc un
navigateur peut servir une réponse en cache pendant jusqu'à \~30 secondes — un créneau réservé
dans cet intervalle peut encore apparaître comme réservable jusqu'au prochain rafraîchissement.
Fais aussi remonter les conflits au moment de la réservation.

## Paramètres de chemin

**id** `string` *required*

Identifiant du lieu (UUID). Utilise l'`id` issu de [Lister les lieux](https://docs.anivahealth.com/fr/api/locations/list-locations.md).

## Paramètres de requête

**start\_date** `string`

Début inclusif de la période au format `YYYY-MM-DD` (interprété dans `timezone`). Facultatif.
Prend par défaut **aujourd'hui** si aucune date n'est fournie, ou **`end_date − 30 days`** si
seule `end_date` est fournie. Les dates passées sont automatiquement ramenées à aujourd'hui.

**end\_date** `string`

Fin inclusive de la période au format `YYYY-MM-DD` (interprétée dans `timezone`). Facultatif.
Prend par défaut **aujourd'hui + 30 jours** si aucune date n'est fournie, ou
**`start_date + 30 days`** si seule `start_date` est fournie. Doit être égale ou postérieure à
`start_date` et dans les 90 jours suivant aujourd'hui.

**timezone** `string`

Fuseau horaire IANA (par ex. `Europe/Berlin`) utilisé pour interpréter `start_date` / `end_date`
et regrouper les créneaux par date calendaire. Facultatif — utilise par défaut le fuseau horaire
du lieu. Les heures de début des créneaux sont toujours renvoyées en instants UTC (`Z`) et ne
varient jamais selon ce paramètre — la grille des créneaux est toujours projetée depuis le fuseau
horaire du lieu ; le paramètre influe uniquement sur le jour calendaire auquel un créneau est
rattaché. Les entrées journalières de la réponse couvrent exactement `start_date`..`end_date`
comme jours calendaires dans ce fuseau horaire. Omets-le sauf si tu affiches le sélecteur dans un
autre fuseau horaire.

## Réponse

En cas de succès, l'API renvoie `200 OK` avec un seul objet de disponibilité.

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

Identifiant du lieu repris tel quel.

**timezone** `string` *required*

Fuseau horaire IANA utilisé pour la réponse (par ex., `Europe/Berlin`) — reprend le paramètre de
requête `timezone` lorsqu'il est fourni, sinon le fuseau horaire du lieu.

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

Intervalle en minutes entre deux débuts de créneaux réservables consécutifs. Le pas de la grille
configurée pour le lieu — chaque créneau de `availability` tombe sur cette grille. `null`
uniquement lorsque le lieu n'a aucune configuration de planning. **Ce n'est pas une durée de
rendez-vous :** les réservations qui se chevauchent à des heures de début différentes n'entrent
pas en conflit ; seules les collisions sur la même heure de début comptent pour la concurrence.

**availability** `array` *required*

Créneaux réservables par jour. Les jours sans aucun créneau réservable sont omis pour garder une
réponse légère. Chaque entrée contient :

**entrée par jour**

**date** `string` *required*

Date calendaire dans le `timezone` de la réponse (`YYYY-MM-DD`).

**slots** `array` *required*

Heures de début des créneaux en instants UTC (ISO 8601 avec le suffixe `Z`), triées par ordre croissant.

## Réponses d'erreur

| Statut | Description |
| - | - |
| `400` | Identifiant de lieu invalide, format de date ou de fuseau horaire invalide, `end_date` antérieure à `start_date` ou `end_date` à plus de 90 jours dans le futur. |
| `403` | Accès refusé — scope `appointments_schedule` manquant ou lieu hors de ton contexte d'accès. |
| `404` | Lieu introuvable ou inactif. |
| `500` | Erreur interne du serveur. |

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