VIRANOMAIS WS API. Suomi.fi-viestit julkinen rajapinta

VIRANOMAIS WS API Suomi.fi-viestit julkinen rajapinta

V.01 RAJAPINTAKUVAUS V 1.1 2 (19) DOKUMNTINHALLINTA Omistaja Laatinut Tarkastanut Hyväksynyt Lasse Pynnönen, VRK Suomi.fi-viestit sovelluskehitystiimi Lasse Pynnönen, VRK Lasse Pynnönen, VRK VRSION HALLINTA versionro mitä tehty pvm/henkilö 0.1 Vanhan dokumentin tiedot tuotu uudelle pohjalle 0.2 Dokumentin stilisointi 0.3 0.4 HaeAsiakkaita vastauksen tilakoodi 320 poistettu. LisaaKohteita vastauksen tilakoodia 524 tarkennettu. Dokumentin nimi muutettu Lisätty vastaussanomien tilakoodien selitteet (luku 1.3). Muutettu Suomi.fi-viestit palvelu muotoon Suomi.fi-viestit tai Viestitpalvelu. Yhdenmukaistettu vastausanomat luvussa 2. Tarkennettu LisaaKohteita ja LahetaViestit operaatioden eroja. Korjattu LahetaViesti kyselysanoman kenttiä. Lisätty HaeTilaTieto sanomien esimerkit lukuun 3.3. 1.0 Päivitetty kenttien nimiä xsd-tiedostoa vastaaviksi. 1.0.1 Tarkennettu muutamia kohtia ja kommentoitu muutamia kohtia, jotka vaativat lisäselvitystä 1.1 Tekstikorjauksia, numerointikorjauksia, kommenttien poistot 5.6.2017 / Jyri Piirainen 11.6.2017 / Lasse Pynnönen 15.6.2017 / Jyri Piirainen 16.6.2017 / Ari Pyykkö 11.9.2017 / Jarmo Karttunen 6.11.2017 / Mikko Väkiparta 24.1.2018/Hannu Korkeala

V.01 RAJAPINTAKUVAUS V 1.1 3 (19) Sisällysluettelo 1 Yleistä... 4 1.1 Rajapinnan tekniset yleistiedot... 4 1.2 Viestin viranomaistiedot... 4 1.3 Tilakoodien selitteet... 5 2 Operaatiot... 5 2.1 Lisää kohteita... 5 Kyselysanoma... 6 Vastaussanoma... 8 2.2 Hae asiakkaita... 9 Kyselysanoma... 9 Vastaussanoma...10 2.3 Hae tilatieto... 11 Kyselysanoma... 11 Vastaussanoma... 11 2.4 Lähetä viesti... 11 Kyselysanoma...12 Vastaussanoma... 13 2.5 SOAP Fault...14 3 simerkit...14 3.1 Lisää kohteita...14 Kyselysanoma...14 Vastaussanoma... 15 3.2 Hae asiakkaita... 15 Kyselysanoma... 15 Vastaussanoma... 16 3.3 Hae tilatieto... 17 Kyselysanoma... 17 Vastaussanoma... 17 3.4 Lähetä viesti... 17 Kyselysanoma... 17 Vastaussanoma...18

V.01 RAJAPINTAKUVAUS V 1.1 4 (19) VIRANOMAIS WS API 1 Yleistä Tässä dokumentissa kuvataan Suomi.fi-viestit (Viestit-palvelun) tarjoama web service (WS) viranomaisrajapinnat. Dokumentissa on kuvattu tarvittavat tiedot kutsujen toteuttamiseksi. Nämä rajapinnat julkaistaan viranomaisjärjestelmille ja julkaisu tapahtuu Valtion Integraatioalusta (VIA) palvelun kautta. Viranomais WS API on VIA-palvelussa julkaistu rajapinta, jolla voidaan käsitellä Viestit-palvelun viestejä ja tilejä rajoitetusti. Viestirakenne noudattaa jo aiemmassa vaiheessa (Kansalaisen asiointitili aikojen) vuoden 2010 suunniteltua rakennetta. Rajapintaan on tehty muutamia muutoksia/lisäyksiä, mutta yhteensopivuus vanhaa rajapintaa käyttävien viranomaisjärjestelmien kanssa on säilytetty. Siitä aiheutuu myös se, että rakenteessa esiintyy vanhaa Asiointitili- termiä. 1.1 Rajapinnan tekniset yleistiedot Sanomissa käytetään UTF-8 enkoodausta ja käytetty formaatti on text/xml. Taulukko 1: Rajapinnan endpoint Url /InternalServices/Viestinvalitys/ViranomaispalvelutWSInterfaceNonSigned Taulukko 2: http asetukset Operaatio SoapAction HaeAsiakkaita http://www.suomi.fi/asiointitili/viranomaispalvelut/haeasiakkaita LisaaKohteita http://www.suomi.fi/asiointitili/viranomaispalvelut/lisaakohteita HaeTilaTieto http://www.suomi.fi/asiointitili/viranomaispalvelut/haetilatieto LahetaViesti http://www.suomi.fi/asiointitili/viranomaispalvelut/lahetaviesti 1.2 Viestin viranomaistiedot Jokaisessa viestissä on ensimmäisenä elementtinä viranomaisen (=lähettäjän) tiedot. Taulukko 3: Viranomainen elementti Kenttä Selite Tyyppi Pakollinen ViranomaisTunnus Viranomaisen tunnus, jonka K viestinvälityspalvelu on antanut. sim. 2574261-7 tai Vero PalveluTunnus Viranomaisen palvelutunnus, K jonka viestinvälityspalvelu on antanut viranomaisen käyttöön. sim. TRASHA KayttajaTunnus Viranomaisjärjestelmän käyttäjän tunniste, joka on ajon suorittanut. sim. timakar Yhteyshenkilo Yhteyshenkilö, jota kontaktoidaan elementti esim. virhetapauksissa. Nimi Yhteyshenkilön nimi Sahkoposti Yhteyshenkilön sähköpostiosoite

V.01 RAJAPINTAKUVAUS V 1.1 5 (19) Matkapuhelin Yhteyshenkilön matkapuhelinnumero Osoite Viranomaisen osoitetiedot elementti Nimi Viranomaisen nimi K Lahiosoite Viranomaisen käyntiosoite K Postinumero Postinumero K Postitoimipaikka Postitoimipaikka K Maa Maa (FI) K SanomaTunniste Viestin yksilöivä tunniste. sim. K GUID1222888223 SanomaVersio Viestin kutsun versionumero. K sim. 1.0 SanomaVarmenneNimi Viranomaisjärjestelmän käyttämän varmenteen varmennenimi (Common Name). sim. Verohallinto K 1.3 Tilakoodien selitteet Jokaisessa vastaussanomassa on TilaKoodi-elementti, joka koostuu tilakoodista, tilakoodin kuvauksesta (= virhekoodin selite) ja sanoman tunnisteesta (= viestin yksilöivä tunniste). Taulukko 4: Vastaussanoman TilaKoodi kentän arvot Koodi Kuvaus 0 Kutsu onnistunut. 400 Kutsuviesti on sisällöltään tai muodoltaan virheellinen. 403 Viranomaistunnus ei vastaa autentikoitua. 404 Palvelutunnus ei vastaa viranomaistunnusta. 405 Toiminto ei sallittu viranomaiselle. 406 Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 Muu virhe käsittelyssä. 453 Kohdepalvelu ei vastaa. 2 Operaatiot 2.1 Lisää kohteita Tämän rajapinnan avulla viranomaisjärjestelmä voi lähettää Viestit-palveluun asiointiasioita, tiedoksiantoja ja saada vastauksia kyselyihin. Lähetetyt asiat voivat sisältää linkkejä viranomaisen välivarastossa oleviin asiakirjoihin tai kokonaisia asiakirjoja, jotka tallennetaan Viestit-palvelun omaan välivarastoon. Lähetetty asia voidaan liittää Viestit -palvelussa jo olemassa olevaan asiaan, jolloin kyseinen asia näkyy asiakkaalle kyseisen asiointiasian yhteydessä (esimerkiksi lisäselvityspyyntö tai vastaus kysymykseen). Lähetetty asia voi olla myös todisteellinen tiedoksianto, jolloin paluukanavan kautta (WSPA4) saadaan tieto tiedoksiannon kuittauksesta. Viranomaisen tulee toimittaa asialle tunniste, jonka tulee olla viranomaisen palvelun sisällä yksilöllinen ajasta riippumatta.

V.01 RAJAPINTAKUVAUS V 1.1 6 (19) Kutsun vastauksena voidaan toimittaa lähetettyjen asioiden tallennustiedot asiakaskohtaisesti (synkroninen) tai pelkkä kuittaus asioiden vastaanottamisesta (asynkroninen). Viestintätyyppi on valittavissa liittymisen yhteydessä viranomaiskohtaisesti. Lisää kohteita -rajapinta periytyy Asiointitilistä ja soveltuu ainoastaan viestien digitaaliseen lähettämiseen. Jos halutaan, että viestit vastaanottajan suostumuksen puuttuessa ohjautuvat kirjepostiin, on käytettävä Lähetä viesti -rajapintaa. Lisää kohteita -rajapinta on aitona WS-rajapintana monipuolisempi digitaalisissa lähetyksissä kuin Lähetä viesti -rajapinta, mutta ei siis sisällä lainkaan paperipostitukseen ohjaamista. Kyselysanoma Taulukko 5: LisaaKohteita Kysely elementti (simerkki) Kenttä Selite Tyyppi Pakollinen KohdeMaara Lähetettävien asioiden lukumäärä int K Kohteet Asiat kokoava elementti elementti Kohde Yhden asian tiedot kokoava elementti [1..n] Asiakas Asiaan liittyvän asiakkaan tiedot. elementti K Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. AsiakasTunnus Asiakkaan henkilötunnus K Sahkoposti Sähköpostiosoite Matkapuhelin Puhelinnumero TunnusTyyppi SSN Osoite Asiakkaan osoite Nimi Asiakkaan nimi K Lahiosoite Lähiosoite K Postinumero Postinumero K Postitoimipaikka Postitoimipaikka K Maa Maakoodi (FI) K ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tunniste. Viittaus elementti ViittausTunniste Liittyvän asian tunniste K ViittausTunnisteTyyppi Liittyvän asian tunnisteen tyyppi. K Arvot: AsiointitiliTunniste tai ViranomaisTunniste VahvistusVaatimus Todisteellinen tiedoksianto, joka int vaatii kuittauksen lukemisesta. 1=kyllä, 0=ei VaadiLukukuittaus Parametrin avulla voidaan pakottaa int viestinvälityspalvelu lähettä- mään kuittausviesti kohteesta, vaikka lukukuittausten lähettäminen olisi muuten disabloitu. 1=kyllä, 0=ei AsiaNumero Viestit -palvelussa näytettävä asiakirjan tunniste (esim. päätöksen numero). Nimeke Asian otsikkotieto, jonka viranomaisjärjestelmä K tuottaa asiak- kaan omalla kielellä. LahetysPvm Lähetyspäivämäärä datetime K

V.01 RAJAPINTAKUVAUS V 1.1 7 (19) LahettajaNimi Lähettäneen viranomaisen tarkempi nimi. KuvausTeksti Vapaamuotoinen kuvaus K Maksullisuus ei käytössä int MaksamisKuvausTeksti ei käytössä Tila Asian viranomaiskäsittelyn tilatieto elementti TilaKoodi Asian viranomaisjärjestelmässä olevaa käsittelyn tilaa kuvaava määrämuotoinen tilatieto. Tila Asian viranomaisjärjestelmässä olevaa käsittelyn tilaa kuvaava vapaamuotoinen tieto. TilaKuvaus Tilaan liittyvä lisätieto. simerkiksi päätöksen tekijä. TilaPvm Tilan päivämäärätieto, eli milloin datetime K päätös on tehty. Tiedostot Asiaan liittyvät asiakirjat elementti Tiedosto elementti [1..n] TiedostonKuvaus Asiakirjan selite TiedostoURL Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään viranomaisen omaa välivarastoa. TiedostoSisalto Tiedosto BAS64 -enkoodattuna. TiedostoID Tiedoston tunniste tallennuspalvelussa, jos tiedosto välitetään tallen- nuspalvelun kautta. TiedostoKoko Tiedoston koko kilotavuina. TiedostoMuoto Tiedoston formaatti (mime type). TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen. Viranomaisenmail Sähköpostiliityntä: Puolipisteellä eroteltuna joko 1 tai useampi sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. SmsLisatieto Heräteviestin sisältö, joka välitetään matkapuhelimeen. maillisatietootsikko Heräteviestin otsikko, joka välitetään sähköpostiin. maillisatietosisalto Heräteviestin sisältö, joka välitetään sähköpostiin. TavoitettavuusTietoSMS Puhelinnumero, joka tallennetaan asiakaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Mikäli asiakkaalla on tili käytössä, ei kenttää huomioida. TavoitettavuusTietomail Sähköpostiosoite, joka tallennetaan asiakkaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Lähettävä viranomainen voi laittaa kenttään hallussaan olevan sähköpostiosoitteen, johon heräte lähetetään. Mikäli asiakkaalla on tili käytössä, ei kenttää huomioida.

V.01 RAJAPINTAKUVAUS V 1.1 8 (19) Vastaussanoma Taulukko 6: LisaaKohteitaResponse elementti (simerkki) lementti Selite TilaKoodi TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=Kutsu onnistunut Virhekoodit: 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Viestit-palvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikoitua. VIA palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestit-palvelu palauttaa. 405=Toiminto ei ole sallittu viranomaiselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestit-palvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA palauttaa, jos ei saa viestit-palveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). TilaKoodiKuvaus Virhekoodin selitekenttä. simerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa. KohdeMaara Käsiteltyjen asioiden lukumäärä. Kohteet Käsitellyt asiat kokoava elementti. Kohde Yhden asian tiedot kokoava elementti. ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä. Sama tunniste, kuin kutsuviestissä. Asiakas Asiaan liittyvän asiakkaan tiedot. Asia liitetään kyseisen loppuasiakkaan Viestit -palvelutiliin. AsiakasTunnus Loppuasiakkaan henkilötunnus. TunnusTyyppi Loppuasiakkaan tunnisteen tyyppi (SSN). AsiointitiliTunniste Asian yksilöivä tunniste, jonka Viestit -palvelu on asialle antanut. Asiointitilitunniste yksilöi viestin aina asiakaskohtaisesti. li toimitettaessa Viestit - palvelutilille sama asia, joka liittyy moneen asiakkaaseen, on asialla kaikille asiakkaille yhteinen viranomaistunniste ja asiakaskohtainen asiointitilitunniste. KohteenTila Kutsun tallennuksen käsittelytila. Käsittelytila palautetaan asiakaskohtaisesti. Onnistuneet statukset: (tässä tilanteessa asia on tallennettu asiointitilipalveluun) 200=kutsu onnistunut ja tallennettu Viestit -palvelutilille. Jos ei toimitettavia liitetiedostoja, voidaan käsitellä loppuun kutsun yhteydessä. 202=kutsu onnistunut ja laitettu käsittelyyn Viestit -palvelussa, mutta se ei vielä näy asiakkaan Viestit -palvelutilillä. Lopullinen vastaus on haettavissa erikseen erillisellä kutsulla. päonnistuneet statukset: (tässä tilanteessa asiaa ei ole tallennettu Viestit -palveluun) 520=annetulla tunnisteella löytyy jo asia, joka on tallennettu Viestit -palveluun eikä se ole virheellinen 521=liitoksen kohdetta (Viittaus) ei löydy tai se on eri asiakkaan asia

V.01 RAJAPINTAKUVAUS V 1.1 9 (19) KohteenTilaKuvaus 522=ongelma liitetiedoston tallennuksessa 523=ongelma liitetiedoston virustarkistuksessa 524=loppuasiakas ei ota vastaan asioita Viestit palvelutilille (tili passivoitu) 525=asian tietosisällössä virheitä 528=ei sallittu liitetiedoston tyyppi 529=liian iso liitetiedoston koko 550=muu virhe Tarkempi kuvaus virheestä. simerkiksi liitetiedostoon liittyvän virheen tapauksessa tiedoston nimi. 2.2 Hae asiakkaita Tämän kyselyn avulla viranomaisjärjestelmä voi tarkistaa mitkä sen asiakkaista ovat Viestit-palvelun sähköisiä käyttäjiä eli vastaanottavat viestejä palvelun kautta sähköisessä muodossa (sähköisen asioinnin yleissuostumus). Kyselyn avulla voi hakea kaikki omat asiakkaat tai tarkistaa annetun tai annettujen henkilötunnusten osalta, ovatko he ottaneet Viestit-palvelun sähköisen kanavan käyttöön. Vastauksessa saadaan tieto, onko loppuasiakkaalla sähköinen kanava käytössä. Kyselyä voidaan myös rajata ajan suhteen siten, että haetaan vain tietyllä aikavälillä Viestit-palvelun käytön aloittaneet loppuasiakkaat. Kyselysanoma Taulukko 7: HaeAsiakkaita Kysely elementti (simerkki) Parametri Selite Tyyppi Pakollinen KyselyLaji Kyselytyypin kertova elementti. Joko kaikki loppuasiakkaat Kaikki tai annettujen asiakkaiden tiedot Asiakkaat. Kyselylajin "Kaikki" tapauksessa, tulee antaa myös KyselyAlku ja KyselyLoppu-tiedot. Kyselylajin "Asiakkaat" tapauksessa, tulee antaa Asiakkaat-elementissä tarkistettavat henkilötunnukset. KyselyAlku Mikäli elementti on annettu, palautetaan vain annettua hetkeä myöhemmin tapahtuneet Viestit - palvelun sähköisen kanavan käyttöönotot ja Viestit -palvelun poiskytkennät. datetime KyselyLoppu HUOM! Pakollinen, jos haetaan Kyselytyypillä Kaikki. Mikäli elementti on annettu, palautetaan vain annettua hetkeä aiemmin tapahtuneet Viestit -palvelun sähköisen kanavan käyttöönotot ja Viestit -palvelun poiskytkennät. datetime

V.01 RAJAPINTAKUVAUS V 1.1 10 (19) Asiakkaat HUOM! Pakollinen, jos haetaan Kyselytyypillä Kaikki. Loppuasiakkaat kokoava elementti, jos haetaan annetun listan sisältämien asiakkaiden tiedot elementti *=pakollinen jos haetaan KyselyTyypillä Asiakkaat AsiakasTunnus Asiakkaan henkilötunnus. K TunnusTyyppi SSN K Vastaussanoma Taulukko 8: HaeAsiakkaitaResponse elementti (simerkki) lementti Selite TilaKoodi TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=Kutsu onnistunut Virhekoodit: 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Viestitpalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikoitua. VIA-palvelu palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestit-palvelu palauttaa. 405=Toiminto ei ole sallittu viranomaiselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestit -palvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA -palvelu palauttaa, jos ei saa Viestit palveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). TilaKoodiKuvaus Virhekoodin selitekenttä. simerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa Asiakkaat Loppuasiakkaat kokoava elementti. AsiakasTunnus Loppuasiakkaan henkilötunnus. TunnusTyyppi Loppuasiakkaan tunnisteen tyyppi (SSN). Tila Loppuasiakkaan tilatieto 300=loppuasiakkaalla on sähköinen kanava käytössä (muut arvot tarkoittavat, että sähköinen asiointi ei ole käytössä) 310=loppuasiakkaalla ei ole sähköistä kanavaa käytössään (ei ole ottanut käyttöön koko palvelua tai tili ei ole aktiivisena) TilaPvm Loppuasiakkaan sähköisen asioinnin suostumuksen viimeisimmän tilan voimaanastumisen aikaleima. Mikäli loppukäyttäjä ei ole antanut suostumusta, tilan päivämääränä on tyhjä tieto. Mikäli suostumus annettu, suostumuksen annon aikaleima. Mikäli suostumus on poistettu, suostumuksen poistohetki. TiliPassivoitu Lisätietokenttä joka kertoo, onko asiakas passivoinut tilinsä ja jos tili passivoitu niin saa arvon 1, muuten aina 0.

V.01 RAJAPINTAKUVAUS V 1.1 11 (19) 2.3 Hae tilatieto Tällä pyynnöllä viranomaisjärjestelmä voi tarkistaa Viestit -palvelun tilan. Kyselysanoma Taulukko 9: HaeTilaTieto elementti (simerkki) Parametri Selite Tyyppi Pakollinen Kysely Tyhjä elementti ei sisällä mitään tietoa. Vastaussanoma Taulukko 10: HaeTilaTietoResponse elementti (simerkki) lementti Selite TilaKoodi TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=kutsu onnistunut Virhekoodit: 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Viestitpalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikoitua. VIA-palvelu palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestit-palvelu palauttaa. 405=Toiminto ei sallittu viranomaiselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestit -palvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA -palvelu palauttaa, jos ei saa Viestit -palveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). TilaKoodiKuvaus Virhekoodin selitekenttä. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa 2.4 Lähetä viesti Tällä pyynnöllä viranomaisjärjestelmä voi lähettää viestejä käyttäjille, jotka päätyvät tarvittaessa paperitulostukseen. Paperitulostukseen lähtevät viestit, joiden vastaanottajalla ei ole aktiivista tiliä Viestit -palvelussa. Lähetä viesti-pyynnön sisältö vastaa pitkälle Lisää kohteita -palvelun sisältöä. Lähetä viesti -palvelu on Lisää kohteita -palveluun verrattuna suppeampi ja myötäilee OpusC apitan ipost (SFTP) -rajapintaa. Tulostusaineisto voidaan antaa usealla eri tavalla: 1) Ohjaustiedot (XML) ja kirjeet (PDF) valmiina ipost-muotoisina tiedostoina kyselyn Tiedostot-elementin alla. 2) Kirjeet yhdessä tiedostossa (PDF) kyselyn Tiedostot-elementin alla ja ohjaustiedot Kohteet-elementin alla.

V.01 RAJAPINTAKUVAUS V 1.1 12 (19) 3) Ohjaustiedot ja kirjeet Kohteet-elementin alla. Lisäksi tiedostot voidaan välittää joko kyselyn sisällä base64-koodattuina tai tallennuspalvelun kautta välitettyinä. Lähtökohtaisesti isot aineistot pitäisi aina välittää tallennuspalvelun kautta. Kyselysanoma Taulukko 11: LahetaViesti elementti (simerkki) Parametri Selite Tyyppi Pakollinen Tiedostot Koko aineistoa koskevat tiedostot. Tässä on mahdollista antaa kaikki tulostettavat kirjeet yhdessä PDF-tiedostossa ja kirjeiden ohjaustiedot XML-tiedostossa. Tiedostojen rakenne on ipost-palvelun mukainen. TiedostonKuvaus ei käytössä TiedostoURL ei käytössä TiedostoSisalto Tiedosto BAS64 -enkoodattuna. TiedostoID Tiedoston tunniste tallennuspalvelussa, jos tiedosto välitetään tallennuspalvelun kautta. TiedostoKoko ei käytössä TiedostoMuoto Tiedoston formaatti (mime type). TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen. Paperi Viestit lähetään aina myös paperilla (vaikka boolean vastaanottajalla olisi aktiivinen tili Viestit -palvelussa). Kohteet Kohteet sisältävä elementti Asiakas Asiaan liittyvän loppuasiakkaan tiedot. Sama asia voidaan lähettää usealle loppuasiakkaalle, jolloin näitä elementtejä voi olla useita. AsiakasTunnus Loppuasiakkaan henkilötunnus. Sahkoposti Sähköpostiosoite Matkapuhelin Puhelinnumero TunnusTyyppi SSN Osoite Loppuasiakkaan osoitetta käytetään, mikäli viesti välitetään paperilla. Nimi Loppuasiakkaan nimi K Lahiosoite Loppuasiakkaan lähisoite K Postinumero Loppuasiakkaan postinumero K Postitoimipaikka Loppuasiakkaan postitoimipaikka K Maa Loppuasiakkaan maakoodi (FI) K ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tun- niste. Viittaus ei käytössä ViittausTunniste ei käytössä K ViittausTunnisteTyyppi ei käytössä K VahvistusVaatimus ei käytössä int VaadiLukukuittaus ei käytössä int AsiaNumero ei käytössä Nimeke Asian otsikkotieto, jonka viranomaisjärjestelmä tuottaa asiakkaan omalla kielellä. LahetysPvm Lähetyspäivämäärä datetime K LahettajaNimi ei käytössä KuvausTeksti Vapaamuotoinen kuvaus K Maksullisuus ei käytössä int MaksamisKuvausTeksti ei käytössä Tila ei käytössä

V.01 RAJAPINTAKUVAUS V 1.1 13 (19) TilaKoodi ei käytössä Tila ei käytössä TilaKuvaus ei käytössä TilaPvm ei käytössä datetime K Tiedostot Asiaan liittyvät asiakirjat. Tässä on mahdollista antaa kirjeen sisältö (PDF) ja/tai Viranomaisen omassa välivarastossa säilytettäviä tiedostolinkkejä. TiedostonKuvaus Asiakirjan selite TiedostoURL Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään viranomaisen omaa välivarastoa TiedostoSisalto Tiedosto BAS64 -enkoodattuna TiedostoID Tiedoston tunniste tallennuspalvelussa, jos tiedosto välitetään tallennuspalvelun kautta. TiedostoKoko ei käytössä TiedostoMuoto Tiedoston formaatti (mime type) TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen Viranomaisenmail ei käytössä SmsLisatieto ei käytössä maillisatietootsikko ei käytössä maillisatietosisalto ei käytössä TavoitettavuusTietoSMS ei käytössä TavoitettavuusTietomail ei käytössä Sivut Mikäli kaikki kirjeet annetaan yhdessä PDF-tiedostossa, tässä elementissä määritellään yh- den kohteen sivut. Alkusivu Miltä sivulta yhteisessä PDF-tiedostossa kohteen int K kirje alkaa. Sivumaara Kuinka monta sivua kohteen kirjeessä on. int K LahetaOC Lähetetäänkö viestit OpusCapita ipost-rajapinnan kautta. Oletus on true.? boolean Vastaussanoma Taulukko 12: LaheteViestiResponse elementti (simerkki) lementti Selite TilaKoodi TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 0=kutsu onnistunut Virhekoodit: 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Viestitpalvelu palauttaa. 403=Viranomaistunnus ei vastaa autentikoitua. VIA-palvelu palauttaa. 404=Palvelutunnus ei vastaa viranomaistunnusta. Viestit-palvelu palauttaa. 405=Toiminto ei sallittu viranomaiselle. 406=Allekirjoitus ei vastaa palvelutunnuksella muodostettua allekirjoitusta. 450 = Muu virhe käsittelyssä. Viestit -palvelu palauttaa. 453= Kohdepalvelu ei vastaa. VIA -palvelu palauttaa, jos ei saa asiointitilipalveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet).

V.01 RAJAPINTAKUVAUS V 1.1 14 (19) TilaKoodiKuvaus SanomaTunniste Virhekoodin selitekenttä. simerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa 2.5 SOAP Fault 3 simerkit 3.1 Lisää kohteita Jos palvelun suorituksessa tapahtuu tekninen virhe, palvelu palauttaa SOAP Faultin kutsujalle. Viestin välitön uudelleen lähetys on turhaa. Tässä osiossa on esimerkkejä dokumentissa aikaisemmin kuvattujen palveluiden käytöstä. Kyselysanoma <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:header> <Action s:mustunderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://www.suomi.fi/asiointitili/viranomaispalvelut/lisaakohteita</action> </s:header> <s:body xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <LisaaKohteita xmlns="http://www.suomi.fi/asiointitili"> <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus>kkayttaja</KayttajaTunnus> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <Asiakas AsiakasTunnus="120551-9999" TunnusTyyppi="SSN" /> <ViranomaisTunniste>123-4431-514</ViranomaisTunniste> <Viittaus ViittausTunniste="123-4431" ViittausTunnisteTyyppi="ViranomaisTunniste" /> <VahvistusVaatimus>0</VahvistusVaatimus> <AsiaNumero>123-4431-514</AsiaNumero> <Nimeke>Työttömyyskorvauspäätös</Nimeke> <LahetysPvm>2010-10-23T12:54:00</LahetysPvm> <LahettajaNimi>Kirjavalan työvoimatoimisto</lahettajanimi> <KuvausTeksti> Päätös työttömäksi työnhakijaksi. työttömyyspäivärahasta</kuvausteksti> <Maksullisuus>0</Maksullisuus> <Tila> <TilaKoodi>123</TilaKoodi> <Tila>Käsitelty</Tila> <TilaKuvaus>Käsittelijä: Kalle Käyttäjä</TilaKuvaus> <TilaPvm>2010-10-12T14:45:00</TilaPvm> </Tila> <Tiedostot>

V.01 RAJAPINTAKUVAUS V 1.1 15 (19) 3.2 Hae asiakkaita <Tiedosto> <TiedostonKuvaus>Päätös työttömyyspäivärahasta</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoKoko>34</TiedostoKoko> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi>123-4431-514.pdf</TiedostoNimi> </Tiedosto> <Tiedosto> <TiedostonKuvaus>Muutoksenhakulomake annettuun päätökseen</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoKoko>125</TiedostoKoko> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi>muutoksenhakulomake.pdf</TiedostoNimi> </Tiedosto> </Tiedostot> </Kohde> </Kohteet> </Kysely> </LisaaKohteita> </s:body> </s:nvelope> Vastaussanoma <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:body xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <LisaaKohteitaResponse xmlns="http://www.suomi.fi/asiointitili"> <LisaaKohteitaResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>kutsu onnistunut</tilakoodikuvaus> <SanomaTunniste>1236</SanomaTunniste> </TilaKoodi> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <ViranomaisTunniste>123-4431-514</ViranomaisTunniste> <Asiakas AsiakasTunnus="120551-9999" TunnusTyyppi="SSN"> <AsiointitiliTunniste>32157254726</AsiointitiliTunniste> <KohteenTila>202</KohteenTila> <KohteenTilaKuvaus></KohteenTilaKuvaus> </Asiakas> </Kohde> </Kohteet> </LisaaKohteitaResult> </LisaaKohteitaResponse> </s:body> </s:nvelope> Kyselysanoma <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:header>

V.01 RAJAPINTAKUVAUS V 1.1 16 (19) <Action s:mustunderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://www.suomi.fi/asiointitili/viranomaispalvelut/haeasiakkaita</action> </s:header> <s:body xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <HaeAsiakkaita xmlns="http://www.suomi.fi/asiointitili"> <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus>230269-9999</KayttajaTunnus> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> <KyselyLaji>Kaikki</KyselyLaji> <KyselyAlku>2010-05-12T17:18:00</KyselyAlku> <KyselyLoppu>2010-05-12T17:18:00</KyselyLoppu> </Kysely> </HaeAsiakkaita> </s:body> </s:nvelope> Vastaussanoma <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:header /> <s:body xmlns:xsi=http://www.w3.org/2001/xmlschema-instance xmlns:xsd="http://www.w3.org/2001/xmlschema"> <HaeAsiakkaitaResponse xmlns="http://www.suomi.fi/asiointitili"> <HaeAsiakkaitaResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>kutsu onnistui</tilakoodikuvaus> <SanomaTunniste>1234</SanomaTunniste> </TilaKoodi> <Asiakkaat> <Asiakas AsiakasTunnus="230942-9999" TunnusTyyppi="SSN"> <Tila>300</Tila> <TilaPvm>2010-10-02T21:42:00</TilaPvm> <TiliPassivoitu>0</TiliPassivoitu> </Asiakas> <Asiakas AsiakasTunnus="270345-9999" TunnusTyyppi="SSN"> <Tila>310</Tila> <TilaPvm>0001-00-00T00:00:00</TilaPvm> <TiliPassivoitu>0</TiliPassivoitu> </Asiakas> <Asiakas AsiakasTunnus="311256-9999" TunnusTyyppi="SSN"> <Tila>310</Tila> <TilaPvm>2010-10-22T20:02:00</TilaPvm> <TiliPassivoitu>1</TiliPassivoitu> </Asiakas> <Asiakas AsiakasTunnus="060686-9999" TunnusTyyppi="SSN"> <Tila>300</Tila> <TilaPvm>2010-10-04T22:54:00</TilaPvm> <TiliPassivoitu>0</TiliPassivoitu> </Asiakas> </Asiakkaat>

V.01 RAJAPINTAKUVAUS V 1.1 17 (19) 3.3 Hae tilatieto 3.4 Lähetä viesti </HaeAsiakkaitaResult> </HaeAsiakkaitaResponse> </s:body> </s:nvelope> Kyselysanoma <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:header> <Action s:mustunderstand="1" xmlns="http://schemas.microsoft.com/ws/2005/05/addressing/none">http://www.suomi.fi/asiointitili/viranomaispalvelut/haetilatieto</action> </s:header> <s:body xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <HaeTilaTieto xmlns="http://www.suomi.fi/asiointitili"> <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus>230269-9999</KayttajaTunnus> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> </Kysely> </HaeTilaTieto> </s:body> </s:nvelope> Vastaussanoma <?xml version="1.0" encoding="utf-8"?> <s:nvelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:header /> <s:body xmlns:xsi=http://www.w3.org/2001/xmlschema-instance xmlns:xsd="http://www.w3.org/2001/xmlschema"> <HaeTilaTietoResponse xmlns="http://www.suomi.fi/asiointitili"> <HaeTilaTietoResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>Kutsu onnistunut</tilakoodikuvaus> <SanomaTunniste>1234</SanomaTunniste> </TilaKoodi> </HaeTilaTietoResult> </HaeTilaTietoResponse> </s:body> </s:nvelope> Kyselysanoma <s:nvelope> <s:header> <Action s:mustunderstand="1">http://www.suomi.fi/asiointitili/viranomaispalvelut/lahetaviesti</action>

V.01 RAJAPINTAKUVAUS V 1.1 18 (19) </s:header> <s:body> <LahetaViesti> <Viranomainen> <ViranomaisTunnus>VANTAA</ViranomaisTunnus> <PalveluTunnus>PÄIVÄHOITOHAKMUS</PalveluTunnus> <KayttajaTunnus>kkayttaja</KayttajaTunnus> <Yhteyshenkilo Nimi="Yrjö Yhteyshenkilö" Sahkoposti="yka@firma.fi" Matkapuhelin="040123456"> <Osoite> <Nimi>Oy Firma Ab</TiedostonKuvaus> <Lahiosoite>Yrityskatu 1</Lahiosoite> <Postinumero>00100</Postinumero> <Postitoimipaikka>Helsinki</Postitoimipaikka> <Maa>FI</Maa> </Osoite> <SanomaTunniste>1234</SanomaTunniste> <SanomaVersio>1.0</SanomaVersio> <SanomaVarmenneNimi>innofactor.com</SanomaVarmenneNimi> </Viranomainen> <Kysely> <KohdeMaara>1</KohdeMaara> <Kohteet> <Kohde> <Asiakas AsiakasTunnus="120551-9999" TunnusTyyppi="SSN"> <Osoite> <Nimi>Antero Asiakas</TiedostonKuvaus> <Lahiosoite>Kotikatu 1</Lahiosoite> <Postinumero>00100</Postinumero> <Postitoimipaikka>Helsinki</Postitoimipaikka> <Maa>FI</Maa> </Osoite> </Asiakas> <ViranomaisTunniste>123-4431-514</ViranomaisTunniste> <Nimeke>Työttömyyskorvauspäätös</Nimeke> <LahetysPvm>2010-10-23T12:54:00</LahetysPvm> <KuvausTeksti>Päätös työttömäksi työnhakijaksi. työttömyyspäivärahasta</kuvausteksti> <Tiedostot> <Tiedosto> <TiedostonKuvaus>Päätös työttömyyspäivärahasta</tiedostonkuvaus> <TiedostoSisalto>AFD8AW4NRCA8PPA3R...A384WNRC9N2</TiedostoSisalto> <TiedostoMuoto>application/pdf</TiedostoMuoto> <TiedostoNimi>123-4431-514.pdf</TiedostoNimi> </Tiedosto> </Tiedostot> </Kohde> </Kohteet> </Kysely> </LahetaViesti> </s:body> Vastaussanoma <s:nvelope> <s:body> <LahetaViestiResponse> <LahetaViestiResult> <TilaKoodi> <TilaKoodi>200</TilaKoodi> <TilaKoodiKuvaus>kutsu onnistunut</tilakoodikuvaus>

V.01 RAJAPINTAKUVAUS V 1.1 19 (19) <SanomaTunniste>1236</SanomaTunniste> </TilaKoodi> </LahetaViestiResult> </LahetaViestiResponse> </s:body> </s:nvelope>