Sprawdzanie dostępności przez API

Za pomocą interfejsu GET /api/v1/availability Twój własny system pyta Univents, czy dany okres jest wolny: dla jednej sali lub dla wszystkich sal workspace. Dzięki temu Twoja strona internetowa, narzędzie do planowania lub inny system może potwierdzić dostępność bez tworzenia rezerwacji.

Odpowiedź jest taka sama, jakiej używają strona rezerwacji i czat: liczą się zajęte wydarzenia, punkty harmonogramu, grupy sal, otwarte zapytania i okresy blokady.

Klucz i uprawnienie

Potrzebujesz klucza API z uprawnieniem Odczyt lokalizacji. Możesz go utworzyć w Integracje → Deweloperzy → Klucze API — konfigurację opisuje artykuł o kluczach API. Wysyłaj go z każdym zapytaniem jako Authorization: Bearer <Schlüssel>. Klucz bez tego uprawnienia otrzyma odmowę, a nie pusty wynik.

Zapytanie

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

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, łącznie dla wszystkich sprawdzonych sal. Przy zapytaniu o jedną salę dodatkowo pojawia się locationAvailable.
• window — co faktycznie zostało sprawdzone. Przy buforze okno jest po obu stronach szersze niż w zapytaniu; requested_from/requested_to pokazują w niezmienionej postaci to, co wysłano. Pokazywany jest przy tym Twój buffer_minutes; czas przygotowania sali nie jest w nim zawarty, tylko podany przy każdym konflikcie w effectiveBufferMinutes.
• free_location_ids — sale, które są wolne w tym oknie.
• conflicts — co stoi na przeszkodzie. type mówi, co dokładnie:

effectiveBufferMinutes pojawia się przy konflikcie zajętości, gdy dla danej sali obowiązywał czas przygotowania i sprzątania: wartość w minutach, z którą liczono — max(buffer_minutes, czas przygotowania sali), najwyżej 1440. Jeśli go brak, sprawdzenie odbyło się bez bufora. Przy konflikcie blocked_period oraz przy limicie zapytań (capacity) go nie ma.

• degraded — występuje tylko wtedy, gdy nie udało się odczytać części sprawdzanych danych. Odpowiedź jest wtedy niewyczerpująca: nie traktuj jej jako potwierdzenia, tylko zapytaj ponownie.
• notes — niuanse, które trzeba znać, aby poprawnie odczytać odpowiedź; zob. poniżej.

Czym odpowiedź nie jest

• To nie rezerwacja. Wywołanie niczego nie rezerwuje. Między zapytaniem a rezerwacją inna operacja może zająć salę — sama rezerwacja sprawdza dostępność ponownie.
• Brak danych osobowych. Odpowiedź zawiera identyfikatory sal i okresy, bez imion i nazwisk, kontaktów i osób do kontaktu.
• Brak limitu na poziomie strony. Limit równoległych zapytań ustawia się dla każdej strony rezerwacji; wywołanie API nie ma odniesienia do żadnej strony. Dlatego nie występuje on w tej odpowiedzi — jego brak nie oznacza zera.
• Brak dokładności do minuty przy okresach blokady i otwartych zapytaniach. Okresy blokady i otwarte zapytania są oceniane dzień po dniu w strefie czasowej workspace, a wydarzenia — co do minuty. Dzięki temu wynik nigdy nie jest łagodniejszy niż na stronie rezerwacji, ale może być surowszy. Pole notes w odpowiedzi informuje o tym w konkretnym przypadku.

Przypadki błędów

Pusty przedział czasu lub literówka w dacie nigdy nie prowadzi do wyniku „Wolne” — takie zapytania są odrzucane. Szczegółowy opis interfejsu wraz ze wszystkimi polami znajdziesz w dokumentacji API pod adresem /api/v1/docs.