VIRANOMAIS WS API. Suomi.fi-viestit julkinen rajapinta

Transkriptio

1 VIRANOMAIS WS API Suomi.fi-viestit julkinen rajapinta

2 V.01 RAJAPINTAKUVAUS V (24) DOKUMENTINHALLINTA Omistaja Laatinut Tarkastanut Hyväksynyt Lasse Pynnönen, VRK Suomi.fi-viestit sovelluskehitystiimi Lasse Pynnönen, VRK (v.1.2) Lasse Pynnönen, VRK (v.1.2) VERSION HALLINTA versionro mitä tehty pvm/henkilö 0.1 Vanhan dokumentin tiedot tuotu uudelle pohjalle 0.2 Dokumentin stilisointi 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 Päivitetty kenttien nimiä xsd-tiedostoa vastaaviksi Tarkennettu muutamia kohtia ja kommentoitu muutamia kohtia, jotka vaativat lisäselvitystä 1.1 Tekstikorjauksia, numerointikorjauksia, kommenttien poistot Tarkennettu LahetaViesti dokumentaatiota ja esimerkkejä luvuissa 2.4 ja 3.4. Lisätty esimerkki allekirjoitetun kyselysanoman Headerelementistä. Poistettu virheellinen tilakoodi (202) ja lisätty puuttuva tilakoodi (580) LisaaKohteitaResponse-sanomaan liittyen. 1.2 Katselmoinnin jälkeiset korjaukset. Muutettu esimerkkisanomia LahetaViesti uudistukset kuvattu dokumentaatioon. (Esimerkkejä ei ole päivitetty) / Jyri Piirainen / Lasse Pynnönen / Jyri Piirainen / Ari Pyykkö / Jarmo Karttunen / Mikko Väkiparta /Hannu Korkeala / Ari Pyykkö / Ari Pyykkö /Jyri Piirainen

3 V.01 RAJAPINTAKUVAUS V (24) HaeAsiakkaita kyselysanomaan lisätty puuttuvat Asiakas-elementti. Lisaakohteita vastaussanoman KohteenTiloja päivitetty. Laheta- Viesti vastaussanoman Tilakoodeja päivitetty. Katselmoinnin jälkeiset korjaukset. Sanomien kuvaustaulukot uudistettu /Jyri Piirainen /Jyri Piirainen

4 V.01 RAJAPINTAKUVAUS V (24) Sisällysluettelo 1 Yleistä Rajapinnan tekniset yleistiedot Viestin viranomaistiedot Tilakoodien selitteet Operaatiot LisaaKohteita Kyselysanoma Asiakas elementti Osoite elementti Viittaus elementti Tila elementti Tiedostot elementti Vastaussanoma TilaKoodi elementti Kohteet elementti Asiakas elementti HaeAsiakkaita Kyselysanoma Asiakkaat elementti Vastaussanoma TilaKoodi elementti Asiakkaat elementti HaeTilatieto Kyselysanoma Vastaussanoma LahetaViesti Kyselysanoma: Ohjaustiedot ja kirjeet Kohteet-elementin alla Kohteet elementti Asiakas elementti Osoite elementti Viittaus elementti Tila elementti Tiedostot elementti Vastaussanoma... 19

5 V.01 RAJAPINTAKUVAUS V (24) 2.5 SOAP Fault Esimerkit LisaaKohteita Kyselysanoma Vastaussanoma HaeAsiakkaita...21 Kyselysanoma...21 Vastaussanoma HaeTilatieto Kyselysanoma Vastaussanoma LahetaViesti Kyselysanoma: Ohjaustiedot ja kirjeet Kohteet-elementin alla Vastaussanoma...23

6 V.01 RAJAPINTAKUVAUS V (24) 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. 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: Viranomais SOAP API http asetukset Operaatio SoapAction HaeAsiakkaita LisaaKohteita HaeTilaTieto LahetaViesti 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. Esim tai Vero PalveluTunnus Viranomaisen palvelutunnus, K jonka viestinvälityspalvelu on antanut viranomaisen käyttöön. Esim. TREASHA KayttajaTunnus Viranomaisjärjestelmän käyttäjän E tunniste, joka on ajon suorittanut. Esim. timakar Yhteyshenkilo Yhteyshenkilö, jota kontaktoidaan elementti E esim. virhetapauksissa. Nimi Yhteyshenkilön nimi E Sahkoposti Yhteyshenkilön sähköpostiosoite E Matkapuhelin Yhteyshenkilön matkapuhelinnumero E Osoite Viranomaisen osoitetiedot elementti E

7 V.01 RAJAPINTAKUVAUS V (24) Nimi Viranomaisen nimi K Lahiosoite Viranomaisen käyntiosoite K Postinumero Postinumero K Postitoimipaikka Postitoimipaikka K Maa Maa (FI) K SanomaTunniste Viestin yksilöivä tunniste. Esim. K GUID SanomaVersio Viestin kutsun versionumero. K Esim. 1.0 SanomaVarmenneNimi Viranomaisjärjestelmän käyttämän varmenteen varmennenimi (Common Name). Esim. 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.

8 V.01 RAJAPINTAKUVAUS V (24) 2 Operaatiot 2.1 LisaaKohteita Kyselysanoma 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. Kutsun vastauksena voidaan toimittaa lähetettyjen asioiden tallennustiedot asiakaskohtaisesti (synkroninen) tai pelkkä kuittaus asioiden vastaanottamisesta (asynkroninen). Viestintätyyppi on valittavissa liittymisen yhteydessä viranomaiskohtaisesti. LisaaKohteita-rajapinta periytyy Asiointitilistä ja soveltuu ainoastaan viestien digitaaliseen lähettämiseen. Jos halutaan, että viestit vastaanottajan suostumuksen puuttuessa ohjautuvat kirjepostiin, on käytettävä LahetaViesti-rajapintaa. Huom. Lähetettävään viestiin kuuluva liitetiedosto välitetään kyselysanoman sisällä base64-koodattuina ja tiedoston (sanoman) koko voi olla enintään kolme megatavua. Taulukko 5: LisaaKohteita -elementti (Esimerkki) KohdeMaara Lähetettävien asioiden lukumäärä. int, pakollinen Kohteet Asiat kokoava elementti elementti Kohde Yhden asian tiedot kokoava elementti [1..n] Asiakas ViranomaisTunniste Viittaus VahvistusVaatimus VaadiLukukuittaus AsiaNumero Asiaan liittyvän asiakkaan tiedot. Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. Asian yksilöivä tunniste viranomaisen järjestelmässä, jonka tulee olla pysyvä, yksilöivä tunniste. Esimerkiksi diaarinumero. Todisteellinen tiedoksianto, joka vaatii kuittauksen lukemisesta. 1=kyllä, 0=ei Parametrin avulla voidaan pakottaa viestinvälityspalvelu lähettämään kuittausviesti kohteesta, vaikka lukukuittausten lähettäminen olisi muuten disabloitu. 1=kyllä, 0=ei Viestit -palvelussa näytettävä asiakirjan tunniste (esim. päätöksen numero). elementti, pakollinen elementti int int

9 V.01 RAJAPINTAKUVAUS V (24) Asiakas elementti Osoite elementti Nimeke Asian otsikkotieto, jonka viranomaisjärjestelmä tuottaa asiakkaan omalla kielellä., pakollinen LahetysPvm Lähetyspäivämäärä. datetime, pakollinen LahettajaNimi Lähettäneen viranomaisen tarkempi nimi. KuvausTeksti Vapaamuotoinen kuvaus asiasta eli lähetettävän viestin sisältö., pakollinen Maksullisuus ei käytössä int MaksamisKuvausTeksti ei käytössä Tila Asian viranomaiskäsittelyn tilatieto elementti Tiedostot Asiaan liittyvät asiakirjat elementti Viranomaisen 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. EI ENÄÄ KÄYTÖSSÄ LisatietoOtsikko Heräteviestin otsikko, joka välitetään sähköpostiin. LisatietoSisalto Heräteviestin sisältö, joka välitetään sähköpostiin. TavoitettavuusTietoSMS Puhelinnumero, joka tallennetaan asiakaan tietoihin, mikäli kutsun seurauksena asiakkaalle luodaan pikatili. Mi- käli asiakkaalla on tili käytössä, ei kenttää huomioida. EI ENÄÄ KÄYTÖSSÄ TavoitettavuusTieto 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. Asiaan liittyvän asiakkaan tiedot. Sama asia voidaan lähettää usealle asiakkaalle, jolloin näitä elementtejä voi olla useita. Elementti on pakollinen. Taulukko 6: Asiakas -elementti AsiakasTunnus Asiakkaan henkilötunnus, pakollinen Sahkoposti Sähköpostiosoite Matkapuhelin Puhelinnumero TunnusTyyppi Henkilöillä SSN, myöhemmin muita vaihtoehtoja. Osoite Asiakkaan osoite elementti Asiakkaan osoite. Osoite-elementti on valinnainen. Taulukko 7: Osoite -elementti Nimi Asiakkaan nimi., pakollinen Lahiosoite Lähiosoite., pakollinen Postinumero Postinumero., pakollinen Postitoimipaikka Postitoimipaikka., pakollinen Maa Maakoodi (FI)., pakollinen

10 V.01 RAJAPINTAKUVAUS V (24) Viittaus elementti Tila elementti Viittaus-elementti on valinnainen. Taulukko 8: Viittaus -elementti ViittausTunniste Liittyvän asian tunniste., pakollinen ViittausTunnisteTyyppi Liittyvän asian tunnisteen tyyppi. Arvot: Asiointitili- Tunniste tai ViranomaisTunniste., pakollinen Asian viranomaiskäsittelyn tilatieto. Tila-elementti on valinnainen. Taulukko 9: Tila -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. Esimerkiksi päätöksen tekijä. TilaPvm Tilan päivämäärätieto, eli milloin päätös on tehty. datetime, pakollinen Tiedostot elementti Vastaussanoma Asiaan liittyvät asiakirjat. Tiedostot-elementti on valinnainen. Taulukko 10: Tiedostot -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 BASE64 -enkoodattuna. TiedostoKoko Tiedoston koko kilotavuina. TiedostoMuoto Tiedoston formaatti (mime type). Esimerkiksi application/pdf. TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen. Huom. Tämä kenttä on tiedostolle pakollinen, jos tiedosto on annettu. Taulukko 11: LisaaKohteitaResponse -elementti (Esimerkki) TilaKoodi elementti KohdeMaara Käsiteltyjen asioiden lukumäärä. int Kohteet Käsitellyt asiat kokoava elementti. elementti

11 V.01 RAJAPINTAKUVAUS V (24) TilaKoodi elementti Vastauksen tilatiedot. Taulukko 12: TilaKoodi -elementti TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan int 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. Viestitpalvelu 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 viestitpalveluun yhteyttä. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). TilaKoodiKuvaus Virhekoodin selitekenttä. Esimerkiksi kutsussa oleva KohdeMaara ei vastaa kutsussa olevien Item:ien määrää. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa Kohteet elementti Käsitellyt asiat kokoava elementti. Taulukko 13: Kohteet -elementti Kohde Yhden asian tiedot kokoava elementti. 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. elementti

12 V.01 RAJAPINTAKUVAUS V (24) Asiakas elementti 2.2 HaeAsiakkaita Asiaan liittyvän asiakkaan tiedot. Asia liitetään kyseisen loppu-asiakkaan Viestit -palvelutiliin. Taulukko 14: Asiakas -elementti 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. Eli 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. int Onnistuneet statukset: (tässä tilanteessa asia on tallennettu Viestit-palveluun) 200=kutsu onnistunut ja tallennettu Viestit palvelun tilille. Jos ei toimitettavia liitetiedostoja, voidaan käsitellä loppuun kutsun yhteydessä. Epäonnistuneet statukset: (tässä tilanteessa asiaa ei ole tallennettu Viestit -palveluun) 460=vastaanottajan tiliä ei löydy 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 524=loppuasiakas ei ota vastaan asioita Viestit palvelun tilille (tili passivoitu) 550=muu virhe 580=liitettä ei saatu haettua tallennuspalvelusta KohteenTilaKuvaus Tarkempi kuvaus virheestä. Esimerkiksi liitetiedostoon liittyvän virheen tapauksessa tiedoston nimi. 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 tietyn aikavälin sisällä Viestitpalvelun käytön aloittaneet loppuasiakkaat.

13 V.01 RAJAPINTAKUVAUS V (24) Kyselysanoma Taulukko 15: HaeAsiakkaita Kysely elementti (Esimerkki) KyselyLaji Kyselytyypin kertova elementti. Joko kaikki loppuasiakkaat Kaikki tai annettujen asiakkaiden tiedot Asiakkaat. Kyselylajin "Kaikki" tapauksessa, tulee antaa myös KyselyAlku ja Kysely- Loppu-tiedot. Kyselylajin "Asiakkaat" tapauksessa, tulee antaa Asiakkaat-elementissä tarkistettavat henkilötunnukset. KyselyAlku KyselyLoppu Asiakkaat 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. 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. HUOM! Pakollinen, jos haetaan Kyselytyypillä Kaikki. Loppuasiakkaat kokoava elementti, jos haetaan annetun listan sisältämien asiakkaiden tiedot datetime datetime elementti *=pakollinen jos haetaan KyselyTyypillä Asiakkaat Asiakkaat elementti Loppuasiakkaat kokoava elementti, jos haetaan annetun listan sisältämien asiakkaiden tiedot HUOM! Pakollinen jos haetaan KyselyTyypillä Asiakkaat. Taulukko 16: Asiakkaat -elementti Parametri Selite Tyyppi Asiakas elementti AsiakasTunnus Asiakkaan henkilötunnus., pakollinen TunnusTyyppi Henkilöillä SSN, myöhemmin muita vaihtoehtoja., pakollinen Vastaussanoma Taulukko 17: HaeAsiakkaitaResponse -elementti (Esimerkki) Elementti Selite TilaKoodi Asiakkaat Loppuasiakkaat kokoava elementti.

14 V.01 RAJAPINTAKUVAUS V (24) TilaKoodi elementti Vastauksen tilatiedot. Taulukko 18: TilaKoodi -elementti TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan int 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-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ä. Esimerkiksi 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 elementti Loppuasiakkaat kokoava elementti. Taulukko 19: Asiakkaat -elementti Asiakas elementti AsiakasTunnus Loppuasiakkaan henkilötunnus. TunnusTyyppi Loppuasiakkaan tunnisteen tyyppi (SSN). Tila Loppuasiakkaan tilatieto int 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 datetime 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. int

15 V.01 RAJAPINTAKUVAUS V (24) 2.3 HaeTilatieto Kyselysanoma Vastaussanoma Tällä pyynnöllä viranomaisjärjestelmä voi tarkistaa Viestit-palvelun tilan. Taulukko 20: HaeTilaTieto elementti (Esimerkki) Parametri Selite Tyyppi Kysely Tyhjä elementti ei sisällä mitään tietoa. Taulukko 21: HaeTilaTietoResponse -elementti (Esimerkki) Elementti Selite TilaKoodi Vastauksen tilatiedot. elementti TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan int 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-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 LahetaViesti Tällä kyselyllä viranomaisjärjestelmä voi lähettää asiakkaille viestejä, jotka päätyvät tarvittaessa paperitulostukseen. Paperitulostukseen lähtevät viestit, joiden vastaanottajalla ei ole aktiivista tiliä Viestit -palvelussa. Paperipostituksen edellytyksenä on, että viranomainen on sopinut sekä VRK:n että tulostustoimittajan kanssa paperipostituksen käytöstä. Aineistojen siirto tulostustoimittajan tulostus- ja postituspalveluun vaatii testauksen Viestit -palvelun asiakastestiympäristössä ennen tuotantoon vientiä. Tulostustoimittaja on kerrottava LahetaViesti-kyselysanoman Tulostustoimittaja-kentässä. Tällä hetkellä tuetaan vain ipost-rajapinnan ( mukaisia ohjaustietoja ja kirjeitä. Lähetettävään aineistoon kuuluva PDF-tiedosto välitetään kyselysanoman sisällä base64-koodattuina ja tiedoston (sanoman) koko voi olla enintään kolme megatavua.

16 V.01 RAJAPINTAKUVAUS V (24) Jos viesti menee sähköisen toimituksen sijasta kirjepostitukseen, sinne tulostetaan vain viestin liitetiedostot (yksi tai useampi riippuen kyselysanomatyypistä). Lähetettävän viestin kaikki asiasisältö tulee siis tallentaa liitteisiin. Viranomainen on vastuussa siitä, että lähetetty aineisto soveltuu paperipostitukseen eli ohjaustiedot ja PDF-muotoinen kirje täytyy olla siinä muodossa, että ne voidaan tarvittaessa lähettää paperipostina Kyselysanoma: Ohjaustiedot ja kirjeet Kohteet-elementin alla Tämä tapa käyttää LahetaViesti-operaatiota vastaa LisaaKohteita-operaation tapaa lähettää viestejä kansalaisille. Lähetettävän viestin (kirjeen) ohjaustiedot annetaan Kohteet-elementissä ja samoin myös lähetettävä viestin liite (kirje) PDF-tiedostona. Samassa kyselysanomassa voi lähettää viestejä (kirjeitä) useille vastaanottajille, mutta tällöin täytyy jokaisella vastaanottajalla olla oma Kohdeelementti ja siellä jokaiselle vastaanottajalle oma PDF-tiedosto, joka sisältää lähetettävän viestin liitteet (kirjeen). Huom. Base64-koodattujen PDF-tiedostojen yhteiskoko (sanoman koko) voi olla enintään kolme megatavua. Lähetettävän viestin kaikki asiasisältö tulee tallentaa yhteen PDF-tiedostoon, joka liitetään viestiin. Viestiä ei voi lähettää ilman liitettä. PDF-liitteitä ei voi olla useampia kuin yksi yhtä vastaanottajaa kohden. Jos yhdellä LahetaViesti-sanomalla halutaan lähettää kerralla useita dokumentteja, ne tulee koostaa peräkkäin yhteen PDF-tiedostoon. Jos yhdellä LahetaViesti-sanomalla halutaan lähettää kerralla viestejä useille vastaanottajille, jokainen vastaanottaja ja liitetiedosto pitää sijoittaa omaan Kohde-elementtiinsä. Yhteen Kohde-elementtiin ei siis voi sisällyttää useampia vastaanottajia tai useampia liitetiedostoja. Jotta viesti voidaan toimittaa aina perille, onpa kansalainen ottanut käyttöön viestin sähköisen vastaanottamisen tai ei, jokaisessa viestissä pitää olla osoitetietoina sekä henkilötunnus että katuosoite. VRK ei siis hae katuosoitetta väestötietojärjestelmästä, vaan viranomaisen pitää täyttää se kyselysanoman Osoite-osioon. Taulukko 22: LahetaViesti Kysely-elementti (Esimerkki) Parametri Selite Tyyppi Paperi Viestit lähetään aina myös paperilla, vaikka vastaanottajalla boolean, pakollinen olisi aktiivinen tili Viestit -palvelussa. Kohteet Kohteet sisältävä elementti elementti Tulostustoimittaja Rajapinta 1.1 muutos: Tulostustoimittaja, jonka, pakollinen kanssa viranomaisella on tulostussopimus. Esim. Edita tai OpusCapita LahetaTulostukseen (aikaisemmin LahetaOC) Rajapinta 1.1 muutos: Lähetetäänkö viestit paperipostitukseen. Oletus on true. Tarkoitettu lähinnä testaamiseen asiakastestausympäristössä, jossa ei välttämättä haluta lähettää viestejä paperipostitukseen, tällöin kentän arvoksi annetaan false. boolean

17 V.01 RAJAPINTAKUVAUS V (24) Kohteet elementti Kohteet sisältävä elementti. Elementti on pakollinen. Taulukko 23: Kohteet -elementti Parametri Selite Tyyppi Kohde Yhden kohteen tiedot kokoava elementti elementti [1..n] Asiakas Asiakkaan tiedot sisältävä elementti elementti, pakollinen ViranomaisTunniste Asian yksilöivä tunniste viranomaisen järjestelmässä,, pakollinen jonka tulee olla pysyvä, yksilöivä tunniste. Esimerkiksi diaarinumero. Viittaus elementti VahvistusVaatimus Todisteellinen tiedoksianto, joka vaatii kuittauksen int lukemisesta. 1=kyllä, 0=ei VaadiLukukuittaus Parametrin avulla voidaan pakottaa viestinvälityspalvelu int 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ä, pakollinen tuottaa asiakkaan omalla kielellä. LahetysPvm Lähetyspäivämäärä datetime, pakollinen LahettajaNimi Lähettäneen viranomaisen tarkempi nimi. KuvausTeksti Vapaamuotoinen kuvaus asiasta eli lähetettävän, pakollinen viestin sisältö. Tila Asian viranomaiskäsittelyn tilatieto elementti Tiedostot Asiaan liittyvät asiakirjat. Tässä on mahdollista antaa elementti, pakollinen kirjeen sisältö (PDF). SmsLisatieto Heräteviestin sisältö, joka välitetään matkapuhelimeen. EI ENÄÄ KÄYTÖSSÄ LisatietoOtsikko Heräteviestin otsikko, joka välitetään sähköpostiin. LisatietoSisalto 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. EI ENÄÄ KÄYTÖSSÄ TavoitettavuusTieto 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.

18 V.01 RAJAPINTAKUVAUS V (24) Asiakas elementti Osoite elementti Viittaus elementti Tila elementti Asiakkaan tiedot sisältävä elementti. Elementti on pakollinen. Taulukko 24: Asiakas -elementti Parametri Selite Tyyppi AsiakasTunnus Asiakkaan henkilötunnus, pakollinen Sahkoposti Sähköpostiosoite Matkapuhelin Puhelinnumero TunnusTyyppi Henkilöillä SSN, myöhemmin muita vaihtoehtoja. Osoite Asiakkaan osoite, pakollinen Asiakkaan osoite. Elementti on pakollinen Taulukko 25: Osoite -elementti Parametri Selite Tyyppi Nimi Asiakkaan nimi, pakollinen Lahiosoite Lähiosoite, pakollinen Postinumero Postinumero, pakollinen Postitoimipaikka Postitoimipaikka, pakollinen Maa Maakoodi (FI), pakollinen Viittaus-elementti on valinnainen. Taulukko 26: Viittaus -elementti Parametri Selite Tyyppi ViittausTunniste Liittyvän asian tunniste ViittausTunnisteTyyppi Liittyvän asian tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste Asian viranomaiskäsittelyn tilatieto. Taulukko 27: Tila -elementti Parametri Selite Tyyppi 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. Esimerkiksi päätöksen tekijä. TilaPvm Tilan päivämäärätieto, eli milloin päätös on tehty. datetime, pakollinen

19 V.01 RAJAPINTAKUVAUS V (24) Tiedostot elementti Asiaan liittyvät asiakirjat. Tässä on mahdollista antaa kirjeen sisältö (PDF). Elementti on pakollinen. Taulukko 28: Tiedostot elementti Parametri Selite Tyyppi TiedostonKuvaus Tiedoston sisällön kuvaus TiedostoSisalto Tiedosto BASE64 enkoodattuna. Maksimikoko 3 megatavua, pakollinen TiedostoMuoto Tiedoston formaatti (mime type): arvo on aina application/pdf, pakollinen TiedostoNimi Tiedoston nimi sisältäen tiedostopäätteen, pakollinen Vastaussanoma LahetaViesti-kyselyn käsittely poikkeaa LisaaKohteita-kyselystä. LisaaKohteita-kyselyssä viestit tallennetaan suoraan Viestit-palveluun ja tallennuksen onnistumisesta palautetaan heti vastaus. LahetaViesti-kyselyn vastausanoma (LahetaViestiResponse) lähetetään, kun aineisto (viestit) on tallennettu Viestit-palvelun käsittelyjonoon, josta viestit lähetetään sähköisesti tai paperipostitukseen. Jos aineiston lähetys tai jatkokäsittely epäonnistuu, lähetetään erillinen ilmoitus LahetaViesti-sanoman Viranomainen-elementissä annettuun yhteyshenkilön sähköpostiin (Yhteyshenkilo-elementin Sahkoposti-kenttä). Sähköpostissa kerrotaan tarkempi syy epäonnistumiselle. Taulukko 29: LahetaViestiResponse -elementti (Esimerkki) TilaKoodi Vastauksen tilatiedot. elementti TilaKoodi Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan int tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit: 202=Kutsu on onnistunut ja viestit on tallennettu Viestit-palvelun käsittelyjonoon, mutta viesti tai viestit ei vielä näy asiakkaalle tai asiakkaille. Virhekoodit: 400=Kutsuviesti on sisällöltään tai muodoltaan virheellinen. Viestit-palvelu 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. 453= Kohdepalvelu ei vastaa. VIA -palvelu palauttaa, jos ei saa asiointitilipalveluun yhteyttä. 525=Asian tietosisällössä virheitä. 550=Muu virhe. Lisäksi muissa virhetilanteissa voidaan palauttaa SOAPFAULT (esimerkiksi alustatason virheet). TilaKoodiKuvaus Virhekoodin selitekenttä. Esimerkiksi kutsussa olevassa tietosisällössä on virheitä. SanomaTunniste Viestin yksilöivä id-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa

20 V.01 RAJAPINTAKUVAUS V (24) 2.5 SOAP Fault 3 Esimerkit 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ä. Esimerkki allekirjoitetun kyselysanoman otsikko (Header)-elementistä: LisaaKohteita Kyselysanoma Vastaussanoma <?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:asi=" <soap:body xmlns:soap=" <asi:lisaakohteitaresponse xmlns:asi=" <asi:lisaakohteitaresult> <asi:tilakoodi> <asi:tilakoodi>0</asi:tilakoodi> <asi:tilakoodikuvaus>new messages created</asi:tilakoodikuvaus> <asi:sanomatunniste> _ </asi:sanomatunniste> </asi:tilakoodi> <asi:kohdemaara>1</asi:kohdemaara> <asi:kohteet> <asi:kohde> <asi:viranomaistunniste>vaka </asi:viranomaistunniste> <asi:asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <asi:asiointitilitunniste>574909</asi:asiointitilitunniste> <asi:kohteentila>200</asi:kohteentila> <asi:kohteentilakuvaus>asia on tallennettuna ja näkyy asiakkaalle.</asi:kohteentilakuvaus> </asi:asiakas> </asi:kohde> </asi:kohteet> </asi:lisaakohteitaresult> </asi:lisaakohteitaresponse> </soap:body> </soapenv:envelope>

21 V.01 RAJAPINTAKUVAUS V (24) 3.2 HaeAsiakkaita Kyselysanoma Vastaussanoma <?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:asi=" <soapenv:body xmlns:asi=" <asi:haeasiakkaitaresponse> <asi:haeasiakkaitaresult> <asi:tilakoodi> <asi:tilakoodi>0</asi:tilakoodi> <asi:tilakoodikuvaus>onnistui</asi:tilakoodikuvaus> <asi:sanomatunniste> _ </asi:sanomatunniste> </asi:tilakoodi> <asi:asiakkaat> <asi:asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <asi:tila>300</asi:tila> <asi:tilapvm> t11:00: :00</asi:tilapvm> <asi:tilipassivoitu>0</asi:tilipassivoitu> </asi:asiakas> <asi:asiakas AsiakasTunnus=" N" TunnusTyyppi="SSN"> <asi:tila>300</asi:tila> <asi:tilapvm> t10:16: :00</asi:tilapvm> <asi:tilipassivoitu>0</asi:tilipassivoitu> </asi:asiakas> <asi:asiakas AsiakasTunnus=" " TunnusTyyppi="SSN"> <asi:tila>300</asi:tila> <asi:tilapvm> t14:37: :00</asi:tilapvm> <asi:tilipassivoitu>0</asi:tilipassivoitu> </asi:asiakas> </asi:asiakkaat> </asi:haeasiakkaitaresult> </asi:haeasiakkaitaresponse> </soapenv:body> </soapenv:envelope>

22 V.01 RAJAPINTAKUVAUS V (24) 3.3 HaeTilatieto Kyselysanoma Vastaussanoma <?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:asi=" <soapenv:body xmlns:asi=" <asi:haetilatietoresponse> <asi:haetilatietoresult> <asi:tilakoodi> <asi:tilakoodi>0</asi:tilakoodi> <asi:tilakoodikuvaus>ok</asi:tilakoodikuvaus> </asi:tilakoodi> </asi:haetilatietoresult> </asi:haetilatietoresponse> </soapenv:body> </soapenv:envelope> 3.4 LahetaViesti Kyselysanoma: Ohjaustiedot ja kirjeet Kohteet-elementin alla Kohteet-elementin alla yksi vastaanottaja (Kohde-elementti) ja yksi liite: Kohteet-elementin alla useita vastaanottajia (Kohde-elementtejä), jokaisella oma PDF-liite:

23 V.01 RAJAPINTAKUVAUS V (24) Vastaussanoma Aineisto (viestit) on tallennettu Viestit-palvelun käsittelyjonoon:?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:asi=" <soapenv:body xmlns:asi=" <LahetaViestiResponse xmlns=" xmlns:soap=" <LahetaViestiResult> <TilaKoodi> <TilaKoodi>202</TilaKoodi> <TilaKoodiKuvaus>Asia tallennettuna asiointitilipalvelun käsittelyjonoon, mutta se ei vielä näy asiakkaan asiointitilillä. Lopullinen vastaus on haettavissa erikseen erillisellä kutsulla.</tilakoodikuvaus> <SanomaTunniste> _ </SanomaTunniste> </TilaKoodi> </LahetaViestiResult> </LahetaViestiResponse> </soap:body> </soap:envelope> Aineiston sisällössä oli virhe:?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:asi=" <soapenv:body xmlns:asi=" <LahetaViestiResponse xmlns=" xmlns:soap=" <LahetaViestiResult> <TilaKoodi> <TilaKoodi>525</TilaKoodi> <TilaKoodiKuvaus>Asian tietosisällössä virheitä.</tilakoodikuvaus> <SanomaTunniste> _ </SanomaTunniste> </TilaKoodi> </LahetaViestiResult> </LahetaViestiResponse> </soap:body> </soap:envelope> Aineiston käsittely päättyi muuhun virheeseen:?xml version="1.0" encoding="utf-8"?> <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:asi=" <soapenv:body xmlns:asi=" <LahetaViestiResponse xmlns=" xmlns:soap=" <LahetaViestiResult> <TilaKoodi> <TilaKoodi>550</TilaKoodi> <TilaKoodiKuvaus>Muu virhe.</tilakoodikuvaus> <SanomaTunniste> _ </SanomaTunniste> </TilaKoodi> </LahetaViestiResult>

24 V.01 RAJAPINTAKUVAUS V (24) </LahetaViestiResponse> </soapenv:body> </soapenv:envelope>