Interroger la disponibilité via l’API

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 tout autre système peut ainsi donner une réponse ferme sans déclencher de réservation.

Le résultat est le même que celui utilisé par la page de réservation et le chat : les événements en cours, les points du déroulé, les groupes de salles, les demandes ouvertes et les périodes de blocage sont pris en compte.

Clé et autorisation

Vous avez besoin d’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 à chaque requête sous la forme Authorization: Bearer <clé>. Une clé sans cette autorisation reçoit un refus, pas 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=false

Sans fuseau horaire, la date et l’heure sont interprétées dans le fuseau de votre workspace. Si vous ajoutez un Z ou un décalage (2026-10-01T18:00Z), la valeur est prise telle quelle.

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, pour l’ensemble des salles vérifiées. Si vous avez demandé une seule salle, locationAvailable est ajouté.
• window : ce qui a réellement été vérifié. Avec un tampon, la fenêtre est plus large que la période demandée de chaque côté ; requested_from/requested_to reprennent à l’identique ce que vous avez envoyé. Votre buffer_minutes est affiché ici ; le temps de préparation d’une salle n’y figure pas, mais dans effectiveBufferMinutes pour chaque conflit.
• free_location_ids : les salles libres dans la fenêtre.
• conflicts : ce qui pose problème. type indique la cause :

effectiveBufferMinutes figure sur un conflit d’occupation dès qu’un temps de préparation et de nettoyage était effectif pour cette salle : c’est la valeur en minutes utilisée pour le 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 tampon. Il n’apparaît pas pour le conflit blocked_period ni pour la limite 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 considérez pas comme une confirmation ferme, interrogez à nouveau.
• notes : les subtilités à connaître pour lire correctement 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 requête et la réservation, une autre opération peut occuper la salle ; la réservation elle-même revérifie.
• Aucune donnée personnelle. La réponse indique des identifiants de salle et des périodes, pas de noms, pas de contacts, pas d’interlocuteurs.
• Pas de limite propre à la page. La limite 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 elle ne figure pas dans cette réponse : son absence ne signifie pas zéro.
• Pas de précision à la minute pour les périodes de blocage et les demandes ouvertes. Les périodes de blocage et les demandes ouvertes sont évaluées jour par jour dans le fuseau horaire du workspace, tandis que les événements le sont à la minute. Le résultat n’est ainsi jamais plus généreux que celui de 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

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.