Czego wymaga specyfikacja od systemu KD
System KD wysyła zdarzenia odbić w czasie rzeczywistym. Każde zdarzenie niesie czas odbicia odczytany z czytnika, kierunek (wejście albo wyjście) oraz identyfikator zdarzenia, a obok nich identyfikator karty lub konta i identyfikator czytnika. Dzięki czasowi zdarzenia z czytnika historia obecności odzwierciedla rzeczywisty moment przejścia, a nie moment dostarczenia wiadomości.
InnerWeb przyjmuje zdarzenia z systemu KD przez uwierzytelniony webhook i łączy je z kwalifikacjami, zezwoleniami, obecnością i RCP. Zasady parowania wejść i wyjść oraz odrzucania duplikatów ustala się w specyfikacji razem z dostawcą KD, bo zależą od konfiguracji czytników i bram w zakładzie. Jeśli czytnik w danej instalacji KD nie zwraca kierunku, jest to fakt techniczny po stronie KD i trzeba go opisać w specyfikacji osobno.
Jak opisać zdarzenie w specyfikacji
Specyfikacja dla integratora powinna być krótka i jednoznaczna. Każde pole ma nazwę, typ, format i opis wartości dopuszczalnych. Opisuje też uwierzytelnienie: token o ograniczonym czasie ważności, odnawiany automatycznie przez integrację.
- Identyfikator konta lub karty w formie uzgodnionej między systemami.
- Identyfikator czytnika zgodny z miejscem zdefiniowanym w systemie zezwoleń.
- Czas zdarzenia z czytnika, ze strefą czasową, w stałym formacie.
- Kierunek: wejście lub wyjście, zgodnie z konfiguracją czytnika w systemie KD.
- Unikalny identyfikator zdarzenia do ponawiania wysyłki i usuwania powtórzeń.
Dlaczego czytnik musi mieć miejsce w systemie
Odbicie z czytnika bez przypisanego miejsca, czyli punktu akcji, nie uruchamia alarmu szkoleniowego. Zdarzenie dochodzi, ale nie ma efektu. Przed uruchomieniem integracji sprawdź, czy każdy czytnik ma odpowiednik w systemie.
Elementy specyfikacji integracji KD
Parowanie wejść z wyjściami i duplikaty
Przy parowaniu wejść z wyjściami odbiorca łączy kolejne odbicia tego samego konta w pary, a zdarzenia bez pary oznacza do weryfikacji. Maksymalny odstęp między wejściem a wyjściem należy dobrać do organizacji pracy w zakładzie, z zapasem na nadgodziny i przerwy. Konkretną wartość oraz zasady postępowania z niesparowanymi zdarzeniami ustala się w specyfikacji z dostawcą KD.
Parowanie to metoda, nie dowód: raport powinien pokazywać, które pary są wynikiem reguły, a które pochodzą bezpośrednio z czytnika. Dzięki temu kontrola obecności i RCP pozostaje czytelna dla audytu.
Powtórzone odbicia
Pracownik przykłada kartę dwa razy, bo brama nie otworzyła się od razu. Specyfikacja powinna określić, jak krótko po sobie następujące odbicia tej samej karty na tym samym czytniku są traktowane, aby liczba odbić w ciągu zmiany nie stała się nieparzysta i pary się nie rozjeżdżały. Próg czasowy uzgadnia się z dostawcą KD.
Sieć zakładu i kolejka outbox
Sieć zakładu bywa skonfigurowana tak, że serwer aplikacji nie może wysyłać ruchu na zewnątrz. Webhooki wychodzące mogą być wtedy kolejkowane w tabeli outbox, a odbiór następuje innym kanałem uzgodnionym z klientem. Integrator opisuje ten kanał w specyfikacji, razem z maksymalnym opóźnieniem dostarczenia.
Z perspektywy integratora ważna jest idempotencja: to samo zdarzenie wysłane dwa razy nie może powstać jako dwa odbicia. Unikalny identyfikator zdarzenia rozwiązuje ten problem.
Bezpieczeństwo kont przy łączeniu zdarzeń
System nigdy nie łączy ani nie przekierowuje aktywnego konta wyłącznie na podstawie podobieństwa nazwiska, a konta z kartą pokazuje na liście jako pierwsze. Zdarzenia z KD trafiają więc do właściwego konta po identyfikatorze, nie po nazwisku.
Warto uzgodnić z dostawcą KD, że identyfikator w zdarzeniu jest stały i nie zmienia się przy wymianie karty. Wtedy migracja kart na nową technologię nie przerywa historii odbić.
Testy przed uruchomieniem
Przed uruchomieniem sprawdź cztery przypadki. Pierwszy: odbicie wejścia i wyjścia w tej samej zmianie tworzy parę. Drugi: powtórzone odbicie w krótkim odstępie liczy się jako jedno. Trzeci: wysłanie tego samego zdarzenia dwa razy z tym samym identyfikatorem nie tworzy duplikatu. Czwarty: odbicie z czytnika bez miejsca w systemie jest zgłaszane jako błąd konfiguracji.
Wyniki testów zapisz w protokole odbioru integracji. Integrator i klient mają wtedy wspólny dowód, że webhook działa zgodnie ze specyfikacją, a w razie sporu da się odtworzyć zdarzenia z dziennika.
Materiał wideo
Często zadawane pytania
Jakie dane powinno zawierać zdarzenie z KD?
Czas zdarzenia z czytnika, kierunek wejście lub wyjście, identyfikator zdarzenia, identyfikator karty lub konta i identyfikator czytnika.
Po co unikalny identyfikator zdarzenia?
Pozwala ponawiać wysyłkę bez ryzyka powstania dwóch odbić. Odbiorca usuwa powtórzenia po tym identyfikatorze.
Co, gdy serwer nie może łączyć się z zewnętrzną siecią?
Webhooki mogą być kolejkowane w tabeli outbox, a odbiór odbywa się innym kanałem uzgodnionym z klientem.
Specyfikacja webhooka dla Twojego integratora
Przygotujemy z Tobą opis pól, parowania i kolejkowania zdarzeń z KD. Umów rozmowę z zespołem InnerWeb.
Porozmawiajmy