Co API osoby vrací
API osoby pro portál vrací tři druhy informací: seznam školení se stavem, osobní odkaz na školení a propustku. Každá z nich se týká jedné osoby identifikované v závodě, takže portál nemusí uchovávat vlastní kopii stavu oprávnění.
Takové řešení jasně rozděluje odpovědnost: zdrojem pravdy o školeních a propustce je systém závodu, portál je pouze jejich zobrazením. Změna stavu v závodě je v portálu vidět při dalším dotazu.
Jaké stavy školení se vracejí?
Čtyři: todo, done, expiring a expired. Stav todo znamená školení k absolvování, done školení absolvováno, expiring absolvováno, ale vyprší do 30 dnů, a expired školení, jehož platnost uplynula.
Stav expiring umožňuje portálu zobrazit varování s předstihem, dříve než osoba ztratí možnost vstupu na areál.
Co je osobní odkaz na školení?
Je to adresa, kterou API vystaví pro konkrétní osobu a konkrétní školení. Portál ji může zobrazit jako tlačítko a osoba školení absolvuje bez ručního přihlašování do samostatného systému.
Jak je API zabezpečené
Všechna volání API osoby vyžadují strojový token. Token je uložen na straně serveru portálu a v panelu závodu se klíče do prohlížeče nedostanou: nastavení integrace jsou pouze pro čtení.
Pro integrátora z toho plyne jednoduché pravidlo: volání API provádí backend portálu, nikdy kód spuštěný v prohlížeči uživatele. Token v kódu stránky by byl prozrazeným tokenem.
Co se stane, když je token chybný?
Volání je odmítnuto. U obdobného API žádostí o přístup vrací chybějící nebo chybný token odpověď 401. Integrátor má s odpovědí 401 zacházet jako s pokynem zkontrolovat nastavení, a ne ji opakovat ve smyčce.
Může token patřit běžnému účtu zaměstnance?
Neměl by. Strojový token je určen pro integraci, má omezený rozsah a jeho použití lze odlišit od činností lidí v deníku výměny. Doporučení pro technický účet popisujeme v samostatném materiálu o oprávněních.
Kódy odpovědí u žádostí o přístup
Chyby a okrajové případy
Účet smazaný v systému vrací odpověď 404. Portál má 404 chápat jako informaci, že osoba v závodě neexistuje, a propojení na své straně odstranit nebo označit jako neaktuální, místo aby zobrazoval staré údaje.
V deníku výměny na straně závodu se ukládají události se směrem, výsledkem a kódem HTTP. Zápis do deníku nikdy nepřeruší obsluhu dotazu. Při diagnostice problému tak integrátor může porovnat vlastní logy s deníkem závodu.
Jak odlišit osobu bez školení od smazané osoby?
Osoba bez školení dostane správnou odpověď s prázdným nebo krátkým seznamem, smazaná osoba dostane 404. Portál tak nezamění absenci dat za absenci účtu.
Co s žádostmi o přístup, které odesílá portál?
Žádost o přístup přichází samostatným voláním POST se strojovým tokenem. Odpověď 201 znamená novou žádost, 200 opakování téhož identifikátoru žádosti, 400 chybná data a 401 chybějící nebo chybný token. Údaje o oprávněních, školeních a lékařských prohlídkách se přijímají jen tehdy, když je pokrývá rozsah souhlasu osoby.
Role správce a operátora
Panel integrace v modulu oprávnění zobrazuje stav spojení, počet aktivních propustek, propojených účtů, žádostí čekajících na vyřízení a chyb za posledních 7 dnů, a také deník výměny. Panel vidí správce a pracovník BOZP.
Schválení, zamítnutí a opakované odeslání rozhodnutí u žádostí o přístup z portálu je dostupné výhradně pro roli správce služby. Toto rozdělení má chránit před situací, kdy osoba s oprávněním k prohlížení mění rozhodnutí o přístupu.
Co s rozhodnutím, které se nepodařilo doručit?
Nedoručené rozhodnutí zůstane v řádku s popisem chyby a lze je z panelu znovu odeslat. Operátor tak nemusí žádat integrátora o ruční obnovení požadavku.
Videomateriál
Často kladené otázky
Musí portál uchovávat kopii školení?
Ne. Zdrojem stavu je závod a portál jej načte při dotazu. Vlastní kopie je potřeba jen pro mezipaměť.
Jak často dotazovat API osoby?
Při vstupu osoby na stránku portálu, a ne ve smyčce na pozadí. Stav expiring má okno 30 dnů, takže obnovení jednou za návštěvu stačí.
Co dělat, když portál dostane 404 pro známou osobu?
Účet byl v závodě smazán. Označte propojení jako neaktuální a osobu odkažte na opakovanou žádost o přístup.
Vrací API data, na něž osoba nedala souhlas?
Údaje o oprávněních, školeních a lékařských prohlídkách se ve žádostech přijímají jen tehdy, když je rozsah souhlasu pokrývá.
Připojte portál k závodu
Na testovacích datech ukážeme dotaz na API osoby a probereme, jak má portál dodavatelů zobrazovat stavy školení. Domluvte si konzultaci s firmou InnerWeb.
Pojďme si promluvit