Cennik i uprawnienia

Dostęp do API jest kontrolowany przez funkcję subskrypcji ApiAccess. Jest ona zawarta w planie Enterprise oraz dostępna jako płatny dodatek w każdym innym planie. Zapytania uwierzytelnione kluczem API skierowane do firmy bez ApiAccess zwracają status HTTP 402 z kodem code: "API_ACCESS_NOT_ENABLED", zanim trafią do kontrolera.

Ta strona stanowi autorytatywne źródło informacji o tym, jakiego planu potrzebuje klient partnera. Strony marketingowe (locco.hr/cijene) opisują plany w przystępny dla człowieka sposób, natomiast poniższa macierz przedstawia reguły wymuszane przez środowisko uruchomieniowe.

Reguła

ApiAccess jest zawarty w planie Enterprise.
W każdym innym planie ApiAccess jest dostępny jako płatny dodatek. Bez tego dodatku zapytania są odrzucane ze statusem 402.
Weryfikacja odbywa się raz na zapytanie, po uwierzytelnieniu i po przypisaniu nagłówka X-Company-Id do docelowej firmy. Zapytanie, które pomyślnie przejdzie tę weryfikację, zużywa limit w ramach okien limitów zapytań, natomiast zapytanie odrzucone go nie zużywa.

Dostępność funkcji jest określana na podstawie firmy docelowej powiązanej z nagłówkiem X-Company-Id, a nie użytkownika będącego właścicielem klucza API. Użytkownik należący do dwóch firm (jednej z ApiAccess i jednej bez) pomyślnie wykona zapytanie do uprawnionego podmiotu, natomiast dla drugiej firmy otrzyma status 402 przy użyciu tego samego klucza.

Macierz planów

Plan	Dostęp do API
Free	Dodatek
Business	Dodatek
Plus	Dodatek
Professional	Dodatek
Enterprise	W cenie

Aby odblokować dostęp do API, klienci mogą przejść na plan Enterprise (który zawiera ApiAccess w pakiecie z pozostałymi funkcjami planu) lub dodać dodatek ApiAccess do swojego obecnego planu. Obie ścieżki są dostępne w aplikacji webowej locco w sekcji Ustawienia -> Subskrypcja.

Odpowiedź 402

Gdy klucz odwołuje się do firmy, która nie posiada ApiAccess, API partnera zwraca status HTTP 402 z kanoniczną strukturą błędu:

{
  "code": "API_ACCESS_NOT_ENABLED",
  "type": "PaymentRequired",
  "title": "<localized human message>",
  "status": 402
}

code: stała wartość. Partnerzy filtrują zapytania na podstawie tego ciągu znaków. Stała znajduje się w katalogu błędów.
type: kategoria historyczna (legacy), zachowana w celu zapewnienia kompatybilności z aplikacjami SPA. Nie należy opierać na niej logiki warunkowej.
title: zlokalizowany zgodnie z nagłówkiem Accept-Language żądania (domyślnie hr). Nie należy go parsować. Treść komunikatu może ulec zmianie między wersjami. Rzeczywisty tekst pochodzi z plików zasobów API partnera (SharedResource.resx / SharedResource.hr.resx).
status: odzwierciedla linię statusu HTTP. 402 Payment Required to standardowy kod dla brakujących uprawnień. Jest to ten sam status, który jest powszechnie stosowany w branży, gdy dane uwierzytelniające są poprawne, ale plan nie obejmuje danego obszaru funkcjonalnego.

Nagłówek Content-Type ma wartość application/json. Odpowiedź jest krótka: nie zawiera słownika errors ani szczegółów dotyczących poszczególnych pól. Partner nie ma możliwości ponowienia próby z innymi danymi wejściowymi. Jedynym rozwiązaniem jest przejście klienta na wyższy plan.

Zalecana obsługa po stronie partnera

Status 402 z API partnera oznacza błąd stanu klienta, a nie błąd przejściowy. Ponowne użycie tego samego klucza dla tej samej firmy będzie skutkować zwracaniem statusu 402, dopóki klient nie przejdzie na wyższy plan.

Rekomendowany sposób obsługi po stronie klienta:

W przypadku błędu 402 z kodem code: "API_ACCESS_NOT_ENABLED", należy zatrzymać pętlę odpytywania (polling) integracji dla tej firmy i wyświetlić jasny komunikat “plan locco tego klienta nie obejmuje dostępu do API” w interfejsie użytkownika lub konsoli operacyjnej.
Nie należy stosować mechanizmu ponawiania prób (backoff i retry). Ten stan nie jest przejściowy.
Jeśli integracja obejmuje wiele firm, należy ograniczyć blokadę wyłącznie do firmy, która wygenerowała błąd. Inne firmy korzystające z planu Enterprise powinny nadal działać bez zakłóceń.

Szczegółowy opis każdego kodu błędu, który może zostać zwrócony przez API partnera, znajduje się w katalogu błędów.

Powiązane tematy

Uwierzytelnianie: tokeny bearer, nagłówek X-Company-Id oraz rotacja kluczy.
Błędy: pełny katalog stabilnych, czytelnych dla maszyn kodów błędów.
Limity zapytań: limity sekundowe, godzinowe i dobowe w planie Enterprise.