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ètreObligatoireSignification
fromouiDébut de la période. Date (2026-10-01) ou date avec heure (2026-10-01T18:00).
toouiFin de la période, même notation. Une date seule désigne la journée entière.
location_idnonCette salle précisément. S’il est absent, la réponse porte sur toutes les salles du workspace.
buffer_minutesnonMarge 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_holdsnonValeur 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, locationAvailable s’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_to montrent, inchangé, ce que vous avez envoyé. La valeur affichée ici est votre buffer_minutes ; le temps de préparation d’une salle n’y figure pas, mais apparaît pour chaque conflit dans effectiveBufferMinutes.
  • free_location_ids : les salles qui sont libres dans la fenêtre.
  • conflicts : ce qui fait obstacle. type indique la cause :
typeSignification
event_overlapUn événement se situe dans la fenêtre. confirmed indique s’il est déjà confirmé.
schedule_item_overlapUn point du déroulé (montage, démontage, livraison) occupe la salle.
group_cascadeUne autre salle du même groupe de salles est occupée : le groupe est retenu dans son ensemble.
soft_holdUne demande ouverte est en cours. Uniquement avec include_soft_holds=true.
capacityLe plafond de demandes parallèles est atteint dans la fenêtre.
blocked_periodUne 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. Les notes de la réponse l’indiquent au cas par cas.

Cas d’erreur

RéponseSignification
400from/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.
401Clé absente ou inconnue.
403La clé n’a pas l’autorisation Lire les lieux.
429Trop 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.

Newsletter Univents

Actualités produit et conseils pratiques pour les professionnels de l'événementiel et de la restauration. Environ une fois par mois, pas plus.

La newsletter est envoyée en anglais.

Thèmes