Download the PHP package tomas-kulhanek/czech-data-box without Composer

Czech Data Box — PHP knihovna pro datové schránky (ISDS)

Klient pro Informační systém datových schránek (ISDS) Digitální a informační agentury (DIA). Odesílá i přijímá datové zprávy, zvládá velkoobjemové datové zprávy (VoDZ) a odpovídá aktuálnímu rozhraní ISDS podle Provozního řádu účinného od 26. 06. 2026 (WSDL 3.11).

• ✅ Odesílání i příjem datových zpráv — createMessage(), getListOfReceivedMessages(), messageDownload()
• ✅ Aktuální rozhraní ISDS — WSDL verze 3.11 z přílohy 2 Provozního řádu účinného od 26. 06. 2026
• ✅ 56 ze 76 operací sedmi WSDL služeb ISDS; matici pokrytí generuje a v CI hlídá skript
• ✅ Velkoobjemové datové zprávy (VoDZ) do 100 MiB včetně uploadu příloh a stahování
• ✅ Guzzle 8 i Symfony HttpClient 7/8 (kompatibilní se Symfony 8), nebo vlastní klient přes rozhraní
• ✅ Produkční i testovací prostředí DIA (datovka.gov.cz / datovka-test.gov.cz) i vlastní doména KIVS
• ✅ PHP 8.4+, typovaná DTO, PHPStan na levelu max
• ✅ XSD validace serializovaných požadavků proti schématům Provozního řádu + integrační testy proti testovacímu ISDS
• ✅ Bezpečnostní hardening — parsování odpovědí bez sítě (LIBXML_NONET), limit velikosti odpovědi, #[\SensitiveParameter] u hesel a klíčů

Obsah

• Instalace
• Rychlý start
• Kompatibilita s ISDS
• Odeslání datové zprávy
• Načtení seznamu přijatých zpráv
• Stažení obsahu zprávy
• Volba HTTP klienta
• Velkoobjemové datové zprávy (VoDZ)
• Správa vlastní schránky
• Pokrytí webových služeb ISDS
• Povinnosti aplikace dle Provozního řádu ISDS
• Přechod z jiné ISDS knihovny

Instalace

Balíček se instaluje přes composer spolu s HTTP klientem — Guzzle nebo Symfony HttpClient:

Knihovna vyžaduje PHP ^8.4 a rozšíření curl, dom, mbstring, openssl a xml. Povyšujete-li z verze 5.x, řiďte se návodem UPGRADE-6.0.md; přecházíte-li z jiné ISDS knihovny, viz Přechod z jiné ISDS knihovny.

Podrobnosti k oběma klientům jsou v sekci Volba HTTP klienta. 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ů. Poslední parametr sendRequest() nese maximální velikost odpovědi v bajtech (null = výchozí limit implementace); uplatněte ho ještě před načtením celého těla do paměti — hotové počítadlo i kontrolu hlavičky Content-Length nabízí TomasKulhanek\CzechDataBox\Provider\ResponseSizeLimit.

Volitelná validace požadavků

Request DTO nesou atributy #[Assert\*] ze symfony/validator, ale knihovna sama validátor nespouští — jsou to metadata pro vaši aplikaci. Pokud chcete požadavky validovat před odesláním, doinstalujte si validátor a zavolejte ho sami:

Knihovna si sama hlídá jen kontroly, které vyplývají z Provozního řádu (limity velikosti a počtu příloh, povolené formáty, povinná pověření). Regresní shodu serializovaných požadavků se schématy Provozního řádu hlídá XSD validace v testech.

Rychlý start

Knihovna nemá stavové přihlášení — přístupové údaje nese TomasKulhanek\CzechDataBox\Account a předávají se do každé operace. Connector je jediný vstupní bod ke všem operacím ISDS:

[!IMPORTANT] Napojení na ISDS se řídí Provozním řádem ISDS. Část povinností (evidence stažených zpráv, frekvence dotazů, nakládání s přístupovými údaji) musí zajistit vaše aplikace — viz Povinnosti aplikace dle Provozního řádu ISDS.

Kompatibilita s ISDS

Řada 6.x je sjednocená s Provozním řádem ISDS účinným od 26. 06. 2026 a s jeho přílohou 2, tedy WSDL verze 3.11. Rozsah pokrytých operací najdete v matici pokrytí, kterou generuje skript z WSDL v tests/_data/wsdl/ a kontroluje CI.

Prostředí (produkce/test) určuje EndpointProvider předaný HTTP providerovi — výchozí je produkce:

Původní domény mojedatovaschranka.cz a czebox.cz zůstávají podle DIA funkční minimálně do

31. 12. 2027, knihovna je ale od verze 6.0 už nepoužívá.

[!WARNING] Vlastní doména musí pocházet z důvěryhodné konfigurace, nikdy z uživatelského vstupu. Na výslednou URL se posílají přihlašovací údaje (Basic Auth) i klientský certifikát, takže podvržená doména znamená jejich únik. EndpointProvider proto přijímá pouze holé jméno hostu — bez schématu, přihlašovacích údajů, portu a cesty (datovka.cms2.cz ano, https://datovka.cms2.cz/ ne). Neplatná hodnota skončí výjimkou TomasKulhanek\CzechDataBox\Exception\InvalidEndpointDomain.

Odeslání datové zprávy

Zprávu složíte ze tří částí: obálky (Envelope), jednoho či více příjemců (Recipient) a příloh (File, právě jedna z nich musí mít metaType main). Odesílá Connector::createMessage():

Dvě věci, které při odesílání překvapí nejčastěji — obojí plyne z toho, že Connector::createMessage() volá hromadnou operaci ISDS CreateMultipleMessage i pro jedinou zprávu (metoda createMultipleMessage() proto v knihovně neexistuje):

1. Příjemci se zadávají mimo obálku, přes Recipient (dmRecipients/tRecipients). Organizační jednotku příjemce nastavíte Recipient::setOrgUnit() / setOrgUnitNum(), „k rukám" pak Recipient::setToHand(). Obálka (Envelope, XSD typ tMultipleMessageEnvelopeSub) žádný prvek o příjemci nemá.
2. Odpověď nemá přímé dmID. Je typu tMultipleMessageCreateOutput, takže ID odeslané zprávy najdete až v dílčím stavu — getMultipleStatus() vrací pole MessageStatus (jeden na příjemce) a ID se čte z MessageStatus::getDataMessageId().

Před odesláním knihovna sama hlídá limity Provozního řádu: 1–50 příjemců, nejvýše 100 příloh (z toho 10 kontejnerových), součet příloh do 20 MiB, povolené formáty dle vyhlášky č. 194/2009 Sb. a délky polí obálky. Větší zprávy patří mezi velkoobjemové (VoDZ).

Načtení seznamu přijatých zpráv

Minimální příklad reálné operace — seznam přijatých zpráv s filtrem stavů a časovým rozsahem:

Odeslané zprávy vrací obdobná operace getListOfSentMessages() s GetListOfSentMessages (místo setRecipientOrgUnitNum() má setSenderOrgUnitNum()).

[!WARNING] Volání GetListOfReceivedMessages je podle § 17 odst. 3 zákona č. 300/2008 Sb. doručením přihlášením — žádná jiná operace doručení nezpůsobí. Seznamy proto nestahujte v kratších intervalech, než odpovídá potřebě aplikace.

Stažení obsahu zprávy

Seznam vrací jen obálky. Obsah zprávy včetně příloh stáhne messageDownload(); podepsanou variantu (dmSignature, dostupná přes getSignature()) pak signedMessageDownload(). Operace markMessageAsDownloaded() označí přijatou zprávu jako přečtenou:

Volba HTTP klienta

Knihovna žádného HTTP klienta nevyžaduje — komunikaci obstarává implementace TomasKulhanek\CzechDataBox\Provider\ClientProviderInterface. Přibalené jsou dvě:

Podporované rozsahy jsou guzzlehttp/guzzle ^8.0 a symfony/http-client 7.*|8.* — knihovna je tedy použitelná i v aplikacích na Symfony 8.

Velkoobjemové datové zprávy (VoDZ)

Zprávy s přílohami nad 20 MiB se odesílají jako velkoobjemové datové zprávy (VoDZ) s limitem 100 MiB (Connector::MAX_BIG_MESSAGE_ATTACHMENTS_SIZE; Provozní řád mluví o 100 MB, knihovna limit počítá binárně ve prospěch odesílatele). Komunikace probíhá přes SOAP 1.2 na endpointech ws2[c].…/DS/vodz — knihovna to řeší automaticky.

Oproti běžné zprávě je postup dvoufázový a příjemce je právě jeden (hromadné odeslání ISDS u VoDZ nepodporuje): každou přílohu nejprve nahrajte přes uploadAttachment(), poté odešlete zprávu přes createBigMessage(), kde na nahrané přílohy odkážete pomocí ExtFile a vráceného identifikátoru. Stahování obstarávají bigMessageDownload(), signedBigMessageDownload(), signedSentBigMessageDownload(), downloadAttachment() a ověření authenticateBigMessage().

Knihovna ještě před odesláním validuje vstupy a může vyhodit výjimky MissingRequiredField (chybějící popis, obsah, příjemce či anotace), MissingMainFile (žádná příloha s metaType main), DisallowedAttachmentFormat (přípona mimo whitelist vyhlášky č. 194/2009 Sb.), AttachmentCountOverflow (příliš mnoho příloh), FileSizeOverflow (překročení 100 MiB) a FieldLengthOverflow (překročení délkových limitů obálky dle XSD — dmAnnotation 255 znaků, dmSenderRefNumber/dmRecipientRefNumber a dmSenderIdent/dmRecipientIdent 50 znaků) — všechny z namespace TomasKulhanek\CzechDataBox\Exception.

Správa vlastní schránky (db_manipulations)

Operace služby db_manipulations (endpoint …/DS/DsManage) vyžadují oprávnění PRIVIL_OWNER_ADM. Knihovna pokrývá správu pověřených osob — getDataBoxUsers2(), addDataBoxUser2(), updateDataBoxUser2(), deleteDataBoxUser2() — a nově i tyto tři operace vlastníka schránky:

• setOpenAddressing() — zapne otevřené adresování (§ 18a), schránka pak může přijímat poštovní datové zprávy od kohokoli. Vstupem je jen dbID (a volitelně dbApproved / dbExternRefNumber).
• clearOpenAddressing() — otevřené adresování zase vypne, stejný vstup.
• newAccessData2() — vyžádá vydání nových přístupových údajů uživateli isdsID ve schránce dbID. Povinný je příznak dbFeePaid (zaplacený správní poplatek); pro virtuální obálku se navíc posílá dbVirtual a email, na nějž přijde odkaz na Aktivační portál. Odpověď vrací nové dbUserID a dbAccessDataId — samotné heslo webová služba nikdy nevrací, ISDS je doručuje mimo rozhraní.

Ostatní operace služby (CreateDataBox2, DeleteDataBox2, EnableOwnDataBox2, DisableOwnDataBox2, UpdateDataBoxDescr2, DisableDataBoxExternally2) jsou určeny pro OVM/správce a knihovna je zatím nepokrývá.

Pokrytí webových služeb ISDS

Tabulka ukazuje, které operace rozhraní ISDS knihovna umí — pro každou operaci z WSDL uvádí odpovídající metodu Connector, nebo důvod, proč pokrytá není. Slouží jako kontrola před nasazením: než začnete integraci psát, ověříte si v ní, že operace, kterou potřebujete, existuje.

Matici generuje php tools/wsdl-coverage.php z WSDL v tests/_data/wsdl/ (příloha 2 Provozního řádu, verze 3.11) a z reflexe třídy TomasKulhanek\CzechDataBox\Connector — čísla proto nemohou zastarat vůči kódu. Soulad matice se skutečností hlídá CI (composer check:wsdl-coverage), matici proto needitujte ručně.

Legenda: ✅ implementováno · ⛔ záměrně vynecháno (operaci nahradila novější varianta) · ❌ neimplementováno (skutečná mezera).

Souhrn

db_access.wsdl

služby související s přístupem do ISDS

db_search.wsdl

vyhledávání datových schránek

db_manipulations.wsdl

manipulace s datovou schránkou a její uživatelé

dm_operations.wsdl

odesílání a stahování datových zpráv

dm_info.wsdl

informace o datových zprávách

dm_VoDZ.wsdl

velkoobjemové datové zprávy (VoDZ, do 100 MiB)

dm_arch.wsdl

archivace (přerazítkování) ZFO

Mimo záběr knihovny

Následující WSDL přílohy 2 knihovna vědomě neimplementuje, nejde tedy o mezery v pokrytí:

• ChangePassword.wsdl (služba asws) — změna hesla přes SMS kód / OTP (SendSMSCode, ChangePasswordOTP) běží na samostatné službě asws s vlastní autentizací. Knihovna podporuje běžnou změnu hesla operací ChangeISDSPassword z db_access.wsdl.
• SetConcept.wsdl — zakládání konceptů zpráv (SetConcept, SetMultipleConcept) je určené pro předání rozepsané zprávy do webového Portálu datových schránek, ne pro strojové odesílání. Knihovna zprávy odesílá přímo přes dm_operations.wsdl.
• ExtWs.wsdl — odesílací brána (OB) — odesílací brána (extWsLogout, GetCredential) je samostatný produkt ISDS s vlastním modelem autentizace a smluvním režimem. Knihovna cílí na přímé napojení aplikace na ISDS.

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 MiB odesílejte jako velkoobjemové (VoDZ, do 100 MiB) 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.

Přechod z jiné ISDS knihovny

Migrujete-li existující integraci z balíčku dfridrich/czech-data-box, projděte si Přechod z dfridrich/czech-data-box — obsahuje mapu API obou knihoven, dva úplné příklady „před → po“ (přihlášení se seznamem přijatých zpráv a odeslání zprávy) a checklist migrace.

Povyšujete-li z verze 5.x této knihovny, řiďte se návodem UPGRADE-6.0.md.

Pomoc a řešení 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.

⚠ Bezpečnostní chybu prosím nehlaste veřejným Issue — postup najdete v SECURITY.md.

Odkazy

• Changelog knihovny - CHANGELOG.md
• Migrace z 5.x na 6.0 - UPGRADE-6.0.md
• Přechod z dfridrich/czech-data-box - MIGRATION-FROM-DFRIDRICH.md
• Jak přispívat - CONTRIBUTING.md
• Bezpečnostní politika - SECURITY.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í

Formuláře žádostí pro orgány veřejné moci i ostatní typy schránek vydává DIA na stránce Zřízení datové schránky. Původní odkazy na datoveschranky.info už nefungují, portál se přesunul na datovka.gov.cz.

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í

Používáte knihovnu v produkci? Budu rád za ⭐ na GitHubu — pomáhá ostatním vývojářům najít aktuálně udržovanou implementaci ISDS.