InnerWeb
Przejdź do treści

Webhook odbić kart z KD do RCP: uwagi wdrożeniowe

Odbicie karty na bramie ma trafić do ewidencji czasu pracy bez ręcznego przepisywania. InnerWeb przyjmuje zdarzenie odbicia z systemu kontroli dostępu przez webhook, więc zadanie dostawcy KD to wysłanie właściwych pól właściwym kanałem. Poniżej uwagi dla integratora i działu IT: pola, token, kolejność prac.

12 h
czas ważności tokenu webhooka
Źródło: karta
4
etapy wdrożenia: spec, test, hala, zakład
Źródło: opracowanie własne

Cel integracji i podział odpowiedzialności

Zakład ma system kontroli dostępu z czytnikami i kartami oraz system ewidencji czasu pracy. InnerWeb jest niezależnym systemem uzupełniającym: przyjmuje zdarzenia odbicia, łączy je z kwalifikacjami, zezwoleniami, obecnością i rejestracją czasu pracy, i nie zastępuje ani KD, ani RCP, ani HR.

InnerWeb nie produkuje ani nie wymienia czytników. Specyfikacja integracji jest przeznaczona dla dostawcy KD: to on konfiguruje wysyłanie zdarzeń. Zadaniem zakładu jest zapewnić, by dostawca dostał specyfikację i dostęp do środowiska testowego.

Pola zdarzenia: co dostawca KD ma wysłać

Zdarzenie odbicia karty zawiera między innymi czas, miejsce, imię, nazwisko, firmę, numer aktywnej karty, telefon, e-mail i język osoby. Nie wszystkie pola muszą być dostępne w systemie KD, dlatego specyfikację uzgadnia się na poziomie pól obowiązkowych i opcjonalnych.

Minimum praktyczne to czas odbicia, miejsce (bramka lub czytnik) i identyfikator osoby: numer aktywnej karty. Pozostałe pola ułatwiają dopasowanie osoby do konta, ale dane osobowe należy przekazywać w zakresie niezbędnym i zgodnym z podstawą prawną zakładu.

  • czas odbicia z oznaczeniem strefy czasowej
  • miejsce: identyfikator bramki lub czytnika
  • numer aktywnej karty
  • imię i nazwisko oraz firma, jeśli system KD je przechowuje
  • język osoby, jeśli ma służyć komunikatom

Przykładowy harmonogram integracji webhooka (założenie)

Przykładowy harmonogram integracji webhooka (założenie)Słupki: 5, 3, 5 i 5 dni roboczych.012345dni roboczychSpecyfikacja i środowisko testowe: 5 dni roboczych5Specyfikacja iśrodowisko testoweTest z jednej bramki: 3 dni roboczych3Test z jednej bramkiJedna hala: 5 dni roboczych5Jedna halaCały zakład: 5 dni roboczych5Cały zakład
Źródło: Kalkulacja przykładowa: czasy założone do planowania, do zastąpienia ustaleniami z dostawcą KD

Uwierzytelnienie: token z ograniczonym czasem ważności

InnerWeb przyjmuje zdarzenie odbicia karty przez webhook uwierzytelniony tokenem z ograniczonym czasem ważności: 12 godzin. Dostawca KD musi więc zaplanować odnawianie tokenu przed wygaśnięciem, a nie dopiero po odrzuceniu zdarzenia.

W specyfikacji warto zapisać, kto i jak odnawia token, co się dzieje ze zdarzeniami wysłanymi po wygaśnięciu oraz jak dostawca dowiaduje się o błędzie. Dobra praktyka to kolejka po stronie KD, która ponawia wysyłkę, gdy odbiór nie został potwierdzony.

Token nie może być zapisany w jawnym pliku konfiguracyjnym ani w treści zgłoszenia serwisowego. Przekazanie odbywa się kanałem uzgodnionym przez działy IT obu stron.

Kolejność prac: od testu do produkcji

Etap pierwszy: dostawca KD dostaje specyfikację i dane środowiska testowego. Etap drugi: wysyłka zdarzeń testowych z jednej bramki, sprawdzenie pól i czasu. Etap trzeci: wysyłka z wszystkich bramek jednej hali. Etap czwarty: włączenie całego zakładu i porównanie liczby odbić po obu stronach.

Porównanie liczby odbić jest kluczowym testem: liczba zdarzeń wysłanych przez KD i przyjętych przez InnerWeb w tym samym oknie czasowym powinna być taka sama. Różnice analizuje się według bramki i godziny, bo często wskazują konkretny czytnik albo moment wygaśnięcia tokenu.

Pułapki: czas, duplikaty i odbicia bez osoby

Pierwsza pułapka to strefa czasowa: czas odbicia zapisany w czasie lokalnym bez oznaczenia strefy daje błąd o godzinę w okresie zmiany czasu, co w ewidencji pracy wygląda jak godzina nadliczbowa. Czas należy przekazywać z oznaczeniem strefy.

Druga pułapka to duplikaty: ta sama karta odbita dwukrotnie w ciągu kilku sekund, bo czytnik odczytał ją i przy wejściu, i przy wyjściu. Reguły filtrowania ustala się z ochroną, nie w kodzie integracji.

Trzecia pułapka to odbicia bez osoby: numer karty, który nie ma przypisanego konta, albo przypisany do konta zdublowanego. Takie zdarzenie trafia do listy wyjątków, a kontrola par zdublowanych kont po imporcie kart ogranicza ich liczbę.

Odbiór i utrzymanie

Odbiór kończy się protokołem: lista bramek, wynik porównania liczby odbić, test wygaśnięcia i odnowienia tokenu, test awarii łącza. Utrzymanie to alarm braku zdarzeń z bramki w godzinach, w których zwykle są odbicia, bo cisza z jednej bramki bywa pierwszym objawem awarii.

Zakład powinien wskazać osobę, która odbiera alarmy, i dostawcę KD, który je rozwiązuje po stronie swojego systemu. Bez tego integracja działa, dopóki nie zdarzy się pierwszy problem.

Przy rozbudowie zakładu o nową halę lub bramę dostawca KD dopisuje nowe czytniki do wysyłki, a zakład aktualizuje listę miejsc, żeby zdarzenia z nowej bramy nie trafiały jako odbicia bez lokalizacji. Zmiana listy bramek powinna być krokiem w procedurze zmiany, równie obowiązkowym jak zamówienie czytnika.

Materiał wideo

Często zadawane pytania

Czy InnerWeb wymienia czytniki?

Nie. InnerWeb integruje się z istniejącym systemem KD, a specyfikacja jest przeznaczona dla jego dostawcy.

Jak długo ważny jest token webhooka?

12 godzin, więc dostawca KD musi zaplanować jego odnawianie.

Jakie dane zawiera zdarzenie odbicia?

Między innymi czas, miejsce, imię, nazwisko, firmę, numer aktywnej karty, telefon, e-mail i język osoby, w zakresie uzgodnionym z zakładem.

Jak sprawdzić, że integracja działa?

Porównaj liczbę odbić wysłanych przez KD i przyjętych przez InnerWeb w tym samym oknie czasowym, według bramki.

Źródła

Przekaż specyfikację dostawcy KD

Przygotujemy specyfikację pól i uwierzytelnienia dla Państwa dostawcy KD oraz plan testów z jednej bramki.

Porozmawiajmy