Upozornění: Text přílohy byl získán strojově a nemusí přesně odpovídat originálu. Zejména u strojově nečitelných smluv, kde jsme použili OCR. originál smlouvy stáhnete odsud
Popis REST API rozhraní mezi systémy „ISTEM“ a „e-Vydej“
Komunikace mezi systémy e-Vydej a ISTEM v rámci výdeje dat
Výdej dat
Popis REST API rozhraní mezi systémy „ISTEM“ a „e-Vydej“
verze 1.4
Historie dokumentu
Verze
Datum
Autor
Změny
1.0
15.3.2023
xxx
Úvodní naplnění dokumentu.
1.1
27.3. 2023
xxx
Doplnění requestId a responseId do hlavičky volání endpointů.
1.2
16.4.2024
xxx
Úpravy vstupních parametrů.
1.3
19.7.2024
xxx
Úprava formátů datových sad
1.4
23.4.2025
xxx
Oprava URL endpointů
Obsah
1 API vystavené a straně systému „ISTEM“ 3
1.1 Endpoint „VydejVerejneStavoveDatoveSady“ 4
1.1.1 Specifikace 4
1.1.2 Request 4
1.1.3 Response 8
1.2 Endpoint „VydejVerejneZmenoveDatoveSady“ 10
1.2.1 Specifikace 10
1.2.2 Request 10
1.2.3 Response 13
1.3 Endpoint „VyhotoveniAdhocVerejneDatovesady“ 15
1.3.1 Specifikace 15
1.3.2 Request 15
1.3.3 Response 17
2 Odkazy na další dokumenty 19
API vystavené a straně systému „ISTEM“
Přes API vystavuje systém „ISTEM“ endpointy, kterými volající systém „e-Vydej“ zasílá požadavky na výdej datových sad uložených v IS DTM kraje. API vystavuje pro účel výdeje dat celkem 3 endpointy.
Základní informace vystavenému na API
Název API: /api/istem/vydej
URI: bude specifikováno později
Proces: Výdej dat
Poskytovatel: ISTEM
Volající: e-Vydej
Protokol: REST
Datový typ: JSON
Typ API: SYNC
Verze: 1.0.0
Systém „ISTEM“ bude výdej veřejných stavových i změnových dat zpracovávat synchronně a respose endpointů (VydejVerejneStavoveDatoveSady, VydejVerejneZmenoveDatoveSady) bude rovnou vracet výsledek výdeje.
Výdej veřejných dat generovaných ad hoc za vybrané území zadané pomocí polygonu bude systém „ISTEM“ zpracovávat asynchronně. Výsledek výdeje v případě asynchronního zpracování bude vracen pomocí volání endpointu vystaveného na API systému „e-Vydej“ (viz dokument „IA - výdej dat - eVydej – REST.docx“).
Endpoint „VydejVerejneStavoveDatoveSady“
Endpoint pro zaslání požadavku ze strany e-Vydeje na předgenerované veřejné stavové datové sady za definovanou administrativní jednotku. Odkaz ke stažení požadovaných dat je vracen synchronně jako součást BODY response.
Specifikace
Endpoint: /api/istem/vydej/vydejVerejneStavoveDatoveSady
Popis: Služba pro zaslání požadavku na výdej veřejných stavových dat.
Zabezpečení: JWT token
Metoda
Typ: POST
Response: synchronní, http kód + JSON struktura
Batch: single
Request
V hlavičce requestu jsou povinně zasílány autorizační JWT token a parametr „requestId“ pro potřeby logování a auditu.
Vstupní parametry kolekce zasílané v těle requestu
Název parametru
Popis
Datový typ
Povinný
zadatelFo
Žadatel o data jako fyzická osoba.
Struktura
Ano podmíněně
jmeno
Jméno žadatele
String
Ano
prijmeni
Příjmení žadatele
String
Ano
email
Kontaktní email žadatele
String
Ano
zadatelPo
Žadatel o data jako právnická osoba.
Struktura
Ano podmíněně
Nazev
Obchodní název právnické osoby
String
Ano
Ico
IČ právnické osoby
String
Ano
email
Kontaktní email právnické osoby
String
Ano
datum
Datum, ke kterému jsou požadována data
Date
Ano
format
Formát, ve kterém jsou požadována data.
Musí být zadán právě jeden z těchto formátů: JVF, DGN, SHP, GPKG
Formát JVF je možné zadat vždy.
Formát DGN, SHP, GPKG je možné zadat pouze v případě, že v parametru uzemniJednotky je vybrána ‘mestska_cast’ a současně jsou požadovány pouze tyto datové sady (všechny nebo některé): zpsKresba, zpsPodrobneBody, zpsOdvozenePlosneTypyObjektu, zpsDoprovodneInformace.
String
Ano
datoveSady
Specifikace požadovaných datových sad
Struktura
Ano
zpsKresba
Příznak, že je požadována datová sada ZPS kresba.
Boolean
Ano podmíněně
zpsPodrobneBody
Příznak, že je požadována datová sada ZPS podrobné body.
Boolean
Ano podmíněně
zpsOdvozenePlosneTypyObjektu
Příznak, že je požadována datová sada ZPS odvozené plošné typy objektů.
Boolean
Ano podmíněně
zpsDoprovodneInformace
Příznak, že je požadována datová sada ZPS doprovodné informace.
Boolean
Ano podmíněně
di
Příznak že je požadována datová sada DI (bez záměrů a ochranných pásem).
Boolean
Ano podmíněně
ti
Příznak že je požadována datová sada TI (bez záměrů a ochranných pásem)
Boolean
Ano podmíněně
uzemniSpecifikace
Definice územního vymezení, za které jsou požadována data
Struktura
Ano
typ
Typ územního vymezení
String
Ano
uzemniJednotky
Administrativní jednotky, ve kterých je požadován výdej. Možné hodnoty (je povoleno zadat pouze jeden z následujících typů územní jednotky):
obec
katastr
mestska_cast
Struktura
Ne
kod
RUIAN kód
String
Ano
nazev
Název administrativní jednotky
String
Ano
Struktura JSON souboru zasílaného v requestu
{
"data": {
"zadatelFo": [
{
"jmeno": "Jan",
"prijmeni": "Novak",
"email": "jan.novak@seznam.cz"
}
],
"zadatelPo": [
{
"ico": "04510221",
"nazev": "ČEZ a.s.",
"email": "cez@distribuce.cz"
}
],
"datum": "2023-03-07",
"format": "JVF",
"datoveSady":
{
"zpsKresba": true,
"di": true,
"ti": false,
},
"uzemniSpecifikace":
{
"typ": "mestskaCast",
"uzemniJednotky": [
{
"kod": "19",
"nazev": "Praha 1"
}
]
}
}
}
Validace
· Na vstupu je alespoň jedna podřízená položka elementu „datoveSady“ = true, pokud ne tak vracet chybový kód 400
· Na vstupu je zadána administrativní jednotka, která není součástí volaného IS DTM kraje -> chybový kód 400
· Zadané datum nesmí být starší než 3 měsíce zpět. Pokud podmínka nesplněna, tak vracet chybový kód 400
· Platnost JWT tokenu -> chybový kód 401
Response
Endpoint po úspěšné validaci vrací v hlavičce
· návratový kód 200
· responseId s vazbou na requestId pro potřeby logování a auditu (vraceno i v případě chybového stavu)
V těle response je vracena JSON struktura s výstupními parametry kolekce „Data“
Název parametru
Popis
Datový typ
Povinný
isDtmk
Kód DTM kraje
String
Ano
vysledek
Výsledek výdeje dat (u veřejných dat automaticky schváleno)
String
Ano
oduvodneni
Odůvodnění zamítnutí výdeje dat (v případě veřejných dat není položka povinná).
String
Ne
datoveSady
Vydané datové sady. Pokud nejsou na základě požadavků nalezena data, vrací se prázdné pole.
Struktura
Ano podmíněně
nazev
Název souboru
String
Ano
format
Formát výstupních dat
String
Ano
velikost
Velikost výstupních dat
String
Ano
url
URL odkaz ke stažení dat
String
Ano
vyhotoveno
Datum vyhotovení datové sady
Date
Ano
platnost
Datum, ke kterému je vztažen stav dat.
Date
Ano
platnostUrl
Datum do kdy je URL odkaz aktivní.
Date
Ano
Návratové kódy
Kód
Název
Popis
200
Ok
V případě úspěšné validace vstupních parametrů vrací endpoint potvrzení o zpracování se stavovým kódem 200.
400
Bad request
Zasílat kód 400 v případě aplikační chyby na straně ISTEMU.
401
Unauthorized
Zasílat kód 401 v případě chyby autorizace volajícího
500
Internal server error
Zasílat kód 500 v případě výskytu chyby na straně serveru.
Příklad response
{
"data": {
"isDtmk": "CZ010",
"vysledek": "VydejPovolen",
"oduvodneni": "",
"datoveSady": [
{
"nazev": "VS_CZ010_MOMC_19_20231031_ZPS_KR.jvf.zip",
"format": "JVF",
"velikost": "9.0",
"url": "https://www.isdtmk.cz/vydej...19_zps.zip",
"vyhotoveno": "2023-03-01T00:00:00.000Z",
"platnost": "2023-03-01T00:00:00.000Z",
"platnostUrl": "2023-03-10T00:00:00.000Z"
},
{
"nazev": "VS_CZ010_MOMC_19_20231031_DI.jvf.zip",
"format": "JVF",
"velikost": "13.6",
"url": "https://www.isdtmk.cz/vydej...19_di.zip",
"vyhotoveno": "2023-03-01T00:00:00.000Z",
"platnost": "2023-03-01T00:00:00.000Z",
"platnostUrl": "2023-03-10T00:00:00.000Z"
}
]
}
}
Endpoint „VydejVerejneZmenoveDatoveSady“
Endpoint k zaslání požadavku na výdej předgenerovaných změnových dat DTM za území celého kraje. Odkaz ke stažení požadovaných dat je vracen synchronně jako součást BODY response.
Specifikace
Endpoint: /api/istem/vydej/vydejVerejneZmenoveDatoveSady
Popis: Služba pro zaslání požadavku na výdej veřejných změnových dat.
Zabezpečení: JWT token
Metoda
Typ: POST
Response: synchronní, http kód + JSON struktura
Batch: single
Request
V hlavičce requestu jsou povinně zasílány autorizační JWT token a parametr „requestId“ pro potřeby logování a auditu.
Vstupní parametry kolekce zasílané v těle requestu
Název parametru
Popis
Datový typ
Povinný
zadatelFo
Žadatel o data jako fyzická osoba.
Struktura
Ano podmíněně
jmeno
Jméno žadatele
String
Ano
prijmeni
Příjmení žadatele
String
Ano
email
Kontaktní email žadatele
String
Ano
zadatelPo
Žadatel o data jako právnická osoba.
Struktura
Ano podmíněně
Nazev
Obchodní název právnické osoby
String
Ano
Ico
IČ právnické osoby
String
Ano
email
Kontaktní email právnické osoby
String
Ano
datum
Datum, ke kterému jsou požadována data
Date
Ano
format
Formát, ve kterém jsou požadována data
Lze zadat pouze formát JVF.
String
Ano
datoveSady
Specifikace požadovaných datových sad
Struktura
Ano
zpsKresba
Příznak, že je požadována datová sada ZPS kresba.
Boolean
Ano podmíněně
zpsPodrobneBody
Příznak, že je požadována datová sada ZPS podrobné body.
Boolean
Ano podmíněně
zpsOdvozenePlosneTypyObjektu
Příznak, že je požadována datová sada ZPS odvozené plošné typy objektů.
Boolean
Ano podmíněně
zpsDoprovodneInformace
Příznak, že je požadována datová sada ZPS doprovodné informace.
Boolean
Ano podmíněně
di
Příznak že je požadována datová sada DI (bez záměrů a ochranných pásem).
Boolean
Ano podmíněně
ti
Příznak že je požadována datová sada TI (bez záměrů a ochranných pásem)
Boolean
Ano podmíněně
Struktura JSON souboru zasílaného v requestu
{
"data": {
"zadatelFo": [
{
"jmeno": "Jan",
"prijmeni": "Novak",
"email": "jan.novak@seznam.cz"
}
],
"zadatelPo": [
{
"ico": "04510221",
"nazev": "ČEZ a.s.",
"email": "cez@distribuce.cz"
}
],
"datum": "2023-03-07",
"format": "JVF",
"datoveSady":
{
"zpsKresba": true,
"di": true,
"ti": false,
}
}
}
Validace
· Na vstupu je alespoň jedna podřízená položka elementu „datoveSady“ = true, pokud ne tak chybový kód 400
Response
Endpoint po úspěšné validaci vrací v hlavičce
· návratový kód 200
· responseId s vazbou na requestId pro potřeby logování a auditu (vraceno i v případě chybového stavu)
V těle response vrací JSON strukturu s výstupními parametry kolekce „Data“
Název parametru
Popis
Datový typ
Povinný
isDtmk
Kód DTM kraje
String
Ano
vysledek
Výsledek výdeje dat (u veřejných dat automaticky schváleno)
String
Ano
oduvodneni
Odůvodnění zamítnutí výdeje dat (v případě veřejných dat není položka povinná).
String
Ne
datoveSady
Vydané datové sady. Pokud nejsou na základě požadavků nalezena data, vrací se prázdné pole.
Struktura
Ano podmíněně
nazev
Název souboru
String
Ano
format
Formát výstupních dat
String
Ano
velikost
Velikost výstupních dat
String
Ano
url
URL odkaz ke stažení dat
String
Ano
vyhotoveno
Datum vyhotovení datové sady
Date
Ano
platnost
Datum, ke kterému je vztažen stav dat.
Date
Ano
platnostUrl
Datum do kdy je URL odkaz aktivní.
Date
Ano
Návratové kódy
Kód
Název
Popis
200
Ok
V případě úspěšné validace vstupních parametrů vrací endpoint potvrzení o zpracování se stavovým kódem 200.
400
Bad request
Zasílat kód 400 v případě aplikační chyby na straně ISTEMU.
401
Unauthorized
Zasílat kód 401 v případě chyby autorizace volajícího
500
Internal server error
Zasílat kód 500 v případě výskytu chyby na straně serveru.
Příklad response
{
"data": {
"isDtmk": "CZ010",
"vysledek": "VydejPovolen",
"oduvodneni": "",
"datoveSady": [
{
"nazev": "VZ_CZ010_20231025_ZPS_KR.jvf.zip",
"format": "JVF",
"velikost": "9.0",
"url": "https://www.isdtmk.cz/vydej...ZPS_KR.jvf.zip"",
"vyhotoveno": "2023-03-01T00:00:00.000Z",
"platnost": "2023-03-01T00:00:00.000Z",
"platnostUrl": "2023-03-10T00:00:00.000Z"
},
{
"nazev": "VZ_CZ010_20231025_DI.jvf.zip",
"format": "JVF",
"velikost": "13.6",
"url": "https://www.isdtmk.cz/vydej...DI.jvf.zip",
"vyhotoveno": "2023-03-01T00:00:00.000Z",
"platnost": "2023-03-01T00:00:00.000Z",
"platnostUrl": "2023-03-10T00:00:00.000Z"
}
]
}
}
Endpoint „VyhotoveniAdhocVerejneDatovesady“
Specifikace
Základní informace k endpointu
Endpoint: /api/istem/vydej/vyhotoveniAdhocVerejneDatovesady
Popis: Služba pro zaslání požadavku na vyhotovení ad hoc veřejných stavových dat.
Zabezpečení: JWT token
Metoda
Typ: POST
Response: synchronní, http kód + JSON struktura
Batch: single
Request
V hlavičce requestu jsou povinně zasílány autorizační JWT token a parametr „requestId“ pro potřeby logování a auditu.
Vstupní parametry kolekce zasílané v těle requestu
Název parametru
Popis
Datový typ
Povinný
zadatelFo
Žadatel o data jako fyzická osoba.
Struktura
Ano podmíněně
jmeno
Jméno žadatele
String
Ano
prijmeni
Příjmení žadatele
String
Ano
email
Kontaktní email žadatele
String
Ano
zadatelPo
Žadatel o data jako právnická osoba.
Struktura
Ano podmíněně
nazev
Obchodní název právnické osoby
String
Ano
ico
IČ právnické osoby
String
Ano
email
Kontaktní email právnické osoby
String
Ano
idZadosti
Jedinečný identifikátor požadavku/objednávky vytvořený v aplikaci e-Vydej. Slouží k identifikaci při zasílání výsledku výdeje.
String
Ano
datum
Datum, ke kterému jsou požadována data (tj. časové určení stavu dat)
Date
Ano
format
Formát, ve kterém jsou požadována data.
Lze zadat právě jeden z těchto formátů:
JVF, DGN, SHP, GPKG
String
Ano
datoveSady
Specifikace požadovaných datových sad
Struktura
Ano
zps
Příznak že je požadována datová sada ZPS.
Boolean
Ano podmíněně
di
Příznak že je požadována datová sada DI (veřejná bez ZM,OP,BP).
Boolean
Ano podmíněně
ti
Příznak že je požadována datová sada TI (veřejná bez ZM,OP,BP)
Boolean
Ano podmíněně
uzemniSpecifikace
Definice územního vymezení, za které jsou požadována data
Struktura
Ano
typ
Typ územního vymezení
String
Ano
geometry
Geometrie polygonu.
Struktura
Ano
type
Typ geometrie
String
Ano
coordinates
Souřadnice lomových bodů.
Pole
Ano
Struktura JSON souboru zasílaného v requestu
{
"data": {
"zadatelFo": [
{
"jmeno": "Jan",
"prijmeni": "Novak",
"email": "jan.novak@seznam.cz"
}
],
"zadatelPo": [
{
"ico": "04510221",
"nazev": "ČEZ a.s.",
"email": "cez@distribuce.cz"
}
],
"idZadosti": "7b3302d7-5b67-4eaa-aaec-401bff97fc6d",
"datum": "2023-03-07",
"format": "JVF",
"datoveSady":
{
"zps": true,
"di": true,
"ti": false,
},
"uzemniSpecifikace":
{
"typ": "zakreslenaOblast",
"geometry": {
"type": "Polygon",
"coordinates": [
[102.0, 0.0],
[103.0, 1.0],
[104.0, 0.0],
[105.0, 1.0]
]
}
}
}
}
Validace
· Na vstupu je alespoň jedna podřízená položka elementu „datoveSady“ = true, pokud ne -> chybový kód 400
· Na vstupu je zasláno v elementu „idZadosti“ s hodnotou pod kterou již v ISTEMU existuje požadavek na výdej -> chybový kód 400
· Platnost JWT tokenu -> chybový kód 401
Response
Endpoint po úspěšné validaci vrací v hlavičce
· návratový kód 200
· responseId s vazbou na requestId pro potřeby logování a auditu (vraceno i v případě chybového stavu)
V těle response je vraceno potvrzení o přijetí požadavku na výdej dat. Samotný výsledek je vrácen voláním endpointu eVydej/VydejDat/VysledekVyhotoveniAdHocVerejneDatoveSady vystavený v API aplikace e-Vydej. ISTEM tento endpoint volá v okamžiku kdy ukončí asynchronní zpracování procesu výdeje ad hoc veřejných dat DTM.
Název parametru
Popis
Datový typ
Povinný
idZadosti
Identifikátor zaslaný na vstupu
String
Ano
stav
Informace o přijetí požadavku v ISTEM („Požadavek na výdej dat byl přijat ke zpracování v ISTEM“).
String
Ano
Návratové kódy
Kód
Název
Popis
200
Ok
V případě úspěšné validace vstupních parametrů vrací endpoint potvrzení o zpracování se stavovým kódem 200.
400
Bad request
Zasílat kód 400 v případě aplikační chyby na straně ISTEMU
401
Unauthorized
Zasílat kód 401 v případě chyby autorizace volajícího
500
Internal server error
Zasílat kód 500 v případě výskytu chyby na straně serveru.
Odkazy na další dokumenty
Název dokumentu
Popis
Verze
IA - výdej dat - eVydej – REST.docx
Dokument popisuje endpointy REST API, určené pro zaslání výsledku zpracování požadavku na výdej dat DTM na straně aplikace „e-Vydej“.
1.1.
Strana 7 (celkem 9)