REST API

Moduł REST API zbiera w jednym miejscu wszystko, co potrzebne do zintegrowania własnego oprogramowania z Systemem: bieżące wykorzystanie limitu żądań, klucze dostępu operatorów oraz instrukcję pozyskania tokenu.

Moduł znajduje się w Administracja  Integracje zewnętrzne  REST API.

image1 b2c
Rysunek 1. Adminsitracja - REST API
Dostęp do API to usługa dodatkowa, dostępna w trzech wariantach różniących się dopuszczalną liczbą żądań. Usługę można wykupić w module Moje rozrachunki Administracja  Konfiguracja. Do czasu jej wykupienia moduł prezentuje zestawienie wariantów wraz z limitami oraz odsyłacz do dokumentacji REST API.

Dostępne są limity żądań:

Wariant Limit żądań

Podstawowy

100 żądań / 24 godz.

Zaawansowany

5 000 żądań / 24 godz.

Max

50 000 żądań / 24 godz.

Dokumentacja metod REST API

U góry po prawej stronie dostępny jest przycisk: "Otwórz dokumentacje API". Po jego kliknięciu w nowej karcie otwiera się pełna dokumentacja metod REST API.

Wykorzystanie limitu żądań

Sekcja prezentuje Wykorzystanie limitu żądań. Jeśli przesłane zostało już jakieś żądanie, w sekcji prezentowana jest również informacja, o terminie odnowienia Limitu. Limit odnawia się jednorazowo po upływie 24 godzin od pierwszego żądania w bieżącym okresie. Oznacza to, że limit nie odświeża się np. zawsze o północy. Np. jeśli pierwsze żądanie przesłane zostało o godzinie 11:15, limit zostanie zresetowany kolejnego dnia o 11:15. Dopóki w danym okresie nie padło żadne żądanie, dostępna jest pełna pula zapytań zgodnie z dostępnym limitem.

Limit jest wspólny dla wszystkich Operatorów/Kluczy dla danego konta. Dodanie kolejnego klucza nie zwiększa limitu.

Klucze API

Sekcja prezentuje listę Operatorów konta dla których wygenerowany zostął klucz wraz z ich ID klienta. Uprawnieni Operatorzy mogą wygenerować klucze dla nowego Operatora - opcja Dodaj klucz. Po jej kliknięciu wyświetlona zostanie lista wyboru, która zawiera wyłącznie Operatorów aktywnych, którzy nie mają jeszcze klucza. Dla istniejącego klucza dostępne są opcje Nowy klucz oraz Usuń.

Po wygenerowaniu wyświetlone zostanie okno z wygenerowanym ID klienta oraz Kluczem API. Klucz ten należy skopiować, ponieważ po zamknięciu okna nie będzie on nigdzie prezentowany. ID klienta będzie natomiast widoczne w tej sekcji.
Klucz działa z uprawnieniami Operatora, dla którego został wygenerowany. Przez API dostępne będą dokładnie te dane, do których ten Operator ma dostęp w Panelu Administracyjnym. Dezaktywacja Operatora unieważnia jego klucz.
Klucz dostępu można nadal wygenerować także w szczegółach danego Operatora Administracja  Konfiguracja  Operatorzy. Wygenerowany w tamtym Id klienta klucz również będzie widoczny w tej sekcji, a klucz również tam wyświetlany jest jednorazowo.

Jak uzyskać token dostępu

Sekcja zawiera skróconą instrukcję uwierzytelnienia w protokole OAuth 2.0. Dostępna jest również opcja stworzenia gotowego cURL. W tym celu należy wybrać z listy jednego z Operatorów, dla których wygenerowany został Klucz API. Gotowy cURL można również uzupełnić o Klucz API, w tym celu podać ten Klucz w polu "Client secret". Po uzupełnieniu danych komenda uzupełnia się o nie i można ją skopiować do schowka klikając przycisk Kopiuj cURL

System nie przechowuje Klucza API podawanego w polu "Client secret". Wartość wpisana w polu nie jest nigdzie wysyłana ani zapisywana.

ID klienta i Klucz API służą do uwierzytelnienia w protokole OAuth 2.0:

  1. Wygeneruj klucz dla wybranego operatora w sekcji Klucze API.

  2. Wyślij żądanie POST na endpoint autoryzacji https://auth.assecobs.com/oauth2.0/accessToken z parametrem grant_type=client_credentials.

  3. Otrzymany token dołączaj do każdego wywołania w nagłówku Authorization: Bearer TOKEN.

  4. Token ma ograniczoną ważność (pole expires_in w odpowiedzi, w sekundach) — po wygaśnięciu pobierz nowy.

Większość nowoczesnych bibliotek HTTP oraz narzędzi integracyjnych wspierających OAuth 2.0 realizuje ten proces automatycznie — pozyskuje token przy pierwszym zapytaniu, odświeża go po wygaśnięciu i dołącza poprawny nagłówek do kolejnych wywołań. Ręczne pozyskiwanie tokenu nie jest wtedy potrzebne.

Przykładowe biblioteki i narzędzia wspierające ten mechanizm:

  • Java: Spring Security OAuth2 (WebClient z ReactiveOAuth2AuthorizedClientManager)

  • Python: requests-oauthlib, Authlib

  • .NET: HttpClientFactory z OAuthMessageHandler

  • Node.js: axios-oauth-client, simple-oauth2

  • Narzędzia typu low-code/no-code do automatyzacji procesów, takie jak N8N, make.com, czy Zapier.

image62
Rysunek 2. Moduł REST API - widok w Panelu Administracyjnym - przykład