Popis webových služeb ISPOP pro validaci a podání hlášení

Obsah

1 Úvod

Aplikace ISPOP poskytuje ucelenou sadu webových služeb, které umožňují využít celou řadu funkčností. Tento dokument popisuje způsob napojení na webové služby ISPOP související s podáním do ISPOP, tzn. popisuje sadu webových služeb, které umožňují odeslat hlášení do systému a provést jeho validaci.

2 Dostupnost

Webové služby jsou dostupné na produkčním i testovacím prostředí. Produkční a testovací prostředí obsahují stejné sady webových služeb, na testovacím prostředí mohou být dopředu k dispozici nejnovější aktualizace jak samotných WS, tak validace na formuláře na následující rok, které ještě nejsou nasazené na produknčím prostředí.

Samotné koncové body webové služby (zpracování příchozích požadavků) jsou definovány v příslušném WSDL souboru.

3 Zabezpečení

Některé služby poskytované systémem ISPOP jsou cíleně dostupné bez autorizace (nezabezpečené) – to je vždy uvedeno u konkrétní služby.

U služeb je zabezpečení realizováno na úrovni HTTP protokolu s využitím HTTP Basic (http://www.ietf.org/rfc/rfc2617.txt). Každý uživatel má svůj účet a autorizuje se pomocí jména a hesla; popř. je možné se autorizovat pomocí Cenia Single-Sign-On tokenu ve formě HTTP cookie. Autorizaci pomocí tokenu je zejména vhodné používat, pokud systém třetí strany volá webové služby ISPOP v kontextu přihlášeného uživatele – není nutné znát jméno a heslo, postačí platný token.

Přístup k produkčním službám je šifrován pomocí SSL. Pro přístup k některým službám je nutné mít platné jméno a heslo. Jméno a heslo na produkční prostředí je možné zajistit standardním registračním procesem. Pro získání jména a hesla do testovacího prostředí je nutné se obrátit na provozovatele systému.

Přístup ke službě probíhá na úrovni (1) funkčnosti a (2) v rámci dané funkčnosti se kontroluje k jakým objektům a v jakém rozsahu může uživatel přistupovat.

WSDL pokrývají ucelené oblasti a je běžné, že v rámci jedné oblasti jsou poskytovány metody s různou úrovní zabezpečení, takže určitý uživatel může volat jen určité metody. Jsou aplikována stejné pravidla, jako kdyby uživatel přistupoval přímo do aplikace skrze webové rozhraní.

Webové služby jsou bezstavové a pokud je nějaká stavová informace potřebná na straně klienta, je odpovědností klienta si tuto informaci spravovat a udržovat (například návratové hodnoty volaných metod, jež bývají využity v další komunikaci).

Každému uživateli jsou po přihlášení jménem a heslem (authentication) přiřazeny (authorization) bezpečnostní role, jež definují k jakým funkčnostem a jakým objektům má přístup.

Uživatelé mohou mít více rolí a výsledná oprávnění jsou určena jako sjednocení všech oprávnění, zároveň platí, že nadřazená role (viz níže) přebírá všechny oprávnění podřazené role.

4 Popis služeb ISPOP

Pro podporu při práci s Hlášením vznikla sada webových služeb zaměřená na formuláře hlášení. Aktuální webové služby s označením v20130505 umí správně zpracovat i starší formuláře hlášení - v tomto rozhraní je tedy možné zpracovat i formuláře. Webové služby slouží k nahrání hlášení (UploadService) a validaci (ValidateService).

4.1 HlaseniUploadService

Pomocí této služby lze odeslat hlášení do ISPOP s rozšířenými možnostmi validace. Tato služba je preferovaný způsob, jak hlášení do ISPOP odeslat. Novější verze dokumentů PDF (2014 a novější) již využívají výlučně toto rozhraní. Pokud dokument neodpovídá datovému standardu, je systémem vyhodnocen v dalším zpracování jako nevalidní. Dokumenty, které nejsou dynamickými PDF (formuláře ISPOP) nebo XML podle datového standardu, jsou v každém případě vyřazeny. Dokument je přijat pouze v případě, že validace – po použití funkce validate – proběhne úspěšně.

HlaseniUploadService testovací prostředí: https://test.ispop.cz/ispop/ispop-ws/wsdl/hlaseniupload/v20130505/hlaseniupload.wsdl produkční prostředí: https://www.ispop.cz/ispop/ispop-ws/wsdl/hlaseniupload/v20130505/hlaseniupload.wsdl Autorizovaná služba pro odeslání a případnou validaci formuláře hlášení

plantuml-HlaseniUploadService.png

validate Metoda pro validaci. ROLE_UZIVATEL
upload Metoda pro odeslání (upload) formuláře na server. ROLE_UZIVATEL

Metoda validate příjímá serializované XML a provádí validaci dokumentu jako v případě 4.2. s tím rozdílem, že vyžaduje autorizaci uživatele a díky tomu může provést (vedle jiných) i validaci příslušnosti k subjektu, tj. validaci, která ověří, že daný uživatel má právo zaslat hlášení do ISPOP za daný subjekt.

Metoda upload příjímá binární stream dat a vrací číslo dokumentu jako výsledek. Číslo dokumentu je základní identifikátor dokumentu v systému ISPOP. Pokud klient v budoucnu bude provádět s dokumentem další operace (například řízení workflow), měl by si číslo dokumentu uchovat. Dokument je tak přijat ke zpracování. Metoda musí přijmout jakýkoli stream dat a vždy reaguje vrácením čísla dokumentu.

Navíc však může provést i validaci dokumentu před samotným příjmem dokumentu, pokud klient poskytne XML data serializovaná v elementu /hlaseniUploadDto/hlaseniValidateDto. Dokument je přijat jen v případě, že validace proběhne v pořádku. Pro vyhodnocení validace příslušnosti k subjektu je použit uživatel, který hlášení odesílá.

Jde o konvenci, která je zavedena s ohledem na optimální výkon. Bylo by možné získat v reálném čase XML přímo z binárních dat, nicméně to je náročná operace na CPU a I/O, zejména v případě, kdy jde o PDF formulář. V době ohlašovací špičky může ISPOP přijímat tisíce hlášení za hodinu. Tím že, data poskytnete klient ve stejné podobě jako pro validaci – jde o ten samý datový typ – je možné provést validaci online.

Budiž explicitně uvedeno – metodu upload je možné provolat i bez validace (stačí neuvést /hlaseniUploadDto/hlaseniValidateDto) – a tak zaslat libovolná data, nicméně validace bude v průběhu zpracování stejně provedena, takže její vykonání před odesláním lze jen doporučit – uživateli je tak možné ušetřit dost času.

Vstup:

<?xml version="1.0" encoding="utf-8"?>
<xsd:complexType name="HlaseniUploadDto">
    <!-- use all instead of sequence as this gets called from Adobe Acrobat, which is unable to handle sequence correctly -->
    <xsd:all>
        <xsd:element name="hlaseniUpload" type="tns:HlaseniUpload">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Vstupní dokument.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="hlaseniValidateDto" type="hlasenivalidate:HlaseniValidateDto" minOccurs="0">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Pokud je zaslané hlášení v binární podobě (element /HlaseniUploadDto/hlasenidoc) v jiném
                    formátu, než XML, je možné vyplnit tento element odpovídajícím XML k danému hlášení.
                    Pokud se tak stane, je hlášení před samotným postoupením systému zvalidováno a pokud jsou
                    zjištěny závažné chyby, je odmítnuto. Validační chyby jsou pak součástí odpovědi serveru
                    (/HlaseniUploadResultDto/hlaseniValidationResultDto).
                    Vyplnění tohoto elementu je volitelné.
                    Ať již element vyplněn je nebo není, je hlášení během následujícího procesu zpracování podrobeno
                    stejným validačním kontrolám.
                    Tento element by měl vyplnit inteligentní klient, jehož cílem je varovat uživatele pokud možno
                    dopředu, že s hlášením není vše v pořádku a nečekat až na následné zpracování serverem.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
    </xsd:all>
</xsd:complexType>

<xsd:complexType name="HlaseniUpload">
    <!-- use all instead of sequence as this gets called from Adobe Acrobat, which is unable to handle sequence correctly -->
    <xsd:all>
        <xsd:element name="binarydoc" type="xsd:base64Binary">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Data hlášení zakódovaná v base64.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="name" type="wscommon:MediumString" minOccurs="0">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Volitelný název hlášení.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="comment" type="wscommon:LongString" minOccurs="0">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Volitelná libovolná vlastní poznámka k dokumentu.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
    </xsd:all>
</xsd:complexType>

Výstup pak kombinuje výstup validace s případným číslem dokumentu:

<?xml version="1.0" encoding="utf-8"?>
<xsd:complexType name="HlaseniUploadResultDto">
    <xsd:sequence>
        <xsd:element name="documentNumber" type="wscommon:ShortString" minOccurs="0">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Číslo dokumentu. Klient by si měl ve vlastním zájmu uchovat číslo dokumentu. Jde o význačný
                    identifikátor, který doprovází dokument během celého jeho zpracování.
                    Dokument lze pomocí něho vyhledat, posouvat ve workflow apod.
                    Není nastaveno jen v případě, že v požadavku bylo uvedeno XML k validaci
                    (/HlaseniUploadDto/hlaseniValidateDto) a byly zjištěny zásadní nedostatky během validace, blíže
                    viz /HlaseniUploadResultDto/hlaseniValidateResultDto.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="hlaseniValidateResultDto" type="hlasenivalidate:HlaseniValidateResultDto" minOccurs="0">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Pokud byl vyplněn element /HlaseniUploadDto/hlaseniValidateDto, obsahuje tento element výstup
                    validace (viz /HlaseniValidateResultDto).
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
    </xsd:sequence>
</xsd:complexType>

4.2 HlaseniValidateService

HlaseniValidateService testovací prostředí: https://test.ispop.cz/ispop/ispop-ws/wsdl/hlasenivalidate/v20130505/hlasenivalidate.wsdl produkční prostředí: https://www.ispop.cz/ispop/ispop-ws/wsdl/hlasenivalidate/v20130505/hlasenivalidate.wsdl Neautoriovaná služba pro validaci formuláře hlášení

Během validací při odeslání a zpracování se provádí navíc validace příslušnosti k subjektu, která zjišťuje, zda uživatel, který odeslal hlášení, může podat hlášení za daný subjekt. Bez autorizace uživatele není možné tuto validaci provést. Tzn., že používáním této neautorizované verze se vystavujete riziku, že hlášení může být zamítnuto z důvodu validační chyby i když samotná metoda nevrátí žádnou chybu.

plantuml-HlaseniValidateService.png

validate Metoda pro validaci. ROLE_GUEST

Metoda validate příjímá serializované XML a provádí validaci dokumentu. Uživatel je neznámý a proto se neprovádí validace příslušnosti k subjektu, tj. validace, která ověří, že daný uživatel má právo zaslat hlášení do ISPOP za daný subjekt.

Vstup:

<?xml version="1.0" encoding="utf-8"?>
<xsd:complexType name="HlaseniValidateDto">
    <!-- use all instead of sequence as this gets called from Adobe Acrobat, which is unable to handle sequence correctly -->
    <xsd:all>
        <xsd:element name="xmldoc" type="xsd:string">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    XML hlášení serializované do řetězce.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="instant" type="xsd:dateTime" minOccurs="0">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Pokud je zadáno, provede se validace k zadanému okamžiku, jinak se bere aktuální čas.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="provideFormattedValidationOutput" type="xsd:boolean">
            <xsd:annotation>
                <xsd:documentation xml:lang="cs">
                    Pokud je nastaveno na true, bude nastaven formátovaný výstup validace
                    /HlaseniValidateResultDto/formattedValidationOutpu.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:element>
    </xsd:all>
</xsd:complexType>

Klient má možnost nastavit /HlaseniValidateDto/provideFormattedValidationOutput/ na true a může tak vedle výstupu chyb v XML elementech získat i formátovaný výpis vhodný k prezentaci.

Výstup pak obsahuje řadu podrobných informací, z nichž klíčový je /HlaseniValidateResultDto/validationStatus, určující výsledek validační kontroly:

<?xml version="1.0" encoding="utf-8"?>
<xsd:simpleType name="ValidationStatus">
    <xsd:restriction base="xsd:string">
        <xsd:enumeration value="OK">
            <xsd:annotation>
                <xsd:documentation>Validace proběhla v pořádku, nenastala žádná chyba, hlášení může být odesláno na
                    server.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:enumeration>
        <xsd:enumeration value="VALIDATION_ERROR">
            <xsd:annotation>
                <xsd:documentation>Chyba při logické validaci -- dokument je formálně dobře, obsahuje ale zasadní
                    logické chyby. Dokument není možné odeslat.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:enumeration>
        <xsd:enumeration value="XSD_ERROR">
            <xsd:annotation>
                <xsd:documentation>Chyba XSD -- tj. chyba ve struktuře dokumentu. Dokument není možné odeslat.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:enumeration>
        <xsd:enumeration value="DOCUMENT_VERSION_NOT_SUPPORTED">
            <xsd:annotation>
                <xsd:documentation>Verze vstupního dokumentu není podporovaná.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:enumeration>
        <xsd:enumeration value="UNEXPECTED_ERROR">
            <xsd:annotation>
                <xsd:documentation>Nastala neočekávaná chyba na serveru. Kontaktujte správce webových služeb.
                </xsd:documentation>
            </xsd:annotation>
        </xsd:enumeration>
    </xsd:restriction>
</xsd:simpleType>

Autor: Dain s.r.o. (www.dain.cz)

Revize: CENIA (www.cenia.cz)

Aktualizace: 2018-11-26

Validate