Sprawdzanie dostępności przez API
Po lekturze tego artykułu będziesz umieć sprawdzić przez API, czy jedna sala lub wszystkie sale w workspace są wolne w danym przedziale czasu — z listą konfliktów, buforem czasowym, obowiązującym czasem przygotowania każdej sali i kontekstem zajętości.
Za pomocą interfejsu GET /api/v1/availability Twój system pyta Univents, czy dany okres jest wolny: dla jednej sali lub dla wszystkich sal w workspace. Dzięki temu Twoja strona internetowa, narzędzie do planowania lub inny system może udzielić zapewnienia bez wywoływania rezerwacji.
Odpowiedź opiera się na tych samych zasadach, które stosują strona rezerwacji i czat: liczą się wszystkie wydarzenia w Twoim workspace (także wersje robocze i opcje; nie liczą się tylko anulowane, odrzucone i zarchiwizowane), a do tego punkty harmonogramu, grupy sal i okresy blokady. Otwarte zapytania nie blokują sali — możesz jednak w razie potrzeby uwzględnić je jako rezerwację wstępną.
Klucz i uprawnienie
Potrzebujesz klucza API z uprawnieniem Odczyt lokalizacji. Utworzysz go w Integracje → Deweloperzy → Klucze API — konfigurację opisuje artykuł o kluczach API. Wysyłaj go przy każdym żądaniu jako Authorization: Bearer <Schlüssel>. Klucz bez tego uprawnienia otrzyma odmowę, a nie pusty wynik.
Żądanie
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
| Parametr | Wymagany | Znaczenie |
|---|---|---|
from | tak | Początek okresu. Data (2026-10-01) lub data z godziną (2026-10-01T18:00). |
to | tak | Koniec okresu, zapis taki sam. Sama data oznacza cały dzień. |
location_id | nie | Dokładnie ta sala. Jeśli go brak, odpowiedź dotyczy wszystkich sal w workspace. |
buffer_minutes | nie | Czas przed i po w minutach (montaż, demontaż). 0 (wartość domyślna) oznacza, że żądany okres jest sprawdzany dosłownie. Wartość to dolna granica: jeśli sala ma w polu Czas przygotowania i sprzątania (minuty) własny czas przygotowania, dla tej sali obowiązuje większa z obu wartości, a nie ich suma. Która wartość zadziałała, podaje odpowiedź przy konflikcie (zob. effectiveBufferMinutes). |
include_soft_holds | nie | Domyślnie false: otwarte, jeszcze nierozstrzygnięte zapytania nie liczą się jako zajęte — tak samo jak przy wysyłaniu rezerwacji. Z true zobaczysz je jako rezerwację wstępną (soft_hold). |
Bez strefy czasowej data i godzina są interpretowane w strefie czasowej Twojego workspace. Jeśli dodasz Z lub przesunięcie (2026-10-01T18:00Z), wartość obowiązuje dosłownie.
Odpowiedź
{
"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— wolne lub nie, dla wszystkich sprawdzonych sal. Przy zapytaniu o pojedynczą salę dodatkowo pojawia sięlocationAvailable.window— to, co faktycznie sprawdzono. Z buforem okno jest po obu stronach szersze niż żądane;requested_from/requested_topokazują bez zmian to, co zostało wysłane. Pokazywany jest Twójbuffer_minutes; czas przygotowania sali nie jest w nim zawarty, lecz podany przy każdym konflikcie weffectiveBufferMinutes.free_location_ids— sale, które są wolne w oknie.conflicts— co stoi na przeszkodzie.typemówi, przez co:
type | Znaczenie |
|---|---|
event_overlap | Wydarzenie przypada w oknie. confirmed wskazuje, czy jest już potwierdzone. |
schedule_item_overlap | Punkt harmonogramu (montaż, demontaż, dostawa) zajmuje salę. |
group_cascade | Zajęta jest inna sala z tej samej grupy sal — grupa jest blokowana w całości. |
soft_hold | Istnieje otwarte zapytanie. Tylko z include_soft_holds=true. |
capacity | W oknie osiągnięto limit równoległych zapytań. |
blocked_period | Obowiązuje okres blokady. location_id ma tu wartość null, jeśli blokada dotyczy całego workspace. |
effectiveBufferMinutes pojawia się przy konflikcie zajętości, gdy dla tej sali obowiązywał czas przygotowania i sprzątania: wartość w minutach, której użyto do obliczeń — max(buffer_minutes, Rüstzeit des Raums), najwyżej 1440. Jeśli go brak, sprawdzanie odbyło się bez bufora. Przy konflikcie blocked_period i przy limicie zapytań (capacity) go nie ma.
degraded— występuje tylko wtedy, gdy nie udało się odczytać części sprawdzenia. Wtedy odpowiedź nie jest ostateczna: nie traktuj jej jako zapewnienia, tylko zapytaj ponownie.notes— niuanse, które trzeba znać, by poprawnie odczytać odpowiedź; zob. poniżej.
Czym odpowiedź nie jest
- To nie rezerwacja. Wywołanie niczego nie rezerwuje. Między sprawdzeniem a rezerwacją inny proces może zająć salę — sama rezerwacja sprawdza dostępność ponownie.
- Brak danych osobowych. Odpowiedź podaje identyfikatory sal i okresy, bez nazwisk, kontaktów i osób kontaktowych.
- Brak limitu na poziomie strony. Limit równoległych zapytań ustawia się dla każdej strony rezerwacji; wywołanie API nie ma odniesienia do strony. Dlatego nie ma go w tej odpowiedzi — jego brak nie oznacza zera.
- Brak dokładności co do minuty przy okresach blokady i zapytaniach wstępnych. Okresy blokady oraz (z
include_soft_holds=true) otwarte zapytania są oceniane dniami w strefie czasowej workspace, natomiast wydarzenia co do minuty. Dzięki temu wynik nigdy nie jest bardziej liberalny niż strona rezerwacji, ale może być surowszy.notesw odpowiedzi informują o tym w konkretnym przypadku.
Przypadki błędów
| Odpowiedź | Znaczenie |
|---|---|
400 | Brakuje from/to, są nieczytelne lub podane w odwrotnej kolejności; location_id nie jest prawidłowym identyfikatorem; buffer_minutes jest ujemne lub większe niż 1440. Odpowiedź podaje przyczynę. |
401 | Brak klucza lub klucz nieznany. |
403 | Klucz nie ma uprawnienia Odczyt lokalizacji. |
429 | Zbyt wiele żądań w krótkim czasie. |
Puste okno czasowe lub literówka w dacie nigdy nie prowadzi do wyniku „Wolne” — takie żądania są odrzucane. Szczegółowy opis interfejsu wraz ze wszystkimi polami znajdziesz w dokumentacji API pod adresem /api/v1/docs.