API dokumentace

1 Úvod

Tato stránka dokument popisuje API systému EK CÚD ve verzi v1.2, dále jen „CÚD API“. Verze v1.2 je implementuje funkční požadavky fáze I. a II. projektu CÚD.

2 Základní informace

CÚD API je architektonicky koncipováno jako REST webová služba s následujícími vlastnostmi:

Vstupní/výstupní formát dat: JSON s kódování UTF-8.
Přístup ke službě je omezen pouze pro autentizované uživatele.
Autentizace probíhá pomocí API klíčů, které jsou přiděleny skrze CÚD.
Služba je zabezpečena proti úniku dat pomocí protokolu HTTPS.

Služba je provozována v produkční (ostrém) a testovací režimu.

CÚD API je dostupné na URL:

Produkční server: https://api.centralnideska.cz (v1.2)
Testovací server: https://api.test.centralnideska.cz (v1.2)

Testovací rozhraní pro WWW-prohlížeče je dostupné na URL:

Produkční server: https://api.centralnideska.cz/api-docs/swagger-ui.html (v1.2)
Testovací server: https://api.test.centralnideska.cz/api-docs/swagger-ui.html (v1.2)

3 Autentizace

Autentizace je vyžadována pro všechny požadavky na CÚD API. Autentizace probíhá pomocí API klíče o délce 32 znaků. API klíč byl předán soudním exekutorům skrze datovou schránku. Lze jej také získat v administračním rozhraní CÚD (Můj úřad → Správa API klíčů).

API klíč je předáván v rámci každého HTTP požadavku v HTTP hlavičce X-API-Key. Alternativně je podporována také autentizace skrze HTTP Basic Authentication s uživatelským jménem odpovídajícím API klíči a prázdným heslem.

Veškeré požadavky provedené skrze HTTP protokol jsou přesměrovány na zabezpečený HTTPS protokol. Využití HTTP protokolu je zakázáno, jelikož může vést k odposlechnutí přístupových údajů.

3.1 Žádost o přístup pro organizace třetích stran

O přístup do CÚD API mohou třetí strany (např. dodavatelé SW) požádat skrze e-mailovou adresu: admin@centralnideska.cz.

4 HTTP stavové kódy

CÚD API využívá standardní HTTP stavové kódy, které umožnují validovat odpověď služby v klientských aplikacích. V tabulce níže jsou vypsány všechny využívané stavové kódy s krátkým popisem jejich významu.

Kód	Název	Popis
200	OK	Požadavek byl úspěšně vykonán. Odpověď serveru obsahuje požadovaná data.
201	Created	Požadavek byl úspěšně vykonán – byl vytvořen nový objekt v rámci CÚD. HTTP hlavička Location obsahuje URI nově vytvořeného objektu.
204	No Content	Požadavek byl úspěšně vykonán, odpověď neobsahuje žádný obsah.
400	Bad Request	Požadavek odmítnut – obsahuje nevalidní parametry nebo vstupní data. Odpověď serveru obsahuje detailní důvod.
401	Unauthorized	Požadavek odmítnut – chyba autentizace.
403	Forbidden	Požadavek odmítnut – požadavek není povolen pro autentizovaného klienta.
404	Not Found	Požadavek odmítnut – požadovaný zdroj/objekt nenalezen.
405	Method Not Allowed	Požadavek odmítnut – požadovaný zdroj/objekt nepodporuje použitou HTTP metodu.
406	Not Acceptable	Požadavek odmítnut – požadovaný formát dat není podporován (HTTP hlavička Accept). Použijte `application/json`.
413	Request Entity Too Large	Požadavek odmítnut – velikost dat přesahuje povolený limit. Uploadujte soubory menší než 20 MB.
415	Unsupported Media Type	Požadavek odmítnut – vstupní formát dat není podporován (HTTP hlavička `Content-type`). Použijte `application/json`.
422	Unprocessable Entity	Požadavek odmítnut – požadavek je správně, ale stav dat jej neumožnuje provést.
500	Internal Server Error	Chyba serveru – při opakujících se problémech kontaktujte prosím podporu CÚD.
503	Service Unavailable	Server dočasně nedostupný – probíhá údržba CÚD API.

4.1 Obsah odmítnutého/chybového požadavku

Bližší popis stavu lze pro odpovědi se stavy 4xx a 5xx nalézt obsahu odpovědi. Jedná se o JSON objekt s následujícími atributy:

Název atributu	Formát	Popis
`stav`	číslo	Hodnota shodná s HTTP stavovým kódem odpovědi
`cas`	řetězec s časovou značkou ve formátu ISO 8601	Čas vygenerování odpovědi na serveru
`chyba`	řetězec	Textový popis chyby
`dilciChyby`	pole řetězců	Nepovinný atribut se seznamem dílčích chyb. Obvykle použitý pouze pro stav 400, kdy je obsahem seznam selhaných validací vstupních dat.

Příklad obsahu odpovědi pro stav 400:

{
  "stav":400,
  "chyba":"Chyba vstupních dat",
  "cas":"2021-11-22T13:39:28",
  "dilciChyby":[
    "Pole 'idPisemnost' nesmí být prázdné",
    "Pole 'vyvesitDne' musí být vyplněno"
  ]
}

5 Datové formáty komunikace

CÚD API podporuje pro komunikaci až na určené výjimky pouze datový formát JSON (MIME typ application/json).

5.1 Textové řetězce

Všechny řetězce jsou kódovány pomocí UTF-8.

5.2 Formát časových značek

Pokud není uvedeno jinak, všechny atributy obsahující datum či datum s časem jsou ve formátu ISO 8601. Pro datum se používá formát yyyy-MM-dd a pro čas formát yyyy-MM-ddTHH:mm:ss.

5.3 Formát čísla jednacího

CÚD vyžaduje využívat následující formát čísla jednacího: {Číslo exekutora}{Rejstřík}{Kmen}/{Rok}‑{List}

Kde:

{Číslo exekutora} - třímístné číslo exekutora doplněné úvodními nulami
{Rejstřík} - EX, ED nebo DD
{Kmen} - číslo od 1 do 999999 bez úvodních nul
{Rok} - dvoumístné číslo definující rok od 2000
{List} - nepovinné číslo listu obsahující číslice a písmena, maximálně 6 znaků, bez úvodních nul

CÚD ve výchozí konfigurace vyžaduje výše uvedený formát. Pokud dokument obsahuje chybné číslo, je jeho zpracování odmítnuto (HTTP kód 400).

5.4 Formát pro nahrávání souborů

PDF soubory písemností, které jsou nahrávány na CÚD, jsou přímo vkládány do JSON požadavku. Obsah souboru lze do příslušného pole JSON objektu vložit jako řetězec kódovaný pomocí BASE64 .

6 Dostupné zdroje

Dostupné zdroje jsou dokumentovány pomocí formátu OpenAPI verze 3. Součástí této dokumentace je soubor cud-api-v03.openapi.json, který obsahuje úplný popis všech dostupných zdrojů ve formátu OpenAPI 3.

Dostupné zdroje lze prohlížet včetně možnosti přímého otestování skrze WWW-prohlížeč skrze nástroj Swagger UI. Odkazy na Swagger UI jsou uvedeny v kapitole 2.

Pomocí nástroje Swagger Editor je také možné z OpenAPI souboru vygenerovat zdrojové kódy pro klientskou aplikaci v široké škále programovacích jazyků.

7 ChangeLog

Dokumentace změn API zdrojů.

7.1 Verze 0.1

První verze.

7.2 Verze 0.2

7.2.1 GET /

Doplněn atribut odpovědi verze obsahující verzi CÚD API.

7.2.2 GET /ud

Atribut odpovědi idPisemnost nahrazen za atribut sidp, který obsahuje seznam ID písemností.

7.2.3 GET /ud/{cudid}

Atribut odpovědi idPisemnost odstraněn.
Přidán atribut odpovědi zasilky, který obsahuje seznam zásilek (písemností) v dokumentu s následujícími atributy:

idPisemnost - identifikátor doručované písemnosti z interního systému exekutora,
cisloJednaci - číslo jednací,
cisloJednaciValidni - indikace zda je číslo jednací validní (vyhovující formátu stanoveném pro CÚD).

7.2.4 POST /ud/OHL

Atributy požadavku cisloJednaci, pisemnost a idPisemnost odstraněny a přesunuty do atributu zasilky, který obsahuje pole objektu s těmito atributy.
Atribut požadavku ohlasovny byl nahrazen za atribut ohlasovna, který obsahuje právě jednu adresu, u které je povinné uvést atribut adm.
U atributu požadavku cisloJednaci není vyzadován přesný formát.
Atribut požadavku pisemnost může mít neomezenou délku.
Přidána odpověď s atributy:

cudid - interní systémová identifikace dokumentu,
vyvesitDne - datum požadovaného vyvěšení,
doslaniDoDne - datum určující do kdy je možné písemnost vyzvednout, nebo poslat žádost o doslání na jinou adresu,
svesitDne - datum předpokládaného svěšení,
cislaJednaniValidni - indikace zda předaná čísla jednací byla validní. Nevalidní čísla jednací jsou uložena, ale některé operace CÚD mohou tyto dokumenty ignorovat.

7.3 Verze 0.3

7.3.1 GET /ud/{cudid}

Přidány nové atributy: vlozeno, upraveno, vyvesitDne, vyveseno, doslaniDoDne, svesitDne, sveseno, test.

7.3.2 POST /ud/OHL

Zdroj zrušen a rozdělen dva dílčí zdroje POST /ud/OHL-56a a POST /ud/OHL-56b

7.3.3 POST /ud/OHL-56a

Nový zdroj odpovídající původní POST /ud/OHL pro OHL dle §56a.

Atribut požadavku ohlasovna.nazev je nově povinný.

7.3.4 POST /ud/OHL-56B

Nový zdroj vycházející z POST /ud/OHL pro OHL dle §56b.

Atribut požadavku ohlasovna byl nahrazen za atribut mistoDoruceni s nepovinným dílčím atributem adm.

7.4 Verze 0.4

7.4.1 GET /ud

Atribut odpovědi sidp nahrazen za atribut interniId, který obsahuje pouze jedno interní ID exekutora.

7.4.2 GET /ud/{cudid}

Atribut odpovědi zasilky přejmenován na pisemnosti.

7.4.3 POST /ud/OHL-56a

Doplněn povinný atribut požadavku interniId.
Atribut požadavku idPisemnosti ze zasilky je nepovinný.
Atribut požadavku druhDoruceni přesunut zasilky - nově je součástí každné zásilky.
Atribut požadavku zasilky přejmenován na pisemnosti.
Atribut požadavku pisemnost ze zasilky přejmenován na popis.

7.4.4 POST /ud/OHL-56b

Doplněn povinný atribut požadavku interniId.
Atribut požadavku idPisemnosti ze zasilky je nepovinný.
Atribut požadavku druhDoruceni přesunut zasilky - nově je součástí každné zásilky.
Atribut požadavku zasilky přejmenován na pisemnosti.
Atribut požadavku pisemnost ze zasilky přejmenován na popis.

7.5 Verze 0.5

7.5.1 POST /ud/OHL-56a

Formát čísla jednacího u dokumentu i písemností je stkriktně validován. Dokumenty s nevalidnim číslem jednacím jsou odmítnuty (HTTP kód 400).

7.5.2 POST /ud/OHL-56b

Formát čísla jednacího u dokumentu i písemností je stkriktně validován. Dokumenty s nevalidnim číslem jednacím jsou odmítnuty (HTTP kód 400).

7.5.3 DELETE /ud/{cudid}

Změna prováděné operace:

Pro vyvěšené dokumenty provádí operaci předčasného svěšení. Dokument je přesunut do archivu.
Pro nevyvěšené dokumenty je fukcionalita zachováná. Dokument je trvale smazán.
Pokud je pozadavek volána nad dokumentem v archivu, je zpracování odmítnuto s odpovědí s HTTP stavem 422.

7.6 Verze 0.6

7.6.1 GET /ud/vlastni

Nový zdroj umožňující výpis seznamu detailů vlastních dokumentů ÚD (dokumentů vložených úřadem).

7.6.2 GET /ud/vlastni/nevyzvednute

Nový zdroj umožňující výpis seznamu detailů vlastních dokumentů ÚD (dokumentů vložených úřadem) s nevyzvednutým potvrzením. Umožňuje jednoduše stahovat všechna nová potvrzení.

7.6.3 GET /ud/{cudid}/potvrzeni

Doplněn nový atribut odpovědi vyzvednuto, který obsahuje časovou značku vyzvednutí potvrzení, pokud bylo vyzvednuto pomocí /ud/{cudid}/potvrzeni/typ-{typ}.

7.6.4 GET /ud/{cudid}

Neumožňuje přístup k dokumentům jiných kanceláří (HTTP stav 403).

7.6.5 GET /ud/{cudid}/potvrzeni

Neumožňuje přístup k dokumentům jiných kanceláří (HTTP stav 403).

7.7.6 GET /ud/{cudid}/potvrzeni/typ-{typ}

Neumožňuje přístup k dokumentům jiných kanceláří (HTTP stav 403).

7.8 Verze 1.0

Verze 1.0 podporuje nové typy dokumentů a poskytuje informace o jejich číselnících.

7.8.1 GET /ud/ciselniky

Nový zdroj umožňující získat informace o podporovaných číselnících dokumentů.

7.8.2 POST /ud/OZN

Nový zdroj umožňující vyvěšení OZN dokumentu.

7.8.3 POST /ud/U29

Nový zdroj umožňující vyvěšení U29 dokumentu.

7.8.4 POST /ud/X29

Nový zdroj umožňující vyvěšení X29 dokumentu.

7.8.5 POST /ud/V49

Nový zdroj umožňující vyvěšení V49 dokumentu.

7.8.6 POST /ud/X49

Nový zdroj umožňující vyvěšení X49 dokumentu.

7.8.7 POST /ud/P50

Nový zdroj umožňující vyvěšení P50 dokumentu.

7.8.8 POST /ud/X50

Nový zdroj umožňující vyvěšení X50 dokumentu.

7.8.9 POST /ud/P52

Nový zdroj umožňující vyvěšení P52 dokumentu.

7.8.10 POST /ud/X52

Nový zdroj umožňující vyvěšení X52 dokumentu.

7.8.11 POST /ud/PXX

Nový zdroj umožňující vyvěšení PXX dokumentu - volné vyvěšení písemností.

7.9 Verze 1.1

Verze 1.1 přidává nové atributy v detailu dokumentů.

7.9.1 GET /ud/{cudid}

Detail dokumentu poskytuje nové atributy, které umožnují získat informace o vztazích mezi V49 a X49 dokumenty.

Doplněn nový atributy odpovědi rodicovskyDokument obsahující CUDID dokumentu, ze kterého vychází dotyčný dokument (např. CUDID V49 dokumentu, rodiče dokumentu X49).
Doplněn nový atributy odpovědi navazujiciDokumenty obsahující seznam CUDID dokumentů, jejichž rodičem je dotyčný dokument (např. CUDID X49 dokumentu pro rodičovský V49 dokument).

7.10 Verze 1.2

Verze 1.2 zavádí podporu pro právnické osoby. Nově je umožněno vkládání adresáta ve formě právnické osoby pro dokumenty OZN, U29, V49, X49, P50 a P52.