InnerWeb
Přejít na obsah

Dotazy k integraci KD s BHP: FAQ pro integrátora

Integrátor systému kontroly přístupu klade před prvním voláním webhooku stále stejné otázky: jak se ověřit, jaká pole jsou povinná a co se stane, když karta není známá. Odpovědi jsme seřadili v pořadí, v jakém se objevují při spuštění. InnerWeb čtečky nedodává, takže veškerá práce na straně KD spočívá v jediném HTTP POST požadavku při každém čipnutí.

JWT
ověřený webhook, token se obnovuje automaticky
Zdroj: interní karta
real-time
odesílání událostí z KD průběžně
Zdroj: interní karta
2 000+
čipnutí za pracovní den v závodech s více agenturami
Zdroj: interní karta

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

Pole hlášení čipnutí kartySloupcový graf: 2 povinná pole a 5 volitelných v hlášení čipnutí karty012345počet políPovinná (jméno a příjmení,firma)Povinná (jméno a příjmení, firma): 2 počet polí2Volitelná (zkratka, karta,telefon, e-mail, jazyk)Volitelná (zkratka, karta, telefon, e-mail, jazyk): 5 počet polí5
Zdroj: Interní karta: webhook č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