InnerWeb
Přejít na obsah

Webhook událostí z KD: specifikace integrace pro integrátora

Systém řízení přístupu eviduje každé odbití karty: kdo, kde a kdy. Integrátor, který popisuje webhook pro systém oprávnění, ve specifikaci určí, jaká pole systém KD posílá, jak je kanál ověřen a jak příjemce zachází s opakováním. Níže jsou požadavky na pole, párování, duplicity a řazení do fronty.

5
základních polí události ve specifikaci
Zdroj: karta
4
testovací případy před spuštěním integrace
Zdroj: karta

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

Prvky specifikace integrace KDGraf: 5 polí události a 4 testovací případy ve specifikaci integrace.012345početPole událostiPole události: 5 počet5Testovací případyTestovací případy: 4 počet4
Zdroj: Karta komórki: struktura specifikace a testů

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