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
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