DLA PROGRAMISTÓW · API V1
API klienta i integracji OSiR
Free: najbliższy termin, zakres dat i godzin, wyszukiwanie po dyscyplinie i zasobie, rezerwowanie oraz własne zapisy. Premium: filtry ceny, długości i miejsc, wspólna dostępność kilku zasobów, integracje zarządzające i powiadomienia o zmianach.
Pobierz OpenAPI 3.1 → Panel OSiR
Połączenie i bezpieczeństwo
Adres: /api/v1/.... Produkcja wymaga HTTPS. Token klienta i klucz integracji to dwa różne rodzaje dostępu. Przekazuj Authorization: Bearer TOKEN. Token klienta otrzymasz wyłącznie po haśle i OTP; nie przyznaje on uprawnień pracownika.
Odpowiedź: {"data": ...}. Błąd: {"error":{"status":409,"message":"..."}}. Kwoty w groszach PLN, terminy odpowiedzi w UTC. Daty i godziny wyszukiwania: Europe/Warsaw.
Przykładowe wyszukiwanie Free
GET /api/v1/public/schedules/UUID/availability?from=2026-10-01&to=2026-10-07&time_from=16:00&time_to=20:00&nearest=1
Wyszukiwanie dotyczy już opublikowanych terminów. Dostępność jest sprawdzana ponownie przy zapisie. Edycja i anulowanie wymagają zgody OSiR, zachowania wyprzedzenia i wersji wpisu. Zmiana terminu z rozliczeniami wymaga obsługi. Anulowanie nie zwraca automatycznie pieniędzy.
Endpointy
| Metoda | Ścieżka | Opis |
|---|---|---|
| POST | /client/auth/register | Utwórz wyzwanie rejestracji klienta |
| POST | /client/auth/register/verify | Potwierdź OTP: register |
| POST | /client/auth/login | Sprawdź hasło klienta i wyślij OTP |
| POST | /client/auth/login/verify | Potwierdź OTP: login |
| POST | /client/auth/reset | Wyślij OTP resetu hasła klienta |
| POST | /client/auth/reset/verify | Potwierdź OTP: reset |
| GET | /client/me | Własne konto klienta |
| POST | /client/logout | Unieważnij bieżący token klienta |
| GET | /client/bookings | Lista własnych rezerwacji |
| POST | /client/bookings | Zarezerwuj opublikowany termin - Free |
| POST | /client/bookings/claim | Przypisz zapis z linku potwierdzenia |
| GET | /client/bookings/{id} | Szczegóły własnego zapisu |
| PATCH | /client/bookings/{id} | Edytuj lub przenieś własny zapis - Free |
| POST | /client/bookings/{id}/cancel | Anuluj własny zapis - Free |
| GET | /public/schedules/{uuid}/availability | Wyszukaj wolne terminy |
| GET | /accounts/{account}/client-policy | Zasady klientowskiej samoobsługi - panel Free |
| PATCH | /accounts/{account}/client-policy | Zasady klientowskiej samoobsługi - panel Free |
| GET | /accounts/{account}/changes | Pobierz zmiany OSiR - Premium |
| GET | /accounts/{account}/api-management | Lista kluczy i ustawień - panel administratora |
| POST | /accounts/{account}/api-management | Utwórz klucz integracji - Premium |
| PATCH | /accounts/{account}/api-management | Włącz lub wyłącz klucze |
| DELETE | /accounts/{account}/api-management | Unieważnij klucz |
| GET | /accounts/{account}/webhooks | Lista odbiorców zmian |
| POST | /accounts/{account}/webhooks | Dodaj webhook - Premium |
| PATCH | /accounts/{account}/webhooks | Wstrzymaj lub wznów webhook - Premium |
| DELETE | /accounts/{account}/webhooks | Usuń webhook |
| GET | /accounts/{account}/outages | Lista awarii |
| POST | /accounts/{account}/outages | Zgłoś czasową awarię |
| GET | /accounts/{account}/outages/{id} | Terminy i liczba zapisów objętych awarią |
| PATCH | /accounts/{account}/outages/{id} | Wyłącz awarię przed końcem okresu |
| GET | /client/waitlist-context | Szczegóły terminu dla listy |
| GET | /client/waitlist | Własne 100 ostatnich wpisów |
| POST | /client/waitlist | Dołącz do kolejki pełnego terminu |
| POST | /client/waitlist/{id}/accept | Przyjmij ofertę z jawną ceną |
| POST | /client/waitlist/{id}/cancel | Zrezygnuj z listy |
| GET | /client/notifications | Strumień powiadomień z kursorem |
| GET | /accounts/{account}/client-notifications | Strumień powiadomień z kursorem |
| POST | /client/notifications/{id}/read | Oznacz własną wiadomość jako przeczytaną |
Integracje Premium
Administrator tworzy klucz w panelu API OSiR: odczyt, obsługa rezerwacji lub zarządzanie grafikami. Wygaśnięcie Premium wstrzymuje klucze i webhooki. Panel pracowników oraz podstawowe operacje klienta nadal działają.
Webhooki wymagają uruchamiania bin/deliver-webhooks.php w harmonogramie serwera. Odbiorca sprawdza HMAC-SHA256 z timestamp + "." + surowe body, nagłówki X-OSiR-Timestamp i X-OSiR-Signature. Ponowienia są możliwe: deduplikuj zmiany po ID. Sekret przechowuj wyłącznie na serwerze.
Dokładne pola, ograniczenia i odpowiedzi są w specyfikacji OpenAPI. Instrukcja integracji z przykładami curl i Swift znajduje się w repozytorium: docs/API-KLIENTA.md.