WS-rajapinta
Huomaattehan, että Suomi.fi-viestien vanhat rajapinnat ovat ylläpitotilassa, eikä niihin lähtökohtaisesti enää tuoteta uusia toiminnallisuuksia. Kaikki vanhat rajapinnat suljetaan 1.1.2027. Tämä tarkoittaa sitä, että kaikkien Suomi.fi-viestejä käyttävien palvelujen pitää siirtyä käyttämään uutta REST-rajapintaa ennen vuotta 2027.
Web Service (WS) on Suomi.fi-viestien vanhoista rajapinnoista monipuolisin. Rajapinta tukee sekä viestien kaksisuuntaisuutta että paperipostiin ohjaamista.
WS-rajapinta jakautuu pakolliseen Viranomaispalvelut-rajapintaan ja vapaaehtoiseen Paluukanava-rajapintaan. Viranomaispalvelut-rajapinnan kautta organisaationne lähettää viestejä ja liitteitä loppukäyttäjille. Paluukanava-rajapinnan kautta Suomi.fi-viestit voi toimittaa järjestelmällenne lähettämienne viestien tilatietoja sekä loppukäyttäjien lähettämiä viestejä.
Viranomaispalvelut- ja Paluukanava-rajapinnan kuvaukset on koottu alle. Huomaattehan, että rajapintojen viestirakenne noudattaa jo vuonna 2010 Kansalaisen asiointitiliä varten suunniteltua rakennetta. Rajapintoihin on tehty muutamia muutoksia ja lisäyksiä, mutta yhteensopivuus vanhoja rajapintoja käyttävien asiakasorganisaatioiden järjestelmien kanssa on säilytetty. Tästä johtuen viestirakenteessa esiintyy vanhoja, asiointitiliin liittyviä termejä.
Sanomissa käytetään UTF-8-enkoodausta, ja niiden formaatti on text/xml.
WS-rajapinnan käyttöönottoon liittyvät yksityiskohdat on kuvattu viimeisessä laajennettavassa osiossa.
Ensimmäinen WS-rajapinta on nimeltään "Viranomaispalvelut". Sen kautta organisaationne voi lähettää viestejä ja liitteitä loppukäyttäjille sekä tarkistaa loppukäyttäjän postilaatikon tai Suomi.fi-viestien järjestelmän tilan.
Rajapinta mahdollistaa neljän eri operaation hyödyntämisen:
- LahetaViesti-operaatiolla organisaationne voi lähettää loppukäyttäjille sähköisiä viestejä, jotka päätyvät tarvittaessa paperitulostukseen.
- LisaaKohteita-operaatiolla organisaationne voi lähettää loppukäyttäjälle sähköisiä viestejä.
- HaeAsiakkaita-operaation avulla organisaationne voi tarkistaa, ketkä tai mitkä asiakkaistanne ovat antaneet suostumuksensa sähköiseen viestintään Suomi.fi-viesteissä.
- HaeTilaTieto-operaatiolla järjestelmänne voi tarkistaa Suomi.fi-viestien järjestelmän tilan.
Rajapinnan varmenteella allekirjoitettu päätepiste on "/Asiointitili/ViranomaispalvelutWSInterface". Varmentamaton päätepiste on "/Asiointitili/ViranomaispalvelutWSInterfaceNonSigned".
Operaatioiden SoapAction-attribuutit on kuvattu taulukossa 1.
Operaatio | SoapAction |
|---|---|
LahetaViesti | http://www.suomi.fi/asiointitili/Viranomaispalvelut/LahetaViesti |
LisaaKohteita | http://www.suomi.fi/asiointitili/Viranomaispalvelut/LisaaKohteita |
HaeAsiakkaita | http://www.suomi.fi/asiointitili/Viranomaispalvelut/HaeAsiakkaita |
HaeTilaTieto | http://www.suomi.fi/asiointitili/Viranomaispalvelut/HaeTilaTieto |
Taulukko 1. Viranomaispalvelut-rajapinnan operaatiot ja niiden SoapAction-attribuutit.
Viranomaispalvelut-rajapinnan kaikkien operaatioiden kyselyn ensimmäisenä elementtinä ovat aina organisaationne tiedot. Tiedot kokoava Viranomainen-elementti on kuvattu alla taulukossa 2.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> ViranomaisTunnus | Suomi.fi-viestien organisaatiollenne antama tunnus, esim. viranomainen_ws | string | pakollinen |
> PalveluTunnus | Suomi.fi-viestien organisaationne palvelulle antama tunnus, esim. viranomainen_ws_palvelu | string | pakollinen |
> KayttajaTunnus | Ajon suorittaneen organisaationne järjestelmän käyttäjän tunniste, esim. timakar | string | - |
> Yhteyshenkilo | Yhteystietonne, johon Suomi.fi-viestit ottaa yhteyttä esim. virhetapauksissa. Sähköpostialiaksen käyttö on suositeltavaa. | attribuuteilla tarkennettu elementti | - |
Yhteyshenkilo > Nimi | Yhteystiedon nimi | attribuutti, string | - |
Yhteyshenkilo > Sahkoposti | Yhteystiedon sähköpostiosoite | attribuutti, string | pakollinen, jos käytetään LahetaViesti-operaatiota |
Yhteyshenkilo > Matkapuhelin | Yhteystiedon matkapuhelinnumero | attribuutti, string | - |
> Osoite | Organisaationne osoitetiedot | lapsielementtejä sisältävä elementti | pakollinen. jos käytetään LahetaViesti-operaation LisaaOsoitesivu-ominaisuutta |
Osoite > Nimi | Organisaationne nimi | string | pakollinen |
Osoite > Lahiosoite | Organisaationne käyntiosoite | string | pakollinen |
Osoite > Postinumero | Postinumero | string | pakollinen |
Osoite > Postitoimipaikka | Postitoimipaikka | string | pakollinen |
Osoite > Maa | Maakoodi (FI) | string | pakollinen |
> SanomaTunniste | Kyselysanoman yksilöivä tunniste, esim. GUID1222888223 | string | pakollinen |
> SanomaVersio | Viestin kutsun versionumero, esim. 1.0 | string | pakollinen |
> SanomaVarmenneNimi | Asiakasorganisaation järjestelmän käyttämän varmenteen varmennenimi (Common Name), esim. Verohallinto | string | pakollinen |
Taulukko 2. Viranomaispalvelut-rajapinnan operaatioiden vaatima Viranomainen-elementti, joka sisältää organisaationne tiedot.
LahetaViesti-operaation avulla organisaationne voi lähettää viestejä, jotka ohjautuvat vastaanottajan postilaatikon tilan mukaan toimitettavaksi joko sähköisesti tai paperipostilla. Täten LahetaViesti-operaation käyttö edellyttää aina TKJ-palvelun käyttöönottoa.
Lähetettävään aineistoon kuuluva PDF-tiedosto välitetään kyselysanoman sisällä Base64-koodattuna. Tiedoston (sanoman) koko voi olla enintään 10 Mt.
Jos viesti menee sähköisen toimituksen sijasta paperipostitukseen, toimitetaan vastaanottajalle vain viestin liitetiedosto. Lähetettävän viestin kaikki asiasisältö tulee siis tallentaa yhteen PDF-tiedostoon. Organisaationne on vastuussa siitä, että lähetetty aineisto soveltuu paperipostitukseen: osoitetietojen ja PDF-muotoisen viestin täytyy olla Postin iPost-palvelun vaatimuksien mukainen. Vaatimukset löydätte Suunnitteluohjeesta kirjeiden lähettämiseen (Posti). Avautuu uuteen ikkunaan.
LahetaViesti-operaation kyselysanoma
Lähetettävän viestin ohjaustiedot ja PDF-muotoinen liite annetaan Kohteet-elementissä. Lähetettävän viestin kaikki asiasisältö tulee tallentaa liitettyyn PDF-tiedostoon. 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.
Samassa kyselysanomassa voi lähettää viestejä useille vastaanottajille. Tällöin jokaisella vastaanottajalla tulee olla oma Kohde-elementti ja siellä jokaiselle vastaanottajalle oma PDF-tiedosto, joka sisältää lähetettävän viestin sisällön. Yhteen Kohde-elementtiin ei voi sisällyttää useampia vastaanottajia tai useampia liitetiedostoja.
Jotta viesti voidaan toimittaa aina perille (olipa loppukäyttäjä antanut suostumuksensa sähköiseen viestintään tai ei), jokaisessa viestissä pitää olla sekä vastaanottajan henkilö- tai Y-tunnus että katuosoite. Digi- ja väestötietovirasto ei hae katuosoitetta väestö- tai yritys- ja yhteisötietojärjestelmästä, vaan organisaationne pitää täyttää se itse kyselysanoman Osoite-osioon.
Taulukossa 3 on esitetty LahetaViesti-operaation kyselysanoman Kysely-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> Paperi | Hallitsee lähetyksen pakotusta paperipostiin. Jos arvoksi asetetaan "true", lähetetään viesti aina myös paperipostilla, vaikka vastaanottajalla olisi sähköinen postilaatikko. | boolean | - |
> Kohteet | Välitettävien viestien tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohteet > Kohde | Yhden viestin tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohde > Asiakas | Loppukäyttäjän tiedot sisältävä elementti | lapsielementtejä sisältävä attribuuteilla tarkennettu elementti | pakollinen |
Asiakas > Asiakastunnus | Loppukäyttäjän henkilö- tai Y-tunnus. Yrityksen Y-tunnus validoidaan, mutta sen olemassaoloa ei tarkasteta yritys- ja yhteisötietojärjestelmästä. | attribuutti, string | pakollinen |
Asiakas > Sahkoposti | EI ENÄÄ KÄYTÖSSÄ | attribuutti, string | - |
Asiakas > Matkapuhelin | EI ENÄÄ KÄYTÖSSÄ | attribuutti, string | - |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä ”CRN” | attribuutti, string | - |
Asiakas > Osoite | Loppukäyttäjän osoite | lapsielementtejä sisältävä elementti | pakollinen |
Osoite > Nimi | Loppukäyttäjän nimi | string | pakollinen |
Osoite > Lahiosoite | Lähiosoite | string | pakollinen |
Osoite > Postinumero | Postinumero | string | pakollinen |
Osoite > Postitoimipaikka | Postitoimipaikka | string | pakollinen |
Osoite > Maa | Maakoodi (FI) | string | pakollinen |
Kohde > Viranomaistunniste | Viestin yksilöivä tunniste organisaationne järjestelmässä. Tunnisteen tulee olla pysyvä ja yksilöivä, esim. diaarinumero. | string | pakollinen |
Kohde > Viittaus | Käytössä silloin, kun viesti on vastaus aikaisempaan loppukäyttäjän lähettämään viestiin | attribuuteilla tarkennettu elementti | - |
Viittaus > ViittausTunniste | Liittyvän viestin tunniste | attribuutti, string | - |
Viittaus > ViittausTunnisteTyyppi | Liittyvän viestin tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste. | attribuutti, string | - |
Kohde > VahvistusVaatimus | Todisteellinen tiedoksianto, joka vaatii kuittauksen lukemisesta (1 = kyllä, 0 = ei) | int | - |
Kohde > VaadiLukukuittaus | Viestinvälityspalvelu voidaan pakottaa lähettämään kuittausviesti kohteesta, vaikka lukukuittausten lähettäminen olisi muuten disabloitu (1 = kyllä, 0 = ei) | int | - |
Kohde > AsiaNumero | Esim. päätöksen numero | string | - |
Kohde > Nimeke | Viestin otsikkotieto, jonka organisaationne järjestelmä tuottaa loppukäyttäjän omalla kielellä. Maksimipituus on 256 merkkiä. | string | pakollinen |
Kohde > LahetysPvm | Lähetyspäivämäärä | dateTime | pakollinen |
Kohde > LahettajaNimi | Organisaationne tarkempi nimi | string | - |
Kohde > KuvausTeksti | Vapaamuotoinen kuvaus asiasta eli lähetettävän viestin sisältö | string | pakollinen |
Kohde > Tila | EI ENÄÄ KÄYTÖSSÄ | lapsielementtejä sisältävä elementti | - |
Kohde > Tiedostot | Viestiin liittyvät asiakirjat, mahdollista antaa kirjeen sisältö (PDF) | lapsielementtejä sisältävä elementti | pakollinen |
Tiedostot > Tiedosto | Yhden tiedoston tiedot kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
Tiedosto > TiedostonKuvaus | Tiedoston sisällön kuvaus | string | pakollinen |
Tiedosto > TiedostoSisalto | Tiedosto Base64-enkoodattuna, maksimikoko 10 megatavua | base64Binary | pakollinen |
Tiedosto > TiedostoMuoto | Tiedoston formaatti (MIME Type), arvo on aina “application/pdf” | string | pakollinen |
Tiedosto > TiedostoNimi | Tiedoston nimi sisältäen tiedostopäätteen | string | pakollinen |
Kohde > SmsLisatieto | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > EmailLisatietoOtsikko | Uusi viesti -ilmoituksen otsikko, joka välitetään loppukäyttäjän sähköpostiin | string | - |
Kohde > EmailLisatietoSisalto | Uusi viesti -ilmoituksen sisältö, joka välitetään loppukäyttäjän sähköpostiin | string | - |
Kohde > TavoitettavuusTietoSMS | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > TavoitettavuusTietoEmail | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > LisaaOsoitesivu | Postitettavan liitetiedoston ensimmäisen sivun tulee sisältää tarpeelliset tiedot lähettäjästä ja vastaanottajasta kirjeen perille toimittamiseksi. Asettamalla LisaaOsoitesivu arvoon "true", luodaan automaattisesti postitettavaan kirjeeseen osoitesivu, nimi- ja osoitetiedoilla. Käytettäessä osoitesivun luontia myös lähettäjän täydelliset osoitetiedot ovat pakolliset Viranomainen-elementti sanomassa. Oletusarvo on "false". | boolean | - |
Kohde > SalliLiitteenKiertoPystyyn | Postitettavan liitetiedoston kaikkien sivujen on oltava mitoiltaan pystyyn asetetun A4-arkin kokoisia, sillä sitä suuremmista sivuista leikataan ylimääräinen sisältö pois automaattisesti. Asettamalla SalliLiitteenKiertoPystyyn arvoon true, Suomi.fi-viestit yrittää tunnistaa vaakasivut ja kääntää ne ennen paperipostitusta. Oletusarvo on "false". | boolean | - |
> Tulostustoimittaja | Tulostustoimittaja, jonka kanssa asiakasorganisaatiolla on tulostussopimus. Tällä hetkellä tuettuna on vain "Posti". | string | pakollinen |
> LahetaTulostukseen (aikaisemmin LahetaOC) | EI ENÄÄ KÄYTÖSSÄ | boolean | - |
> Laskutus | TKJ-palvelun käytön laskutuksen vaatimat tiedot | lapsielementtejä sisältävä elementti | pakollinen |
Laskutus > Tunniste | Tulostustoimittajalle toimitettava palvelukohtainen TKJ-tunniste | string | pakollinen |
Laskutus > Salasana | Laskutukseen liittyvä salasana, jos tulostustoimittaja sitä vaatii | string | - |
Laskutus > Kustannuspaikka | Asiakasorganisaation sisäiseen kustannusten seurantaan tai niiden kohdentamista varten käytettävä tunniste. Tunniste on 1-15 merkkiä pitkä, muoto [A-Z0-9]{1,15}. | string | - |
> Varitulostus | Asetetaan värillinen tulostus postitusaineistoon, oletuksena mustavalkoisuus | boolean | - |
Taulukko 3. LahetaViesti-operaation Kysely-elementti sekä sen sisältämät elementit.
LahetaViesti-operaation vastaussanoma
LahetaViesti-kyselyn vastausanoma (LahetaViestiResponse) lähetetään organisaatiollenne, kun aineisto (viestit) on tallennettu Suomi.fi-viestien käsittelyjonoon, josta viestit lähetetään sähköisesti tai paperipostituksella. Jos aineiston lähetys tai jatkokäsittely epäonnistuu, siitä 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.
Taulukossa 4 on esitetty LahetaViesti-operaation vastaussanoman LahetaViestiResponse-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> LahetaViestiResult | Vastaussanoman tulokset kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
LahetaViestiResult > TilaKoodi | Vastauksen tilatiedot | lapsielementtejä sisältävä elementti | - |
Tilakoodi > TilaKoodi | Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa TilaKoodiKuvaus-selitekentässä. Onnistumista kuvaavat koodit:
Virhekoodit:
Lisäksi muissa virhetilanteissa (esim. alustatason virheet) voidaan palauttaa SOAP Fault. Viestin välitön uudelleenlähetys on turhaa. | int | pakollinen |
Tilakoodi > TilaKoodiKuvaus | Virhekoodin selitekenttä. Esimerkiksi Viranomaistunnisteella löytyy jo viesti, joka on tallennettu asiakkaan postilaatikkoon Suomi.fi-viesteissä. | string | - |
Tilakoodi > SanomaTunniste | Kyselysanoman yksilöivä ID-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa | string | - |
Taulukko 4. LahetaViesti-operaation vastaussanoman LahetaViestiResponse-elementti sekä sen sisältämät elementit.
LisaaKohteita-operaation avulla organisaationne järjestelmä voi lähettää Suomi.fi-viesteihin sähköisiä asiointiasioita ja tiedoksiantoja sekä saada vastauksia kyselyihin. Lähetetyt viestit voivat sisältää linkkejä organisaationne välivarastossa oleviin asiakirjoihin tai kokonaisia asiakirjoja, jotka tallennetaan Suomi.fi-viestien välivarastoon.
Lähetetty viesti voidaan liittää jo olemassa olevaan viestiin, jolloin se näkyy loppukäyttäjälle olemassa olevan asiointiasian yhteydessä (esimerkiksi lisäselvityspyyntö tai vastaus kysymykseen).
Organisaationne tulee toimittaa jokaiselle viestille tunniste. Tunnisteen tulee olla yksilöllinen organisaationne palvelun sisällä ajasta riippumatta.
Kyselyn vastauksena voidaan toimittaa lähetettyjen viestien tallennustiedot loppukäyttäjäkohtaisesti (synkroninen) tai pelkkä kuittaus viestien vastaanottamisesta (asynkroninen). Viestintätyyppi on valittavissa liittymisen yhteydessä asiakasorganisaatiokohtaisesti.
LisaaKohteita soveltuu ainoastaan viestien sähköiseen lähettämiseen. Jos loppukäyttäjä ei ole antanut suostumustaan sähköiseen viestintään ja organisaationne haluaa, että viestit toimitetaan paperipostilla, on käytettävä LahetaViesti-operaatiota.
Huom! Lähetettävään viestiin kuuluva liitetiedosto välitetään kyselysanoman sisällä Base64-koodattuna. Tiedoston (sanoman) koko voi olla enintään 10 Mt.
LisaaKohteita-operaation kyselysanoma
Taulukossa 5 on esitetty LisaaKohteita-operaation kyselysanoman Kysely-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> KohdeMaara | Lähetettävien asioiden lukumäärä | int | pakollinen |
> Kohteet | Viestit kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohteet > Kohde | Yhden viestin tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohde > Asiakas | Viestiin liittyvän loppukäyttäjän tiedot. Elementissä voidaan toimittaa vain yhden loppukäyttäjän tiedot. | lapsielementtejä sisältävä attribuuteilla tarkennettu elementti | pakollinen |
Asiakas > AsiakasTunnus | Loppukäyttäjän henkilötunnus tai Y-tunnus. Yrityksen Y-tunnus validoidaan, mutta sen olemassaoloa ei tarkasteta yritys- ja yhteisötietojärjestelmästä. | attribuutti, string | pakollinen |
Asiakas > Sahkoposti | EI ENÄÄ KÄYTÖSSÄ | attribuutti, string | - |
Asiakas > Matkapuhelin | EI ENÄÄ KÄYTÖSSÄ | attribuutti, string | - |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä ”CRN” | attribuutti, string | - |
Asiakas > Osoite | Loppukäyttäjän osoite | lapsielementtejä sisältävä elementti | - |
Osoite > Nimi | Loppukäyttäjän nimi | string | pakollinen |
Osoite > Lahiosoite | Lähiosoite | string | pakollinen |
Osoite > Postinumero | Postinumero | string | pakollinen |
Osoite > Postitoimipaikka | Postitoimipaikka | string | pakollinen |
Osoite > Maa | Maakoodi (FI) | string | pakollinen |
Kohde > ViranomaisTunniste | Viestin yksilöivä tunniste asiakasorganisaation järjestelmässä. Tunnisteen tulee olla pysyvä ja yksilöivä, esim. palvelu + vastaanottaja + senderLetterID on kokonaisuutena aina globaalisti yksilöivä. Maksimipituus on 256 merkkiä. | string | pakollinen |
Kohde > Viittaus | Käytössä silloin, kun viesti on vastaus aikaisempaan loppukäyttäjän lähettämään viestiin | attribuuteilla tarkennettu elementti | - |
Viittaus > ViittausTunniste | Liittyvän viestin tunniste | attribuutti, string | pakollinen |
Viittaus > ViittausTunnisteTyyppi | Liittyvän viestin tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste. | attribuutti, string | pakollinen |
Kohde > VahvistusVaatimus | Todisteellinen tiedoksianto, joka vaatii kuittauksen lukemisesta (1 = kyllä, 0 = ei) | int | - |
Kohde > VaadiLukukuittaus | Viestinvälityspalvelu voidaan pakottaa lähettämään kuittausviesti kohteesta, vaikka lukukuittausten lähettäminen olisi muuten disabloitu (1 = kyllä, 0 = ei) | int | - |
Kohde > AsiaNumero | Esim. päätöksen numero | string | - |
Kohde > Nimeke | Viestin otsikkotieto, jonka organisaationne järjestelmä tuottaa loppukäyttäjän omalla kielellä. Maksimipituus on 256 merkkiä. Jos viestityyppi on ilmoitusviesti, viestin otsikkotieto välittyy kokonaan uusi viesti -ilmoitukseen. | string | pakollinen |
Kohde > LahetysPvm | Lähetyspäivämäärä | dateTime | pakollinen |
Kohde > LahettajaNimi | Lähettäneen asiakasorganisaation tarkempi nimi | string | - |
Kohde > KuvausTeksti | Vapaamuotoinen kuvaus asiasta eli lähetettävän viestin sisältö. Jos viestityyppi on ilmoitusviesti, viestin sisältö välittyy kokonaisuudessaan myös uusi viesti -ilmoitukseen. | string | pakollinen |
Kohde > Maksullisuus | EI ENÄÄ KÄYTÖSSÄ | int | - |
Kohde > MaksamisKuvausTeksti | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > Tila | EI ENÄÄ KÄYTÖSSÄ | lapsielementtejä sisältävä elementti | - |
Kohde > Tiedostot | Viestiin liittyvät asiakirjat | lapsielementtejä sisältävä elementti | - |
Tiedostot > Tiedosto | Yhden tiedoston tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Tiedosto > TiedostonKuvaus | Asiakirjan selite | string | - |
Tiedosto> TiedostoURL | Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään organisaationne omaa välivarastoa | string | - |
Tiedosto > TiedostoSisalto | Tiedosto Base64-enkoodattuna | base64Binary | - |
Tiedosto > TiedostoKoko | Tiedoston koko kilotavuina | string | - |
Tieodosto > TiedostoMuoto | Tiedoston formaatti (MIME Type), esim. ”application/pdf” | string | - |
Tiedosto > TiedostoNimi | Tiedoston nimi sisältäen tiedostopäätteen | string | pakollinen, jos tiedosto annettu |
Kohde > ViranomaisenEmail | Sähköpostiliityntä: Puolipisteellä eroteltuina joko 1 tai useampi sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. | string | - |
Kohde > SmsLisatieto | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > EmailLisatietoOtsikko | Uusi viesti -ilmoituksen otsikko, joka välitetään loppukäyttäjän sähköpostiin | string | - |
Kohde > EmailLisatietoSisalto | Uusi viesti -ilmoituksen sisältö, joka välitetään loppukäyttäjän sähköpostiin | string | - |
Kohde > TavoitettavuusTietoSMS | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > TavoitettavuusTietoEmail | EI ENÄÄ KÄYTÖSSÄ | string | - |
Kohde > Viestityyppi | Normaaliviesti = 1 (oletus jos viestityyppiä ei annettu), ilmoitusviesti = 2 | int | - |
Taulukko 5. LisaaKohteita-operaation Kysely-elementti sekä sen sisältämät elementit.
LisaaKohteita-operaation vastaussanoma
Taulukossa 6 on esitetty LisaaKohteita-operaation vastaussanoman LisaaKohteitaResponse-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> LisaaKohteitaResult | Vastaussanoman tulokset kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
LisaaKohteitaResult > TilaKoodi | Vastauksen tilatiedot | lapsielementtejä sisältävä elementti | - |
TilaKoodi > TilaKoodi | Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit:
Virhekoodit:
Lisäksi muissa virhetilanteissa (esim. alustatason virheet) voidaan palauttaa SOAP Fault. | int | pakollinen |
Tilakoodi > TilaKoodiKuvaus | Virhekoodin selitekenttä. Esimerkiksi kyselyssä oleva KohdeMaara ei vastaa kyselyssä olevien Itemien määrää. | string | - |
Tilakoodi > SanomaTunniste | Kyselysanoman yksilöivä ID-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa | string | - |
LisaaKohteitaResult > KohdeMaara | Käsiteltyjen asioiden lukumäärä | int | - |
LisaaKohteitaResult > Kohteet | Käsitellyt viestit kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohteet > Kohde | Yhden viestin tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohde > ViranomaisTunniste | Viestin yksilöivä tunniste asiakasorganisaation järjestelmässä, sama kuin kyselysanomassa | string | - |
Kohde > Asiakas | Viestiin liittyvän loppukäyttäjän tiedot. Viesti liitetään kyseisen loppukäyttäjän sähköiseen postilaatikkoon Suomi.fi-viesteissä. | lapsielementtejä sisältävä attribuuteilla tarkennettu elementti | - |
Asiakas > AsiakasTunnus | Loppukäyttäjän henkilötunnus tai yrityksen Y-tunnus | attribuutti, string | - |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä ”CRN” | attribuutti, string | - |
Asiakas > AsiointitiliTunniste | Viestin yksilöivä tunniste, jonka Suomi.fi-viestit on viestille antanut. AsiointitiliTunniste yksilöi viestin aina loppukäyttäjäkohtaisesti. | string | - |
Asiakas > KohteenTila | Kyselyn tallennuksen käsittelytila. Käsittelytila palautetaan loppukäyttäjäkohtaisesti. Onnistuneet statukset (viesti on tallennettu Suomi.fi-viesteihin):
Epäonnistuneet statukset (viestiä ei ole tallennettu Suomi.fi-viesteihin):
| int | pakollinen |
Asiakas > KohteenTilaKuvaus | Tarkempi kuvaus virheestä, esim. liitetiedostoon liittyvän virheen tapauksessa tiedoston nimi | string | - |
Taulukko 6. LisaaKohteita-operaation vastaussanoman LisaaKohteitaResponse-elementti sekä sen sisältämät elementit.
HaeAsiakkaita-operaation avulla organisaationne järjestelmä voi tarkistaa, ketkä tai mitkä asiakkaistanne ovat antaneet suostumuksensa sähköiseen viestintään Suomi.fi-viesteissä. Tarkistus voidaan tehdä joko yksittäisen henkilö- tai Y-tunnuksen osalta tai kaikista organisaationne asiakkaista.
Vastaussanomassa saadaan tieto, onko loppukäyttäjällä käytössään sähköinen postilaatikko Suomi.fi-viesteissä.
Kyselyä voidaan myös rajata ajan suhteen siten, että haetaan vain ne loppukäyttäjät, jotka ovat aloittaneet Suomi.fi-viestien käytön tietyn aikavälin sisällä.
Kyselyä ohjataan kutsusanoman KyselyLaji-elementillä (ks. ensimmäinen elementti taulukossa 7). Sallitut arvot ovat Kaikki, Asiakkaat ja TilaMuutos.
Kaikki- tai TilaMuutos-kyselylajien vastaussanomassa on enintään 1000 loppukäyttäjän tiedot. Jos vastaussanomassa on tasan 1000 loppukäyttäjän tiedot, kyselyä vastaavia loppukäyttäjiä on lisää. Tällöin organisaationne pitää tehdä uusi haku, jossa KyselyAlku-elementin arvoksi laitetaan edellisen kyselyn vastaussanomassa viimeisenä olevan loppukäyttäjän TilaPvm. Tätä toistetaan, kunnes vastaussanomassa on vähemmän kuin 1000 loppukäyttäjän tiedot.
HaeAsiakkaita-operaation kyselysanoma
Taulukossa 7 on esitetty HaeAsiakkaita-operaation kyselysanoman Kysely-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> KyselyLaji | Kyselytyypin kertova elementti. Vaihtoehdot ovat:
Jos käytetään kyselylajia Kaikki, on annettava KyselyAlku- ja KyselyLoppu-tiedot. Jos käytetään kyselylajia Asiakkaat, on annettava Asiakkaat-elementissä tarkistettavat tunnukset. Jos käytetään kyselylajia TilaMuutos, on annettava KyselyAlku- ja KyselyLoppu-tiedot. | string | - |
> KyselyAlku | Jos elementti on annettu, palautetaan vain
| dateTime | pakollinen, jos haetaan kyselylajilla Kaikki tai TilaMuutos |
> KyselyLoppu | Jos elementti on annettu, palautetaan vain
| dateTime | pakollinen, jos haetaan kyselylajilla Kaikki tai TilaMuutos |
> Asiakkaat | Loppukäyttäjät kokoava elementti, jos haetaan annetun listan sisältämien loppukäyttäjien tiedot | lapsielementtejä sisältävä elementti | pakollinen, jos haetaan kyselylajilla Asiakkaat ei käytössä, jos haetaan kyselylajilla TilaMuutos |
Asiakkaat > Asiakas | Yhden loppukäyttäjän tiedot kokoava elementti | attribuuteilla tarkennettu elementti | - |
Asiakas > AsiakasTunnus | Henkilön henkilötunnus tai yrityksen Y-tunnus | attribuutti, string | pakollinen |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä ”CRN” | attribuutti, string | pakollinen |
Taulukko 7. HaeAsiakkaita-operaation Kysely-elementti sekä sen sisältämät elementit.
HaeAsiakkaita-operaation vastaussanoma
Taulukossa 8 on esitetty HaeAsiakkaita-operaation vastaussanoman HaeAsiakkaitaResponse-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> HaeAsiakkaitaResult | Vastaussanoman tulokset kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
HaeAsiakkaitaResult > TilaKoodi | Vastaussanoman tilatiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Tilakoodi > TilaKoodi | Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit:
Virhekoodit:
Lisäksi muissa virhetilanteissa (esim. alustatason virheet) voidaan palauttaa SOAP Fault. | int | pakollinen |
Tilakoodi > TilaKoodiKuvaus | Virhekoodin selitekenttä. Esimerkiksi ViranomaisTunnus ei vastaa autentikointitietoa. | string | - |
Tilakoodi > SanomaTunniste | Kyselysanoman yksilöivä ID-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa | string | - |
HaeAsiakkaitaResult > Asiakkaat | Loppukäyttäjät kokoava elementti | lapsielementtejä sisältävä elementti | - |
Asiakkaat > Asiakas | Yhden loppukäyttäjän tiedot kokoava elementti | lapsielementtejä sisältävä attribuuteilla tarkennettu elementti | - |
Asiakas > AsiakasTunnus | Henkilön henkilötunnus tai yrityksen Y-tunnus | attribuutti, string | - |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä ”CRN” | attribuutti, string | - |
Asiakas > Tila | Loppukäyttäjän tilatieto
| int | pakollinen |
Asiakas > TilaPvm | Kaikki- ja Asiakkaat-kyselylajit: Loppukäyttäjän Suomi.fi-viesteissä olevien tietojen muutosaikaleima. TilaMuutos-kyselylaji: Loppukäyttäjän viimeisimmän tilamuutoksen aikaleima. | dateTime | pakollinen |
Asiakas > TiliPassivoitu | Lisätietokenttä. Kertoo, onko loppukäyttäjä passivoinut sähköisen postilaatikkonsa Suomi.fi-viesteissä. Jos postilaatikko on passivoitu, arvo on 1, muuten aina 0. | int | pakollinen |
Taulukko 8. HaeAsiakkaita-operaation vastaussanoman HaeAsiakkaitaResponse-elementti sekä sen sisältämät elementit.
Organisaationne järjestelmä voi tarkistaa Suomi.fi-viestit-palvelun tilan HaeTilaTieto-operaation avulla.
HaeTilaTieto-operaation kyselysanoma
Taulukossa 9 on esitetty HaeTilaTieto-operaation kyselysanoman Kysely-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
Kysely | Tyhjä elementti, ei sisällä mitään tietoa | - | - |
Taulukko 9. HaeTilaTieto-operaation Kysely-elementti.
HaeTilaTieto-operaation vastaussanoma
Taulukossa 10 on esitetty HaeTilaTieto-operaation vastaussanoman HaeTilaTietoResponse-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> HaeTilaTietoResult | Vastaussanoman tulokset kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
HaeTilaTietoResult> TilaKoodi | Vastaussanoman tilatiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Tilakoodi > TilaKoodi | Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Onnistumista kuvaavat koodit:
Virhekoodit:
Lisäksi muissa virhetilanteissa (esim. alustatason virheet) voidaan palauttaa SOAP Fault. | int | pakollinen |
Tilakoodi > TilaKoodiKuvaus | Virhekoodin selitekenttä | string | - |
Tilakoodi > SanomaTunniste | Kyselysanoman yksilöivä ID-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa | string | - |
Taulukko 10. HaeTilaTieto-operaation vastaussanoman HaeTilaTietoResponse-elementti sekä sen sisältämät elementit.
Paluukanava-rajapinta on toinen Suomi.fi-viesteissä käytettävistä WS-rajapinnoista. Paluukanavan avulla Suomi.fi-viestit voi toimittaa organisaationne järjestelmälle viestien tilatietoja sekä loppukäyttäjien lähettämiä viestejä. Paluukanavan käyttäminen on vapaaehtoista.
Organisaationne määrittelee rajapinnan osoitteen itse ja ilmoittaa sen Suomi.fi-viesteille.
Rajapinta mahdollistaa kahden eri operaation hyödyntämisen:
VieKohteita-operaatio toimittaa loppukäyttäjän lähettämän viestin organisaationne järjestelmälle.
VieKohdeTiloja-operaatio toimittaa organisaationne järjestelmälle viestien tilatietoja.
Operaatioiden SoapAction-attribuutit on kuvattu taulukossa 11.
Parametri | SoapAction |
|---|---|
VieKohteita | http://www.suomi.fi/asiointitili/ViranomaisPaluukanava/VieKohteita |
VieKohdeTiloja | http://www.suomi.fi/asiointitili/ViranomaisPaluukanava/VieKohdeTiloja |
Taulukko 11. Paluukanava-rajapinnan operaatiot ja niiden SoapAction-attribuutit.
Paluukanavan URL eli URL organisaationne järjestelmään välitetään SOAP-sanoman headerissa (ks. taulukko 12).
Parametri | Selite | Tyyppi |
|---|---|---|
paluukanavaUrl | Organisaationne järjestelmän URL | string |
Taulukko 12. PaluukanavaUrl-elementti, johon organisaationne järjestelmän URL määritellään.
Molempien paluukanava-rajapinnan operaatioiden kyselyn ensimmäisenä elementtinä ovat organisaationne tiedot. Tiedot kokoava Viranomainen-elementti on kuvattu alla taulukossa 13.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> ViranomaisTunnus | Suomi.fi-viestien organisaatiollenne antama tunnus, esim. viranomainen_ws | string | pakollinen |
> PalveluTunnus | Suomi.fi-viestien organisaationne palvelulle antama tunnus, esim. viranomainen_ws_palvelu | string | pakollinen |
> KayttajaTunnus | Ajon suorittaneen asiakasorganisaation järjestelmän käyttäjän tunniste, esim. timakar | string | - |
> SanomaTunniste | Kutsusanoman yksilöivä tunniste, esim. GUID1222888223 | string | pakollinen |
> SanomaVersio | Viestin kutsun versionumero, esim. 1.0 | string | pakollinen |
> SanomaVarmenneNimi | Asiakasorganisaation järjestelmän käyttämän varmenteen varmennenimi (Common Name), esim. Verohallinto | string | pakollinen |
Taulukko 13. Paluukanava-rajapinnan operaatioiden vaatima Viranomainen-elementti, joka sisältää organisaationne tiedot.
Paluukanava-rajapintaan on versiosta 2.0 alkaen lisätty tuki loppukäyttäjien tekemälle puolesta asioinnille. Henkilö voi siis asioida toisen henkilön tai yrityksen puolesta, jolloin hänestä käytetään nimitystä asiamies. Asiamiehen tunniste ja nimi toimitetaan sanoman Asiakas-elementissä, mutta vain VieKohteita-operaatiossa.
Tieto Paluukanavassa käytettävän rajapinnan versiosta tallennetaan samaan paikkaan kuin muut asiakas- ja palvelukohtaiset määrittelyt. Vaikka rajapintaversiota 2.0 ei olisi otettu määrittelyissä käyttöön, Viranomainen-elementin SanomaVersio-kentässä toimitetaan tieto siitä, että kyseessä oli toisen puolesta asiointi. Rajapintaversio 2.0 on taaksepäin yhteensopiva.
VieKohteita-operaatio toimittaa loppukäyttäjän lähettämän viestin organisaationne järjestelmälle.
Lähetettävään viestiin kuuluvat liitetiedostot välitetään kyselysanoman sisällä Base64-koodattuna. Liitetiedostojen (sanoman) yhteenlaskettu enimmäiskoko on 10 Mt.
VieKohteita-operaation kyselysanoma
Taulukossa 14 on esitetty VieKohteita-operaation kyselysanoman Kysely-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> KohdeMaara | Lähetettävien viestien lukumäärä | int | pakollinen |
> Kohteet | Viestit kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohteet > Kohde | Yhden viestin tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohde > Asiakas | Viestiin liittyvän loppukäyttäjän tiedot | attribuuteilla tarkennettu elementti | pakollinen |
Asiakas > AsiakasTunnus | Henkilön henkilötunnus tai yrityksen Y-tunnus | attribuutti, string | pakollinen |
Asiakas > Sahkoposti | EI ENÄÄ KÄYTÖSSÄ | attribuutti, string | - |
Asiakas > Matkapuhelin | EI ENÄÄ KÄYTÖSSÄ | attribuutti, string | - |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä "CRN" | attribuutti, string | - |
Asiakas > PuolestaAsioijanTunnus | Asiamiehen henkilötunnus, jos kyse puolesta-asioinnista | attribuutti, string | - |
Asiakas > PuolestaAsioijanNimi | Asiamiehen nimi muodossa "Etunimi Sukunimi", jos kyse puolesta-asioinnista | attribuutti, string | - |
Kohde > Asiointitilitunniste | Yksilöivä tunniste, jonka Suomi.fi-viestit on antanut viestille | string | - |
Kohde > Viittaus | Viittaus toiseen viestiin, johon kyseinen viesti liittyy. Tietoa voidaan käyttää viestiketjujen muodostamiseen. | lapsielementtejä sisältävä elementti | - |
Viittaus > Viittaus_WS | Viittauksen kokoava elementti | attribuuteilla tarkennettu elementti | - |
Viittaus_WS > ViittausTunniste | Liittyvän viestin tunniste | attribuutti, string | pakollinen |
Viittaus_WS > ViittausTunnisteTyyppi | Liittyvän viestin tunnisteen tyyppi. Arvot: AsiointitiliTunniste tai ViranomaisTunniste. | attribuutti, string | pakollinen |
Kohde > Nimeke | Viestin otsikkotieto | string | pakollinen |
Kohde > LahetysPvm | Lähetyspäivämäärä | dateTime | pakollinen |
Kohde > LahettajaNimi | Viestin lähettäjän nimi | string | - |
Kohde > Kuvausteksti | Vapaamuotoinen kuvaus | string | - |
Kohde > Tiedostot | Viestiin liittyvät asiakirjat | lapsielementtejä sisältävä elementti | - |
Tiedostot > Tiedosto | Yhden tiedoston tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Tiedosto > TiedostonKuvaus | Asiakirjan selite | string | - |
Tiedosto > TiedostoURL | Tiedoston URL, josta asiakirja on ladattavissa, jos käytetään asiakasorganisaation omaa välivarastoa | string | - |
Tiedosto > TiedostoSisalto | Tiedosto Base64-enkoodattuna | base64Binary | - |
Tiedosto > TiedostoKoko | Tiedoston koko kilotavuina | string | - |
Tiedosto > TiedostoMuoto | Tiedoston formaatti (MIME Type) | string | - |
Tiedosto > TiedostoNimi | Tiedoston nimi sisältäen tiedostopäätteen | string | - |
Kohde > ViranomaisenEmail | Sähköpostiliityntä: Puolipisteellä eroteltuina joko 1 tai useampi sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. | string | - |
Taulukko 14. VieKohteita-operaation Kysely-elementti sekä sen sisältämät elementit.
VieKohteita-operaation vastaussanoma
Taulukossa 15 on esitetty VieKohteita-operaation vastaussanoman VieKohteitaResponse-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> VieKohteitaResult | Vastaussanoman tulokset kokoava elementti | lapsielementtejä sisältävä elementti | - |
VieKohteitaResult > TilaKoodi | Vastaussanoman tilatiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
TilaKoodi > TilaKoodi | Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Suomi.fi-viestit yrittää lähettää sanoman uudelleen jos tilakoodina palautetaan muu kuin 0 tai 400-449. Onnistumista kuvaavat koodit:
Virhekoodit:
| int | pakollinen |
TilaKoodi > TilaKoodiKuvaus | Virhekoodin selitekenttä. Esimerkiksi kyselyssä oleva KohdeMaara ei vastaa kyselyssä olevien Itemien määrää. | string | - |
TilaKoodi > SanomaTunniste | Kyselysanoman yksilöivä ID-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa | string | - |
VieKohteitaResult > KohdeMaara | Käsiteltyjen viestien lukumäärä | int | pakollinen |
VieKohteitaResult > Kohteet | Käsitellyt viestit kokoava elementti, samat tiedot kuin kyselysanomassa | lapsielementtejä sisältävä elementti | pakollinen |
Kohteet > Kohde | Yhden viestin tiedot kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
Kohde > AsiointitiliTunniste | Yksilöivä tunniste, jonka Suomi.fi-viestit on antanut viestille | string | - |
Kohde > ViranomaisTunniste | Viestin yksilöivä uusi tunniste organisaationne järjestelmässä (Ei sama kuin kyselysanomassa Viittaus-elementissä oleva ViranomaisTunniste). Suomi.fi-viestit tallentaa tämän järjestelmään ja tätä tunnistetta voidaan hyödyntää myöhemmin Viittaus-elementissä ja käyttää viestiketjujen muodostamiseen organisaationne järjestelmässä. | string | - |
Kohde > KohteenTila | Kyselyn tallennuksen käsittelytila. Suomi.fi-viestit ei yritä sanoman uudelleenlähetystä epäonnistuneella statuksella oleville. Onnistuneet statukset
Epäonnistuneet statukset
| int | pakollinen |
Kohde > KohteenTilaKuvaus | Tarkempi kuvaus virheestä. Esimerkiksi liitetiedostoon liittyvän virheen tapauksessa tiedoston nimi. | string | - |
Taulukko 15. VieKohteita-operaation vastaussanoman VieKohteitaResponse-elementti sekä sen sisältämät elementit.
VieKohdeTiloja-operaatio toimittaa organisaationne järjestelmälle viestien tilatietoja.
Tilat voivat saapua viranomaisjärjestelmään missä tahansa järjestyksessä ja tästä johtuen esimerkiksi todisteellisen tiedoksiannon kuittaus voi saapua ennen lukukuittausta. "KohteenTilaPvm"-aikaleima kertoo, milloin viestin tila on muuttunut, joten päättelyt viestin tilaan liittyen kannattaa tehdä tämän aikaleiman perusteella.
VieKohdeTiloja-operaation kyselysanoma
Taulukossa 16 on esitetty VieKohdeTiloja-operaation kyselysanoman Kysely-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> KohdeMaara | Lähetettävien viestien lukumäärä | int | pakollinen |
> Kohteet | Viestit kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohteet > Kohde | Yhden viestin tiedot kokoava elementti | lapsielementtejä sisältävä elementti | - |
Kohde > ViranomaisTunniste | Viestin yksilöivä tunniste organisaationne järjestelmässä. Tunnisteen tulee olla pysyvä ja yksilöivä. Tämä tunniste on sama kuin LahetaViesti/LisaaKohteita-operaatiossa ja tällä yksilöidään mitä organisaationne lähettämää viestiä sanomassa saadut tilatiedot koskevat. | string | - |
Kohde > Asiakas | Viestiin liittyvän loppukäyttäjän tiedot | lapsielementtejä sisältävä attribuuteilla tarkennettu elementti | - |
Asiakas > AsiakasTunnus | Henkilön henkilötunnus tai yrityksen Y-tunnus | attribuutti, string | pakollinen |
Asiakas > TunnusTyyppi | Henkilöillä ”SSN”, yrityksillä "CRN" | attribuutti, string | pakollinen |
Asiakas > AsiointitiliTunniste | Tunniste, jolla organisaationne lähettämä viesti yksilöitiin Suomi.fi-viesteissä. Jos loppukäyttäjä vastaa viestiin, tämä tunniste välittyy vastauksessa (ks. VieKohteita-operaatio). | string | - |
Asiakas > KohteenTila | Kuittauksen lajikoodi:
| int | pakollinen |
Asiakas > KohteenTilaPvm | Kohteen tilan muutosaikaleima | dateTime | pakollinen |
Asiakas > KohteenTilaKuvaus | Kohteen tilan selite. Esimerkiksi viesti on tallennettuna ja näkyy loppukäyttäjälle. | string | - |
Kohde > ViranomaisenEmail | Sähköpostiliityntä: Puolipisteellä eroteltuina joko 1 tai useampi sähköpostiosoite (jos reply-to on eri). Viestit lähetetään kaikkiin osoitteisiin. | string | - |
Kohde > Nimeke | Viestin otsikkotieto | string | - |
Taulukko 16. VieKohdeTiloja-operaation Kysely-elementti sekä sen sisältämät elementit.
VieKohdeTiloja-operaation vastaussanoma
Taulukossa 17 on esitetty VieKohdeTiloja-operaation vastaussanoman VieKohdeTilojaResponse-elementti.
Parametri | Selite | Tyyppi | Pakollisuus |
|---|---|---|---|
> VieKohdeTilojaResult | Vastaussanoman tulokset kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
VieKohdeTilojaResult > TilaKoodi | Vastaussanoman tilatiedot kokoava elementti | lapsielementtejä sisältävä elementti | pakollinen |
Tilakoodi > TilaKoodi | Vastauksen tilakoodi. Tarkempi tieto virhetilanteiden tapauksessa annetaan tekstimuotoisessa virhekoodin selitekentässä. Jos tilakoodina palautetaan muu kuin 0 tai 400-449, Suomi.fi-viestit yrittää lähettää sanoman uudelleen. Onnistumista kuvaavat koodit:
Virhekoodit:
Jos palvelun suorituksessa tapahtuu tekninen virhe, palvelu palauttaa kutsujalle SOAP Faultin. Viestin välitön uudelleenlähetys on turhaa. | int | pakollinen |
Tilakoodi > TilaKoodiKuvaus | Virhekoodin selitekenttä. Esimerkiksi kyselyssä oleva KohdeMaara ei vastaa kyselyssä olevien Itemien määrää. | string | - |
Tilakoodi > SanomaTunniste | Kutsusanoman yksilöivä ID-tieto, jota voidaan käyttää esim. lokitiedon tutkimisessa | string | - |
Taulukko 17. VieKohdeTiloja-operaation vastaussanoman VieKohdeTilojaResponse-elementti sekä sen sisältämät elementit.
Mikä tahansa WS-rajapintaa tukeva organisaationne jo olemassa oleva tietojärjestelmä voidaan liittää Suomi.fi-viesteihin. Tietojärjestelmä liitetään Valtorin Yhteiseen integraatioalustaan (VIA), jonka kautta viestiliikenne kulkee. VIA tarjoaa liitynnän SOAP-palveluna HTTPS-siirtoprotokollan yli.
Vaihtoehtoisesti ohjelmistotoimittaja voi tehdä ohjelmistoonsa valmiin liitynnän Suomi.fi-viesteihin. Tämän ns. connectorin avulla asiakasorganisaatiot voivat ottaa Suomi.fi-viestit käyttöön paljon nopeammin ja halvemmalla kuin rakentamalla integraation alusta asti itse. Ohjelmistotoimittaja päättää, mitä ominaisuuksia connector-liitäntäänsä toteuttaa.
Suomi.fi-viesteihin liittyminen WS-rajapintaa käyttäen tapahtuu Digi- ja väestötietoviraston tarjoaman testiympäristön kautta. Testiympäristöön kytkeydytään VIAn QAT-ympäristön kautta. Tuotantoympäristöön voi liittyä vasta, kun tarvittavat testaukset testiympäristössä on suoritettu. Tuotantoympäristöön kytkeydytään VIAn PRO-ympäristön kautta.
Testaus
Suomi.fi-viestien rajapintojen testaaminen voidaan suorittaa kahdessa vaiheessa: ilman sanomien allekirjoitusta ja allekirjoituksen kanssa. Molempiin vaiheisiin liittyvät testit on mahdollista suorittaa rinnakkain, jolloin integraation toteuttaminen nopeutuu. Testiympäristö on sama molemmissa vaiheissa. Molemmissa rajapinnoissa (sekä Viranomaispalvelut että Paluukanava) käytetään samaa ympäristöä ja samoja testaamisen vaiheita.
Seuraavaksi on esitetty testaamisen vaiheiden sisältö. Kuvassa 1 on esitetty sanoman kulku Viranomaispalvelut-rajapintaan ja kuvassa 2 Paluukanava-rajapintaan.
Vaihe 1: Testaaminen ilman allekirjoitusta
Kaikkien WS-kutsusanomien Viranomainen-elementtiin tulee täyttää elementti SanomaVarmenneNimi. Kentän arvon on hyvä olla sama kuin myöhemmissä vaiheissa allekirjoitukseen käytettävän varmenteen Common Name (CN).
Testaamisessa käytettävän VIA-rajapinnan osoite Viranomaispalvelut-rajapinnan osalta on
- https://qat.integraatiopalvelu.fi/Asiointitili/ViranomaispalvelutWSInterfaceNonSigned
- IP: 192.49.232.194.
Paluukanava-rajapinnan osalta VIA-palvelu ottaa yhteyttä viranomaistunnukseen määritettyyn osoitteeseen.
Vaihe 2: Testaaminen allekirjoituksen kanssa ja hyväksymistestaus
Kaikkien WS-kutsusanomien Viranomainen-elementtiin tulee täyttää elementti SanomaVarmenneNimi. Kentän arvon on oltava sama kuin allekirjoitukseen käytettävän varmenteen Common Name (CN).
Testaamisessa käytettävän VIA-rajapinnan osoite Viranomaispalvelut-rajapinnan osalta on
- https://qat.integraatiopalvelu.fi/Asiointitili/ViranomaispalvelutWSInterface
- IP: 192.49.232.194.
Tässä osoitteessa testataan organisaationne järjestelmän ja VIA-palvelun välillä käytettävän WS-kutsujen allekirjoituksen toimivuus. Samalla integroitavalle järjestelmälle suoritetaan hyväksymistestaus.
Paluukanava-rajapinnan osalta VIA-palvelu ottaa yhteyttä viranomaistunnukseen määritettyyn osoitteeseen. Kun organisaationne haluaa siirtyä testaamaan allekirjoitettua paluukanavaa, tulee teidän pyytää konfiguraatiomuutosta Digi- ja väestötietovirastolta.
Kuvassa 1 on esitetty, kuinka organisaationne järjestelmä lähettää sanoman VIAn kautta Suomi.fi-viestien Viranomaispalvelut-rajapintaan testiympäristössä.
Kuva: 2. Sanoman lähettäminen Paluukanava-rajapintaan testiympäristössä.
Tuotantoon siirtyminen
Tuotantoympäristö on kokonaan erillinen ympäristö, johon organisaationne kytkeytyy VIAn PRO-ympäristön kautta. Organisaationne voi liittyä tuotantoympäristöön vasta, kun tarvittavat testaukset testiympäristössä on suoritettu. Tuotantoympäristön kokoonpano on esitetty kuvassa 3.
- https://pr0.integraatiopalvelu.fi:443/Asiointitili/ViranomaispalvelutWSInterface
- IP: 192.49.232.195.
WS-tietoliikenteen toteuttaminen
Alle on koottu tietoa WS-rajapinnan tietoliikenteen toteuttamisen yksityiskohdista.
Palvelinvarmenteet
Yhteys VIA-palvelun palvelimiin muodostetaan käyttämällä HTTPS-protokollaa. Palvelinten varmenteet ovat saatavissa Yhteisen integraatioalustan varmenteiden listasta (Valtori)Avautuu uuteen ikkunaan..
Kutsujen allekirjoittaminen ja varmenteet
Organisaationne järjestelmän tulee allekirjoittaa lähettämänsä kutsusanomat. VIA allekirjoittaa vastaavasti paluusanomat. Allekirjoitukset tulee tehdä X509V3-varmenteella, jonka on myöntänyt jokin VIAn hyväksymistä varmentajista. Hyväksyttyjen varmentajien lista sekä varmenteet, joilla VIA allekirjoittaa paluusanomat, ovat saatavissa Yhteisen integraatioalustan varmenteiden listasta (Valtori)Avautuu uuteen ikkunaan..
Allekirjoitusvarmenteina ei voi käyttää domain-varmenteita (CN=*.domain.com).
Asiakasorganisaation järjestelmästä tarvittavat tiedot
Digi- ja väestötietovirasto tarvitsee tietoliikenneavauksia varten tiettyjä tietoja organisaationne järjestelmästä. Digi- ja väestötietovirasto lähettää organisaatiollenne VIA_Tietoliikenneavaukset-lomakkeen, joka teidän tulee palauttaa täytettynä Digi- ja väestötietovirastolle. Digi- ja väestötietovirasto lähettää lomakkeen edelleen Valtorille, joka suorittaa tietoliikenteen avaamiseen tarvittavat toimet.
VIA_Tietoliikenneavaukset-lomakkeelle syötetään tai siihen syötettyjen tietojen perusteella muodostetaan esimerkiksi seuraavat tiedot:
- Kutsun lähettävien palvelinten osoitteet: IP-osoitteet, joista organisaationne palveluiden kutsut tulevat. Tiedot on toimitettava samalla sekä organisaationne järjestelmän testi- että tuotantoympäristön osalta.
- Viranomaistunnus ja siihen liitettävät raportointitiedot: DVV muotoilee viranomaistunnuksen nimestä, jonka organisaationne täyttää lomakkeeseen. VIA tekee raportointia kutsussa olevan Viranomaistunnus-elementin sisällön perusteella.
- Allekirjoitukseen käytetty varmenne: Julkiset osat niistä varmenteista, joilla organisaationne järjestelmä allekirjoittaa sanomat. Varmenteet on toimitettava sekä testi- että tuotantoympäristön osalta.
Paluukanavan käyttöönotto
Suomi.fi-viestit lähettää Paluukanava-rajapinnan mukaisen sanoman organisaationne järjestelmälle. Suomi.fi-viestien ja organisaationne välissä toimiva VIA reitittää sanoman perille Viranomaistunnus-elementin sisällön perusteella.
VIA olettaa, että organisaationne järjestelmään on toteutettu palvelu Paluukanavan sanomien vastaanottamiseksi ja että se noudattaa Digi- ja väestötietovirastolta saatavaa WSDL:ää.
VIA allekirjoittaa lähettämänsä Paluukanavan sanomat. Organisaationne järjestelmä allekirjoittaa lähettämänsä vastaussanomat VIA-palvelun edellyttämällä tavalla (ks. yllä kohta Kutsujen allekirjoittaminen ja varmenteet).
Jos organisaationne haluaa käyttää Paluukanava-rajapintaa, tulee teidän toimittaa yllä mainitussa VIA_Tietoliikenneavaukset-lomakkeessa myös Paluukanavan vaatimat tiedot. Tiedot ovat:
- Paluukanava-palvelun osoite, muotoa https://viranomainen.fi/Paluukanava
- palvelinten nimet ja IP-osoitteet
- julkiset osat varmenteista, joilla organisaationne järjestelmä allekirjoittaa sanomat.
Varmenteet ja osoitteet on toimitettava sekä testi- että tuotantoympäristön osalta. Organisaationne kannattaa ensin testata allekirjoittamaton Paluukanava ja vasta sitten pyytää Digi- ja väestötietovirastolta konfiguroinnin muutosta allekirjoitettuun Paluukanavaan.
Tietoliikenneongelmat
Palvelun käytössä voi ilmetä satunnaisia tietoliikenneongelmia, joiden takia yksittäinen kutsu voi epäonnistua. Epäonnistunutta rajapintakutsua on hyvä yrittää uudelleen automaattisesti.