Viranomaistietorajapinta velvoitteidenhoitoselvitysten tekemiseen. Rajapintakuvaus

Viranomaistietorajapinta velvoitteidenhoitoselvitysten tekemiseen Rajapintakuvaus 1.0.54 Vtpr/Sote/Verohallinto 17.09.2014

SISÄLTÖ 1 YLEISTÄ... 4 1.1 Dokumentin kohderyhmä... 4 1.2 Velvoitteidenhoitoselvitys (vhs)... 4 1.3 Käytön sopiminen... 4 1.4 Integraatiotavat... 4 1.4.1 Salaustekniikat... 5 2 FTP-SIIRTO... 5 2.1 Vhs-pyyntö... 6 2.2 Ftp-siirroissa käytettävät skeemat... 6 2.3 Ftp-tiedostojen nimeäminen... 6 2.4 Yhteysosoitteet, palomuuriavaukset... 6 2.5 Tiedostojen hakeminen... 6 3 HTTPS-POHJAISET KYSELYT... 6 3.1 Palvelusopimus... 7 3.1.1 Huoltokatkot... 7 3.1.2 Velvoitteidenpyyntöpalvelun vasteajat... 7 3.1.3 Tunnistautuminen... 8 3.2 Tarjottavat palvelut... 8 3.2.1 Wsdl... 10 3.2.2 https-siirroissa käytettävät skeemat... 10 3.2.3 Muutokset palvelussa ja sen tietorakenteissa... 10 3.3 Vhs-pyyntö... 10 3.3.1 Parametrit... 10 3.3.2 Paluuarvo... 10 3.3.3 Reaaliaikapyyntö... 11 3.3.4 Virhetilanteet... 11 3.4 Hae selvitys... 11 3.4.1 Palvelut... 11 3.4.2 Parametrit... 12 3.4.3 Paluuarvo... 12 3.4.4 Virhetilanteet... 12 3.5 Virhekoodit on jaettu kanteen osaan, yleiset ja muut virhekoodit. Yleiset kuvaavat virheitä jotka voivat tulla kaikista palveluista. Muut kuvaavat virhetilanteita, jotka liittyvät johonkin tiettyyn tilanteeseen sovelluksen kannalta.... Virhe. Kirjanmerkkiä ei ole määritetty. 3.6 Hae organisaation valmistuneet selvitykset... 12 3.6.1 Parametrit... 13 3.6.2 Paluuarvo... 13 3.6.3 Virhetilanteet... 13 3.7 Tilakysely... 13 3.7.1 Parametrit... 13 3.7.2 Paluuarvot... 13 3.7.3 Virhetilanteet... 14 3.8 Kuittaa selvitys haetuksi... 14 3.8.1 Parametrit... 14 3.8.2 Paluuarvo... 14 3.8.3 Virhetilanteet... 14 3.9 Virhekoodit... 14 Lauri Toivola 10.02.2014

3 (22) 3.9.1 Yleiset virhekoodit... 14 3.9.2 Muut virhekoodit... 15 4 SANOMIEN TIETORAKENTEET... 15 4.1 Enkoodaukset... 15 4.1.1 Ftp-siirrot... 15 4.1.2 https... 15 4.2 VhsPyynto ja VhsSovellusPyynto... 15 4.2.1 Käyttötarkoitukset... 18 4.2.2 Pakettitunniste... 19 4.2.3 Esimerkki minimaalisesta VhsPyynto-pyynnosta... 19 4.2.4 Esimerkki minimaalisesta VhsSovellusPyynto-pyynnosta... 19 4.3 Vhs-vastaus... 20 4.4 Palautettavat tiedot... 20 4.5 Xml tietorakenne ohjelmalliseen käsittelyyn... 21 4.5.1 Organisaation tiedot xml tietorakenteena... 21 4.5.2 Organisaatiohenkilön tiedot xml tietorakenteena... 21 5 VIITTEET... 21 Versiohistoria Versio ja pvm Laatija Muutoksen kuvaus 1.0 10.02.2014? VTPR-projekti Ensimmäinen versio 1.0.52 19.01.2016 VTPR-projekti HakuAlkuPvm- ja HakuLoppuPvm-kentillä ei enää pyyntösanomailla merkitystä, sovellus päättelee 3/5-vuoden raportin viranomaisen ja pakettitunnuksen mukaan. Muutos voimaan 25.1.2016. 1.0.54 08.12.2017 VTPR-projekti Päivitetty käyttötarkoitukset 12/2017 tilanteen mukaan. Lisätty SSovellusPyynto-kuvaus. KysyjanViite-tiedon pituus.

4 (22) 1 YLEISTÄ Dokumentin tarkoitus on kuvata viranomaistietorajapinta (Vtpr) velvoitteidenhoitoselvityspyyntöjen (vhs) koneelliseen muodostamiseen. Dokumentti kuvaa velvoitteidenhoitoselvityspyyntöjen (vhs-pyyntö) vaihtoehdot ja tekniset rajapintakuvaukset. 1.1 Dokumentin kohderyhmä Tämä dokumentti on tarkoitettu vhs-pyyntöjä tekevän organisaation teknisille henkilöille. Dokumentissa käydään läpi mitä teknisiä vaatimuksia toteutukselle ja mitä kutsujen toteuttaminen vaatii kutsuvalta organisaatiolta. 1.2 Velvoitteidenhoitoselvitys (vhs) 1.3 Käytön sopiminen 1.4 Integraatiotavat Velvoitteidenhoitoselvityksellä tarkoitetaan selvitystä, joka voidaan tehdä organisaatiosta tai organisaatiohenkilöstä Harmaan talouden selvitysyksiköstä annetun lain (1207/2010) 6 :ssä säädettyihin käyttötarkoituksiin. Velvoitteidenhoitoselvitys kerää tietoa organisaation tai organisaatiohenkilön velvoitteidenhoidosta useista viranomaislähteistä. Palvelua käyttävien organisaatioiden on sovittava minimissään seuraavista asioista ennen kuin velvoitteidenhoitoselvityksiä ryhdytään tekemään: 1. Integraatiotavat, ftp tai https 2. Sertifikaattien vaihto Veron ja kutsujan välillä 3. Palomuuriavaukset, yhteysosoitteet 4. Ajastukset, palvelun käyttöaika (palvelu on rajoitetusti 24/7) 5. Käyttömäärät. Palvelun käyttömäärää rajoittavat ulkoiset tietolähteet, joista tietoja haetaan. 6. Yhteystiedot tiedotuksia ja ongelmatilanteita varten. 7. Syötetiedot eli pyytävälle viranomaiselle annetaan viranomaisnumero, käyttötarkoitusten tunnisteet, pakettikoodi ja tietyissä tapauksissa tekninen tunniste, jota viranomainen käyttää pyynnössään. 8. Palautettavat tiedot ovat pakettitunnisteeseen liittyvät tiedot jotka määritelty Veron ja viranomaisen palvelusopimuksessa. Velvoitteidenhoitoselvitysten tekemiseen on suunniteltu kaksi tapaa. 1. ftp-pohjainen siirtokanava 2. https-pohjainen palvelukutsu (Web Service) Ftp-siirtoa käytetään pääsääntöisesti tilanteissa, joissa Verohallinnolla on jo olemassa olevat ratkaisut palvelua käyttävän tahon kanssa. Perusratkaisut on suunniteltu siten, että valittava hajautusratkaisu ei periaatteessa vaikuta loogiseen tapaan toimia 1. Ftp ja http tavat eroavat kuitenkin käyttötavoiltaan toisistaan johtuen olemassa olevista käytännöistä. 1 Asia täsmentyy pilotin edetessä.

5 (22) 1.4.1 Salaustekniikat 2 FTP-SIIRTO Web Service ratkaisussa tarkoituksena on käyttää tietoturvan kannalta turvallisinta ratkaisua, johon kutsuva organisaatio pystyy. Tämä tarkoittaa SOAP viestin allekirjoittamista ja salaamista, vaikka kutsut kulkevat https-protokollan sisällä. Viestitason allekirjoitus mahdollistaa joustavan siirtymisen välittäjätahojen käyttämiseen, tietoturvan siitä kärsimättä. Mikäli kutsuvalla organisaatiolla ei ole valmiuksia SOAP-viestien salaamiseen ja allekirjoittamiseen käytetään tiedonvälityksen salaamisessa vain https-protokollaa. Ftp-yhteydet suojataan käyttäen ensisijaisesti sftp-protokollaa. Vaihtoehtoisesti voidaan myös käyttää ftps-protokollaa tai jotain tunnelointitekniikkaa. Ftp-yhteyksissä ei käytetä SOAP viestitason salausta, sillä ftp:n yli ei ole tarkoitus välittää SOAP-viestejä. Salattujen yhteyksien muodostaminen tehdään käyttäen sertifikaatteja. Kutsujan tunnistaminen tehdään X.509 sertifikaatilla. Testiympäristössä sertifikaattien pitää olla hierarkkisia eli testisertifikaatilla pitää olla myöntäjä. Ftp-siirrolla tarkoitetaan tilannetta, jossa siirtoprotokollana on jokin ftp johdannainen siirtoprotokolla. Oletuksena sftp (SSH File Transfer Protocol) vaihtoehtoisesti ftps (File Transfer Protocol over SSL). Ftp-siirroissa siirrettävä tieto serialisoidaan xml-skeeman mukaiseen xml tiedostoon. Ftp siirroissa ei käytetä SOAP 1.2 mukaista viestirakennetta, vaikka se olisi teknisesti mahdollista. Ftp-pohjaista siirtotietä käytetään tilanteissa, joissa Vhs-pyyntöjä tekevällä taholla on olemassa oleva ftp-siirtoyhteys Verohallintoon. Siirtoyhteydet toteutetaan siten, että Verohallinto huolehtii pyyntöjen hakemisesta pyytäjän ftp-jaosta, ja palauttaa valmistuneet pyynnöt pyytäjän ftp-kansioon. Verohallinto ei tarjoa ftp-palvelinta, jonne integroituva taho voisi siirtää tietoja. Asia on kuvattu alla: Valmistuneet Velvoitteidenhoitoselvitykset palautetaan kutsuvan tahon ftp-kansioon Verohallinnon toimesta.

6 (22) 2.1 Vhs-pyyntö Vhs-pyyntö tehdään ftp-mallissa siten, että pyynnön tekevä organisaatio kirjoittaa ennalta sovittuun ftp-palvelimen kansioon skeeman SPyynto.xsd mukaisen xml-tiedoston. Verohallinto käy hakemassa tiedoston kansiosta sovitun käytännön mukaisesti. 2.2 Ftp-siirroissa käytettävät skeemat Ftp-siirroissa käytetään seuraavia skeemoja: Vhs-pyyntö (SPyynto.xsd ja VtprYleinen.xsd). Skeemojen sisältö on tarkemmin kuvattu kappaleessa 4. 2.3 Ftp-tiedostojen nimeäminen Vhs-pyyntöjen tiedostonimien on oltava uniikkeja. Muita rajoitteita ei tällä hetkellä ole. 2.4 Yhteysosoitteet, palomuuriavaukset Sovitaan tapauskohtaisesti Verohallinnon ja vhs-pyyntöjä tekevän tahon välillä. 2.5 Tiedostojen hakeminen Tiedostojen hakemisessa suositeltavaa on, että ulkoisen tahon ftp-palvelimella on kaksi kansiota. 1. Vhs-pyyntö-hakemisto, josta Vero hakee Vhs-pyynnöt. 2. Tmp-kansio, johon Verohallinto voi siirtää pyynnön ennen siirtoa. Tmp kansiosta voidaan suorittaa uudelleensiirto, jos alkuperäisessä siirrossa tapahtui tekninen virhe. 3 HTTPS-POHJAISET KYSELYT Https-pohjainen Vtpr-rajapinta toimii loogisesti toisella tapaa mitä ftp-siirrot. Httppohjaisissa pyynnöissä pyytäjä aloittaa kutsuketjun kutsumalla Verohallinnon Web Service-palvelua. Pyytäjä saa pyynnöstä kuittauksen vastaanotosta, jossa on mukana Verohallinnon palauttama käsittelyid pyynnölle. Pyytäjä voi käsittelyid:n avulla hakea valmistuneen velvoitteidenhoitoselvityksen myöhemmin. Pyynnön tekemisen jälkeen kutsuja käyttää toista palvelurajapintaa pyynnön tilan kyselyyn, valmiin velvoitteidenhoitoselvityksen hakemiseen ja pyynnön kuittaamiseen haetuksi. Massakäsittelyyn tai muuhun tarkoitukseen rajapinta tarjoaa lisäksi muutaman muun palvelun. Lisää palvelumetodeista kappaleessa 3.2.

7 (22) 3.1 Palvelusopimus Vhs-pyyntöjä vastaanottava palvelu on päällä virka-aikaan ja pääsääntöisesti virka-ajan ulkopuolella. Taustajärjestelmissä on useammin huoltokatkoja, mutta viestejä pyritään vastaanottamaan aina, vaikka taustajärjestelmät eivät niitä pysty käsittelemään. Mikäli hakevat palvelukutsut palauttavat virheen, voi kutsuva taho kutsua myöhemmin palvelua. Vtpr-palvelun rajapinnasta muodostetaan aina organisaatiokohtainen palveluosoite. Palvelut tarjotaan oletuksen SOAP 1.2 versiolla. Tarvittaessa voidaan tarjota SOAP 1.1 versiolla. Alla on lueteltu esimerkkinä miten palveluosoite muodostetaan. Jokaiselle organisaatiolle tulee oma palvelupäätepiste. Palvelun osoite (SOAP 1.2): Ympäristö Tuotanto Testi Osoite https://btstuot1.vero.fi/[organisaatiokohtainen osa]/ivtpr12.svc https://btstst1.vero.fi/[organisaatiokohtainen osa]/ivtpr12.svc Palvelun osoite (SOAP 1.1): Ympäristö Tuotanto Testi Osoite https://btstuot1.vero.fi/[organisaatiokohtainen osa]/ivtpr11.svc https://btstst1.vero.fi/[organisaatiokohtainen osa]/ivtpr11.svc 3.1.1 Huoltokatkot Palvelua ei pysty kutsumaan viranomaisverkosta tai internetistä suoraan. Palvelua voi kutsua vain jos Verohallinnon ja kutsuvan tahon välille on tehty tarvittavat palomuuriavaukset. Kansallisen palveluväylän käyttöönotto on vireillä mutta tarkka aikataulu ei vielä tiedossa (tilanne 12/2017). Tuotantoympäristö: Verohallinto varaa huoltokatkolle ajan jokaisen parillisen viikon torstaille alkaen 17:00. Toinen katkoajankohta varataan jokaisen parillisen kuukauden ensimmäiselle lauantaille. Pidettävistä katkoista ilmoitetaan erikseen palvelun käyttäjiä. Palvelunkäyttäjiltä tarvitaan tekninen yhteysosoite johon tiedotteet katkoista ilmoitetaan. Verohallinnon valvomo informoi käyttäjiä käyttökatkoista. Testiympäristö: Testiympäristössä voi esiintyä katkoja ilman ennakkovaroitusta varsinkin pilotoinnin aikana tai Verohallinnon sisäisten testauksien tai huoltokatkojen vuoksi. 3.1.2 Velvoitteidenpyyntöpalvelun vasteajat Velvoitteidenhoitoselvitykset vaativat tietojen keräämistä monesta eri tietojärjestelmistä. Tämä tarkoittaa, että selvitysten valmistumisessa odotettavissa seuraavia viiveitä: Vhs sisältää tietoja Pelkästään Verohallinnon tietoja Odotettu vasteaika noin tunti

8 (22) Myös ulkoisten järjestelmien tietoja tunteja, max 14h 3.1.3 Tunnistautuminen Mikäli ulkoisista järjestelmistä ei saada tietoja 14 tunnin sisällä, palautetaan velvoitteidenhoitoselvitys ilman kyseisiä tietoja. Https-pohjaisessa palvelussa kutsujan tunnistaminen tehdään X.509 sertifikaatilla. Kutsujan varmenne välitetään palvelulle SSL/TLS kättelyn yhteydessä, varmennetta ei tarvitse lähettää varsinaisen viestin osana tai liitteenä. Tavoitteena on viestitason salaus ja allekirjoituksen käyttäminen kutsujan tunnistamiseen. Minimissään käytetään siirtoprotokollatason kutsujasertifikaattia (client certificate) WS- SecurityPolicy määritysten mukaisesti (Esim. SOAP 1.1 kutsuissa http://www.xmlsoap.org/ws/2005/07/securitypolicy/ ). SOAP 1.2-sanomissa pitäisi riittää että käytössä on WS Addressing ja että SOAP kutsun otsikkotiedoista löytyy WS-Aattribuutit To ja Action oikeilla arvoilla. Soap 1.2 esimerkkisanoma - HaeOrganisaationValmistuneetSelvitysIdt <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:header> <Action xmlns="http://www.w3.org/2005/08/addressing">haeorganisaationvalmistuneetselvitysidt</action> <MessageID xmlns="http://www.w3.org/2005/08/addressing">urn:uuid:c8f0721a-a419-46f0-b126- e3581e717b57</messageid> <To xmlns="http://www.w3.org/2005/08/addressing">https://btstst1.vero.fi/[organisaatiokohtainen osa]/ivtpr12.svc</to> <ReplyTo xmlns="http://www.w3.org/2005/08/addressing"> <Address>http://www.w3.org/2005/08/addressing/anonymous</Address> </ReplyTo> </soap:header> <soap:body> <ns3:haeorganisaationvalmistuneetselvitysidt xmlns:ns2="http://www.vero.fi/skeemat/vtpr/yleisethakutiedot" xmlns:ns3="http://www.vero.fi/vero.selvityskone/vtpr/" xmlns:ns4="http://www.vero.fi/skeemat/vtpr/vhsvastaus/2013/04/25" xmlns:ns5="http://www.vero.fi/skeemat/vtpr/vhstiedot/2013/02/05" xmlns:ns6="http://www.vero.fi/skeemat/vtpr/vhspyynto/2013/04/25" xmlns:ns7="http://www.vero.fi/skeemat/vtpr/2013/04/25" xmlns:ns8="http://www.vero.fi/vtpr/vhspyyntokasittelyidresponse"> <ns3:organisaatiotieto> <ns7:avaintiedot> <ns7:viranomaisnro>1</ns7:viranomaisnro> </ns7:avaintiedot> </ns3:organisaatiotieto> </ns3:haeorganisaationvalmistuneetselvitysidt> </soap:body> </soap:envelope> 3.2 Tarjottavat palvelut Käytettävät tunnistamistapa valitaan kutsujaorganisaation kyvykkyyden muukaan. VTPR-rajapinta tarjoaa seuraavat palvelut. Palvelut on kuvattua tarkemmin myöhäisemmissä kappaleissa. Palvelu VhsPyynto Kuvaus Vhs-pyyntöjen tekemiseen tarkoitettu palvelu. Palvelu ottaa parametrikseen VhsPyynto.xsd

9 (22) mukaisen sanoman, jossa pyynnön tekemisen tarvittavat tiedot. Käytetään vain eräkäsittelyssä käsiteltävien pyyntöjen tekemiseen. VhsSovellusPyynto HaeSelvitys HaeVhsSelvitys HaeVhs HaeOrganisaationValmistuneetSelvitysIdt Vhs-pyyntöjen tekemiseen tarkoitettu palvelu. Palvelu ottaa parametrikseen VhsSovellus- Pyynto.xsd mukaisen sanoman, jossa pyynnön tekemisen tarvittavat tiedot. Käytetään erä ja reaaliaikapyyntöjen tekemiseen. Viranomaisen X pyyntö voi tietyissä tilanteissa tulla viranomaisen Y sovelluksen kautta. ). Tämä on jatkossa suositeltavin operaatio. Hakee tietyn selvityksen. Vaatii käsittelyid:n parametriksi. HaeSelvitys palauttaa tietosisällön vain PDF-asiakirjana. Hakee tietyn selvityksen. Vaatii käsittelyid:n parametriksi. Pyynnöstä riippuen voi palauttaa tietosisällön PDF-asiakirjana tai rakenteisessa muodossa (jolloin palautetaan kevään 2015 tilanteen mukaisia rakenteisia tietoeriä). Hakee tietyn selvityksen. Vaatii käsittelyid:n parametriksi. Pyynnöstä riippuen voi palauttaa tietosisällön PDF-asiakirjana tai rakenteisessa muodossa (jolloin palautetaan VTPRhankkeen päättymishetken tilanteen mukaisia rakenteisia tietoeriä eli PDF-tiedoston ja rakenteisen muodon tietosisältö vastaa toisiaan). Tämä on jatkossa suositeltavin operaatio. Hakee organisaation kaikkien valmiiden selvitysten käsittelyid:t. Palauttaa kaikki käsittelyid:t selvitykset aikaväliltä, joita ei ole kuitattu haetuksi. Palauttaa myös tiedon virhetilaan menneistä selvityksistä. HaeSelvityksenTila KuittaaSelvitysHaetuksi Metodilla voidaan kysellä yksittäisen selvityksen tilaa käsittelyid:n avulla. Palvelu kuittaa Verohallinnolle, että selvitys on haettu. Kuittaaminen mahdollistaa sen, että organisaation ei tarvitse tehdä omaa tilakäsittelyä. Kutsuvan tahon on minimissään kutsuttava kahta palvelua velvoitteidenhoitoselvitysten tekemiseen. 1. VhsPyynto tai VhsSovellusPyynto (suositus jatkossa) 2. HaeSelvitys tai HaeVhsSelvitys tai HaeVhs (suositus jatkossa) Mikäli organisaatio ei halua tai voi tehdä käsittelyid:n varastointia, joudutaan käyttämään myös muita palveluja.

10 (22) 3.2.1 Wsdl Palvelun wsdl-kuvauksen palveluista voi ladata osoitteesta: (SOAP 1.2) https://btstst1.vero.fi/[organisaatiokohtainenosa]/ivtpr12.svc?wsdl Wsdl voidaan myös toimittaa tiedostona, jos yhteydet eivät ole vielä avattuina. HUOM! Tätä kirjoitettaessa pakolliset VhsPyynnön tai VhsSovelluspyynnön tietojen pakollisuudet eivät näy oikein Wsdl:ssä. Pakolliset kutsutiedot on katsottava kappaleesta 4.2. 3.2.2 https-siirroissa käytettävät skeemat https-pohjaiset kutsut nojaavat samaan skeemaan mitä ftp-siirrot. Erona protokollien välillä on, että https-pohjaisissa ftp:tä vastaava xml rakenne välitetään SOAP rakenteen sisällä SOAP bodyssä. 3.2.3 Muutokset palvelussa ja sen tietorakenteissa 3.3 Vhs-pyyntö Tarjottavien palvelujen rajapinnat tulevat muuttumaan ajan saatossa. Suurin muutospaine on tietorakenteessa, joka sisältää velvoitteidenhoitoselvityksen tiedot ohjelmallisen käsittelyyn. Uusia tietoja voi tulla lisää ja vanhoja voi poistua. Käsiteltäessä vhs:n tietoja ohjelmallisesti palvelun käyttäjän on varauduttava siihen, että jotain tietoa ei ole vhs:n mukana tai mukana tulee uusia tietoja. Vhs-pyyntöpalvelun avulla tehdään velvoitteidenhoitoselvitys. Http-kutsumetodi on synkroninen, vaikka varsinainen velvoitteidenhoitoselvitys ei ole. Vero palauttaa kutsujalle tiedon pyynnön vastaanotosta ja vasta sen jälkeen taustajärjestelmät rupeavat käsittelemään pyyntöä. 3.3.1 Parametrit 3.3.2 Paluuarvo https-pohjaisissa kutsuissa käytetään skeeman SPyynto.xsd, SSovellusPyynto.xsd ja VtprYleinen.xsd mukaista tietorakennetta kutsujen tekemiseen. Lisää tietorakenteesta kappaleessa 4.2. Verohallinto palauttaa yleisen tiedon Vhs-pyynnön onnistuneesta vastaanotosta. Palvelu palauttaa kutsujalla käsittelyid:n, jonka avulla kutsuja voi varmistaa, että Verohallinto on

11 (22) 3.3.3 Reaaliaikapyyntö 3.3.4 Virhetilanteet 3.4 Hae selvitys vastaanottanut pyynnön. Käsittelyid:n avulla voidaan myös hakea valmistuneita velvoitteidenhoitoselvityksiä. 2017 alkaen tietoa voi pyytää ns. reaaliaikapyyntönä käyttäen VhsSovellusPyyntooperaatiota. Reaalipyynnön tekeminen sovitaan tapauskohtaisesti Veron ja pyytäjän kanssa, koska siihen liittyy tietyt pakettitunnukset ja tarkistukset, että pyynnössä halutut tiedot löytyvät ns. nopeista tietolähteistä. Reaaliaikapyyntö tehdään samalla kutsusekvenssillä (tee pyyntö, vastaanota käsittelyid, odota hetki, kysy pyynnön tila, hae selvitys) kuin eräpyyntö. Pyynnön tilan kysely ja vastauksen haku voidaan kuitenkin tehdä noin 1-2 minuutissa (tapauksesta riippuen) mikä mahdollistaa esim. asiakassovellusten käyttöliittymien rakentamisen siten, että vastaus pyyntöön saadaan samassa istunnossa kuin missä pyyntö on tehty. VTPR-rajapinta näkyy ulos synkronisena, mutta on sisäisesti asynkroninen. S-pyyntöä vastaanotettaessa Verohallinto tarkistaa käytännössä kaksi asiaa: 1. Tunnistautunut kutsuja ja kutsun ViranomaisNro vastaavat toisiaan. 2. S-pyyntö vastaa sovittua skeemaan (VhsPyynto tai VhsSovellusPyynto). Edellä mainittujen virheiden lisäksi käsittelyssä voi tapahtua ennalta määrittelemättömiä teknisiä virheitä, joista palvelu palauttaa tiedon. Vhs-pyyntöprosessissa virheitä voi tapahtua vielä myöhäisemmässä vaiheessa. Näistä virheistä kutsuja saa tiedon vasta Vhs:n haun yhteydessä (kts. kappale 3.4 Hae selvitys/haesselvitys/haevhs ja kappale 3.6 Hae organisaation valmistuneet selvitykset). Palvelu palauttaa kappaleessa 0 kuvattujen virhekoodien mukaisia virhetietoja. Valmistuneet velvoitteidenhoitoselvitykset haetaan käsittelyid:n ja viranomaistiedon (tunnistautumistieto ja viranomaisnro) avulla. 3.4.1 Palvelut HaeSelvitys-palvelu käyttää skeemaversiota SVastaus.xsd ja VhsTiedot.xsd

12 (22) 3.4.2 Parametrit 3.4.3 Paluuarvo 3.4.4 Virhetilanteet HaeVhsSelvitys-palvelu käyttää uusia skeemaversiota SVastaus2.xsd ja VhsTiedot2.xsd, jotka sisältävät korjauksia vanhoihin tietoeriin ja myös uusia tietoeriä. HaeVhs-palvelu käyttää uusia skeemaversiota SVastaus3.xsd ja VhsTiedot3.xsd, jotka sisältävät VTPR-hankkeen loppuvaiheen vastaussanoman tietosisällön siten, että PDF:n ja rakenteisen muodon sisältö vastaavat toisiaan (aiemmin rakenteisessa muodossa on saanut vähemmän tietoja kuin PDF:llä). Palvelu ottaa parametrikseen käsittelyid:n, jonka Verohallinta palautti VhsPyynnön yhteydessä ja viranomaisnnro:n. HaeSelvitys-palvelu: Vero palauttaa skeemoissa SVastaus.xsd ja VhsTiedot.xsd mukaisen tietorakenteen kutsuvalle taholle. HaeVhsSelvitys-palvelu: Vero palauttaa skeemoissa SVastaus2.xsd ja VhsTiedot2.xsd mukaisen tietorakenteen kutsuvalle taholle. Palautettavat tiedot on kuvattu tarkemmin kappaleessa 4.3 Vhs-vastaus. Haettaessa velvoitteidenhoitoselvityksiä palautetaan tieto virhetilanteista, jotka ovat tapahtuneet taustajärjestelmissä. Esimerkkejä virhetilanteista: Kutsuja on pyytänyt pakettitunnisteella, jota ei ole olemassa tai ei ole käytettävissä pyytävälle viranomaiselle. Pyynnön käyttötarkoitus ei ole sallittu viranomaiselle. Velvoitteidenhoitoselvitys ei ole vielä valmistunut. Velvoitteidenhoitoselvitys on tehty kohteesta, jota ei ole olemassa. Lisää virhekoodeista kappaleessa 0 Palauttaa kappaleen 3.9.1Yleiset virhekoodit mukaisia virheitä. Virhekoodit 3.5 Virhekoodit on jaettu kanteen osaan, yleiset ja muut virhekoodit. Yleiset kuvaavat virheitä jotka voivat tulla kaikista palveluista. Muut kuvaavat virhetilanteita, jotka liittyvät johonkin tiettyyn tilanteeseen sovelluksen kannalta. Yleiset virhekoodit 3.6 Hae organisaation valmistuneet selvitykset Valmistuneiden velvoitteidenhoitoselvitysten kyselyllä tarkoitetaan tilannetta, jossa kutsuva organisaatio kysyy Verolta oman organisaationsa valmistuneita velvoitteidenhoitoselvityksiä. Vero palauttaa kutsujalle organisaation valmistuneista velvoitteidenhoitoselvityksistä käsittelyid-listan (ja virhetilat), jonka avulla kutsuja erikseen hakee organisaation valmistuneet velvoitteidenhoitoselvitykset. Palvelurajapinta on tehty sitä varten, että kutsuvan organisaation olisi mahdollisimman helppo tehdä selvityksiä. Velvoitteidenhoitoselvitykset valmistuvat viimeistään 14h kuluessa. Verohallinto hakee Vhs:n tietoja ulkoisista järjestelmistä, eikä vastauksia saada reaaliajassa. Mikäli Verohal-

13 (22) 3.6.1 Parametrit 3.6.2 Paluuarvo linnon kutsuma palvelu ei vastaa 14h kuluessa, palautuu Vhs niillä tiedoilla mitä saatiin siihen mennessä kerättyä. Nopeimmillaan Vhs valmistuu silloin, kun siihen on pyydetty vain tietoeriä jotka saadaan suoraan Verohallinnon tietojärjestelmistä. Tällöin puhutaan noin tunnin tai alle viiveestä. Käytettäessä tätä rajapintaa, on haun jälkeen kuitattava selvitys haetuksi. Kuittaus poistaa selvityksen listauksesta. Palvelu ottaa parametrikseen ViranomaisNro:n. Paluuarvona tulee kokoelma tietorakenteesta, jossa on käsittelyid, tieto onko selvitys mennyt virhetilaan ja selväkielinen teksti virhetilasta. Arvo KasittelyId PaattynytVirhetilaan Selite KäsittelyId joka identifioi VhsPyynnön. Sama joka palautuu VhsPyyntöä tehtäessä. Rakenteltaan Guid. Boolean arvo joka kertoo onko Velvoitteidenhoitoselvitys-pyyntö päättynyt virhetilaan. Virhekoodi Virheen identidioiva koodi. Arvot lueteltu kappaleessa 0 VirheSelite Selväkielinen selite virhetilasta suomen kielellä. Tarkoitettu virheselvittelyyn. 3.6.3 Virhetilanteet 3.7 Tilakysely 3.7.1 Parametrit 3.7.2 Paluuarvot Palvelurajapinta palauttaa kappaleen 0 virhekoodit virhetilanteessa. Palvelu palauttaa myös virhetiedon selvityksistä, joita ei ole voitu tehdä. Selvitys menee virhetilaan esim. jos pyynnön kohdetta ei ole olemassa tai kutsuva taho on pyytänyt tietoa johon sillä ei ole oikeutta. Lisää kappaleessa 3.6.2. Tilakyselyn avulla voidaan kysyä yksittäisen selvityspyynnön tilaa. Tilakysely ottaa parametrikseen käsittelyid:n ja ViranomaisNro:n. Vhs-pyynnön tilat: Tila Arvo Selite Vastaanotettu 10 Vhs-pyyntö on vastaanotettu, mutta se odottaa vielä käsittelyn aloittamista. Käsittelyssä 1 Selvityksen tekeminen on aloitettu.

14 (22) Valmis 2 S on valmis ja voidaan noutaa. Haettu 3 Selvitys on jo haettu. Tämä tarkoittaa sitä, että velvoitteidenhoitoselvitystä ei listata palvelun HaeOrganisaationValmistuneetSelvitysIdpaluuarvoissa. Virhe 99 Selvityksen tekeminen on jäänyt virhetilaan. 3.7.3 Virhetilanteet Palauttaa kappaleen 3.9.1Yleiset virhekoodit mukaisia virheitä. 3.8 Kuittaa selvitys haetuksi 3.8.1 Parametrit 3.8.2 Paluuarvo 3.8.3 Virhetilanteet 3.9 Virhekoodit 3.9.1 Yleiset virhekoodit Palvelun avulla voidaan kuitata velvoitteidenhoitoselvitys haetuksi. Tällöin velvoitteidenhoitoselvityksen käsittelyid ei palaudu palvelun HaeOrganisaationValmistuneetSelvitysId paluuarvona. Palvelu ottaa parametrikseen ViranomainNro:n ja kasittelyid:n. Palvelu palauttaa boolean tiedon onnistumisesta. Palauttaa kappaleen 3.9.1Yleiset virhekoodit mukaisia virheitä. Virhekoodit on jaettu kanteen osaan, yleiset ja muut virhekoodit. Yleiset kuvaavat virheitä jotka voivat tulla kaikista palveluista. Muut kuvaavat virhetilanteita, jotka liittyvät johonkin tiettyyn tilanteeseen sovelluksen kannalta. Alla olevaan taulukkoon on koottu yleiset virhekoodit, jotka voivat tulla mistä tahansa palvelurajapinnasta. virhekoodi Selite A400.1 Kutsuviestin kehystiedot ovat sisällöltään tai muodoltaan virheellisiä A400.2 Kutsuviesti on muodoltaan virheellinen. A400.3 Kutsuviesti on sisällöltään virheellinen. A403.1 Toiminto ei ole sallittu kyseiselle organisaatiolle. A408.1 Timeout, toiminto ei ole onnistunut määräajassa. A502.1 Ongelmia pyyntöä välittävän ja taustajärjestelmä välillä. Yhteys saa-

15 (22) daan, mutta kutsua ei saada suoritettua onnistuneesti. A503.1 Service Unavailable: Palvelu ei ole käytettävissä. A600 Sanomapohjainen reititys ei onnistu (sääntöjä ei ole määritelty) 3.9.2 Muut virhekoodit Alla olevia virhekoodeja ei tule kaikista palveluista. Virhekoodi A1000 A1001 A1002 A1003 A1004 A1005 A1006 A1007 A1008 Selitys Sisäinen järjestelmävirhe. Kutsuja on pyytänyt pakettia, johon sillä ei ole oikeutta. Velvoitteidenhoitoselvityksen muodostaminen on kesken. Käsittelyid:llä ei löydy valmista ja siirtämätöntä selvitystä. Velvoitteidenhoitoselvityksen pyynnön tiedoissa oli puutteita, jotka estävät selvityksen muodostamisen. Henkilötunnus ei ole organisaatiohenkilön henkilötunnus. Velvoitteidenhoitoselvitys voidaan tehdä vain organisaatiohenkilöille. Pakollinen tieto [abc] puuttuu. Henkilöä tai yritystä ei ole olemassa. VhsPyyntö on tehty kohteelle, jota ei ole olemassa Verohallinnon järjestelmissä. Käyttötarkoitus ei ole sallittu kutsujalle. 4 SANOMIEN TIETORAKENTEET 4.1 Enkoodaukset 4.1.1 Ftp-siirrot 4.1.2 https Tässä kappaleessa on kuvattu sanomien tietorakenteista. Tarkka kuvaus löytyy skeemoista ja palvelun wsdl:stä. Kappale keskittyy oleellisten tietojen esittelyyn. Vhs-pyyntöjen xml-tiedoston enkoodauksena pitää käyttää UTF-8 enkoodausta. Verohallinnon palauttamat xml tietorakenteet palautetaan UTF-8 enkoodauksella. SOAP palveluissa käytetään UTF-8 enkoodausta. 4.2 VhsPyynto ja VhsSovellusPyynto VhsPyynto skeema kuvaa, mitä tietoja ja millaisessa rakenteessa tarvitaan velvoitteidenhoitoselvityksen tekemiseen. Tiedot on kuvattu tarkemmin rakenteeltaan ja tietotyypiltään skeemassa SPyynto.xsd. Tässä kappaleessa esitellään keskeisimmät tiedot.

16 (22) VhsSovellusPyynto on em. skeeman uusi versio, jota mahdollistaa ns. reaaliaikapyynnöt ja viranomaisten pyyntöjen välittämisen toisen viranomaisen ns. välityssovelluksen kautta. Alla on erikseen mainittu, mitkä tiedot ovat VhsSovellusPyynto-tietoja. Tiedon nimi Pakollisuus Kuvaus ViranomaisNro pakollinen Verohallinnon antama viranomaisnumero kutsuvalle organisaatiolle. Verohallinto tarkistaa, että viranomaisnumero vastaa kutsun tekevää tahoa. Tunnistaminen tehdään sanoman allekirjoituksesta tai kutsuvan organisaation sertifikaatista. KohdeTunnus pakollinen Velvoitteidenhoitoselvityksen kohteen tunnus, y-tunnus tai henkilötunnus. Kayttotarkoitus pakollinen Verohallinnon antama käyttötarkoituksen kuvaava tunniste. Tunnisteet on kuvattu kappaleessa 4.2.1. Kutsuva organisaatio voi välittää vain erikseen sovittuja käyttötarkoitustunnisteita. ViranomainenYksikko ei pakollinen PyytajanNimi ei pakollinen PyytajanPuhNro ei pakollinen PyytajanSahkopostiOsoite ei pakollinen Kysyjanviite ei pakollinen KohdeNimi ei pakollinen AsiakirjaTyypit ei pakollinen VhsDataMukana ei pakollinen Kutsuvan viranomaisen yksikkö. Vhs-pyynnön tekijän nimi. Vhs-pyynnön tekijän puhelinnumero. Vhs-pyynnön tekijän sähköposti. S-kyselyn tekevän tahon uniikki tunniste kyselylle. Tämän tiedon avulla vhs-pyynnön tekijä voi yhdistää palautetavan Vhs:n tehtyyn kyselyyn. Velvoitteidenhoitoselvityksen kohteen nimi selkokielisenä. Informatiivinen tieto. Tiedostotyyppi jossa velvoitteidenhoitoselvitys palautetaan. Tätä kirjoitettaessa tuetaan ainoastaan pdf muotoa, joka on myös oletusarvo. Ohjaustieto, halutaanko vastaussanoman tietosisältö PDFdokumenttina vai rakenteisessa

17 (22) muodossa. False tai arvoa ei annettu: vastaussano-malle tietosisältö on PDF-asiakirja. True: vastaussano-malle tietosisältö on XML-muodossa. Pakettitunniste pakollinen Verohallinnon antamalla pakettitunnisteella voidaan ennalta sopia eri tietosisältöisiä Velvoitteidenhoitoselvityksiä eli pakettitunnukseen liittyy n kappaletta tietoeriä, joihin pyytäjällä on käyttötarkoituksen puitteissa oikeus. Esim. Kutsuva organisaatio tarvitsee laajan velvoitteidenhoitoselvityksen ja suppean velvoitteidenhoitoselvityksen. Molemmille selvityksille määritellään oma pakettitunniste johon sovitaan halutut tietoerät. Pakettitunniste siis käytännössä abstrahoi käytettävät tietoerät. Pakettitunniste ja siihen liittyvät tietoerät on sovittava erikseen Verohallinnon kanssa. HakuAlkuVuosi ei pakollinen Hakuvuosi mistä asti tietoja halutaan hakea kohti nykyhetkeä (tai HakuLoppuVuosi). Toistaiseksi velvoitteiden hoitoselvityksen voi tehdä vain 3 tai 5 vuotta nykyhetkestä taaksepäin. Mikäli arvoa ei anneta, palautetaan velvoitteidenhoitoselvitys viimeisen 3 vuoden ajalta. Syy tähän rakenteeseen on, että tulevaisuudessa voi olla mahdollista Vhs:n tarkempi rajaaminen tietylle ajanjaksolle. Ei käytössä. HakuAlkuPvm- ja HakuLoppuPvmkentillä ei ole enää pyyntösanomailla merkitystä, sovellus päättelee 3/5-vuoden raportin viranomaisen ja pakettitunnuksen mukaan. HakuLoppuVuosi ei pakollinen Rajaa mihin asti Vhs-tietojen haku tehdään. Esim. HakuAlkuVuosi 2010 ja HakuLoppuVuosi 2011 hakee vuosien 2010 ja 2011 tiedot. HUOM! Tätä kenttää ei käytetä alkuvaiheessa. Kenttä on varautumista tarkempiin hakuaikoihin.

18 (22) Ei käytössä. HakuAlkuPvm- ja HakuLoppuPvmkentillä ei enää pyyntösanomailla merkitystä, sovellus päättelee 3/5- vuoden raportin viranomaisen ja pakettitunnuksen mukaan. VhsSovellusPyynto.PyytajanYTunnus ei pakollinen Pyytävän viranomaisen Y-tunnus. Käytössä vain ns. YTJtapauksessa. Muut pyytäjät jättävät kentän tyhjäksi. VhsSovellusPyynto.TekninenTunniste ei pakollinen Jos viranomaisen X pyyntö tulee kolmannen osapuolen välityssovelluksen välityksellä, niin tekninen tunniste on tapauskohtaisesti sovittava välityssovelluksen tunniste. Tunnisteen antaa Vero. Muutoin arvo on 0 (nolla). VhsSovellusPyynto.Kasittelytapa ei pakollinen Varattu tulevaisuuden käyttöön. Toistaiseksi annetaan oletusarvo 0 (nolla). VhsSovellusPyynto.Lisaparametrit ei pakollinen Varattu tulevaisuuden käyttöön tilanteissa, joissa pyytäjällä on ennakoimaton tarve välittää pyynnön lisätietoja pyynnön käsittelyn ohjaamiseksi. 4.2.1 Käyttötarkoitukset Käyttötarkoituksilla kuvataan mihin käyttötarkoitukseen Vhs tulee. Pyynnössä on kerrottava käyttötarkoitus johon Vhs:ää käytetään. Käyttötarkoitukset ovat organisaatiokohtaisia. id Selite 1 Rikosten ennalta estäminen ja selvittäminen (Huom. lisäedellytys 1v + org) 2 Liiketoimintakiellon määräämisen edellytysten tutkinta ja liiketoimintakiellon valvonta 3 Rahanpesun ja terrorismin rahoittamisen estäminen ja selvittäminen 4 Menettämisseuraamuksen selvittäminen ja määrittäminen 5 Velvoitteiden täytäntöönpano 6 Tullitoimenpiteen suorittaminen (sis. rikosten ennaltaestäminen) 7 Rikosten esitutkinta (Huom lisäedellytys 1v + org) 8 Menettämisseuraamuksen selvittäminen ja määrittäminen 9 Työeläkevakuuttamisvelvoitteiden valvonta 10 Työttömyysvakuutusmaksujen perintämenettelyn toimeenpanon valvonta 11 Alkoholilain 42 :n mukaisten tehtävien hoitaminen 12 Alkoholilain 41 :n mukaisten tehtävien hoitaminen 13 Organisaation toimintaa varten annettavan rahoituksen myöntäminen ja valvonta

19 (22) 14 Rakennerahastolain 28 :n mukaiset tehtävät 15 Konkurssipesien hallinnon valvonta 16 Verotuksen toimittaminen 17 Perintä 18 Verovalvonta 19 Veronsaajien oikeudenvalvonta 20 Verojen ja maksujen kanto 21 Tilitys 22 Rikosten ennalta estäminen ja selvittäminen (Huom lisäedellytys 1v + org) 23 Menettämisseuraamuksen selvittäminen ja määrittäminen 24 Liikenneluvan myöntäminen tai peruuttaminen 25 Organisaation toimintaa varten annettavan rahoituksen myöntäminen ja valvonta 26 Säätiölain 14 luvun 1 :ssä säädetty valvontatehtävä 27 Muu 28 Luotonantajien ja luotonvälittäjien rekisteröinnistä annetun lain mukaiset tehtävät 29 Julkisten hankintojen harkinnanvaraisten poissulkemisperusteiden olemassaolon tarkistus 30 Palkkaturvalain mukaisten tehtävien hoitaminen 31 Tilaajan selvitysvelvollisuuden valvonta 32 Työsuhteen vähimmäisehtojen noudattamisen valvonta 33 Ulkomaalaisen työvoiman käytön valvonta 34 Kiinteistönvälitysliikkeiden ja vuokrahuoneiston välitysliikkeiden rekisteröinti ja valvonta 35 Vakuuttamisvelvoitteiden valvonta 4.2.2 Pakettitunniste Pakettitunnisteen avulla voidaan sopia kutsuvan organisaation kanssa vaihtoehtoisista Vhs-tietosisällöistä. Kutsuvalle organisaatiolle voidaan määritellä erilaisia tietosisältöjä Vhs-tiedoista, jotka tulevat paluusanomassa. Pakettitunniste kerää ennalta sovitut tietoerät sovittuun pakettiin. Pakettitunniste sovitaan yhdessä Verohallinnon kanssa. 4.2.3 Esimerkki minimaalisesta VhsPyynto-pyynnosta Olennaiset pakolliset tiedot keltaisella. <?xml version="1.0" encoding="utf-8"?> <VhsPyyntoSanoma xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns="http://www.vero.fi/skeemat/vtpr/vhspyynto/2013/04/25"> <Avaintiedot xmlns="http://www.vero.fi/skeemat/vtpr/2013/04/25"> <ViranomaisNro>37</ViranomaisNro> <KysyjanViite>Oma viite, max 50 merkkiä</kysyjanviite> </Avaintiedot> <VhsPyynto> <ViranomainenYksikko>Yksikkö AB</ViranomainenYksikko> <KohdeTunnus>010199-123A</KohdeTunnus> <PyytajanNimi>Veijo Tarkastaja</PyytajanNimi> <PyytajanPuhNro>1234567890</PyytajanPuhNro> <PyytajanSahkopostiOsoite>veijo.terkastaja@vero.fi</PyytajanSahkopostiOsoite> <Kayttotarkoitus>1</Kayttotarkoitus> <AsiakirjaTyypit> <AsiakirjaTyyppi>pdf</AsiakirjaTyyppi> </AsiakirjaTyypit> </VhsPyynto> </VhsPyyntoSanoma> 4.2.4 Esimerkki minimaalisesta VhsSovellusPyynto-pyynnosta Olennaiset pakolliset tiedot keltaisella.

20 (22) <?xml version="1.0" encoding="utf-8"?> <VhsSovellusPyyntoSanoma xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns="http://www.vero.fi/skeemat/vtpr/vhssovelluspyynto/2017/05/12"> <Avaintiedot xmlns="http://www.vero.fi/skeemat/vtpr/2013/04/25"> <ViranomaisNro>37</ViranomaisNro> <KysyjanViite>36ce3443-b749-444c-88f0-3dc1dad595c4</KysyjanViite> </Avaintiedot> <VhsSovellusPyynto> <ViranomainenYksikko>Yksikkö AB</ViranomainenYksikko> <KohdeTunnus>010199-123A</KohdeTunnus> <PyytajanNimi>Veijo Tarkastaja</PyytajanNimi> <PyytajanPuhNro>1234567890</PyytajanPuhNro> <PyytajanSahkopostiOsoite>veijo.terkastaja@vero.fi</PyytajanSahkopostiOsoite> <Kayttotarkoitus>1</Kayttotarkoitus> <PyytajanTekninenTunniste>2</PyytajanTekninenTunniste> <Kasittelytapa>0</Kasittelytapa> </ VhsSovellusPyynto > </ VhsSovellusPyyntoSanoma > 4.3 Vhs-vastaus 4.4 Palautettavat tiedot Vhs-vastauksella tarkoitetaan palautettavaa xml sanomaa, joka sisältää velvoitteidenhoitoselvityksen ja siihen liittyvät tiedot. Vastaus voi vaihtoehtoisesti palauttaa velvoitteidenhoitoselvityksen tiedostona (pdf) tai xml tietorakenteena ohjelmalliseen käsittelyyn. Lisää xml tietorakenteen palauttamisesta kappaleessa 4.5 Xml tietorakenne ohjelmalliseen käsittelyyn. Tässä kappaleessa on kuvattu palautettava tiedot pääpiirteissään. Tarkempi tietojen kuvaus löytyy skeemoista SVastaus.xsd, SVastaus2.xsd ja SVastaus3.xsd. Tieto Kuvaus KasittelyId Kohdetunnus Selvitystunnus SelvitysPvm Kysyjanviite Asiakirjat, Asiakirja, Base64, Tiedostotyyppi OrganisaatioTiedot, OrganisaatioHenkiloTiedot Verohallinnon käsittelyid Vtpr-pyynnölle. Identifioi Vhspyynnön. Selvityksen kohteen tunnus, esim. y-tunnus tai henkilötunnus. Selvityksen tekninen tunnus Verohallinnon järjestelmissä. Päivämäärä ajankohdasta jolloin selvitys on tehty. Kentässä palautetaan kutsujan viite, mikäli selvityksenpyynnön mukana on tullut kyseinen tieto. Tietorakenne jossa palautetaan velvoitteidenhoitoselvitykseen liittyvät asiakirjat. Tällä hetkellä palautetaan vain yksi pdf muotoinen tiedosto base64 enkoodattuna. Rakenteessa on varauduttu tuleviin tarpeisiin ja se mahdollistaa usean tiedoston palauttamisen. Tämän rakenteen alle tulee tietorakenne, joka kuvaa organisaatiota tai organisaatiohenkilöä koskevan velvoitteidenhoitoselvityksen tiedot xml muodossa. Tietorakenteet on kuvattu skeemoissa VhsTiedot.xsd (HaeSelvitys), ja VhsTiedot2.xsd (HaeVhsSelvitys) ja VhsTiedot3.xsd (HaeVhs).

21 (22) Katso myös kappale 4.5 Xml tietorakenne ohjelmalliseen käsittelyyn. Rakenne voi olla hierarkinen esim. siten, että Organisaatio- Tiedot-elementin alla on joukko OrganisaatioHenkioTiedotelementtejä. 4.5 Xml tietorakenne ohjelmalliseen käsittelyyn VhsVastaus voi sisältää velvoitteidenhoitoselvityksen tiedot xml tietorakenteena ohjelmallista käsittelyä varten. Xml tietorakenne sisältää lähes kaikki pdf-muodossa tulevat tiedot muutamaa poikkeusta lukuun ottamatta. Seuraavat asiat puuttuvat xml tietorakenteesta: o o Vapaatekstikentät. VTPR-pyynnöt menevät automaattikäsittelyn kautta joten virkailijan syöttämät tiedot eivät ole siinä mukana. Tiedot jotka saadaan pdf-raportteina ja liitetään velvoitteidenhoitoselvitys pdf-tiedoston perässä kuten Ulosottorekisteriote Kaupparekisteriote Rasitustodistus Tuloslaskelma Tilinpäätösasiakirjat Selvityskartta. 4.5.1 Organisaation tiedot xml tietorakenteena Kun S-pyynnössä on valittu VhsDataMukana=true, niin vastaussanoman velvoitteidenhoitoselvityksen tietosisältö toimitetaan rakenteisessa xml-muodossa eikä pdfasiakirjana. VhsDataMukana=false tai koko elementtiä ei pyynnössä, vastaussanoman velvoitteidenhoitoselvityksen tietosisältö toimitetaan PDF-dokumenttina. VhsTiedot.xsd- ja VhsTiedot2.xsd ja VhsTiedot3.xsd -skeemojen Organisaatiotiedot- Tyyppi-elementti ja sen alielementit sisältävät organisaatiota koskevat tiedot. VhsTiedot2.xsd -skeemaan on lisätty TaJaMaksutTyyppi3_5v- ja AlvJaMaksutTyyppi3_5v tyypit, mutta näille ei vielä tule dataa. Datan tuominen näille tyypeille toteutetaan myöhemmin. VhsTiedot3.xsd on VTPR-hankkeen loppuvaiheen versio, jonka rakenteisen muodon tietosisältö vastaa PDF-dokumenttia 12/2017-tilanteen mukaan. 4.5.2 Organisaatiohenkilön tiedot xml tietorakenteena 5 VIITTEET Kun S-pyynnössä on valittu VhsDataMukana=true, niin vastaussanoman velvoitteidenhoitoselvityksen tietosisältö toimitetaan xml-muodossa eikä pdf-asiakirjana. VhsTiedot.xsd- ja VhsTiedot2.xsd ja VhsTiedot3.xsd -skeemojen Organisaatiohenkilon- TiedotTyyppi-elementti ja sen alielementit sisältävät organisaatiohenkilöä koskevat tiedot. JHS 170 http://www.jhs-suositukset.fi/web/guest/jhs/recommendations/170

22 (22) PERA Tekninen arkkitehtuuriratkaisu tietovarantojen rajapintapalveluiden toteuttamiselle https://www.yhteentoimivuus.fi/view/asset/asset.singleview.xhtml?id=60052 Liitteet SPyynto.xsd SVastaus.xsd SVastaus2.xsd SVastaus3.xsd VhsTiedot.xsd VhsTiedot2.xsd VhsTiedot3.xsd VtprYleinen.xsd IVtpr.wsdl (+ sen liitetiedostot)