Popis chyb SOAP rozhraní
Struktura chyb Online serveru
Veřejné služby vystavené přes Online server vrací chyby ve struktuře vOKO:Error.
Příklad chyby pro verzi 2 Online serveru (vysvětlení verzí níže):
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP:Body> <SOAP:Fault> <faultcode xmlns:code="http://www.pds.eu/vOKO/v0200">code:Error</faultcode> <faultstring>Systémová chyba: nastala chyba ve vykonávání služby. Neplatná hodnota pro údaj UsniZnamka. Zvíře s ušní známkou CZ000123456789 a druhem TUR neexistuje.</faultstring> <detail> <vOKO:Error xmlns:vOKO="http://www.pds.eu/vOKO/v0200"> <vOKO:ErrorCode>XERR103</vOKO:ErrorCode> <vOKO:ErrorDescription>Systémová chyba: nastala chyba ve vykonávání služby. Neplatná hodnota pro údaj UsniZnamka. Zvíře s ušní známkou CZ000123456789 a druhem TUR neexistuje.</vOKO:ErrorDescription> <vOKO:DateTime>2025-07-29T11:24:04+02:00</vOKO:DateTime> <vOKO:SID>20250729112404569111</vOKO:SID> <vOKO:SRVid serverID="EPO-MZe"/> <vOKO:vOKOid>IZR_HPT01A</vOKO:vOKOid> <vOKO:ResponseLang>CZE</vOKO:ResponseLang> <vOKO:InnerException> <ESBServerError Source="SourceSystem" Code="1" TimeStamp="2025-07-29T11:24:04.8277477+02:00" xmlns="http://www.mze.cz/ESBServer/1.0"> <Description>Neplatná hodnota pro údaj UsniZnamka. Zvíře s ušní známkou CZ000123456789 a druhem TUR neexistuje.</Description> <BusinessErrors> <Error Code="0">Neplatná hodnota pro údaj UsniZnamka. Zvíře s ušní známkou CZ000123456789 a druhem TUR neexistuje.</Error> </BusinessErrors> </ESBServerError> </vOKO:InnerException> </vOKO:Error> </detail> </SOAP:Fault> </SOAP:Body> </SOAP:Envelope>
Struktura je popsána ve WSDL dokumentu pro danou službu. Element <vOKO:ErrorCode> obsahuje kód chyby, podle kterého lze rozlišit různé chyby vyvolané na EPO serveru. Element <vOKO:ErrorDescription> obsahuje text chyby (chybové hlášení). Doporučení jak by měl konzument naložit s jednotlivými chybami lze nalézt v detailu konkrétní služby.
Pokud chyba vznikla až za EPO serverem (na zdrojovém systému), je v elementu <vOKO:InnerException> vrácena původní chyba. Její původ lze rozlišit podle atributu ESBServerError/@Source. Chyba z ESB serveru obsahuje Source="ESBServer", a vrací se pro chyby technického charakteru (například odstávka systému). Tyto chyby lze ve většině případů řešit opakováním volání služby. Chyba ze zdrojového systému (systém LPIS, IZR nebo jiný) obsahuje zpravidla Source="SourceSystem" (případně jinou hodnotu). Pokud není v chybě obsažen element <BusinessErrors>, jedná se obvykle o chyby technického charakteru, které by měly být přechodné. Pokud element <BusinessErrors> obsažen je, jedná se obvykle o logické chyby služeb (problémy ve vstupních datech, apod.). Při jejich řešení je třeba postupovat dle dokumentace ke konkrétní službě.
Nestandardní chyby
Online server je vystaven ve dvou instancích:
starší: https://epomze.gov.cz/ssl/nosso-app/EPO/WS/Online/vOKOsrv.aspx
novější: https://epomze.gov.cz/ssl/nosso-app/EPO/WS/v2Online/vOKOsrv.ashx
Rozdíl mezi nimi je ve struktuře XML vracených chyb. Starší verze vrací nestandardní chyby kvůli zachování kompatibility rozhraní pro starší klienty. Pro některé chyby je použita nestandardní struktura SOAP:Fault, kde jsou elementy <faultcode>, <faultstring> a <detail> ve špatném namespace, například:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <soap:Fault> <soap:faultcode>X230301</soap:faultcode> <soap:faultstring>Pro volání WS je třeba oprávnění WS_CALL. Pro více informací kontaktujte HelpDesk MZe.</soap:faultstring> <soap:detail> <vOKO:Error xmlns:vOKO="http://www.pds.eu/vOKO/v0200"> <vOKO:ErrorCode>X230301</vOKO:ErrorCode> <vOKO:ErrorDescription>Pro volání WS je třeba oprávnění WS_CALL. Pro více informací kontaktujte HelpDesk MZe.</vOKO:ErrorDescription> <vOKO:DateTime>2025-08-15T11:44:23</vOKO:DateTime> <vOKO:srvAuth>-1</vOKO:srvAuth> <vOKO:SID>20250815134423622121</vOKO:SID> <vOKO:vOKOid>IZR_GAZ01A</vOKO:vOKOid> <vOKO:ErrorLevel>Global</vOKO:ErrorLevel> <vOKO:ResponseLang>CZE</vOKO:ResponseLang> </vOKO:Error> </soap:detail> </soap:Fault> </soap:Body> </soap:Envelope>
Pro chyby při komunikaci s ESB/zdrojovým systémem se vrací struktura odpovídající předchozí (ještě starší) verzi integračního serveru, včetně původního namespace. Element s chybou z ESB serveru/zdrojového systému je vložen dovnitř elementu <vOKO:ErrorDescription>, což je méně vhodné pro zpracování.
Příklad:
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP:Header/> <SOAP:Body> <SOAP:Fault> <faultcode>SOAP:Server</faultcode> <faultstring>Server Error</faultstring> <detail> <vOKO:Error xmlns:vOKO="http://vOKOserver/vOKO/XSD/vOKO/v0100"> <vOKO:ErrorCode>XERR103</vOKO:ErrorCode> <vOKO:ErrorDescription>Systémová chyba: nastala chyba ve vykonávání služby.<ESBServerError Source="SourceSystem" Code="2" TimeStamp="2025-07-21T17:00:53.7628177+02:00" xmlns="http://www.mze.cz/ESBServer/1.0"> <Description>BusinessError</Description> <BusinessErrors> <Error Code="102">Chybně zadané IČO 44772273.</Error> </BusinessErrors> </ESBServerError> </vOKO:ErrorDescription> <vOKO:DateTime>2025-07-21T17:00:53</vOKO:DateTime> <vOKO:version>1.1</vOKO:version> <vOKO:vOKOid>JUP_INSPOH01A</vOKO:vOKOid> <vOKO:SID>20250721170053659121</vOKO:SID> <vOKO:ESID/> <vOKO:RequestID/> <vOKO:SRVid>vOKO-XML-MZe</vOKO:SRVid> <vOKO:errorLevel>global</vOKO:errorLevel> <vOKO:responseLang>CZE</vOKO:responseLang> <vOKO:showXSLTpath>http://vOKOserver/vOKO/XSL/Univerzal_xml.xsl</vOKO:showXSLTpath> <vOKO:showXSLTtype>text/xsl</vOKO:showXSLTtype> <vOKO:XSLTVersion>1_0_0_0</vOKO:XSLTVersion> <vOKO:display/> <vOKO:desc/> </vOKO:Error> </detail> </SOAP:Fault> </SOAP:Body> </SOAP:Envelope>
Kvůli vracení nestandardních struktur nedoporučujeme použití původní verze Online serveru pro nové integrace.
Starším klientům také doporučujeme přejít na novou verzi Online serveru na URI https://epomze.gov.cz/ssl/nosso-app/EPO/WS/v2Online/vOKOsrv.ashx