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
ParametrWymaganyZnaczenie
fromtakPoczątek okresu. Data (2026-10-01) lub data z godziną (2026-10-01T18:00).
totakKoniec okresu, zapis taki sam. Sama data oznacza cały dzień.
location_idnieDokładnie ta sala. Jeśli go brak, odpowiedź dotyczy wszystkich sal w workspace.
buffer_minutesnieCzas 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_holdsnieDomyś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_to pokazują bez zmian to, co zostało wysłane. Pokazywany jest Twój buffer_minutes; czas przygotowania sali nie jest w nim zawarty, lecz podany przy każdym konflikcie w effectiveBufferMinutes.
  • free_location_ids — sale, które są wolne w oknie.
  • conflicts — co stoi na przeszkodzie. type mówi, przez co:
typeZnaczenie
event_overlapWydarzenie przypada w oknie. confirmed wskazuje, czy jest już potwierdzone.
schedule_item_overlapPunkt harmonogramu (montaż, demontaż, dostawa) zajmuje salę.
group_cascadeZajęta jest inna sala z tej samej grupy sal — grupa jest blokowana w całości.
soft_holdIstnieje otwarte zapytanie. Tylko z include_soft_holds=true.
capacityW oknie osiągnięto limit równoległych zapytań.
blocked_periodObowią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. notes w odpowiedzi informują o tym w konkretnym przypadku.

Przypadki błędów

OdpowiedźZnaczenie
400Brakuje 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ę.
401Brak klucza lub klucz nieznany.
403Klucz nie ma uprawnienia Odczyt lokalizacji.
429Zbyt 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.

Newsletter Univents

Nowości produktowe i praktyczne wskazówki dla firm eventowych i cateringowych. Mniej więcej raz w miesiącu, nie częściej.

Newsletter wysyłamy w języku angielskim.

Tematy