Przegląd API i uwierzytelnianie

StayPark Suite udostępnia trzy interfejsy REST. Ten przewodnik zbiera to, co jest w nich wspólne: adresy, uwierzytelnianie, kształt odpowiedzi, stronicowanie i limity. Szczegóły każdej operacji (pola, przykłady, odpowiedzi) są w dokumentacji referencyjnej OpenAPI, opisanej niżej.

Trzy interfejsy#

Adres bazowy poprzedza adres instancji, np. https://<adres panelu>/api/sync/v1. Wszystkie interfejsy przyjmują i zwracają JSON. Wyjątkiem są strumienie plików i PDF-ów.

Gdzie jest dokumentacja referencyjna#

Jedynym źródłem kontraktu są pliki OpenAPI 3.0.3 w panelu, w katalogu public/api-docs:

Pliki YAML są publiczne - możesz je wczytać do własnego narzędzia (Postman, Insomnia, generator klienta). Podgląd w panelu (Swagger UI) wymaga zalogowania do panelu. Przewodniki w tej sekcji niczego nie dodają do kontraktu: gdy coś się różni, rozstrzyga plik OpenAPI.

Uwierzytelnianie#

Koperta odpowiedzi#

Wszystkie trzy interfejsy zwracają ten sam kształt odpowiedzi. Powodzenie:

{ "success": true, "data": { } }

Błąd - także 404 przy strumieniach PDF:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "...",
    "errors": { "email": ["..."] }
  }
}

Program kliencki powinien rozpoznawać błąd po error.code, a nie po treści message. Komunikaty są po polsku i mogą się zmieniać. errors występuje przy błędach walidacji. Niektóre kody dokładają własne pola, np. error.required_permission (aplikacja pracownika) albo error.feature i error.field (aplikacja klienta). Pełna lista kodów: Kody błędów.

Nieoczekiwany błąd serwera (500 spoza obsługi operacji) też przychodzi w tej kopercie, z kodem SERVER_ERROR. Szczegóły wyjątku (error.debug) są tylko w trybie debugowania. Traktuj każdą odpowiedź 5xx jako błąd przejściowy, niezależnie od treści.

Pozostałe zasady wspólne:

• daty i znaczniki czasu w ISO 8601;
• zasoby wskazuje się przez uuid; numery id są wewnętrzne dla bazy, a stare pola liczbowe (np. item_id) zostały tylko dla zgodności i są oznaczone jako przestarzałe;
• kwoty: w synchronizacji pola *_minor w groszach, w aplikacji pracownika liczby w złotych, w aplikacji klienta obiekt { "minor": 10000, "amount": "100.00", "formatted": "100,00 zł" }.

Stronicowanie#

Listy w API aplikacji pracownika i klienta mają ten sam kształt: data.items i data.pagination z polami current_page, last_page, per_page, total, from, to.

Synchronizacja nie stronicuje: pobranie zwraca paczkę zmian i kursory, a kasa pyta dalej, dopóki has_more = true. Opis: API synchronizacji.

Limity żądań#

Przekroczenie limitu daje odpowiedź 429 z nagłówkiem Retry-After (liczba sekund do kolejnej próby).

Limit konkretnej operacji jest w jej opisie w dokumentacji referencyjnej. Kod błędu zależy od miejsca, które odmówiło: limit trasy daje HTTP_ERROR, a limit prób w samej operacji (np. odbiór nagrody, kod rabatowy) daje TOO_MANY_REQUESTS albo kod operacji, np. SHOP_TOO_MANY_ATTEMPTS w sklepie czy TOO_MANY_ATTEMPTS przy kodach weryfikacji dwuetapowej w aplikacji pracownika.