InnerWeb
Přejít na obsah

FAQ: API osoby pro portál, tedy školení a propustka

API osoby umožňuje portálu načíst ze závodu seznam školení dané osoby se stavem, osobní odkaz na školení a propustku. Vše funguje za strojovým tokenem a smazaný účet v systému vrací odpověď 404. Níže odpovídáme na otázky integrátorů a vedoucích IT, kteří plánují napojit portál dodavatelů nebo zaměstnanců na závod.

4
stavy školení v odpovědi API
Zdroj: karta funkcji
30 dnů
okno stavu vypršujícího školení
Zdroj: karta funkcji
7 dnů
období počítání chyb v panelu
Zdroj: karta funkcji

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

Kódy odpovědí u žádostí o přístupGraf ukazuje čtyři kódy odpovědí API žádostí: 201, 200, 400 a 401.0100200300400500kód HTTPNová žádost: 201 kód HTTP201Nová žádostOpakování: 200 kód HTTP200OpakováníChybná data: 400 kód HTTP400Chybná dataChybný token: 401 kód HTTP401Chybný token
Zdroj: Karta funkce integrace s portálem

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