Sekce infrmatiky Odbr infrmačních systémů Vykazvání dat prstřednictvím SDNS Web Services Příručka uživatele (prgramátra) verze 1.8 Autr: Zdeněk Teska (NESS Czech s.r..) Jiří Smlík (ČNB) prsinec 2012
Vykazvání dat prstřednictvím SDNS Web Services Verze dkumentu: Verze Datum Autr Část, ppis změny 1.0 11.10.2007 Z. Teska (NESS Czech s.r..) Verze 1.0 1.1 14. 02.2008 J.Smlík (ČNB, dbr 722) Drbné věcné a frmální dplňky a úpravy 1.2 19.02.2008 J.Smlík (ČNB, dbr 722) Úpravy v dst. 3.3.4 a 3.4.3.4, změněn příklad v přílze 7 1.3 6.10.2008 J.Smlík (ČNB, dbr 722) Drbné frmální úpravy a pravy 1.4 2.12.2008 J.Smlík (ČNB, dbr 722) Drbné zpřesnění v dst. 3.4.1 1.5 2.12.2009 J.Ivanvvá (ČNB, dbr 722) Dplnění úprav pr dělitelné výkazy: Úpravy v dst. 3.3.4 a v přílze 3 1.6 9.5. 2011 J.Ivanvvá (ČNB, dbr 722) Dplnění úpravy služby Výsledky zpracvání. D služby byly dplněny detaily výsledků frmátvých kntrl, 3.4.3.4. Dplnění nvé služby Seznam dšlých zpráv s chybu v hlavičce, nvá kapitla 3.5 Aktualizace Přílhy 5 Dplnění Přílhy 8,9 Přejmenvání půvdní přílhy 8 na 10. 1.7 16.4.2012 J.Ivanvvá (ČNB, dbr 722) Úprava WS Zasílání dat : dplnění vhdnějšíh frmátu dat pr velké zprávy 1.8 29.11.2012 J. Diviš (ČNB, dbr 722) Aktualizace přílhy 3 Přílhy: 1. WSDL definice webvé služby Zaslání dat 2. WSDL definice webvé služby Výsledky zpracvání 3. DTD definice vydani.dtd a schéma vydani.xsd 4. XML schéma ews-par.xsd 5. XML schéma ews-result.xsd 6. DTD definice dpvědi WS Zaslání dat 7. Příklad předávací XML struktury 8. Příklad ews-result-vydani_seznam_jh 9. Příklad ews-par-dz_err_seznam.xml, ews-result-dz_err_seznam.xml 10 Příklady ptimalizvané předávací XML struktury 11 Uživatelská dkumentace SDNS 2
Vykazvání dat prstřednictvím SDNS Web Services OBSAH 1. ÚVOD - ÚČEL A OBSAH DOKUMENTACE 5 2. KONCEPCE AUTOMATIZOVANÉHO SBĚRU DAT 6 2.1 SCHÉMA KOMPONENT AUTOMATIZOVANÉHO SBĚRU DAT 6 3. ROZHRANÍ SDNS-WS 8 3.1 SDNS-WS CHARAKTERISTIKA 8 3.2 BEZPEČNOST 8 3.3 SLUŽBA ZASLÁNÍ DAT 8 3.3.1 Ppis 8 3.3.2 Pžadavek 9 3.3.2.1 Parametry 9 3.3.3 Odpvěď 10 3.3.3.1 Frmát 10 3.3.3.2 XML struktura dpvědi 10 3.3.4 Pdrbnější rzbr k DTD definici vydani.dtd 11 3.4 SLUŽBA VÝSLEDKY ZPRACOVÁNÍ 16 3.4.1 Ppis 16 3.4.2 Metda getparams 16 3.4.2.1 Ppis 16 3.4.2.2 Parametry 16 3.4.2.3 Odpvěď - frmát 17 3.4.2.4 XML struktura dpvědi 17 3.4.3 Metda perfrmquery 17 3.4.3.1 Ppis 17 3.4.3.2 Parametry 17 3.4.3.3 Odpvěď - frmát 18 3.4.3.4 XML struktura dpvědi (uváděn jen pr VYDANI_SEZNAM_JH) 18 3
Vykazvání dat prstřednictvím SDNS Web Services 3.5 SLUŽBA SEZNAM DOŠLÝCH ZPRÁV S CHYBOU V HLAVIČCE 20 3.5.1 Ppis 20 3.5.2 Metda getparams 20 3.5.2.1 Ppis 20 3.5.2.2 Parametry 20 3.5.2.3 Odpvěď frmát stejné jak pr Výsledky zpracvání 20 3.5.2.4 XML struktura dpvědi stejné jak Výsledky zpracvání 20 3.5.3 Metda perfrmquery 21 3.5.3.1 Ppis 21 3.5.3.2 Parametry 21 3.5.3.3 Odpvěď - frmát 21 3.5.3.4 XML struktura dpvědi (pr DZ_ERR_SEZNAM_JH) 21 4. DOPLŇUJÍCÍ INFORMACE 23 4.1 URL 23 4.2 STAVOVÉ KÓDY ODPOVĚDI WS ZASLÁNÍ DAT 23 4.3 PŘÍLOHY 23 4
Vykazvání dat prstřednictvím SDNS Web Services 1. Úvd - účel a bsah dkumentace Pr účel sběru dat d nebankvních subjektů (dále pužívána zkratka SDNS) je realizvána internetvá aplikace SDNS, umžňující vykazujícím subjektům zbrazvat si metdické infrmace a zasílat pžadvaná data d ČNB prstřednictvím webvéh rzhraní. Nad aplikací SDNS existuje dále rzhraní realizvané technlgií Web Services (dále pužívána zkratka SDNS-WS), které umžňuje vykazujícím subjektům získávat metdické infrmace autmatizvaně v pdbě XML subrů. Přestže aplikace SDNS pskytuje vykazujícím subjektům veškeru ptřebnu funkcinalitu pr vykázání dat (prezentace metdických infrmací, manuální vyplnění výkazů, imprt dat připravených jinu aplikací, deslání dat, infrmvání výsledcích zpracvání), je určena především pr menší bjemy dat a interaktivní bsluhu. Především pr účely sběru dat bchdech na kapitálvém trhu byla aplikace SDNS rzšířena rzhraní SDNS-WS s webvu službu umžňující vykazujícím subjektům zasílání dat. V tét dkumentaci je ppsána základní kncepce autmatizvanéh sběru dat a způsb využití SDNS-WS pr vykazvání dat d ČNB a získávání infrmací výsledcích zpracvání vykázaných dat. 5
Vykazvání dat prstřednictvím SDNS Web Services 2. Kncepce autmatizvanéh sběru dat 2.1 Schéma kmpnent autmatizvanéh sběru dat Na následujícím brázku je uveden jednduché schéma kmpnent systému sběru dat d nebankvních subjektů d ČNB. V dalších kapitlách je detailně ppsána kmpnenta SDNS-WS. Základem výkaznictví ČNB je infrmační systém ČNB (IS ČNB), který zabezpečuje veškeru funkcinalitu spjenu s výkaznictvím na straně ČNB. Jádrem systému vlastníh sběru dat je kmpnenta Aplikace SDNS, rzšířená rzhraní SDNS-WS. Na straně vykazujícíh subjektu jsu d sběru dat zapjeny kmpnenty IS vykazujícíh subjektu jak zdrj dat a Autmatizace sběru dat jak kmunikační kmpnenta na straně vykazujícíh subjektu. Některé činnsti nelze autmatizvat (registrace subjektu, uživatele, správa uživatelskéh účtu) - na straně vykazujícíh subjektu je nutná sučinnst dpvědné sby. Vykazující subjekt Odpvědná sba IS vykazujícíh subjektu Autmatizace sběru dat Rzhraní Aplikace SDNS SDNS-WS ČNB IS ČNB Kmpnenty řešení je mžn rzdělit d tří vrstev ČNB Rzhraní Vykazující subjekt. Vrstva značená Vykazující subjekt je v kmpetenci každéh vykazujícíh subjektu, statní dvě vrstvy jsu v kmpetenci ČNB. Ppis kmpnent IS ČNB zabezpečuje funkcinalitu suvisející s výkaznictvím na straně ČNB (především tvrbu metdiky a zpracvání dat). 6
Vykazvání dat prstřednictvím SDNS Web Services Rzhraní mezi ČNB a vykazujícím subjektem je tvřen dvěma kmpnentami: Aplikace SDNS internetvá aplikace pskytuje vykazujícím subjektům následující hlavní funkce: prezentace metdických infrmací (veřejná část) autentifikace a autrizace k přístupu d registrvané části prezentace přehledu pžadavků (registrvaná část) ruční vyplnění výkazu (registrvaná část) imprt dat (v XML) připravených aplikací vykazujícíh subjektu (registrvaná část) mžnst dpčtu sučtvých buněk (registrvaná část) předběžné prvedení jednvýkazvých kntrl před desláním výkazu (registrvaná část) sestavení zprávy v XML a deslání, včetně elektrnickéh pdpisu (registrvaná část) přehled výsledků zpracvání (registrvaná část) registrace a administrace uživatelských účtů tat část aplikace je využívána i v případě autmatizvanéh zasílání dat prstřednictvím Web Services. SDNS-WS. Rzhraní je realizván technlgií Web Services - vykazující subjekt má dispzici ppis služby v jazyce WSDL a musí si vytvřit klientsku aplikaci pr kmunikaci s tut službu. Rzhraní pskytuje následující služby: zaslání vykazvaných dat d ČNB získání infrmací výsledcích zpracvání. Vykazující subjekt IS vykazujícíh subjektu infrmační systém, který je zdrjem dat pr výkaznictví ČNB. Autmatizace sběru dat kmpnenta, která v nějaké pdbě pskytuje alespň následující funkce: imprt/transfrmace zdrjvých dat klient pr kmunikaci s rzhraním SDNS-WS sestavení zprávy v XML frmátu a deslání pmcí Web Service klienta sestavení a deslání dtazu na výsledky zpracvání (pět pmcí Web Service klienta) reakce na výsledek dtazu zpracvání. Odpvědná sba jeden neb něklik pracvníků vykazujícíh subjektu, kteří musí zajišťvat: registrace subjektu v ČNB registrace uživatele pužívajících a) registrvaný přístup d SDNS, b) SDNS-WS správa uživatelskéh účtu prstřednictvím SDNS sbní kmunikace s ČNB při řešení prblémů spjených s vykazváním dat. 7
Vykazvání dat prstřednictvím SDNS Web Services 3. Rzhraní SDNS-WS 3.1 SDNS-WS charakteristika Rzhraní SDNS-WS je realizván technlgií Web Services. Pžadavek na službu lze deslat SOAP prtklem (SOAP verze 1.1). Kmunikačním prtklem je prtkl HTTPS. Webvé služby jsu ppsány jazykem WSDL (verze 1.1, wsdl definice viz WSDL definice webvé služby Zaslání dat, WSDL definice webvé služby Výsledky zpracvání, Seznam DZ s chybu v hlavičce ). Rzhraní SDNS-WS bsahuje 2 služby: EwiQueryWS, ZaslaniDat. Služba ZaslaniDat umžňuje zaslat data výkazů d ČNB, služba EwiQueryWS umžňuje získat infrmace výsledku zpracvání zaslaných dat. Zmíněné definice jsu uvedeny v přílhách. 3.2 Bezpečnst Zabezpečení systému na straně vykazujícíh subjektu je v kmpetenci tht subjektu. Kmunikace s aplikací SDNS i rzhraním SDNS-WS je vedena prtklem HTTPS, server se prkazuje servervým certifikátem ČNB. Samtná vykazvaná data mhu být zasílána jak digitálně pdepsaná. Vlba vlitelnsti/pvinnsti desílat data digitálně pdepsaná je mim rzsah tht dkumentu (závisí na příslušné legislativě), rzhraní SDNS-WS umžňuje nastavit vynucení puze digitálně pdepsaných dat. Přístup d registrvané části aplikace SDNS i deslání pžadavků prstřednictvím SDNS-WS je zajištěn uživatelským jménem a heslem. Uživatel musí být registrván v ČNB. V případě, že uživatel desílá data digitálně pdepsaná, musí být v ČNB registrván i certifikát, kterým jsu data pdepsána. 3.3 Služba Zaslání dat 3.3.1 Ppis Služba pskytuje jednu metdu typu RPC, která umžňuje zaslat vykazvaná data d ČNB. Zdrjem dat je XML subr vyhvující definici ppsané v DTD subru vydani.dtd (viz DTD definice vydani.dtd v přílze č. 3). Subr může být pdepsán s následně kmprimván. Výsledný binární tvar musí být kódván algritmem Base64. Takt kódvaný tvar zdrjvých dat je jedním z parametrů vlání služby. Dalšími parametry jsu: jmén subru, autrizační údaje (username, passwrd), kódvé značení frmy digitálníh pdpisu, kódvé značení pužitéh kmprimačníh algritmu detailní ppis parametrů viz níže. Odesláním SOAP pžadavku na URL služby jsu data zaslána d ČNB. Služba je typu RPC, server vygeneruje SOAP dpvěď, která má pdbu řetězce ve frmátu XML. Odpvěď vyhvuje DTD definici ppsané v subru ZaslaniDatOdpved.dtd (viz DTD definice dpvědi WS Zaslání dat v přílze č. 6). Odpvěď bsahuje jmén subru (zkpírván z pžadavku), datum a čas přijetí pžadavku, datum a čas deslání dpvědi, stavvé infrmace zpracvání pžadavku (status + něklik hlášení) detailní ppis bsahu dpvědi viz níže. 8
Vykazvání dat prstřednictvím SDNS Web Services 3.3.2 Pžadavek 3.3.2.1 Parametry becně - všechny řetězcvé parametry mají mezenu maximální délku na 500 znaků při překrčení maximální délky je pžadavek dmítnut status categry = Invalid parameters (viz Odpvěď). filename zipmethd pvinný case-sensitive řetězec význam - jmén subru včetně přípny, jak přípna je chápán pdřetězec za psledním výskytem znaku ".". Tt zaslané jmén subru reprezentuje zaslaná data v IS ČNB má význam lgickéh pjmenvání zaslaných dat. Jmén subru nemusí suhlasit s fyzickým jménem XML subru bsahujícím data, ani žádným jiným fyzickým jménem subru vystupujícím v dalším prcesu přípravy dat před desláním (tj. digitální pdpis, kmprimace, Base64 kódvání) další pžadavky na syntaxi hdnty parametru: pvinný přípna musí mít hdntu "xml" vlastní jmén subru (část bez přípny) musí vyhvvat masce "ws(nnn)[0-9]{7} ", kde nnn je třímístný numerický kód přidělený ČNB vykazujícímu subjektu, sedmimístná numerická hdnta následující za tímt kódem musí být unikátní v rámci všech zpráv (=subrů) zasílaných subjektem; dpručujeme pužít hdntu elementu <CISLO-ZPRÁVY> z hlavičkvé části zasílaných dat (viz dst. 3.3.4 Pdrbnější rzbr k DTD definici vydani.dtd ). case-sensitive řetězec musí nabývat jedné ze tří hdnt ZIP / GZIP / DEFLATE / NONE význam hdnt určuje algritmus, kterým jsu kmprimvána data; pr implementaci na straně ČNB je pužita J2SE 1.4 (1.4.2_06) - bližší specifikace k uvedeným algritmům ZIP/GZIP/DEFLATE je uvedena na adrese http://java.sun.cm/j2se/1.4.2/dcs/api; hdnta NONE = nekmprimván. signaturemethd username pvinný case-sensitive řetězec musí nabývat jedné ze dvu hdnt: PKCS7, NONE význam hdnt určuje specifikaci, pdle které jsu data digitálně pdepsána: PKCS7 pdpis dpvídá RFC3852(Cryptgraphic Message Syntax (CMS)); hdnta NONE = data nejsu pdepsána. pvinný case-insensitive řetězec 9
Vykazvání dat prstřednictvím SDNS Web Services passwrd inputdata význam - viz uživatelská dkumentace k aplikaci SDNS, část "Veřejný a registrvaný přístup", kapitla Registrvaný přístup s certifikátem vydaným veřejnu certifikační autritu (https://apl.cnb.cz/ewi/dc/index.htm). pvinný case-sensitive řetězec význam - viz uživatelská dkumentace k aplikaci SDNS, část "Veřejný a registrvaný přístup", kapitla Registrvaný přístup s certifikátem vydaným veřejnu certifikační autritu (https://apl.cnb.cz/ewi/dc/index.htm). pvinný binární data kódvaná algritmem Base64 význam vlastní vykazvaná data; vstupem je XML subr dpvídající definici "vydani.dtd" (viz DTD definice vydani.dtd v přílze č. 3; ppis elementů viz dst. 3.3.4 Pdrbnější rzbr k DTD definici vydani.dtd ), subr může být digitálně pdepsán, pdepsaná neb nepdepsaná data mhu být následně kmprimvána. Pkud jsu data pdepsána, musí mít parametr signaturemethd hdntu PKCS7 a výsledná data musí vyhvvat uvedenému standardu. Pkud jsu následně data kmprimvána (ať pdepsaná, či nepdepsaná), musí parametr zipmethd nabývat jedné z hdnt (ZIP/ GZIP/ DEFLATE) a výsledná data musí vyhvvat uvedeným standardům. Výsledná data musí být vždy kódvána algritmem Base64. language, cuntry pvinné case-sensitive řetězce, splňující specifikaci ISO-639 (ISO language cdes), resp. ISO-3166(ISO cuntry cdes) význam určení lkalizace dpvědi; dvjice parametrů má vliv puze na lkalizvanu pdbu hlášení v dpvědi, stavvé kódy bsažené v dpvědi lkalizvané nejsu; pkud dvjice parametrů neurčuje některu z pdprvaných lkalizací (aktuálně jsu pdprvány lkalizace jsu cs_cz, en_us), není pžadavek dmítnut jak chybvý, ale míst pžadvané lkalizace je pužita default lkalizace (default lkalizace je dána aktuálním nastavením na straně ČNB). 3.3.3 Odpvěď 3.3.3.1 Frmát Odpvěď je řetězec v XML frmátu vyhvující definici ppsané v DTD subru ZaslaniDatOdpved.dtd (viz DTD definice dpvědi WS Zaslání dat ). Řetězec je kódvaný algritmem Base64. 3.3.3.2 XML struktura dpvědi <LadDataRespnse> rt element <filename> pvinný 10
Vykazvání dat prstřednictvím SDNS Web Services case-sensitive řetězec kpírvaný z pžadavku. <requestreceived> pvinný význam datum a čas přijetí pžadavku (čas aplikačníh serveru ČNB) s přesnstí na tisíciny, frmát dd.mm.yyyy HH:mm:ss,SSS pdle specifikace J2SE. <respnsesent> <status> pvinný význam datum a čas vygenervání dpvědi (čas aplikačníh serveru ČNB) s přesnstí na tisíciny, frmát dd.mm.yyyy HH:mm:ss,SSS pdle specifikace J2SE. pvinný case-sensitive řetězec význam status zpracvání pžadavku; má dva atributy: categry (kategrie stavu), cde (knkrétní stavvý kód v rámci dané kategrie). Hdnty atributů specifikují status, jsu v angličtině, nejsu lkalizvány, seznam kategrií a stavvých kódů viz dst. 4.2 Stavvé kódy dpvědi WS Zaslání dat. <messages> nepvinný nemá vlastní hdntu. <message> nepvinný, 0 neb něklik význam hlášení ze zpracvání pžadavku; má dva atributy: type (typ hlášení, může nabývat jedné z hdnt: errr / warn / inf ), value (bsah hlášení). Hdnta atributu type není lkalizvána, hdnta atributu value je lkalizvána pdle pžadvané lkalizace zaslané v pžadavku (viz parametry pžadavku: language, cuntry). 3.3.4 Pdrbnější rzbr k DTD definici vydani.dtd <VYDANI> - rt element <IDENTIFIKACE-ZPRÁVY> - element ppisující zasílaná data v kntextu zprávy desílané d ČNB <ZASLAL> - identifikace zasílajícíh subjektu numerický kód (většinu se pužívá IČO) přidělený vykazujícímu subjektu při registraci v ČNB <CISLO-ZPRAVY> - sekvenční unikátní čísl zprávy v rámci zasílajícíh subjektu; zdpvědnst za udržvání unikátníh číslvání desílaných zpráv má vykazující subjekt, zprávy sduplicitním číslem budu dmítnuty při zpracvání (při kntrle hlavičky) 11
Vykazvání dat prstřednictvím SDNS Web Services <CASTECNA-ZPRAVA PORADI=1 TYP= První > - nepvinný element bsahující hdnty přadí zprávy a příznak první resp. pslední zprávy. Element Částečnázpráva se pužívá při zasílání extrémně velkých výkazů, které musí být z důvdů technlgických limitů rzděleny d něklika zpráv, tzv. dělitelné výkazy. Atributy mhu nabývat hdnt: PORADI je kladné čísl, Typ je nepvinný a může nabývat hdnt První a Pslední. Atribut přadí uvádí přadí zprávy v sekvenci zpráv zaslaných k dělenému vydání výskytuvýkazu. <CISLO-VYDANI> - identifikace vydání výskytu výkazu vpřípadě, že je slžen z více zpráv. Nepužívá se, pkud je vydání výskytu tvřen jednu zprávu. <NAZEV-DOKUMENTU> - prázdný element; atribut KOD musí mít hdntu Vydání-výskytu-výkazu <METODIKA> - pjem výkaznictví ČNB; kód metdiky, pdle které je sestaven výkaz. Např. MKT20071101.01. Kód metdiky začíná značením blasti vykazvání, následuje datum začátku platnsti metdiky, za tečku následuje čísl verze (zpravidla 01). K nalezení je např. v aplikaci SDNS (https//apl.cnb.cz/ewi ), plžka menu Metdické infrmace, zvlí se Oblast. Obdbí platnsti metdiky musí dpvídat datu, ke kterému se data výkazu zasílají, viz níže atribut <STAV-KE-DNI> <FUNKCE-ZPRAVY> - prázdný element; atribut KOD musí nabývat jedné z hdnt Ostrá / Testvací pdle th, zda jsu zasílána strá neb testvací data <DATUM> - datum vytvření dat pdle masky yyyymmdd ; nemusí suhlasit s datem desílání dat d ČNB ani s hdntu atributu STAV-KE-DNI (viz níže). <ADRESA> - element ppisující subjekty, které se účastní prcesu vykazvání dat: - atribut STRANA musí mít hdntu Odesílatel <KOD-SUBJEKTU> - zpravidla IČO vykazujícíh subjektu <NAZEV-SUBJEKTU> - <MESTO> - <PSC> - <ULICE> - <KONTAKT> - definuje kntaktní sbu zdpvědnu za výkaz; nemusí t být tatáž sba, která výkaz desílá (tj. ta jejíž autentifikační údaje jsu pužity při zasílání dat). Element nemusí být vyplněn, pkud je vyplněn, má při zpracvání ten význam, že v případě řešení nejasnstí spjených se zpracváním dat umžní pracvníkvi ČNB kntaktvat tut dpvědnu sbu - atribut KOD-FUNKCE musí mít hdntu Osba-dpvědná-za-bsah <KOD-ODDELENI> - kód rganizační jedntky sby zdpvědné za bsah <JMENO-OSOBY> - jmén a příjmení sby zdpvědné na bsah <SPOJENI> - vlastní kntaktní infrmace, jejíž hdnta by měla dpvídat vybranému typu (atribut TYP) - atribut TYP by měl nabývat jedné z hdnt: Telefn / Email, ve výjimečných případech i Fax / EDI / Telex. <IDENTIFIKACE-VYKAZU> - element ppisující zasílaná data v kntextu výkaznictví ČNB 12
Vykazvání dat prstřednictvím SDNS Web Services <DATOVY-SOUBOR> - pjem výkaznictví ČNB; kód výkazu, např. MOKAS50.01.00. Kód datvéh subru je k nalezení např. v aplikaci SDNS (https://apl.cnb.cz/ewi ), plžka menu Metdické infrmace, zvlí se Oblast. V přehledu datvých subrů se kliknutím na žlutu šipku na začátku řádky vybere knkrétní datvý subr, kliknutím na plžku Detail se zbrazí pdrbnější infrmace včetně čísel verze a varianty datvéh subru. <VYSKYT> - pjem z výkaznictví ČNB; určuje unikátní instanci výkazu <SUBJEKT> - kód vykazujícíh subjektu, za který se data výkazu zasílají (zpravidla IČO) <ROZSAH-SUBJEKTU> kód rzsahu vykazujícíh subjektu, za který se data výkazu zasílají, např. S_BCRPZB. Kód je k nalezení např. v aplikaci SDNS (https://apl.cnb.cz/ewi ), plžka menu Metdické infrmace, zvlí se Oblast. V přehledu datvých subrů se kliknutím na žlutu šipku na začátku řádky vybere knkrétní datvý subr, kliknutím na plžku Vykazvací pvinnsti se zbrazí pdrbnější infrmace, řádek s parametrem P0046 bsahuje rzsah vykazujícíh subjektu. <STAV-KE-DNI> - datum, ke kterému se data výkazu zasílají (vztahují), maska yyyymmdd <STATUS> - atribut KOD určuje jaká data se zasílají; musí nabývat jedné z hdnt: Nvá-data / Oprava / Strn /, Ptvrzení / Změnvá-prava / Strn-DZ. Pkud bude vyplněna hdnta Nvá-data, nesmí být krmě dělitelných výkazů vyplněn element <REFERENCNI-ZPRAVA>. Hdnty Změnvá-prava, Strn- DZ a Nvá-data s referencí na aktuální vydání je mžn pužít puze pr dělené výkazy, tj. výkazy s Identifikačním parametrem zajišťujícím jednznačnu identifikací řádků. Infrmace dělitelnsti je k nalezení např. v aplikaci SDNS (https://apl.cnb.cz/ewi ), plžka menu Metdické infrmace, zvlí se Oblast. V přehledu datvých subrů se kliknutím na žlutu šipku na začátku řádky vybere knkrétní datvý subr, kliknutím na plžku Detail se dle zbrazí Dělitelnst: An V případě, že zpracvání půvdních nvých dat sknčil a) dmítnutím dat při vlání Web Service, b) data byla prstřednictvím Web Service přijata, ale zpracvání sknčil chybu hlavičky dšlé zprávy (tt lze zjistit prstřednictvím SDNS neb vláním SDNS-WS služby DZ_ERR_SEZNAM_JH ), je nutn data pslat znvu jak Nvá-data, nebť IS ČNB je dmítl jak celek, není c pravvat. Hdnta Oprava se může pužít v případech, kdy zpráva s nvými daty nebyla dmítnuta, ale byly zjištěny: a) frmátvé chyby v těle zprávy, b) lgické chyby v těle zprávy (jednvýkazvé kntrly typu Opravit ), c) lgické chyby v těle zprávy (jednvýkazvé kntrly typu Ptvrdit ) neb pdezřelé hdnty zjištěné při kntrlách časvých řad, které dle zjištění vykazujícíh subjektu je třeba pravdu pravit neb d) z rzhdnutí vykazujícíh subjektu, když zjistí, že dříve zaslaná a ČNB přijatá data nebyla správná, e) z rzhdnutí vykazujícíh subjektu, když zjistí, že dříve zaslaná a ČNB přijatá data dělenéh vydání byla chybná. Lze pravit knkrétní zprávu předchzíh dělenéh vydání. Ve většině případů se psílají všechna data danéh datvéh subru znvu. Ve výjimečných případech např. datvé subry MOKAS50 a MOKAS40 s hlášeními bchdech na kapitálvém trhu, se v případech chyb zjištěných kntrlami typu lkálně pravit v rámci pravy zasílají jen data chybných řádků/transakcí a 13
Vykazvání dat prstřednictvím SDNS Web Services případně i dplňky již zaslaných dat. Pkud bude vyplněna hdnta Oprava, musí být vyplněn element <REFERENCNI-ZPRAVA>. Vyplňuje se reference na knkrétní předchzí zprávu. Hdnta Ptvrzení se pužívá v případě, že vykazující subjekt trvá na tm, že zjištěné nesrvnalsti v časvých řadách neb v lgických kntrlách typu K ptvrzení jsu v přádku. Těl zprávy (element DATA, viz níže) se v tmt případě vynechává. Pkud bude vyplněna hdnta Ptvrzení, musí být vyplněn element <REFERENCNI-ZPRAVA>. Vyplňuje se reference na předchzí vydání. Hdnta Strn se může pužít pr lgické strnvání dříve přijatých dat. Pužívá se zcela výjimečně v situacích, kdy jsu přijatá data z phledu vykazujícíh subjektu nesprávná a není mžné ihned prvést jejich pravu. Těl zprávy (element DATA, viz níže) se v tmt případě vynechává. Pkud bude vyplněna hdnta Strn, musí být vyplněn element <REFERENCNI-ZPRAVA>. Vyplňuje se reference na předchzí vydání. Hdnta Změnvá prava se může pužít puze pr dělitelné výkazy. Změnvá prava vydání umžní zaslání změnvéh subru k vydání výskytu výkazu, který bude bsahvat puze skutečné změny, přidané neb rušené řádky. Pr tent účel se pužívá jednznačný identifikátr dynamickéh řádku, který umžní jednduše identifikvat dynamické řádky a zasílat změny. Pkud bude vyplněna hdnta Změnvá-prava, musí být vyplněn element <REFERENCNI-ZPRAVA>. Vyplňuje se reference na předchzí vydání. Hdnta Strn-DZ se může pužít puze pr dělitelné výkazy. Hdnta Strn- DZ se může pužít pr lgické strnvání části dříve přijatých dat. Těl zprávy (element DATA, viz níže) se v tmt případě vynechává. Pkud bude vyplněna hdnta Strn-DZ, musí být vyplněn element <REFERENCNI-ZPRAVA>. Vyplňuje se reference na knkrétní zprávu předchzíh vydání. <DUVOD> - atribut KOD určuje důvd zasílání dat; musí nabývat jedné z hdnt Na-základě-metdiky / Na-základě-pžadavku-centrální-banky / Úmyslvykazujícíh-subjektu. Hdnta Na-základě-metdiky se pužije pr zaslání nvých dat (STATUS.KOD = Nva-data ). Hdnta Na-základě-pžadavku-centrální-banky se pužije při zaslání pravy (STATUS.KOD = Oprava, Ptvrzení, příp. i Strn resp. Strn-DZ, Změnvá-prava ) z důvdu pžadavku ČNB (autmatizvaně zjištěné chyby, případně i pravy pžadvané pracvníky ČNB). Hdnta Úmysl-vykazujícíhsubjektu (STATUS.KOD = Oprava, Strn resp. Strn-DZ, Změnváprava ) se pužije v případě, že rzhdnutí pravě neb strnu dat vychází z úmyslu vykazujícíh subjektu. <REFERENCNI-ZPRAVA> - pužije se při zasílání pravy dat, ptvrzení, strna neb strna dšlé zprávy; dkazuje na hdntu elementu <CISLO-ZPRÁVY> neb <CISLO-VYDANI> předchzích zasílaných dat. Pr dělené výkazy je mžné pužít jak Opravu dplněním Nvá data s referencí na předchzí vydání. Pzn.: v případě dat psílaných vjedné zprávě <CISLO-ZPRÁVY> je i <CISLO- VYDANI> <AUDIT> - mžné hdnty jsu Data-před-auditem a Data-p-auditu. Ve většině případů (závisí t na legislativě) není tt rzlišvání pžadván; pkud není vyžadván nevyplňvat. <DATA> - element bsahuje vlastní data výkazu; skládá se z datvých blastí (element <DATOVA-OBLAST> neb alternativně DO_COMPRESSED pr velké subry. Nvu 14
Vykazvání dat prstřednictvím SDNS Web Services reprezentaci lze případně zvlit i jen pr jedntlivé datvé blasti) neb blků (element <BLOK>) <DATOVA-OBLAST> - pjem výkaznictví ČNB, dpvídá pjmu tabulka výkazu ); element bsahuje data jedné datvé blasti výkazu; skládá se z řádků (element <RADEK>) - atribut KOD bsahuje kód datvé blasti. Kód je k nalezení např. v aplikaci SDNS (https://apl.cnb.cz/ewi ), plžka menu Metdické infrmace, zvlí se Oblast. V přehledu datvých subrů se kliknutím na žlutu šipku na začátku řádky vybere knkrétní datvý subr, kliknutím na plžku Části se zbrazí pdrbnější infrmace, včetně kódů datvých blastí. <RADEK> - element bsahuje data jednh řádku výkazu; skládá se ze slupců (element SLOUPEC) - atribut PORADI určuje přadí tht řádku <SLOUPEC> - element bsahuje hdntu jedné buňky výkazu - atribut PORADI určuje přadí buňky v řádku Neb alternativně pr DO_COPRESSED: <R> pr řádek a <S> pr slupec. Oba tagy bez atributu určujícíh přadí. Prázdný řádek neb slupec bude uváděn jak prázdný tag s tím, že prázdné řádky na knci datvé blasti a prázdné slupce na knci řádku nebude třeba uvádět. <POZNAMKA> - bvykle nemá element žádný význam, nevyplňvat V SDNS se uplatňuje princip c není zadané, je prázdné, není tedy třeba explicitně zadávat infrmace nevyplnění jedntlivých údajů. Knkrétně: a) Je mžn vynechat celé datvé blasti, pkud jsu prázdné. Například, je-li datvá blast JIS40_11 prázdná, je mžn níže uvedený úsek vynechat: <DATOVA-OBLAST KOD="JIS40_11"> </DATOVA-OBLAST> b) Je mžn vynechat celý řádek datvé blasti, pkud je prázdný. Například, je-li celý řádek 5 prázdný, není třeba příslušný úsek vůbec uvádět (v příkladu vyznačen přeškrtnutím): <RADEK PORADI="4"> <SLOUPEC PORADI="1">06</SLOUPEC> </RADEK> <RADEK PORADI="5"> </RADEK> <RADEK PORADI="6"> <SLOUPEC PORADI="1">14</SLOUPEC> </RADEK> c) Jsu-li v řádku některé údaje prázdné, musí být úsek s příslušným slupcem vynechán. V níže uvedeném příkladu jsu v řádku 6 údaje ve slupcích 9 a 11 až 14 prázdné, příslušné části musí být vynechány (vyznačen přeškrtnutím), nebť daná syntaxe není implementvána.ř <RADEK PORADI="6"> <SLOUPEC PORADI="1">83</SLOUPEC> 15
Vykazvání dat prstřednictvím SDNS Web Services <SLOUPEC PORADI="2">123456789</SLOUPEC> <SLOUPEC PORADI="3">987654321</SLOUPEC> <SLOUPEC PORADI="4">Petr.Nvak@abcd.cz</SLOUPEC> <SLOUPEC PORADI="5">15.08.1968</SLOUPEC> <SLOUPEC PORADI="6">Mgr.</SLOUPEC> <SLOUPEC PORADI="7">0</SLOUPEC> <SLOUPEC PORADI="8">Petr</SLOUPEC> <SLOUPEC PORADI="9"></SLOUPEC> <SLOUPEC PORADI="10">Nvák</SLOUPEC> <SLOUPEC PORADI="11"></SLOUPEC> <SLOUPEC PORADI="12"></SLOUPEC> <SLOUPEC PORADI="13"></SLOUPEC> <SLOUPEC PORADI="14"></SLOUPEC> </RADEK> 3.4 Služba Výsledky zpracvání 3.4.1 Ppis Služba pskytuje dvě metdy typu RPC (v jazyce WSDL messages): getparams, perfrmquery, které umžňují získat infrmace výsledcích zpracvání vydání k výskytu. Jeden dtaz na infrmace výsledku zpracvání (v lgickém smyslu) se skládá ze třech (resp. dvu) krků: vlání getparams (vlitelný krk) pkud již parametrická sada na straně vykazujícíh subjektu existuje, není nutné krk prvádět, zadání hdnt parametrů (pvinný krk). Význam a frmát jedntlivých parametrů v parametrické sadě z jejich definice v XML zřejmý. Parametr Datvý subr se zadává bez kódu verze a varianty, tj. např. jen MOKAS40, vlání perfrmquery (pvinný krk). 3.4.2 Metda getparams 3.4.2.1 Ppis Účelem metdy je získat parametricku sadu k danému typu dtazu. Parametrická sada v pdbě XML subru je dpvědí vlání tét metdy. Ppisuje parametry pr vlání metdy perfrmquery. U každéh parametru je definván jmén, datvý typ, maska, rzlišení zda je parametr pvinný či nepvinný, seznam přípustných hdnt (pkud existuje) a hdnta zatím nevyplněná. XML subr vyhvuje schématu ews-par.xsd (viz XML schéma ews-par.xsd ). Uživatel dplní hdnty parametrů a takt upravený XML subr zašle jak vstupní parametr vlání metdy perfrmquery. 3.4.2.2 Parametry querytype pvinný case-insensitive řetězec význam - kód dtazu: VYDANI_SEZNAM_JH. Pznámka: V případě vykazvání více výkazů by se výjimečně mhl uplatnit i VYSKYTY_SEZNAM_JH, jež by umžnit získat infrmace výskytech. 16
Vykazvání dat prstřednictvím SDNS Web Services 3.4.2.3 Odpvěď - frmát řetězec bsahující subr v XML frmátu vyhvující schématu ews-par.xsd (viz XML schéma ews-par.xsd ). Řetězec je kódván algritmem Base64. 3.4.2.4 XML struktura dpvědi <DefiniceDtazu> - rt element <TypDtazu> - hdnta parametru querytype, zkpírvaná z pžadavku <Ppis> - ppis typu dtazu, vysvětluje účel dtazu a c je bsahem dpvědi <Parametr> - něklik výskytů, jeden výskyt elementu ppisuje jeden parametr danéh typu dtazu - atributy Datatyp, Maska ppisují syntaxi hdnty parametru - atributy Nazev název parametru - atribut Pvinny určuje pvinnst/vlitelnst zadání hdnty parametru při vlání metdy perfrmquery <Ppis> - stručný ppis významu parametru <SeznamHdnt> - seznam mžných hdnt parametru, bsahuje jeden neb něklik výskytů subelementu <Hdnta> <Hdnta> - mžná hdnta parametru <HdntaPar/> 3.4.3 Metda perfrmquery 3.4.3.1 Ppis Úklem vykazujícíh subjektu je d dkumentu získanéh pmcí vlání metdy getparams dplnit hdnty parametrů (tj. dplnit hdntu elementů <HdntaPar>) a takt vyplněný subr deslat jak parametr vlání metdy perfrmquery. Výsledkem vlání metdy perfrmquery je pět XML dkument. Tent dkument bsahuje výsledek dtazu. Dkument vyhvuje schématu ews-result.xsd (viz XML schéma ews-result.xsd ). 3.4.3.2 Parametry querytype xmlparam pvinný case-insensitive řetězec význam - kód dtazu: VYDANI_SEZNAM_JH. Pznámka: V případě vykazvání více výkazů by se výjimečně mhl uplatnit i VYSKYTY_SEZNAM_JH, jež by umžnil získat infrmace výskytech pvinný řetězec bsahující subr v XML frmátu vyhvující schématu ews-par.xsd (viz XML schéma ews-par.xsd ). Řetězec je kódván algritmem Base64. 17
Vykazvání dat prstřednictvím SDNS Web Services 3.4.3.3 Odpvěď - frmát řetězec bsahující subr v XML frmátu vyhvující schématu ews-par.xsd (viz XML schéma ews-par.xsd ). Řetězec je kódván algritmem Base64. 3.4.3.4 XML struktura dpvědi (uváděn jen pr VYDANI_SEZNAM_JH) Struktura dpvědi je pdrbně ppsána ve schématu ews-result.xsd (viz XML schéma ewsresult.xsd ), zde je ppsána puze stručně. Lgický význam některých elementů (datvý subr, výskyt, rzsah, vydání, apd.) je mim rzsah tht dkumentu tyt pjmy výkaznictví ČNB jsu ppsány v Uživatelské dkumentaci SDNS (viz Uživatelská dkumentace SDNS)) <EwiWSResult> - rt element <Dtaz> - vdpvědi jsu pd tímt elementem zkpírvány parametry zxml parametrické sady pžadavku s hdntami (krmě hdnty hesla) <VydaniSeznam> - výsledek dtazu <DatvySubr> - identifikace výkazu (kód, verze, varianta) <Kd> <Verze> <Varianta> <Vyskyt> - identifikace výskytu výkazu, jeh stavvé infrmace <Subjekt> - kód vykazujícíh subjektu <Obdbi> - datum, ke kterému byla data vykázána <Rzsah> - rzsah vykázaných dat <StavKd> - numerický kód stavu výskytu: -1 Termín uplynul, k dispzici jsu jen data replikvána 10 Nejsu žádná data, termín dsud neuplynul 15 Nejsu žádná data, je urgván jejich ddání 18 Nejsu žádná data, všechny stupně upmínek vyčerpány 20 Právě je zpracváván vydání k výskytu 30 Je pžadván zaslání ptvrzení dat vykazujícím subjektem 40 Je pžadván zaslání pravy dat vykazujícím subjektem 50 K výskytu jsu platná data 55 Výskyt je uzavřen, jsu platná data, nelze je již změnit 65 Výskyt je prmlčen, nejsu platná data <Stav> - krátký textvý ppis stavu výskytu <PlanD> - pžadvaný termín ddání dat k výskytu <Termin> - aktuální pžadvaný termín ddání dat k výskytu (např. v případě ptřeby pravy) <Testvaci> - kódvé značení Testvací/Ostrý výskyt <Vydani> <SubrExt> - jmén subru (včetně přípny) zprávy, ve které byla data zaslána; je shdné s hdntu parametru filename th vlání služby Zaslání dat, kterým byla data zaslána 18
Vykazvání dat prstřednictvím SDNS Web Services <CislVydani> - numerické čísl vydání, unikátní v rámci vykazujícíh subjektu <DatumPrijmu> - datum a čas přijetí dat d zpracvání (maska dd.mm.yyyy HH:mi ); není t tentýž kamžik jak příjem zprávy prstřednictvím webvé služby Zaslání dat (ten je uveden v dpvědi vlání tét služby); mezi přijetím zprávy prstřednictvím webvé služby a časem přijetí d zpracvání je určitá technlgická prdleva za nrmálních klnstí něklik minut, může být všem větší <StavKd> - numerický kód stavu vydání -1 Replikvané vydání vzniklé z psledních platných hdnt danéh datvéh subru 0 Fiktivní vydání pr dšlé zprávy typu strn, ptvrzení aj. 5 Data vydání připravena uživatelem SDNS, data nejsu v db 10 Vydání zalžen 15 Fatální chyba v JVK (např. dělení nulu) 16 Zjištěny chyby v JVK, pžadavek na pravu dat 17 Zjištěny chyby v JVK, pžadavek na ptvrzení 18 t.č. nepužíván 19 V rámci JVK nebyla zjištěna chyba 31 Data jsu ulžena v db a je pžadván jejich ptvrzení z důvdu chyby v JVK 32 Data jsu ulžena v db a je pžadván jejich ptvrzení z důvdu chyby v KČŘ 51 Data jsu ulžena v db a jsu platná 52 Data jsu ulžena v db a jsu platná (byla ptvrzena) 59 Data byla strnvána 61 Chybné vydání, jehž data nebyla ulžena d db 62 Strnvané vydání před ptvrzením dat 99 Interní chyba, vydání není mžné zpracvat <Stav> - krátký textvý ppis stavu výskytu <StavOd> - datum a čas, d kdy je vydání v uvedeném stavu (maska dd.mm.yyyy HH:mi ) <Druh> - kódvé značení Odeslané/Připravené vydání <ChybaZpracvani> - chybvé hlášení ze zpracvání vydání (kód, text chyby); element <Vydani> může bsahvat 0..n těcht subelementů 19 <DetailChyby> - Detail chyby zpracvání bsahuje identifikaci řádku, na kterém byla chyba zjištěna <ChybnyKrkKntrly> - element bsahuje ppis s chybnéh krku kntrly včetně jednh neb více detailních hlášení k dané chybě; element <Vydani> může bsahvat 0..n těcht subelementů <DetailChyby> - Detail chyby krku kntrly bsahuje identifikaci řádku, na kterém byla chyba zjištěna <ErrrLg> - stavvé infrmace vztahující se ke zpracvání pžadavku (chybné parametry, neúspěšné přihlášení, nespecifikvaná interní chyba, úspěšné zpracvání)
Vykazvání dat prstřednictvím SDNS Web Services 3.5 Služba Seznam Dšlých Zpráv s chybu v hlavičce 3.5.1 Ppis Služba pskytuje dvě metdy typu RPC (v jazyce WSDL messages): getparams, perfrmquery, které umžňují získat infrmace výsledcích zpracvání dšlých zpráv, které sknčil chybu hlavičky zprávy. Jeden dtaz na infrmace výsledku zpracvání (v lgickém smyslu) se skládá ze tří (resp. dvu) krků: vlání getparams (vlitelný krk) pkud již parametrická sada na straně vykazujícíh subjektu existuje, není nutné krk prvádět, zadání hdnt parametrů (pvinný krk). Význam a frmát jedntlivých parametrů v parametrické sadě z jejich definice v XML zřejmý, vlání perfrmquery (pvinný krk). 3.5.2 Metda getparams 3.5.2.1 Ppis Účelem metdy je získat parametricku sadu k danému typu dtazu. Parametrická sada v pdbě XML subru je dpvědí vlání tét metdy. Ppisuje parametry pr vlání metdy perfrmquery. U každéh parametru je definván jmén, datvý typ, maska, rzlišení zda je parametr pvinný či nepvinný, seznam přípustných hdnt (pkud existuje) a hdnta zatím nevyplněná. XML subr vyhvuje schématu ews-par.xsd (viz XML schéma ews-par.xsd ). Uživatel dplní hdnty parametrů a takt upravený XML subr zašle jak vstupní parametr vlání metdy perfrmquery. 3.5.2.2 Parametry querytype pvinný case-insensitive řetězec význam - kód dtazu: DZ_ERR_SEZNAM_JH. 3.5.2.3 Odpvěď frmát stejné jak pr Výsledky zpracvání řetězec bsahující subr v XML frmátu vyhvující schématu ews-par.xsd (viz XML schéma ews-par.xsd ). Řetězec je kódván algritmem Base64. 3.5.2.4 XML struktura dpvědi stejné jak Výsledky zpracvání <DefiniceDtazu> - rt element <TypDtazu> - hdnta parametru querytype, zkpírvaná z pžadavku <Ppis> - ppis typu dtazu, vysvětluje účel dtazu a c je bsahem dpvědi <Parametr> - něklik výskytů, jeden výskyt elementu ppisuje jeden parametr danéh typu dtazu - atributy Datatyp, Maska ppisují syntaxi hdnty parametru - atributy Nazev název parametru 20