tomas-kulhanek/czech-data-box

PHP library for connection to Integrated system of data box (ISDS) in Czech republic

v5.0.0 2024-05-24 12:05 UTC

Requires

• php: >=8.2
• ext-curl: *
• ext-dom: *
• ext-mbstring: *
• ext-openssl: *
• ext-xml: *
• symfony/validator: ^7.0
• tomas-kulhanek/serializer: ^2.0.3

Requires (Dev)

• guzzlehttp/guzzle: ^7.8
• nyholm/psr7: ^1.8
• php-http/httplug: ^2.4
• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^10.5
• rector/rector: ^1.0
• squizlabs/php_codesniffer: ^3.9
• symfony/http-client: 5.4.*|6.*|7.*

Suggests

• ext-curl: for comunication with czech databox servers
• guzzlehttp/guzzle: for usage with guzzle
• symfony/http-client: for usage with symfony

MIT

• Tomáš Kulhánek

• czech
• ISDS
• datovky

Published on Packagist.org on 2024-05-24 12:43 UTC

README

⚠ POZOR!! Pokud implementujete napojení na ISDS, je potřeba aby jste se řídili dle PROVOZNÍHO ŘÁDU⚠

Instalace

Composer

Pro instalaci balíčku je nutné jej instalovat skrze composer.

composer require tomas-kulhanek/czech-data-box

Dále je potřeba využít nějakého klienta. Buď je možné využít Guzzle nebo Symfony Http client

composer require tomas-kulhanek/czech-data-box guzzlehttp/guzzle:^7.0

composer require tomas-kulhanek/czech-data-box symfony/http-client

V případě využívání vlastního http klienta, stačí implementovat rozhraní TomasKulhanek\CzechDataBox\Provider\ClientProviderInterface a předat ho do konstruktoru třídy TomasKulhanek\CzechDataBox\Connector. Samozřejmostí je třeba zajistit správné nastavení hlaviček nebo SSL klientských certifikátů.

Popis

Tato knihovna slouží k základní komunikaci s Informačním systémem datových schránek ISDS nebo ISDS test

Základní použití

Pro každou operaci je potřebné zadat přístupové údaje

<?php
$account = new \TomasKulhanek\CzechDataBox\Account();
$account->setPassword('mojeTajneHeslo')
        ->setLoginName('mujLogin')
        ->setLoginType(\TomasKulhanek\CzechDataBox\Enum\LoginTypeEnum::NAME_PASSWORD)
        ->setProduction(false);

Využití s Symfony HTTP client

Instalace

composer require tomas-kulhanek/czech-data-box symfony/http-client

Instancování

$serializer = \TomasKulhanek\Serializer\SerializerFactory::create();
$guzzleProvider = \TomasKulhanek\CzechDataBox\Provider\SymfonyClientProvider::create();
$connector = new \TomasKulhanek\CzechDataBox\Connector($serializer, $guzzleProvider);

Využití s Guzzle 7

Instalace

composer require tomas-kulhanek/czech-data-box guzzlehttp/guzzle:^7.0

Instancování

$serializer = \TomasKulhanek\Serializer\SerializerFactory::create();
$guzzleProvider = \TomasKulhanek\CzechDataBox\Provider\GuzzleClientProvider::create();
$connector = new \TomasKulhanek\CzechDataBox\Connector($serializer, $guzzleProvider);

Povinnosti aplikace dle Provozního řádu ISDS

Knihovna řeší komunikaci s ISDS, ale některé povinnosti Provozního řádu musí zajistit až vaše aplikace:

• Evidujte již stažené zprávy a stahujte jen nové (kap. II.17 „Dodržování přiměřenosti"). Aplikace nesmí opakovaně stahovat celé seznamy a obsahy zpráv — použijte filtry GetListOfReceivedMessages/GetListOfSentMessages (od–do, stavy) a vlastní evidenci zpracovaných dmID.
• Lokální (desktopové) aplikace se smí přihlašovat pouze na manuální pokyn uživatele. Serverové aplikace se mohou přihlašovat automatizovaně, ale jen v nezbytné frekvenci.
• Počítejte s omezením počtu dotazů. Při překračování denních limitů ISDS nejprve zasílá systémovou zprávu, poté odpovědi zdržuje o 3 sekundy a souběžný požadavek ze stejného účtu odmítá. Nespouštějte paralelní požadavky pod jedním účtem a implementujte přiměřený retry.
• ⚠ Přístupové údaje nesmí opustit zařízení pod plnou kontrolou uživatele. Předání jména a hesla cloudové/webové aplikaci třetí strany je porušením § 9 odst. 2 zákona č. 300/2008 Sb. — Správce může takové údaje zneplatnit. Doporučená autentizace pro externí systémy je systémový certifikát (LoginTypeEnum::SPIS_CERT).
• Doručení přihlášením (§ 17 odst. 3) způsobuje výhradně volání GetListOfReceivedMessages — ostatní operace doručení nezpůsobí.
• Údržba ISDS probíhá zpravidla v pátek 0:00–1:00 (možná krátká nedostupnost); knihovna při HTTP 503 vyhazuje SystemExclusion.
• Zprávy nad 20 MB odesílejte jako velkoobjemové (VoDZ, do 100 MB) přes uploadAttachment() + createBigMessage(); hromadné odeslání u VoDZ není podporováno.
• Změny webových služeb oznamuje DIA zpravidla 2 měsíce předem na stránce pro dodavatele; dodavatelům aplikací se doporučuje registrace do pracovního prostoru.

Pomoc a řešní chyb

V případě že potřebujete poradit, nebo při implementaci Vám třída zobrazuje chybu vytvořte prosím nové Issues. Základní pomoc je poskytována zcela zdarma pomocí Issues.

Odkazy

• Changelog knihovny - CHANGELOG.md
• Produkční ISDS - https://www.datovka.gov.cz
• Testovací ISDS - https://datovka-test.gov.cz
• Provozní řád ISDS - https://datovka.gov.cz/info/cs/80.html
• Změny pro dodavatele aplikací - https://datovka.gov.cz/info/cs/74.html
• Poradna - https://poradnaisds.cz/

Žádosti o zřízení datové schránky

Produkční prostředí

• orgány veřejné moci - odkaz
• ostatní - odkaz

Testovací prostředí

Zřízení testovací schránky v prostředí datovka-test.gov.cz je možné skrze formulář na produkčním portálu www.datovka.gov.cz po přihlášení v nastavení