Interroger la disponibilité via l’API
Cet article vous explique comment demander à l’API si une salle ou toutes les salles d’un workspace sont libres sur une période donnée, avec la liste des conflits, la marge en amont, le temps de préparation effectif par salle et le contexte d’occupation.
Avec l’interface GET /api/v1/availability, votre propre système demande à Univents si une période est libre : pour une seule salle ou pour toutes les salles d’un workspace. Votre site web, votre outil de planification ou un autre système peut ainsi donner une réponse ferme sans déclencher de réservation.
La réponse repose sur les mêmes règles que la page de réservation et le chat : tous les événements de votre workspace comptent (brouillons et options compris ; seuls les événements annulés, refusés et archivés ne comptent pas), ainsi que les points du déroulé, les groupes de salles et les périodes de blocage. Les demandes ouvertes ne retiennent pas de salle, mais vous pouvez, si vous le souhaitez, les inclure comme occupation provisoire.
Clé et autorisation
Il vous faut une clé API disposant de l’autorisation Lire les lieux. Vous pouvez la créer sous Intégrations → Développeurs → Clés API ; la configuration est décrite dans l’article sur les clés API. Envoyez-la avec chaque requête sous la forme Authorization: Bearer <Schlüssel>. Une clé sans cette autorisation reçoit un refus, et non un résultat vide.
La requête
GET /api/v1/availability?from=2026-10-01&to=2026-10-03 GET /api/v1/availability?from=2026-10-01T18:00&to=2026-10-01T23:00&location_id=<Raum-ID> GET /api/v1/availability?from=2026-10-01&to=2026-10-03&buffer_minutes=120&include_soft_holds=true
| Paramètre | Obligatoire | Signification |
|---|---|---|
from | oui | Début de la période. Date (2026-10-01) ou date avec heure (2026-10-01T18:00). |
to | oui | Fin de la période, même notation. Une date seule désigne la journée entière. |
location_id | non | Cette salle précisément. S’il est absent, la réponse porte sur toutes les salles du workspace. |
buffer_minutes | non | Marge en amont et en aval, en minutes (montage, démontage). 0 (valeur par défaut) signifie que la période demandée est vérifiée à la lettre. La valeur est un minimum : si une salle indique son propre temps sous Temps de préparation et de nettoyage (minutes), c’est la plus grande des deux valeurs qui s’applique à cette salle, et non leur somme. La réponse indique la valeur retenue au niveau du conflit (voir effectiveBufferMinutes). |
include_soft_holds | non | Valeur par défaut false : les demandes ouvertes, pas encore tranchées, ne comptent pas comme occupées, exactement comme lors de l’envoi d’une réservation. Avec true, vous les voyez comme occupation provisoire (soft_hold). |
Sans fuseau horaire, la date et l’heure sont interprétées dans le fuseau horaire de votre workspace. Si vous ajoutez un Z ou un décalage (2026-10-01T18:00Z), la valeur est prise à la lettre.
La réponse
{
"available": false,
"window": {
"requested_from": "2026-10-01",
"requested_to": "2026-10-03",
"from": "2026-09-30T22:00:00.000Z",
"to": "2026-10-03T22:00:00.000Z",
"buffer_minutes": 120
},
"free_location_ids": ["…"],
"locationAvailable": false,
"conflicts": [
{
"type": "event_overlap",
"location_id": "…",
"from": "2026-10-02T15:00:00.000Z",
"to": "2026-10-02T22:00:00.000Z",
"confirmed": true
},
{
"type": "soft_hold",
"location_id": "…",
"from": null,
"to": null
}
],
"notes": ["Soft holds (open, non-archived requests) are counted per day …"]
}
available: libre ou non, sur l’ensemble des salles vérifiées. Si une seule salle a été demandée,locationAvailables’y ajoute.window: ce qui a réellement été vérifié. Avec une marge, la fenêtre est plus large des deux côtés que la période demandée ;requested_from/requested_tomontrent, inchangé, ce que vous avez envoyé. La valeur affichée ici est votrebuffer_minutes; le temps de préparation d’une salle n’y figure pas, mais apparaît pour chaque conflit danseffectiveBufferMinutes.free_location_ids: les salles qui sont libres dans la fenêtre.conflicts: ce qui fait obstacle.typeindique la cause :
type | Signification |
|---|---|
event_overlap | Un événement se situe dans la fenêtre. confirmed indique s’il est déjà confirmé. |
schedule_item_overlap | Un point du déroulé (montage, démontage, livraison) occupe la salle. |
group_cascade | Une autre salle du même groupe de salles est occupée : le groupe est retenu dans son ensemble. |
soft_hold | Une demande ouverte est en cours. Uniquement avec include_soft_holds=true. |
capacity | Le plafond de demandes parallèles est atteint dans la fenêtre. |
blocked_period | Une période de blocage s’applique. location_id vaut ici null si le blocage concerne tout le workspace. |
effectiveBufferMinutes figure sur un conflit d’occupation dès qu’un temps de préparation et de nettoyage s’appliquait à cette salle : c’est la valeur en minutes qui a servi au calcul, soit max(buffer_minutes, temps de préparation de la salle), au maximum 1440. S’il est absent, la vérification a été faite sans marge. Il n’apparaît ni pour le conflit blocked_period ni pour le plafond de demandes (capacity).
degraded: présent uniquement si une partie de la vérification n’a pas pu être lue. La réponse n’est alors pas exhaustive : ne la traitez pas comme une confirmation, mais interrogez de nouveau.notes: les subtilités à connaître pour bien lire la réponse ; voir ci-dessous.
Ce que la réponse n’est pas
- Pas une réservation. L’appel ne réserve rien. Entre la consultation et la réservation, une autre opération peut occuper la salle ; la réservation elle-même effectue une nouvelle vérification.
- Pas de données personnelles. La réponse indique des identifiants de salles et des périodes, aucun nom, aucun contact, aucun interlocuteur.
- Pas de plafond par page. Le plafond de demandes parallèles se règle par page de réservation ; un appel API n’a pas de lien avec une page. C’est pourquoi il ne figure pas dans cette réponse. S’il est absent, cela ne signifie pas zéro.
- Pas de précision à la minute pour les périodes de blocage et les demandes provisoires. Les périodes de blocage et (avec
include_soft_holds=true) les demandes ouvertes sont évaluées jour par jour dans le fuseau horaire du workspace, alors que les événements le sont à la minute près. Le résultat n’est ainsi jamais plus permissif que la page de réservation, mais il peut être plus strict. Lesnotesde la réponse l’indiquent au cas par cas.
Cas d’erreur
| Réponse | Signification |
|---|---|
400 | from/to sont absents, illisibles ou inversés ; location_id n’est pas un identifiant valide ; buffer_minutes est négatif ou supérieur à 1440. La réponse indique le motif. |
401 | Clé absente ou inconnue. |
403 | La clé n’a pas l’autorisation Lire les lieux. |
429 | Trop de requêtes en peu de temps. |
Une fenêtre vide ou une faute de frappe dans la date ne mène jamais à « libre » : ces requêtes sont rejetées. Vous trouverez la description détaillée de l’interface, avec tous les champs, dans la référence API sous /api/v1/docs.