Co specifikace vyžaduje od systému KD
Systém KD posílá události odbití v reálném čase. Každá událost nese čas odbití načtený z čtečky, směr (vstup nebo výstup) a identifikátor události, vedle něj identifikátor karty nebo účtu a identifikátor čtečky. Díky času události z čtečky odpovídá historie docházky skutečnému okamžiku průchodu, a ne okamžiku doručení zprávy.
InnerWeb přijímá události ze systému KD prostřednictvím ověřeného webhooku a páruje je s kvalifikacemi, oprávněními, docházkou a docházkovým systémem. Pravidla párování vstupů s výstupy a odmítání duplicit se ve specifikaci určují společně s dodavatelem KD, protože závisí na konfiguraci čteček a bran v závodě. Pokud čtečka v dané instalaci KD nevrací směr, jde o technickou skutečnost na straně KD a je třeba ji popsat ve specifikaci zvlášť.
Jak popsat událost ve specifikaci
Specifikace pro integrátora má být krátká a jednoznačná. Každé pole má název, typ, formát a popis přípustných hodnot. Popisuje také ověření: token s omezenou platností, který integrace obnovuje automaticky.
- Identifikátor účtu nebo karty ve formě dohodnuté mezi systémy.
- Identifikátor čtečky odpovídající místu definovanému v systému oprávnění.
- Čas události z čtečky, se záznamem časového pásma, v pevném formátu.
- Směr: vstup nebo výstup podle konfigurace čtečky v systému KD.
- Jedinečný identifikátor události pro opakované odeslání a odstranění duplicit.
Proč musí mít čtečka místo v systému
Odbití z čtečky bez přiřazeného místa, tedy bez akčního bodu, nespustí školicí upozornění. Událost dorazí, ale nemá žádný účinek. Před spuštěním integrace ověřte, zda má každá čtečka protějšek v systému.
Prvky specifikace integrace KD
Párování vstupů s výstupy a duplicity
Při párování vstupů s výstupy příjemce spojuje následující odbití stejného účtu do dvojic a události bez dvojice označí k ověření. Maximální odstup mezi vstupem a výstupem je třeba zvolit podle organizace práce v závodě, s rezervou na přesčasy a přestávky. Konkrétní hodnotu a postup u nespárovaných událostí určuje specifikace s dodavatelem KD.
Párování je metoda, nikoli důkaz: výstup má ukazovat, které dvojice vznikly podle pravidla a které pocházejí přímo z čtečky. Díky tomu zůstane kontrola docházky a pracovní doby přehledná i pro audit.
Opakovaná odbití
Zaměstnanec přiloží kartu dvakrát, protože se brána neotevřela hned. Specifikace má určit, jak se krátce po sobě následující odbití stejné karty na stejné čtečce počítají, aby počet odbití během směny nebyl lichý a dvojice se nerozpadaly. Časový práh se dohodne s dodavatelem KD.
Síť závodu a fronta outbox
Síť závodu může být nastavena tak, že aplikační server nesmí posílat provoz ven. Odchozí webhooky lze pak řadit do tabulky outbox a příjem probíhá jiným kanálem dohodnutým s klientem. Integrátor tento kanál popíše ve specifikaci spolu s maximálním zpožděním doručení.
Z pohledu integrátora je důležitá idempotence: stejná událost odeslaná dvakrát nesmí vzniknout jako dvě odbití. Jedinečný identifikátor události tento problém řeší.
Bezpečnost účtů při propojování událostí
Systém nikdy nepropojí ani nepřesměruje aktivní účet pouze na základě podobnosti příjmení a účty s kartou zobrazuje v seznamu jako první. Události z KD tak směřují na správný účet podle identifikátoru, nikoli podle příjmení.
S dodavatelem KD je vhodné dohodnout, že identifikátor v události je stálý a nemění se při výměně karty. Pak výměna karet za novou technologii nepřeruší historii odbití.
Testy před spuštěním
Před spuštěním ověřte čtyři případy. První: odbití vstupu a výstupu ve stejné směně vytvoří dvojici. Druhý: opakované odbití v krátkém odstupu se počítá jako jedno. Třetí: odeslání téže události dvakrát se stejným identifikátorem nevytvoří duplikát. Čtvrtý: odbití z čtečky bez místa v systému se hlásí jako chyba konfigurace.
Výsledky testů zapište do protokolu o převzetí integrace. Integrátor a klient pak mají společný důkaz, že webhook funguje podle specifikace, a v případě sporu lze události zrekonstruovat z deníku.
Videomateriál
Často kladené otázky
Jaká data má obsahovat událost z KD?
Čas události z čtečky, směr vstup nebo výstup, identifikátor události, identifikátor karty nebo účtu a identifikátor čtečky.
K čemu slouží jedinečný identifikátor události?
Umožňuje opakovat odeslání bez rizika vzniku dvou odbití. Příjemce odstraňuje opakování podle tohoto identifikátoru.
Co když server nemůže komunikovat s vnější sítí?
Webhooky lze řadit do tabulky outbox a příjem probíhá jiným kanálem dohodnutým s klientem.
Specifikace webhooku pro vašeho integrátora
Připravíme s vámi popis polí, párování a řazení událostí z KD. Domluvte si schůzku s týmem InnerWeb.
Pojďme si promluvit