Architektura, kybernetická bezpečnost a integrace
Shrnutí tématu pro vaši roli — argumenty, omezení a další krok.
Centrum znalostí
API elektronické vrátnice: co má umět a na co se ptát
API elektronické vrátnice má umět tři základní operace: přijmout nahlášení vjezdu vozidla z externího zařízení, odpovědět na dotaz na povolení vjezdu podle registrační značky (dále SPZ) a řídit průjezd — otevřít, nebo neotevřít. K tomu má být zabezpečené API klíčem i tokenem (JWT) a dokumentované tak, aby se na řídicí systém dala napojit i brána, závora nebo kiosek, které v areálu už stojí. Tenhle článek je psaný pro vývojáře a integrátory: shrnuje, co deklaruje strojové rozhraní systému SECAPRO, a hlavně dává checklist otázek, které položit jakémukoli dodavateli vrátnice dřív, než se integrace slíbí do projektu.
Proč se na API ptát dřív než na kamery a závory
Málokterý areál se automatizuje na zelené louce. Typický výchozí stav: u vjezdu stojí závora s vlastním pohonem, na turniketech běží přístupový systém s tisíci vydaných karet a část odbavení drží pohromadě telefon a zvyk. Nová elektronická vrátnice do tohohle prostředí vstupuje — a jestli existující techniku doplní, nebo vynutí její výměnu, rozhoduje právě strojové rozhraní.
Systém bez použitelného API je uzavřená krabice: každé propojení znamená čekat na výrobce a každý další požadavek znamená čekat znovu. Systém s dokumentovaným API je otevřená strana mostu, na kterou umí navázat integrátor i interní vývojář. Rozdíl se neprojeví v den instalace — projeví se ve chvíli, kdy provoz poprvé potřebuje něco, co v původním zadání nebylo. Proto patří otázka na API do výběru dodavatele stejně samozřejmě jako otázka na kamery a závory, a proto ji web SECAPRO řadí mezi hlavní témata stránky integrace na podnikové systémy.
Co má API deklarovat: tři operace na bráně
Rozhraní systému SECAPRO je typu M2M (machine-to-machine): komunikují spolu stroje, bez obrazovky a bez člověka u klávesnice. Pro zařízení na bráně deklaruje tři operace:
- Nahlášení vjezdu. Externí brána, kiosek nebo závora oznámí řídicímu systému, že přijelo vozidlo. Průjezd tak vznikne v jedné společné evidenci, i když ho fyzicky odbavilo cizí zařízení.
- Dotaz na povolení podle SPZ. Zařízení se zeptá, jestli vozidlo s danou registrační značkou smí do areálu. Rozhodnutí zůstává v evidenci řídicího systému — externí zařízení dostane odpověď na konkrétní dotaz, ne přístup k datům.
- Řízení průjezdu. Rozhraní umí průjezd i řídit, takže se cizí závora dá zapojit do stejné rozhodovací logiky jako závory dodané se systémem.
Nad rámec samotné brány deklaruje rozhraní také ohlášení vozidla a dotaz na plán — tedy operace, kterými se s vrátnicí domlouvá plánování dopravy. S cizím přístupovým systémem si systém přes rozhraní obousměrně vymění identity, karty a oprávnění. A kde to dává smysl, předá se i stav seznámení s BOZP, aby se člověk bez platného seznámení k bráně vůbec nedostal; jak se platnost seznámení eviduje a dokládá, popisuje stránka Modulu Seznámení BOZP.
Schválně tu nevyjmenováváme konkrétní endpointy, formáty zpráv ani strukturu polí. Nejsou tajné — dokumentaci rozhraní poskytujeme k projektu — ale rozsah rozhraní roste s každou realizovanou integrací a výčet volání v článku by zastaral dřív, než by komu pomohl. Pro rozhodování o dodavateli je podstatné, jaké typy operací rozhraní deklaruje a jak je zabezpečené, ne přesné názvy polí.
Zabezpečení: klíč, token a žádný přímý přístup do databáze
Strojová rozhraní systému jsou zabezpečená API klíčem i tokenem (JWT). Důležitější než výčet mechanismů je ale princip, který za tím stojí: API je jediná definovaná cesta, kterou se externí zařízení nebo systém k vrátnici dostane. Databáze řídicí platformy PSA (průjezdový systém areálu) běží lokálně, není vystavená ven a žádná komponenta není přímo dostupná z veřejného internetu. Integrující strana tedy nikdy nedostává přístup do databáze — vždy jen k definovaným operacím rozhraní.
Popis síťové architektury, segmentace a přehled portů sem záměrně nepatří — je na stránce řídicí platformy PSA a pro schválení integrace u vašeho IT je to obvykle první podklad, který bude potřeba. Širší bezpečnostní otázky na celý systém — kde běží, kudy vede servisní přístup, co obsahuje auditní stopa — pokrývá článek co znamená NIS2 pro technologie na bráně. Tady zůstáváme u jediné z nich: u strojového rozhraní.
Cizí brány a závory: doplnit, ne vyměnit
Praktický důsledek deklarovaných operací: systém se umí napojit na brány, závory a kiosky, které už na místě jsou — kvůli nové vrátnici se nemusí měnit celá infrastruktura vjezdu. Stejně se přistupuje k cizímu přístupovému systému: přes rozhraní se obousměrně vymění identity, karty a oprávnění, systém se nenahrazuje, doplňuje se. Jak vypadá celá sestava — závory, kamery pro rozpoznávání registračních značek (LPR — License Plate Recognition), kiosky, LED navádění — popisuje stránka elektronické vrátnice.
Má to jednu podmínku a je fér ji říct dopředu: otevřené API je jedna strana mostu, druhou musí mít i protějšek. Napojení cizí závory nebo cizího přístupového systému předpokládá, že jejich řízení je přístupné a dokumentované. Platí proto stejná metodika jako u podnikových systémů — nejdřív ověřit rozhraní druhé strany, potom slíbit. Jak tahle metodika vypadá krok za krokem, včetně role odpovědné osoby a vedení vývoje rozhraní jako samostatné položky rozpočtu, popisuje článek jak propojit vrátnici s ERP; pro brány a závory platí beze zbytku.
Checklist: šest otázek na každého dodavatele vrátnice
Odpovědi na následující otázky oddělí otevřený systém od uzavřené krabice. Ptejte se jimi každého dodavatele — včetně SECAPRO.
- Má systém dokumentované API? Písemná dokumentace operací, ne ústní „integrace umíme“. Ptejte se i na to, kdy a jak se k dokumentaci dostanete — jestli až po podpisu smlouvy, nebo už ve fázi nabídky, aby ji vaši vývojáři mohli posoudit.
- Jak je API zabezpečené? Čím se protistrana autentizuje (API klíč, token) a kudy požadavky tečou. Odpověď „otevřeme vám port do systému“ nebo přímý přístup do databáze je varovný signál — rozhraní má nabízet definované operace, ne díru do evidence.
- Co umí API číst a co řídit? To jsou dvě různé úrovně. Čtení znamená dotazy a záznamy — povolení podle SPZ, ohlášení vjezdu, dotaz na plán. Řízení znamená akci — otevření průjezdu. Chtějte vědět, které operace jsou externím zařízením k dispozici a jak se jim přidělují oprávnění.
- Jak se rozhraní verzuje? Integrace se píše jednou, ale žije roky. Jak se dozvíte o změnách rozhraní, zůstane dosavadní integrace po aktualizaci systému funkční a kdo ji po aktualizaci otestuje? Dodavatel, který tuhle otázku slyší poprvé, s dlouhým životem integrací nepočítá.
- Je vývoj rozhraní samostatná položka rozpočtu? Integrace skrytá „v ceně licence“ znamená, že nevíte, co stojí, a nemůžete ji odložit do druhé etapy. Položkový rozpočet je i test poctivosti nabídky.
- Chce dodavatel před slibem vidět rozhraní protistrany? Dodavatel, který slibuje napojení na vaši závoru nebo docházku bez toho, aby viděl dokumentaci druhé strany, slibuje něco, co ještě nemohl ověřit. Zpoždění, které z toho vznikne, půjde za vámi, ne za ním.
Jak na tenhle checklist odpovídá SECAPRO: dokumentace rozhraní se poskytuje k projektu, zabezpečení je API klíčem i tokenem (JWT), deklarované operace jsou popsané výše, vývoj rozhraní se vede jako samostatná položka rozpočtu a bez dokumentace protistrany se integrace neslibuje. Rozsah rozhraní roste s každou realizovanou integrací.
Kdy to nedává smysl
- Když není co spojovat. Jediná brána, celá sestava od jednoho výrobce, žádné stávající závory ani podnikový systém, který by měl s vrátnicí mluvit — pak se integrace neplatí předem „pro jistotu“. Dokumentované API má smysl jako pojistka do budoucna, ne jako položka v první etapě.
- Když protistrana žádné použitelné rozhraní nemá. Most má dvě strany. Když druhá chybí, je poctivé to říct a navrhnout jinou cestu — u datových výměn typicky pravidelný import souboru, jak ho popisuje článek o propojení s ERP. Slib „nějak to propojíme“ bez ověření je nejčastější zdroj zpoždění projektů.
- Když za druhou stranu nikdo neodpovídá. Bez osoby, která rozhraní protistrany zpřístupní a bude u testů, se integrace nedá seriózně termínovat — ani když je dokumentace na světě.
- Když má API nahradit rozmyšlený proces. Rozhraní přenese dotaz a otevře průjezd, ale nerozhodne za vás, kdo smí do areálu, v jakém čase a za jakých podmínek. Bez vyjasněných pravidel vjezdu není co volat — návrh procesu je předpoklad integrace, ne její výstup.
Časté dotazy
Máte veřejné API pro naše vývojáře?
Systém má M2M rozhraní — nahlášení vozidla, dotaz na plán, povolení vjezdu — zabezpečené API klíčem. Dokumentaci poskytujeme k projektu, není volně ke stažení; rozsah rozhraní roste s každou realizovanou integrací.
Můžou si integraci napsat naši vlastní vývojáři?
Ano, přesně k tomu dokumentace k projektu slouží. Na vaší straně je potřeba osoba odpovědná za integrovaný systém; na naší straně platí, že rozhraní stavíme podle systému zákazníka, ne obráceně.
Umíte se napojit na závory, které už v areálu máme?
Ano — externí brána, kiosek nebo závora může přes rozhraní nahlásit vjezd, dotázat se na povolení podle SPZ nebo řídit průjezd, takže se stávající technika nemusí kvůli nové vrátnici měnit. Konkrétní pohon a jeho řízení se ověřuje před příslibem, ne při realizaci.
Nahradí vaše rozhraní náš přístupový systém?
Ne. S cizím přístupovým systémem si přes rozhraní obousměrně vyměníme identity, karty a oprávnění — systém nenahrazujeme, doplňujeme ho. Vaše vydané karty a nastavená oprávnění zůstávají.
Je API dostupné z internetu?
Žádná komponenta platformy PSA není přímo dostupná z veřejného internetu; databáze běží lokálně a není vystavená ven. Jak přesně je síť segmentovaná a jaké porty systém používá, uvádí stránka platformy PSA — to je podklad pro vaše IT.
Co se s naší integrací stane, když systém aktualizujete?
Přesně tohle je otázka č. 4 checklistu a platí i pro nás: pravidla ohlašování změn rozhraní si vyžádejte k projektu spolu s dokumentací. Obecně platí, že rozhraní se s integracemi rozšiřuje — a integrace, které na něm běží, jsou důvod, proč se změny nedělají mlčky.
Pokud chystáte napojení vlastního zařízení nebo systému, domluvte si komentovanou ukázku — projdeme rozhraní nad vaším konkrétním scénářem.