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
| Parametro | Obbligatorio | Significato |
|---|---|---|
from | sì | Inizio del periodo. Data (2026-10-01) oppure data con orario (2026-10-01T18:00). |
to | sì | Fine del periodo, con la stessa notazione. Una semplice data significa l’intera giornata. |
location_id | no | Esattamente questa sala. Se manca, la risposta vale per tutte le sale del workspace. |
buffer_minutes | no | Anticipo 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_holds | no | Predefinito 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 anchelocationAvailable.window: ciò che è stato effettivamente verificato. Con il buffer, la finestra è più ampia di quella richiesta su entrambi i lati;requested_from/requested_tomostrano invariato ciò che hai inviato. Viene mostrato il tuobuffer_minutes; il tempo di allestimento di una sala non è incluso qui, ma si trova in ogni conflitto ineffectiveBufferMinutes.free_location_ids: le sale libere nella finestra.conflicts: ciò che è d’intralcio.typeindica di cosa si tratta:
type | Significato |
|---|---|
event_overlap | Un evento rientra nella finestra. confirmed indica se è già confermato. |
schedule_item_overlap | Un punto del programma (montaggio, smontaggio, consegna) occupa la sala. |
group_cascade | Un’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. |
capacity | Il limite di richieste parallele è raggiunto nella finestra. |
blocked_period | Si 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. Lenotesdella risposta lo segnalano nel singolo caso.
Casi di errore
| Risposta | Significato |
|---|---|
400 | from/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. |
401 | Chiave assente o sconosciuta. |
403 | La chiave non ha l’autorizzazione Leggere location. |
429 | Troppe 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.