InnerWeb
Przejdź do treści

Specyfikacja integracji dla dostawcy KD: poradnik krok po kroku

Wdrożenie webhooka odbicia karty zamyka się w jednej iteracji tylko wtedy, gdy dostawca KD dostaje kompletną specyfikację na starcie. Brak jednego pola lub nieznane ograniczenie kończy się kolejną rundą testów. Poniżej opisujemy sześć kroków, od uwierzytelnienia po testy akceptacyjne, na podstawie dokumentu integracyjnego przekazywanego dostawcom KD.

6
kroków specyfikacji do jednej iteracji
Źródło: poradnik InnerWeb
2 000+
odbić na dobę w zakładzie z agencjami
Źródło: skala ruchu w zakładzie

Krok 1: opisz cel i granice odpowiedzialności

Specyfikację zacznij od jednego zdania celu: system KD wysyła do InnerWeb żądanie HTTP POST przy każdym odbiciu karty, a InnerWeb wykorzystuje je do sprawdzania szkoleń, zezwoleń i ewidencji czasu pracy. Zapisz jasno granicę: InnerWeb nie dostarcza własnych czytników do tej integracji i nie wymienia czytników, więc cała praca dostawcy KD to konfiguracja wysyłki zdarzeń. Szczegółowa specyfikacja integracji istnieje jako dokument PDF przekazywany dostawcy zewnętrznemu; ten poradnik opisuje, jak ją uporządkować.

Krok 2: uwierzytelnianie i sesja

Wywołanie wymaga tokenu pobieranego z endpointu logowania API. Token ma ograniczony czas ważności i jest odnawiany automatycznie przez integrację, więc specyfikacja musi wymagać od dostawcy odnawiania tokenu z zapasem oraz ponownego logowania po odrzuceniu autoryzacji. Zapisz też wymóg konta technicznego przeznaczonego tylko do integracji i zakaz zapisywania haseł oraz tokenów w logach.

Liczby ze specyfikacji

Liczby ze specyfikacjiWykres słupkowy: sześć kroków specyfikacji, dwa pola wymagane, zero czytników do wymiany.0246liczbaKroków specyfikacjiKroków specyfikacji: 6 liczba6Pól wymaganychPól wymaganych: 2 liczba2Czytników do wymianyCzytników do wymiany: 0 liczba0
Źródło: Poradnik InnerWeb

Krok 3: pola zgłoszenia

Wymień pola jedno pod drugim, z oznaczeniem, które są wymagane. Zgłoszenie obejmuje czas zdarzenia, miejsce odbicia oraz dane osoby: imię i nazwisko (wymagane), akronim, firmę (nazwa wymagana), numer aktywnej karty, telefon, e-mail i język. Numer aktywnej karty jest identyfikatorem łączącym odbicie z kontem osoby, a firma zewnętrzna jest przypisywana po nazwie firmy. Zażądaj więc jednolitej pisowni nazw firm.

  • Wymagane: imię i nazwisko, nazwa firmy.
  • Klucz dopasowania: numer aktywnej karty.
  • Miejsce: pole actionPlace rozróżniające lokalizacje czytników.
  • Opcjonalne: akronim, telefon, e-mail, język.

Krok 4: wymagania wobec zdarzenia i wysyłki

Dwa wymagania muszą trafić do specyfikacji jednoznacznie. Po pierwsze, system KD wysyła zdarzenia w czasie rzeczywistym, z czasem zdarzenia odczytanym z czytnika, a po awarii łącza zdarzenia zachowują swój pierwotny czas. Po drugie, każde zdarzenie niesie 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 i opisuje jako uzgodniony zakres prac.

Dopisz wymóg odporności na serie i powtórzenia: w zakładzie z wieloma agencjami ruch może przekraczać 2 000 odbić na dobę roboczą.

Krok 5: miejsca odbicia i szablony

Poproś dostawcę o listę czytników z nazwami miejsc odbicia w formie, w jakiej trafią do pola actionPlace. Zdarzenia z miejsca niemającego szablonu w InnerWeb trafiają do logu i nie uruchamiają alarmu szkoleniowego, więc lista czytników musi być uzgodniona z konfiguracją po stronie InnerWeb, zanim ruszą testy. Pominięty czytnik to najczęstsza przyczyna odbić widocznych w logu, ale bez efektu na bramie.

Krok 6: testy akceptacyjne

Opisz scenariusze testowe zamiast ogólnego sformułowania o testach. Minimum: odbicie znanej osoby, odbicie osoby nieznanej, powtórzone odbicie w krótkim odstępie, odbicie na każdym czytniku z listy, wygaśnięcie tokenu w trakcie wysyłki i seria zdarzeń. Kryterium zamknięcia: każdy scenariusz ma oczekiwany wynik po stronie InnerWeb. Pamiętaj, że sam webhook bez mapowania na wejścia nie daje RCP, więc dołącz test widoczności odbicia w rejestrze wejść.

Lista kontrolna

Materiał wideo

Często zadawane pytania

Czy dostawca KD musi wymieniać czytniki?

Nie. Integracja to konfiguracja wysyłki zdarzenia odbicia, a InnerWeb nie dostarcza ani nie wymienia czytników.

Dlaczego specyfikacja wymaga wysyłki w czasie rzeczywistym?

Bo czas zdarzenia z czytnika ma zostać zachowany, a opóźniona wysyłka utrudnia parowanie wejść i wyjść oraz kontrolę obecności.

Kto określa kierunek wejścia i wyjścia?

System KD przekazuje kierunek w każdym zdarzeniu, a zasady parowania wejść i wyjść ustala się w specyfikacji z dostawcą KD.

Źródła

Przekażemy specyfikację Waszemu dostawcy KD

Mamy gotowy dokument integracyjny dla dostawców KD. Umów rozmowę z zespołem InnerWeb i zamknijcie wdrożenie w jednej iteracji.

Porozmawiajmy