Co je webhook čipnutí karty a kdo ho volá
Webhook čipnutí karty je místo, kde se propojuje stávající systém KD s InnerWeb. Systém KD posílá do InnerWeb HTTP POST požadavek při každém čipnutí karty na čtečce. Není třeba instalovat nové čtečky, měnit kabeláž ani vyměňovat karty: InnerWeb je výrobcem softwaru a integruje se s KD, které závod již má.
Volajícím je vždy systém KD, nikoli InnerWeb. Dodavatel nebo správce KD nastaví pravidlo odeslání události po čipnutí. Na straně InnerWeb se čipnutí přiřadí osobě, ověří se vůči školení a uloží do historie účtu. Číslo karty z KD se tak stává klíčem k platným školením BHP, kvalifikacím a povolením.
Jak ověřit volání a jak dlouho je token platný
Volání webhooku vyžaduje token JWT. Integrátor ho získá z přihlašovacího endpointu API a připojí ke každému požadavku s čipnutím. Token má omezenou dobu platnosti a integrace ho obnovuje automaticky. Integrátor by měl ve specifikaci popsat způsob obnovy relace, protože na něm závisí plynulé odesílání čipnutí.
Osvědčený postup: technický účet používaný výhradně pro integraci, přihlášení při startu služby, automatické obnovení tokenu s rezervou před vypršením platnosti a opětovné přihlášení po odpovědi odmítající autorizaci. Hesla a tokeny by se neměly dostat do logů služby na straně KD.
Co dělat, když token vyprší během provozu
Čipnutí z období, kdy byl token neplatný, nesmějí být ztracena. Vhodným řešením je fronta na straně KD: neúspěšné volání se uloží do vyrovnávací paměti, služba se znovu přihlásí a události postupně doodešle. Fronta má smysl jen tehdy, když se události odesílají téměř v reálném čase, o čemž píšeme níže.
Pole hlášení čipnutí karty
Jaká pole jsou povinná v hlášení čipnutí
Hlášení nese čas události, místo čipnutí a údaje o osobě. Povinné jsou jméno a příjmení a název firmy. Volitelně se předává zkratka, číslo aktivní karty, telefon, e-mail a jazyk. Čím úplnější sada, tím snazší přiřazení k existujícímu účtu a pozdější oznámení v jazyce dané osoby.
Číslo aktivní karty je identifikátor, podle kterého InnerWeb spáruje čipnutí s účtem osoby. Externí firma se přiřazuje podle názvu firmy uvedeného v hlášení. Pokud se v KD stejná agentura objeví jednou plným názvem a jindy se zkratkou, vzniknou nesrovnalosti, proto by integrátor měl názvy předávat v jednotném zápisu.
- Povinné: jméno a příjmení osoby a název firmy.
- Doporučené: číslo aktivní karty jako klíč pro přiřazení k účtu.
- Volitelné: zkratka, telefon, e-mail, jazyk.
- Vždy: čas události a místo čipnutí.
Co se stane, když karta nebo osoba nejsou známé
Čipnutí karty osobou, kterou systém nezná, založí účet a firmu podle údajů z hlášení. To je pohodlné při velké fluktuaci pracovníků agentur, ale vyžaduje kázeň v datech: chyba v pravopisu příjmení nebo názvu firmy vytvoří duplicitu. Proto otázka „co s neznámou kartou“ se v praxi mění na otázku „kdo odpovídá za kvalitu zdrojových dat v KD“.
Pokud má stejná osoba dva aktivní účty, systém přenese výsledek školení na účet se vstupní kartou, aby brána přestala hlásit chybějící školení. Účty nikdy neslučuje pouze podle příjmení, protože by to vedlo k záměnám mezi osobami se stejným příjmením.
Čas události, směr a duplicity: požadavky specifikace
Specifikace integrace vyžaduje, aby systém KD odesílal události v reálném čase, s časem události načteným z čtečky, bez dávek a nočních odesílání. Díky tomu časy čipnutí v InnerWeb odpovídají skutečnému průchodu bránou a zpoždění na síti nezkreslují evidenci.
Každá událost z KD by měla nést směr (vstup nebo výstup) a identifikátor události a InnerWeb ji přijímá přes ověřený webhook. Pravidla párování vstupů a výstupů a odmítání duplicit se určují ve specifikaci s dodavatelem KD. U závodů s více agenturami může provoz přesáhnout 2 000 čipnutí za pracovní den, proto integrace musí zvládat série událostí a opakované doručení.
Kontrolní seznam
Videomateriál
Často kladené otázky
Je třeba vyměnit čtečky, abych integraci spustil?
Ne. InnerWeb nevyrábí ani nevyměňuje čtečky KD. Integrace spočívá v odeslání události ze stávajícího systému KD do InnerWeb pomocí HTTP POST požadavku.
Jak funguje ověření tokenem?
Token JWT z přihlašovacího endpointu API má omezenou dobu platnosti. Integrace ho obnovuje automaticky, s rezervou před vypršením.
Uloží InnerWeb čas čipnutí z čtečky?
Specifikace integrace počítá s tím, že systém KD posílá události v reálném čase, s časem události z čtečky.
Odkud InnerWeb zná směr vstupu a výstupu?
Směr a identifikátor události posílá systém KD. Pravidla párování vstupů a výstupů a odmítání duplicit se určují ve specifikaci s dodavatelem KD.
Zdroje
Pojďme si promluvit o integraci s vaším KD
Předáme dodavateli KD specifikaci webhooku a projdeme s ním pole, token a odesílání v reálném čase. Domluvte si schůzku s týmem InnerWeb.
Pojďme si promluvit