InnerWeb
Przejdź do treści

Pytania o integrację KD z BHP: FAQ integratora

Integrator systemu kontroli dostępu zadaje przed pierwszym wywołaniem webhooka te same pytania: jak się uwierzytelnić, jakie pola są wymagane i co się stanie, gdy karta nie jest znana. Zebraliśmy odpowiedzi w kolejności, w jakiej pojawiają się podczas uruchomienia. InnerWeb nie wymienia czytników, więc cała praca po stronie KD sprowadza się do jednego żądania HTTP POST przy każdym odbiciu.

JWT
uwierzytelniony webhook, token odnawiany automatycznie
Źródło: karta wewnętrzna
real-time
wysyłka zdarzeń z KD na bieżąco
Źródło: karta wewnętrzna
2 000+
odbić na dobę roboczą w zakładach z wieloma agencjami
Źródło: karta wewnętrzna

Czym jest webhook odbicia karty i kto go wywołuje

Webhook odbicia karty to punkt integracji między istniejącym systemem KD a InnerWeb. System KD wysyła do InnerWeb żądanie HTTP POST przy każdym odbiciu karty na czytniku. Nie trzeba instalować nowych czytników, zmieniać okablowania ani wymieniać kart: InnerWeb jest producentem oprogramowania i integruje się z KD, które zakład już posiada.

Wywołującym jest zawsze system KD, nie InnerWeb. To dostawca lub administrator KD konfiguruje regułę wysyłki zdarzenia po odbiciu. Po stronie InnerWeb odbicie zostaje przypisane do osoby, sprawdzone pod kątem szkolenia i zapisane w historii konta. Dzięki temu numer karty z KD staje się kluczem do ważnych szkoleń BHP, kwalifikacji i zezwoleń.

Jak uwierzytelnić wywołanie i jak długo ważny jest token

Wywołanie webhooka wymaga tokenu JWT. Integrator pobiera go z endpointu logowania API, a następnie dołącza do każdego żądania z odbiciem. Token ma ograniczony czas ważności i jest odnawiany automatycznie przez integrację. Integrator powinien zapisać w specyfikacji sposób odnawiania sesji, bo od niego zależy ciągłość wysyłki odbić.

Praktyczny wzorzec: konto techniczne używane wyłącznie do integracji, logowanie przy starcie usługi, automatyczne odnowienie tokenu z zapasem przed upływem jego ważności i ponowne logowanie po odpowiedzi odrzucającej autoryzację. Hasła i tokeny nie powinny trafiać do logów usługi po stronie KD.

Co zrobić, gdy token wygaśnie w trakcie zmiany

Odbicia z okresu, gdy token był nieważny, nie mogą przepaść. Dobra praktyka to kolejka po stronie KD: nieudane wywołanie trafia do bufora, usługa loguje się ponownie i dosyła zdarzenia po kolei. Kolejka ma sens tylko wtedy, gdy zdarzenia są wysyłane niemal w czasie rzeczywistym, o czym piszemy niżej.

Pola zgłoszenia odbicia karty

Pola zgłoszenia odbicia kartyWykres słupkowy: 2 pola wymagane i 5 opcjonalnych w zgłoszeniu odbicia karty012345liczba pólWymagane (imię i nazwisko,firma)Wymagane (imię i nazwisko, firma): 2 liczba pól2Opcjonalne (akronim, karta,telefon, e-mail, język)Opcjonalne (akronim, karta, telefon, e-mail, język): 5 liczba pól5
Źródło: Karta wewnętrzna: webhook odbicia karty

Jakie pola są wymagane w zgłoszeniu odbicia

Zgłoszenie niesie czas zdarzenia, miejsce odbicia oraz dane osoby. Wymagane są imię i nazwisko oraz nazwa firmy. Opcjonalnie przekazuje się akronim, numer aktywnej karty, telefon, e-mail i język. Im pełniejszy zestaw, tym łatwiejsze dopasowanie do istniejącego konta i późniejsze powiadomienia w języku osoby.

Numer aktywnej karty jest identyfikatorem, po którym InnerWeb łączy odbicie z kontem osoby. Firma zewnętrzna jest przypisywana na podstawie nazwy firmy ze zgłoszenia. Jeśli w KD ta sama agencja występuje raz jako pełna nazwa, raz ze skrótem, powstaną rozbieżności, dlatego integrator powinien przekazywać nazwy w jednolitej pisowni.

  • Wymagane: imię i nazwisko osoby oraz nazwa firmy.
  • Zalecane: numer aktywnej karty jako klucz dopasowania do konta.
  • Opcjonalne: akronim, telefon, e-mail, język.
  • Zawsze: czas zdarzenia i miejsce odbicia.

Co się dzieje, gdy karta lub osoba są nieznane

Odbicie karty przez osobę, której system nie zna, zakłada konto i firmę z danych zgłoszenia. To wygodne przy dużej rotacji pracowników agencji, ale wymaga dyscypliny w danych: błąd w pisowni nazwiska lub firmy utworzy duplikat. Dlatego pytanie „co z nieznaną kartą” w praktyce brzmi „kto odpowiada za jakość danych źródłowych w KD”.

Gdy ta sama osoba ma dwa aktywne konta, system przenosi wynik szkolenia na konto z kartą wejściową, aby brama przestała zgłaszać brak szkolenia. Nigdy nie scala kont wyłącznie po nazwisku, bo to prowadziłoby do pomyłek między osobami o tym samym nazwisku.

Czas zdarzenia, kierunek i duplikaty: wymagania specyfikacji

Specyfikacja integracji wymaga, aby system KD wysyłał zdarzenia w czasie rzeczywistym, z czasem zdarzenia odczytanym z czytnika, bez paczek i wysyłek nocnych. Dzięki temu godziny odbić w InnerWeb odpowiadają faktycznym przejściom przez bramę, a opóźnienia po stronie sieci nie zniekształcają ewidencji.

Każde zdarzenie z KD powinno nieść kierunek (wejście lub wyjście) oraz identyfikator zdarzenia, a InnerWeb przyjmuje je przez uwierzytelniony webhook. Zasady parowania wejść i wyjść oraz odrzucania duplikatów ustala się w specyfikacji z dostawcą KD. Przy zakładach z wieloma agencjami pracy ruch może przekraczać 2 000 odbić na dobę roboczą, więc integracja musi znosić serie zdarzeń i powtórzenia.

Lista kontrolna

Materiał wideo

Często zadawane pytania

Czy trzeba wymieniać czytniki, żeby uruchomić integrację?

Nie. InnerWeb nie produkuje ani nie wymienia czytników KD. Integracja polega na wysyłce zdarzenia z istniejącego systemu KD do InnerWeb żądaniem HTTP POST.

Jak działa uwierzytelnianie tokenem?

Token JWT z endpointu logowania API ma ograniczony czas ważności. Integracja odnawia go automatycznie, z zapasem przed wygaśnięciem.

Czy InnerWeb zapisze czas odbicia z czytnika?

Specyfikacja integracji zakłada, że system KD wysyła zdarzenia w czasie rzeczywistym, z czasem zdarzenia z czytnika.

Skąd InnerWeb zna kierunek wejścia i wyjścia?

Kierunek i identyfikator zdarzenia wysyła system KD. Zasady parowania wejść i wyjść oraz odrzucania duplikatów ustala się w specyfikacji z dostawcą KD.

Źródła

Porozmawiajmy o integracji z Waszym KD

Przekażemy dostawcy KD specyfikację webhooka i przejdziemy z nim przez pola, token i wysyłkę w czasie rzeczywistym. Umów rozmowę z zespołem InnerWeb.

Porozmawiajmy