System Tipi ZHP posiada API, czyli interfejs który umożliwia komunikowanie się z Tipi bezpośrednio przez inne aplikacji za pomocą odpowiednich żądań HTTP.

Przed rozpoczęciem korzystania z API zapoznaj się z niniejszą instrukcją i zasadami bezpieczeństwa.

  • operacje przez API mają taki sam skutek jak operacje wykonywane bezpośrednio w systemie
  • system rejestruje czas oraz dane osoby wprowadzającej zmiany - zarówno bezpośrednio w Tipi jak i przez API
  • nigdy nie udostępniaj swojego klucza API innej osobie, nie zapisuj go otwartym tekstem (np. w opracowanych przez Ciebie skryptach, w repozytorium kodu)
  • ustawiaj maksymalnie krótki czas wygaśnięcia klucza - np. jeśli potrzebujesz używać API przez 3 dni to ustaw ważność klucza tylko na 3 dni
  • jeśli używasz API do pojedynczych operacji - generuj nowy klucz i dezaktywuj go od razu po wykonaniu tych operacji
  • jeśli to możliwe - ograniczaj dostęp do API wyłącznie do adresu IP, z którego będziesz wykonywać operacje
  • wszystkie skrypty i programy wykorzystujące API muszą być uruchamiane bezpośrednio przez Ciebie - API będzie działać z Twoimi uprawnieniami

Założenia i limity

  1. API dostępne jest dla każdego użytkownika systemu. Wykonywanie operacji z wykorzystaniem API zapisuje dane na temat użytkownika i działa z takimi samymi uprawnieniami jak dla operacji w systemie.
  2. Każdy użytkownik może posiadać jeden klucz API, który może w dowolnej chwili dezaktywować.
  3. Czas ważności klucza jest definiowany przez użytkownika i może wynosić minimum 1 a maksymalnie 180 dni.
  4. Limit zapytań dla jednego klucza w ciągu godziny jest obecnie ustawiony na 5000. Po jego przekroczeniu wykonywanie zapytań nie będzie możliwe aż do upłynięcia wymaganego czasu.
  5. Administrator systemu może wyłączyć klucz API dla danego użytkownika bez jego informowania w przypadku stwierdzenie naruszeń.
  6. Administrator systemu może zmieniać ustawione limity maksymalnej ważności klucza i liczby zapyrań.

Jak aktywować API

Aby aktywować dostęp do API należy:

  1. mieć przypisaną rolę "użytkownik API" - jest to publicznie dostępna rola, którą można nadać tak jak każdą inną, nie ma znaczenia w jakiej jednostce będzie nadana, ponieważ dostęp do API działa dla wszystkich innych nadanych ról łącznie
  2. w zakładce "Ustawienia" w swoim profilu wygenerować klucz API
  3. podczas generowania ustawić (opcjonalnie) dozwolone adresy IP i czas wygaśnięcia klucza
  4. zapisać klucz w bezpiecznym miejscu - będzie wyświetlony tylko raz

Dezaktywacja i ponowne generowania klucza

Klucz można w dowolnym momencie wyłączyć za pomocą zielonego przełącznika lub wygenerować nowy.

Wygenerowanie nowego klucza automatycznie dezaktywuje stary klucz.

Dostępne endpointy - dokumentacja

Informacje o wszystkich dostępnych endpointach wraz z dokumentacją oraz możliwością wykorzystania API "na żywo" znajdują się na stronie: https://tipi.zhp.pl/api/swagger-ui/index.html#/

Uwaga! Dostęp do strony możliwy jest po zalogowaniu się na konto ZHP.