Verificare la disponibilità tramite API

Con l’endpoint GET /api/v1/availability il tuo sistema chiede a Univents se un periodo è libero: per una singola sala o per tutte le sale di un workspace. In questo modo il tuo sito web, il tuo strumento di pianificazione o un altro sistema può dare una conferma senza generare una prenotazione.

La verifica è la stessa che usano anche la pagina di prenotazione e la chat: contano gli eventi occupati, le voci del programma, i gruppi di sale, le richieste aperte e i periodi di blocco.

Chiave e autorizzazione

Ti serve una chiave API con l’autorizzazione Leggere location. Puoi crearla in Integrazioni → Sviluppatori → Chiavi API; la configurazione è descritta nell’articolo sulle chiavi API. Inviala a ogni richiesta come Authorization: Bearer <Schlüssel>. Una chiave senza questa autorizzazione riceve un rifiuto, non un risultato vuoto.

La richiesta

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

Senza fuso orario, data e orario valgono nel fuso orario del tuo workspace. Se aggiungi una Z o uno scostamento (2026-10-01T18:00Z), il valore viene preso alla lettera.

La risposta

{
  "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: libero o no, su tutte le sale verificate. Se hai richiesto una singola sala, compare in aggiunta locationAvailable.
• window: ciò che è stato effettivamente verificato. Con il buffer, la finestra è più ampia da entrambi i lati rispetto a quella richiesta; requested_from/requested_to mostrano invariato ciò che hai inviato. Viene mostrato il tuo buffer_minutes; il tempo di allestimento di una sala non è incluso qui, ma compare per ogni conflitto in effectiveBufferMinutes.
• free_location_ids: le sale libere nella finestra.
• conflicts: ciò che è d’ostacolo. type indica di che cosa si tratta:

effectiveBufferMinutes compare in un conflitto di occupazione non appena per quella sala è stato applicato un tempo di allestimento e pulizia: è il valore in minuti usato per il calcolo, ovvero max(buffer_minutes, tempo di allestimento della sala), al massimo 1440. Se manca, la verifica è stata fatta senza buffer. Non compare nel conflitto blocked_period né nel limite di richieste (capacity).

• degraded: presente solo se una parte della verifica non ha potuto essere letta. In tal caso la risposta non è definitiva: non trattarla come una conferma, ma ripeti la richiesta.
• notes: le sfumature da conoscere per leggere correttamente la risposta; vedi sotto.

Che cosa non è la risposta

• Non è una prenotazione. La chiamata non riserva nulla. Tra la verifica e la prenotazione un altro processo può occupare la sala: la prenotazione stessa verifica di nuovo.
• Nessun dato personale. La risposta riporta identificativi delle sale e periodi, nessun nome, nessun contatto, nessun referente.
• Nessun limite per pagina. Il limite di richieste parallele viene impostato per ogni pagina di prenotazione; una chiamata API non ha alcun riferimento a una pagina. Per questo non compare in questa risposta: se manca, non significa zero.
• Nessuna precisione al minuto per periodi di blocco e richieste aperte. I periodi di blocco e le richieste aperte vengono valutati per giorno nel fuso orario del workspace, mentre gli eventi vengono valutati al minuto. Il risultato non è quindi mai più permissivo della pagina di prenotazione, ma può essere più restrittivo. Le notes della risposta lo indicano nel singolo caso.

Casi di errore

Una finestra temporale vuota o un errore di battitura nella data non portano mai a «Libero»: queste richieste vengono respinte. La descrizione completa dell’endpoint, con tutti i campi, si trova nel riferimento API all’indirizzo /api/v1/docs.