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