Verificare la disponibilità tramite API

Dopo aver letto questo articolo saprai chiedere tramite API se una sala o tutte le sale di un workspace sono libere in una finestra temporale, con elenco dei conflitti, buffer di anticipo, tempo di allestimento effettivo per sala e contesto sull’occupazione.

Con l’interfaccia 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. Così 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 la pagina di prenotazione e la chat: contano tutti gli eventi del tuo workspace (anche bozze e opzioni; solo quelli annullati, rifiutati e archiviati no), insieme ai punti del programma, ai gruppi di sale e ai periodi di blocco. Le richieste aperte non bloccano una sala, ma su richiesta puoi includerle come occupazione provvisoria.

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=true
ParametroObbligatorioSignificato
fromsìInizio del periodo. Data (2026-10-01) oppure data con orario (2026-10-01T18:00).
tosìFine del periodo, con la stessa notazione. Una semplice data significa l’intera giornata.
location_idnoEsattamente questa sala. Se manca, la risposta vale per tutte le sale del workspace.
buffer_minutesnoAnticipo e posticipo in minuti (montaggio, smontaggio). 0 (valore predefinito) significa che il periodo richiesto viene verificato alla lettera. Il valore è un minimo: se una sala ha un proprio tempo di allestimento indicato in Tempo di allestimento e pulizia (minuti), per quella sala vale il maggiore dei due valori, non la somma. Il valore effettivamente applicato è indicato dalla risposta sul conflitto (vedi effectiveBufferMinutes).
include_soft_holdsnoPredefinito false: le richieste aperte, non ancora decise, non contano come occupazione, esattamente come all’invio di una prenotazione. Con true le vedi come occupazione provvisoria (soft_hold).

Senza fuso orario, data e orario sono interpretati nel fuso orario del tuo workspace. Se aggiungi una Z o uno scostamento (2026-10-01T18:00Z), il valore viene interpretato 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, è presente anche locationAvailable.
  • window: ciò che è stato effettivamente verificato. Con il buffer, la finestra è più ampia di quella richiesta su entrambi i lati; 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 si trova in ogni conflitto in effectiveBufferMinutes.
  • free_location_ids: le sale libere nella finestra.
  • conflicts: ciò che è d’intralcio. type indica di cosa si tratta:
typeSignificato
event_overlapUn evento rientra nella finestra. confirmed indica se è già confermato.
schedule_item_overlapUn punto del programma (montaggio, smontaggio, consegna) occupa la sala.
group_cascadeUn’altra sala dello stesso gruppo di sale è occupata: il gruppo viene trattenuto nel suo insieme.
soft_holdÈ presente una richiesta aperta. Solo con include_soft_holds=true.
capacityIl limite di richieste parallele è raggiunto nella finestra.
blocked_periodSi applica un periodo di blocco. Qui location_id è null se il blocco riguarda l’intero workspace.

effectiveBufferMinutes compare su un conflitto di occupazione non appena per quella sala è stato applicato un tempo di allestimento e pulizia: il valore in minuti con cui è stato calcolato, cioè 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é per il limite di richieste (capacity).

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

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 di 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 provvisorie. I periodi di blocco e (con include_soft_holds=true) le richieste aperte vengono valutati per giornata 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ù rigoroso. Le notes della risposta lo segnalano nel singolo caso.

Casi di errore

RispostaSignificato
400from/to mancano, non sono leggibili o sono invertiti; location_id non è un identificativo valido; buffer_minutes è negativo o superiore a 1440. La risposta indica il motivo.
401Chiave assente o sconosciuta.
403La chiave non ha l’autorizzazione Leggere location.
429Troppe richieste in poco tempo.

Una finestra temporale vuota o un errore di battitura nella data non portano mai a «Libero»: richieste di questo tipo vengono respinte. La descrizione completa dell’interfaccia con tutti i campi si trova nella documentazione API alla voce /api/v1/docs.

Newsletter di Univents

Novità di prodotto e consigli pratici per attività di eventi e catering. Circa una volta al mese, non di più.

La newsletter viene inviata in inglese.

Temi