Návod k nastavení API pro eDoklady

1 - Účel dokumentu

Účelem dokumentu je poskytnout návod pro konfiguraci na straně API eDokladů.

Instituce, pro které není dostatečně vyhovující funkcionalita existujícího webového rozhraní eDokladů pro správu přepážkových pracovišť a webové čtečky, mohou přistoupit k úpravě a propojení (integraci) vlastního informačního systému či aplikace s eDoklady, pomocí do Internetu publikovaného API, dále jen „Integrační API“.

Instrukce k vlastnímu API a integraci vlastní aplikace naleznete v dokumentu „Integrační manuál na webové aplikace eDoklady“, ke stažení na https://edoklady.gov.cz/docs/technicka-specifikace.zip .

Tento návod je určen především pro správce, kteří budou vlastní informační systém či aplikaci integrovat na API eDokladů a následně provozovat. Návod proto zahrnuje jak počáteční nastavení, tak např. obnovu certifikátů před jejich expirací.

2 - Návod k nastavení API pro eDoklady

2.1 - Požadavky na certifikát

Přístup na Integrační API je zabezpečen šifrováním pomocí certifikátu, který je potřeba si pro účely popisované integrace pořídit (zakoupit).

V souvislosti s certifikátem je třeba zajistit/zajišťovat:

• nahrání veřejné část certifikátu (certifikát ve formátu** PEM** bez privátního klíče) pro účely konfigurace API na straně eDokladů,

• certifikát s privátním klíčem ve vlastní aplikaci či informačním systému při volání Integračního API eDokladů.

• včasnou obnovu certifikátu.

Souhrn nezbytných prerekvizit:

• Přístup do webového rozhraní „Správa ověřovatelů“ eDokladů v roli správce, prostřednictvím účtu v JIP/KAAS s přidělenou rolí správce eDokladů, nebo účtu pro datovou schránku či pomocí lokálního účtu s právy Správce organizace. Příručky a technická specifikace systému JIP/KAAS se nachází na stránce https://www.czechpoint.cz/public/vyvojari/ke-stazeni/ (tento způsob přihlašování je určen primárně pro orgány veřejné moci).

• Přístup do webového rozhraní „Správa ověřovatelů“ eDokladů prostřednictvím testovací datové schránky právnické osoby. Příručka a technická specifikace ke zřízení testovací datové schránky se nachází na stránce https://info.mojedatovaschranka.cz/info/cs/95.html) (tento způsob přihlašování je primárně určen pro právnické osoby a další soukromoprávní subjekty).

• Platný komerční serverový certifikát (viz dále).

Požadavky na certifikát

Je potřeba použít komerční serverový certifikát, který splňuje technické požadavky pro TLS1.2 a vyšší. Tento dále musí být vydán některou z následujících certifikačních autorit:

• 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.

U každého poskytovatele se žádá o certifikát jiným způsobem, proto zde postup získání certifikátu blíže nepopisujeme.

2.2 - Postup uložení certifikátu s veř. klíčem do API eDokladů

Jakmile máte certifikát k dispozici, je potřeba jej nejprve nahrát do konfigurace API na straně eDokladů. Pro nahrání veřejné části certifikátu (tj. bez privátního klíče), musí mít soubor s veřejnou částí certifikátu příponu PEM, CRT či CER. Pokud máte certifikát obsahující privátní klíč nebo soubor s veřejnou částí certifikátu v jiném formátu, je potřeba provést jeho export, případně konverzi, tak aby splňoval výše uvedené.

V případě potřeby provést export či konverzi certifikátu, lze k tomuto účelu použít např. utilitu OPENSSL, CertMgr ve Windows, či jiný vhodný nástroj.

Následně je potřeba takto připravený certifikát nahrát do Správy ověřovatelů eDokladů: https://sprava.edoklady.gov.cz dále popsaným postupem:

Přihlaste se zvoleným způsobem:

Po přihlášení je na úvodní stránce vidět seznam ověřovatelů (pokud již byl nadefinován) a menu v pravém horním rohu:

V menu si zvolte položku Nastavení:

V následujícím okně se ujistěte, že přepínače jsou v pozici zapnuto – jinak API nebude ve vaší organizaci fungovat. Pro nahrání certifikátu zvolte Správa certifikátů:

Tím se dostanete do seznamu certifikátů vaší organizace. Je možné nahrát nový certifikát, zkontrolovat informace o stávajících certifikátech, nebo je smazat.

Po kliknutí na Nahrát certifikát se zobrazí okno s prohlížečem souborů s omezením na certifikáty, zvolte ten váš.

Ten se po nahrání zobrazí ve výčtu dole:

Certifikátů lze nahrát více, aby bylo možné zajistit bezvýpadkový překryv platnosti (tzn. v jeden okamžik může být přítomen jak certifikát s končící platností, tak certifikát před platností).

Kliknutím na tlačítko domů, se uživatel vrátí na domovskou obrazovku.

2.3 - Kontrola – provolání API po nahrání certifikátu

Pro ověření dostupnosti API a správné funkce vloženého certifikátu doporučujeme kontrolní „provolání“ API, pomocí některého z nástrojů, jako je utilita CURL, Postman, SoapUI, apod.

Pokud se provolání nezdaří, může být na vině jak chybný certifikát, tak potenciální blokace ve vaší síti (nastavení na firewallu, komunikace přes webovou proxy apod.). Kontrolu je vhodné provést ze síťového segmentu, ve kterém bude umístěna integrovaná aplikace nebo informační systém. Pro izolaci problému typu „síť“ lze kontrolní provolání provést z PC s přímým přístupem do Internetu – v takovém případě bude příčinou problému již pouze certifikát.

Ukázka možného nastavení a provolání pomocí nástroje CURL či Postman je k dispozici v Příkladech.

3 - Příklady:

3.1 - Ilustrativní příklad exportu / konverze certifikátu pomocí OPENSSL

Na následujícím řádku je pro inspiraci ukázka, jak pomocí utility OPENSSL provést export z certifikátu, jehož součástí je privátní klíč a je ve formátu PKCS#12:

(OpenSSL verze 3.2.0)

Výsledný soubor musí začínat textem: -----BEGIN CERTIFICATE-----

A končit: -----END CERTIFICATE-----

Podrobnější dokumentaci k OPENSSL lze nalézt na odkaze: https://www.openssl.org/docs/

3.2 - Příklady kontrolního provolání API pomocí CURL

Ukázka použití utility CURL:

curl --cert-type P12 --cert soubor.pfx:<heslo> --request POST https://capi-edu.edoklady.gov.cz/integration/presentation/server/requestPresentation

Poznámky:

• Příklad je spouštěn na operačním systému Linux

• Verze CURL je 7.58.0

3.3 - Příklady kontrolního provolání API pomocí Postman

Postman je možno otevřít přímo v prohlížeči (adresa https://web.postman.co/, ale v této podobě nedovolí vložení certifikátů. Proto doporučujeme stažení a instalaci desktopové verze, které se na webu nabízí:

Při instalaci program požaduje povolení pro firewall, což ale pro náš účel není třeba.

V desktopové verzi Postman můžete nahrát yml:

Vyberte Workspaces > My Workspace:

Zvolte Import:

Vyberte yml souboru k vložení:

Načte se obsah yml. Vyberte položku, která se vytvořila importem – zde je nazvána „Integrační API eDoklady“. Překlikněte do „Variables“. Do „baseUrl“ napište správnou adresu do obou označených kolonek, dle prostředí. Vždy je třeba kliknout na „Save“ (uložit změny).

Postman má nyní nahrané metody k volání.

Zbývá nahrát certifikát:

V Postmanovi klikněte na ozubené kolečko a vyberte „Settings“:

Otevře se okno, kde je třeba vybrat „Certificates“.

V „Certificates“ klikněte na „Add Certificate“… (na našem příkladu už byl dříve nějaký certifikát nahrán – ve vašem případě bude napoprvé přehled certifikátů samozřejmě prázdný):

Do „Host“ opět zadejte správnou adresu dle prostředí. Certifikát (se soukromým klíčem) bude nejspíše PFX – tzn. klikněte na „Select File“ u „PFX file“ a vložte certifikát. Soubory obsahující certifikát včetně soukromého klíče jsou chráněny heslem – zadejte jej tedy do „Passphrase“. Tlačítkem „Add“ certifikát vložte. Certifikát se objeví v části „Certificates“.