InnerWeb
Przejdź do treści

FAQ: API osoby dla portalu, czyli szkolenia i przepustka

API osoby pozwala portalowi pobrać z zakładu listę szkoleń danej osoby ze statusem, osobisty link do szkolenia oraz przepustkę. Całość działa za tokenem maszynowym, a konto usunięte w systemie daje odpowiedź 404. Poniżej odpowiadamy na pytania integratorów i kierowników IT, którzy planują podłączyć portal wykonawców lub pracowników do zakładu.

4
statusy szkoleń w odpowiedzi API
Źródło: karta funkcji
30 dni
okno statusu wygasającego szkolenia
Źródło: karta funkcji
7 dni
okres liczenia błędów w panelu
Źródło: karta funkcji

Co zwraca API osoby

API osoby dla portalu zwraca trzy rodzaje informacji: listę szkoleń ze statusem, osobisty link do szkolenia oraz przepustkę. Każda z nich dotyczy jednej osoby zidentyfikowanej w zakładzie, więc portal nie musi przechowywać własnej kopii stanu uprawnień.

Takie rozwiązanie porządkuje odpowiedzialność: źródłem prawdy o szkoleniach i przepustce jest system zakładu, a portal jest widokiem. Zmiana statusu w zakładzie jest widoczna w portalu przy kolejnym zapytaniu.

Jakie statusy szkoleń są zwracane?

Cztery: todo, done, expiring i expired. Status todo oznacza szkolenie do wykonania, done szkolenie zaliczone, expiring zaliczone, ale wygasające w ciągu 30 dni, a expired szkolenie, którego ważność minęła.

Status expiring pozwala portalowi pokazać ostrzeżenie z wyprzedzeniem, zanim osoba straci możliwość wejścia na teren.

Czym jest osobisty link do szkolenia?

To adres, który API wystawia dla konkretnej osoby i konkretnego szkolenia. Portal może go wyświetlić jako przycisk, a osoba przechodzi szkolenie bez ręcznego logowania do osobnego systemu.

Jak API jest zabezpieczone

Wszystkie wywołania API osoby wymagają tokenu maszynowego. Token jest przechowywany po stronie serwera portalu, a w panelu zakładu klucze nie trafiają do przeglądarki: ustawienia integracji są tylko do odczytu.

Dla integratora oznacza to prostą zasadę: wywołania API wykonuje backend portalu, nigdy kod uruchamiany w przeglądarce użytkownika. Token w kodzie strony byłby tokenem ujawnionym.

Co się stanie, gdy token jest błędny?

Wywołanie zostaje odrzucone. W analogicznym API wniosków o dostęp brak lub zły token daje odpowiedź 401. Integrator powinien potraktować 401 jako sygnał do sprawdzenia konfiguracji, a nie do ponawiania w pętli.

Czy token może należeć do zwykłego konta pracownika?

Nie powinien. Token maszynowy jest przeznaczony dla integracji, ma ograniczony zakres i jego użycie da się odróżnić od działań ludzi w dzienniku wymiany. Zalecenia dla konta technicznego opisujemy w osobnym materiale o uprawnieniach.

Kody odpowiedzi przy wnioskach o dostęp

Kody odpowiedzi przy wnioskach o dostępWykres pokazuje cztery kody odpowiedzi API wniosków: 201, 200, 400 i 401.0100200300400500kod HTTPNowy wniosek: 201 kod HTTP201Nowy wniosekPowtórka: 200 kod HTTP200PowtórkaBłędne dane: 400 kod HTTP400Błędne daneZły token: 401 kod HTTP401Zły token
Źródło: Karta funkcji integracji z portalem

Błędy i przypadki brzegowe

Konto usunięte w systemie daje odpowiedź 404. Portal powinien traktować 404 jako informację, że osoba nie istnieje w zakładzie, i usunąć lub oznaczyć powiązanie po swojej stronie, zamiast wyświetlać stare dane.

W dzienniku wymiany po stronie zakładu zapisują się zdarzenia z kierunkiem, wynikiem i kodem HTTP, a zapis do dziennika nigdy nie przerywa obsługi zapytania. Przy diagnozie problemu integrator może więc porównać własne logi z dziennikiem zakładu.

Jak odróżnić osobę bez szkoleń od osoby usuniętej?

Osoba bez szkoleń dostaje poprawną odpowiedź z pustą lub krótką listą, a osoba usunięta dostaje 404. Dzięki temu portal nie myli braku danych z brakiem konta.

Co z wnioskami o dostęp składanymi przez portal?

Wniosek o dostęp przychodzi osobnym wywołaniem POST z tokenem maszynowym. Odpowiedź 201 oznacza nowy wniosek, 200 powtórkę tego samego identyfikatora żądania, 400 błędne dane, a 401 brak lub zły token. Dane uprawnień, szkoleń i badań są przyjmowane tylko wtedy, gdy zakres zgody osoby je obejmuje.

Rola administratora i operatora

Panel integracji w module uprawnień pokazuje status połączenia, liczbę czynnych przepustek, połączonych kont, wniosków do rozpatrzenia i błędów z ostatnich 7 dni, a także dziennik wymiany. Panel widzą administrator i pracownik BHP.

Akceptacja, odrzucenie i ponowienie decyzji we wnioskach o dostęp z portalu jest dostępne wyłącznie dla roli administratora usługi. Podział ma chronić przed sytuacją, w której osoba z uprawnieniami do podglądu zmienia decyzje o dostępie.

Co z decyzją, której nie udało się doręczyć?

Niedoręczona decyzja zostaje w wierszu z opisem błędu i można ją ponowić z panelu. Operator nie musi więc prosić integratora o ręczne odtwarzanie żądania.

Materiał wideo

Często zadawane pytania

Czy portal musi przechowywać kopię szkoleń?

Nie. Źródłem stanu jest zakład, a portal pobiera go przy zapytaniu. Własna kopia jest potrzebna tylko do pamięci podręcznej.

Jak często odpytywać API osoby?

Przy wejściu osoby na stronę portalu, a nie w pętli w tle. Status expiring ma okno 30 dni, więc odświeżanie raz na wizytę wystarcza.

Co zrobić, gdy portal dostaje 404 dla znanej osoby?

Konto zostało usunięte w zakładzie. Oznacz powiązanie jako nieaktualne i skieruj osobę do ponownego wniosku o dostęp.

Czy API zwraca dane, na które osoba nie wyraziła zgody?

Dane uprawnień, szkoleń i badań są przyjmowane we wnioskach tylko wtedy, gdy zakres zgody je obejmuje.

Podłącz portal do zakładu

Pokażemy zapytanie do API osoby na danych testowych i omówimy, jak portal wykonawców ma wyświetlać statusy szkoleń. Umów rozmowę z InnerWeb.

Porozmawiajmy