FAQ k API pro vývojáře

Správce

Nastavení

Odpovědi na nejčastější dotazy vývojářů, týkající se API eDokladů a souvisejících témat.

Obecné dotazy

1. Kde lze najít bližší technický popis jednotlivých variant integrace?

Technická specifikace API rozhraní je k dispozici na tomto odkazu: Technická specifikace. Součástí specifikací je rovněž i popis varianty „Export do schránky“ spočívající ve vygenerování JSON formátu dat.

2. Kam lze zasílat případné dotazy týkající se integrace přes API?

Technické dotazy lze zasílat na adresu edoklady@nakit.cz. Dotazy věcného charakteru na emailovou adresu edoklady@dia.gov.cz. Před zasláním dotazu prosíme o prostudování technické specifikace API a těchto FAQ.

3. Kde je dostupné EDU prostředí pro testování integrace přes API?

Pro účely otestování integrace je k dispozici veřejně dostupné EDU prostředí:

Webová ověřovací aplikace: ctecka-edu.edoklady.gov.cz
Správa ověřovatelů: sprava-edu.edoklady.gov.cz
Integrační rozhraní pro API: capi-edu.edoklady.gov.cz

Certifikáty pro účely komunikace přes API

1. Kde je možné zaevidovat certifikáty které bude ověřující subjekt používat pro komunikaci přes API?

Správa certifikátů pro komunikaci přes API je k dispozici ve Správě ověřovatelů.

2. Jaké certifikáty lze použít pro komunikaci přes API?

Pro účely komunikace s API bude nutné využívat komerční serverové certifikáty vydané následujícími kvalifikovanými poskytovateli služeb vytvářejících důvěru v ČR:

První certifikační autorita a. s.
Česká pošta s. p.
eIdentity a. s.
Správa základních registrů (vydávání nových certifikátů bylo ukončeno nicméně existující komerční serverové certifikáty je případné možné použít)
Správa státních služeb vytvářejících důvěru

Technické požadavky na certifikát – použitelnost pro protokol TLS 1.2 a vyšší. Z pohledu bezpečnosti doporučujeme aby certifikát zaregistrovaný pro účely komunikace s API se používal jen k těmto účelům (tj. aby se stejný certifikát pro autentizaci nepoužíval vůči více systémům).

Pro účely komunikace s API v rámci EDU prostředí je možné využívat stejné typy komerčních serverových certifikátů jako pro produkční prostředí a navíc je pro EDU prostředí možné využívat testovací komerční serverové certifikáty od První certifikační autority a.s. a České pošty s.p. (provozovatel certifikační autority PostSignum).

3. Je vyžadováno pro komunikaci přes API také nějaké uživatelské jméno a heslo?

Pro nastavení certifikátu se musí Správce organizace přihlásit přes účet v JIP/KAAS přes datové schránky nebo pomocí lokálního účtu s rolí Správce organizace do Správy ověřovatelů a tam certifikát nastavit. Samotná komunikace přes integrační API probíhá pomocí certifikátu (nevyžaduje se žádné jméno a heslo pro samotnou komunikaci přes API).

4. Jak bude probíhat autentizace ověřujícího subjektu v případě integrace pomocí webových služeb?

Komunikace s API bude zabezpečena pomocí komerčního serverového certifikátu který si organizace bude moci nastavit v aplikaci Správa ověřovatelů. Popis jednotlivých scénářů komunikace přes API je k dispozici na Technická specifikace.

Lokální účty

1. Bude možné využívat lokální účty i když ověřující subjekt nebude využívat integraci přes API?

Ano ověřující subjekt může nastavit a využívat lokální účty pro přístup svých uživatelů do aplikací eDoklady (registrace mobilní aplikace ověřovatele přístup do webové ověřovací aplikace a přístup do Správy ověřovatelů).

2. Mohou mít lokální účty různá oprávnění?

Ano uživatel s lokálním účtem může mít roli Ověřovatel nebo Správce organizace a v budoucnu také Správce skupiny. Role Správce organizace je privilegovaná role a tak by měla být přidělena pouze omezenému počtu uživatelů.

3. Je možné pozvánky uživatelům pro nastavení lokálního účtu zakládat také manuálně a ne jen přes API?

Pozvánky pro uživatele je možné manuálně zakládat také ve Správě ověřovatelů. Toto právo mají uživatelé s rolí Správce organizace. Pozvánky je možné také nastavit pomocí API (blíže viz Technické specifikace API rozhraní).

4. Jaké údaje jsou potřeba pro založení pozvánky uživatele pro zřízení lokálního účtu?

Jméno příjmení a emailová adresa uživatele na kterou přijde pozvánka pro nastavení lokálního účtu (uživatel si musí nastavit uživatelské heslo). Pro každý lokální účet je nutné také při tvorbě pozvánky nastavit uživatelská oprávnění (Ověřovatel/Správce organizace).

5. Kdy bude implementovaná víceúrovňová správa přepážek ve webové aplikaci? Je možné předřadit individuální sady údajů pro organizaci? Případně zobrazit pouze individuální sady organizace?

Správa skupin v rámci modulu lokálního IdP bude implementována po 1.7.2024. V rámci Správy skupiny bude možné rovněž spravovat ověřovací sady konkrétním skupinám.

6. Jsou lokální účty navázány pouze na konkrétní ověřující subjekt?

Ano lokální účty jsou navázány na konkrétní ověřující subjekt.

Dotazy k variantě Export do schránky

1. V technické specifikaci API je popsán export do schránky v JSON nebo se jedná CBOR?

Součástí JSON souboru je také CBOR. V případě integrace přes API je struktura vrácených údajů popsána v příloze integrační-api.yml operace getBrowserFlowTransactionResult (pro Integrační API Browser flow) případně operace getServerFlowTransactionResult (pro Integrační API Server flow).

Dotazy k variantě Integrační API Browser flow

1. Jaký je způsob přihlášení uživatele na konkrétní přepážku?

Přihlášení bude odvislé od toho jaká varianta integračního API by byla využita ze strany ověřujícího subjektu. V případě varianty Integrační API Browser flow by se ověřovatelé přihlašovali do Webové ověřovací aplikace buď prostřednictvím JIP/KAAS nebo prostřednictvím přihlašovacích údajů do datové schránky nebo pomocí lokálních účtů. V případě varianty Integrační API Server flow nedochází k přihlášení do Webové ověřovací aplikace a přihlášení k přepážce Webové ověřovací aplikace.

Dotazy k variantě Integrační API Server flow

1. V rámci požadavku na vytvoření údajů pro QR kód virtuální přepážky (operace /virtualServiceCounters/{id}/generateQrCode) vrací se QR kód nebo údaje ze kterých je QR kód potřeba vytvořit na straně napojeného systému ověřujícího subjektu?

Operace /virtualServiceCounters/{id}/generateQrCode nevrací QR kód ve formátu obrázku nebo PDF dokumentu. Tato operace vrací pouze data (URL) ze kterých se musí vytvořit QR kód na straně napojeného systému ověřujícího subjektu. Tj. QR kód musí obsahovat URL získanou z výše uvedené operace.

2. Pracuje se ve variantě Integrační API Server flow s ověřovacími sadami?

Při integraci s využitím varianty Integrační API Server flow se nepracuje se sadami údajů. Tyto šablony jsou dostupné v grafickém rozhraní Webové ověřovací aplikace. Při použití integrační varianty API Server flow se u operace POST /presentation/server/requestPresentation očekává pouze seznam konkrétních údajů.

3. Jak by měl ověřující subjekt pracovat s virtuálními přepážkami?

Každá organizace si může definovat vlastní systém práce s virtuálními přepážkami. Ze strany backendu ekosystému eDokladů je pro ověření přes integrační variantu API Server flow pouze potřeba aby virtuální přepážka existovala a měla platný QR kód při procesu ověření údajů (respektive URL zakódovanou v QR kódu). Ověřující subjekt si může například založit pro každou svoji fyzickou přepážku jednu virtuální přepážku a pojmenovat si ji podle té fyzické.

4. Jaká je platnost URL virtuální přepážky?

Současná platnost vygenerované URL virtuální přepážky pro QR kód je 30 dní.

5. Jaký je rozdíl mezi virtualServiceCounter a serviceCounter?

VirtualServiceCounter jsou přepážky pro použití v rámci integrační varianty API Server flow. Tyto přepážky se nezobrazují ve webovém rozhraní Webové ověřovací aplikace a nejde s nimi v rámci této aplikace napřímo pracovat. Navíc tyto virtuální přepážky nemusí být vázány na fyzické přepážky ale mohou být třeba navázány na konkrétní uživatele (organizace virtuálních přepážek závisí na ověřujícím subjektu).

ServiceCounter jsou přepážky které jsou dostupné pro použití ve webovém rozhraní Webové ověřovací aplikace. Tyto přepážky lze tudíž použít i při integraci pomocí varianty Integrační API Browser flow protože tato varianta používá webové rozhraní Webové ověřovací aplikace.

6. Řeší se v rámci varianty Integrační API Server flow přihlašování uživatelů do Webové ověřovací aplikace?

Ne v rámci varianty Integrační API Server flow nedochází k přihlašování uživatelů (ověřovatelů) do Webové ověřovací aplikace. Autentizaci uživatelů do napojeného systému si musí řešit ověřující subjekt na úrovni svého napojeného systému který využívá integraci přes API Server flow.

7. Může virtuální přepážka v jeden čas obsluhovat více požadavků na ověření eDokladů?

Ne každá virtuální přepážka může mít v jeden okamžik pouze jednu zahájenou transakci ověření.

8. Co když bude ověřovatel opakovat požadavek na ověření ještě před dokončením předchozího požadavku v rámci virtuální přepážky? Pokud je na virtuální přepážce požadavek na ověření a nevyužije se kdy expiruje?

Při zahájení nového požadavku na ověření u virtuální přepážky se předchozí požadavky zneplatní. Požadavek na ověření není možné smazat nicméně je nastaven time-out požadavku na 5 minut.

9. Je možné vytvořit skrze API virtuální přepážku pro uživatele z JIP/KAAS?

Ano je to možné. Požadavek na vytvoření virtuálních přepážek vychází z informačního systému ověřujícího subjektu vytvoření přepážky není závislé na tom jakým konkrétním způsobem se ověřovatel identifikuje a autentizuje do informačního systému ověřujícího subjektu („napojený systém“). Nicméně platí že ověřující subjekt musí zajistit spolehlivou identifikaci a autentizaci uživatelů do jeho informačního systému. Vazbu mezi virtuální přepážkou a uživatelem si musí zajistit informační systém ověřujícího subjektu.