Suomi.fi-viestien siirtyminen REST-rajapintaan – mitä siirtymä tarkoittaa palvelua käyttäville organisaatioille?

Suomi.fi-viestien käytössä siirrytään tulevina vuosina uuteen REST-rajapintaan. Suomi.fi-viestejä käyttäville organisaatioille tämä tarkoittaa teknisiä ja hallinnollisia toimenpiteitä.

Tässä blogikirjoituksessa käydään läpi:

• Mitä REST-rajapinta tarkoittaa ja miksi siirtymä tehdään?
• Miten eri rajapinnat (WS, SMTP, SFTP) eroavat toisistaan ja mistä tiedät, mitä rajapintaa organisaatiosi käyttää?
• Siirtymän aikataulu ja mitä organisaation tulee seuraavaksi tehdä.

Mikä on rajapinta?

Rajapinta on tekninen ratkaisu, jonka avulla mahdollistetaan integraatiot järjestelmien välillä. Nykyisin organisaatiot käyttävät Suomi.fi-viesteihin eri rajapintoja, kuten WS, SMTP (sähköposti-rajapinta) ja SFTP.

Nyt nämä vanhat rajapinnat korvataan REST-rajapinnalla. REST on moderni rajapinta, joka mahdollistaa eri järjestelmien välisen viestinnän HTTP-protokollan avulla. Se on suunniteltu yksinkertaiseksi ja joustavaksi.

POST-rajapinta, eli POST-lomakkeet tai Suomi.fi-viestien sähköiset lomakkeet, ovat tarjolla myös jatkossa. POST-rajapinta tarvitsee rinnalleen toisen rajapinnan, jotta viesti kulkee organisaatiolle asti. Jatkossa myös sen on oltava REST-rajapinta.

Miksi siirrytään REST-rajapintaan?

REST-rajapinnan myötä kaikki Suomi.fi-viestien toiminnallisuudet ovat saatavilla yhden rajapinnan kautta. Tämä yksinkertaistaa palvelun käyttöönottoa ja vähentää tarvetta vertailla eri rajapintoja organisaation tarpeisiin. Lisäksi REST-rajapinta tehostaa viestien välittämistä ja mahdollistaa nopeamman reagoinnin mahdollisiin vikatilanteisiin.

Mitä eroa on WS-, SMTP-, SFTP- ja POST-rajapinnoilla?

Mistä tiedän, mikä rajapinta organisaatiossani on käytössä?

Jos ette ole varmoja, mitä rajapintaa organisaationne käyttää, voitte selvittää sen esimerkiksi näin:

1. Tarkistakaa, miten viestit välittyvät

• Jos viestit lähtevät organisaation järjestelmästä, käytössä voi olla WS tai SFTP.
• Jos viestit kulkevat sähköpostitse, käytössä on SMTP-rajapinta.
• Jos sähköpostiin tulee Suomi.fi-viestien lomakkeita, käytössä on POST-rajapinta yhdistettynä SMTP-rajapintaan. Jos lomakkeet ohjautuvat järjestelmään, käytössä on WS.

2. Kysykää asiaa organisaatiosi ICT-asiantuntijoilta tai järjestelmää ylläpitävältä ohjelmistotoimittajalta.

3. Apua rajapinnan selvittämiseen voi kysyä myös Digi- ja väestötietovirastolta Suomi.fi-viestien Käyttöönotoilta osoitteella viestit-kayttoonotot@dvv.fi.

Siirtymän aikataulu

Digi- ja väestötietovirasto (DVV) on määritellyt aikataulun, jolla vanhoista liitynnöistä tullaan luopumaan. Jokaisen Suomi.fi-viestejä käyttävän organisaation tulee siirtyä käyttämään uutta REST-rajapintaa 1.1.2027 mennessä.

Siirtymä tapahtuu vaiheittain ja vanhat rajapinnat poistuvat käytöstä seuraavasti:

1.1.2025: Uusia liityntöjä ei tehdä enää vanhoihin rajapintoihin. Kaikki uudet käyttöönotot tehdään REST-rajapinnalle.

1.1.2026: Vanhojen rajapintojen olemassa oleviin liityntöihin ei voi enää lisätä uusia palveluita. Koskee erityisesti ICT-palvelutuottajien tarjoamia ohjelmistoratkaisuja.

1.1.2027: Kaikki vanhat rajapinnat poistuvat käytöstä.

Varatkaa riittävästi aikaa siirtymään. Tekninen ja hallinnollinen siirtymä sekä käyttötavan ja prosessien uudistaminen voi viedä useita kuukausia, joten on tärkeää aloittaa suunnittelu ajoissa.

Mitä organisaation tulee seuraavaksi tehdä?

Tehtävät toimenpiteet riippuvat siitä, mikä rajapinta on käytössä. Organisaatiollanne voi olla Suomi.fi-viesteissä useita palveluita, jotka toimivat eri rajapintojen kautta. Organisaationne tulee siis ensin selvittää, mitkä kaikki rajapinnat ovat käytössä.

WS- ja SFTP-rajapintojen tekninen siirtymä

Integraation suunnittelu kannattaa aloittaa tutustumalla ohjeisiin Suomi.fi kehittäjille -sivustolla ja lähettämällä täytetty Palvelutietolomake Digi- ja väestötietovirastolle.

WS- ja SFTP-rajapinnoista siirtyminen REST-rajapintaan onnistuu yleensä suoraviivaisemmin. Jos käytätte WS-rajapintaa, voitte testata ja viedä tuotantoon aina yhden päätepisteen kerrallaan. SFTP-rajapinnasta siirtyminen tapahtuu helpoiten käyttämällä REST-rajapinnan monikanavaista /messages-päätepistettä. Paperipostitse välitettävät viestit on lähetettävä tulostuskelpoisena PDF-tiedostona, mutta sähköisessä viestissä voi olla parempi kirjoittaa sisältö viestiin. REST-rajapinta mahdollistaa myös sähköisen viestisisällön muotoilun Markdown-symboleilla.

Merkittävä muutos aiempiin liityntätapoihin on, että lähettämienne viestien tilatietojen seuraaminen ja viestien vastaanottaminen loppukäyttäjiltä ei enää tapahdu REST-rajapinnassa paluukanavan kautta. Sen sijaan järjestelmänne pitää aktiivisesti hakea tietoja viestien tilamuutoksista ja mahdollisista loppukäyttäjien lähettämistä viesteistä kutsumalla säännöllisesti REST-rajapinnan events-päätepistettä. Tilatietojen hakemista varten järjestelmänne tulee tallentaa viimeisin Suomi.fi-viestien REST-rajapinnan /events-päätepisteen palauttama continuationToken-arvo.

Muutosten yhteydessä on aina paikallaan testata kaikki käyttämänne toiminnot Suomi.fi-viestien QA-ympäristöä vasten testausohjeitamme hyödyntäen. Kun kaikki on valmista, täyttäkää ja palauttakaa Käyttöönoton tarkistuslista Digi- ja väestötietovirastolle. Ilmoittakaa samalla tuotantokäytön aloituksen päivämäärä. Tarkistuslista auttaa Digi- ja väestötietovirastoa ja teitä itseänne varmistamaan, että kaikki tarvittava on huomioitu ennen tuotantokäytön aloitusta.

Jos olette ottaneet Suomi.fi-viestit käyttöön jonkin toisen ICT-järjestelmätoimittajan tarjoaman ohjelmiston kautta, olkaa suoraan yhteydessä omaan järjestelmätoimittajaanne, joka vastaa teknisestä siirtymisestä sekä aikataulusta. Huolehtikaa itse mahdollisista hallinnollisista toimenpiteistä.

Jos rakennatte REST-rajapinnan itse omaan järjestelmäänne, edetkää ohjeiden mukaan ja olkaa tarvittaessa yhteydessä Suomi.fi-viestien Käyttöönottoihin (viestit-kayttoonotot@dvv.fi).

WS- ja SFTP-rajapintojen hallinnollinen siirtymä

Jos organisaationne Suomi.fi-viestejä käyttävät palvelut eivät muutu, uutta käyttölupaa ei tarvitse hakea. Jos mukaan tulee uusia palveluita, niille pitää hakea uusi käyttölupa Suomi.fi-palveluhallinnasta ohjeidemme mukaisesti.

Esimerkki: Organisaation käytössä on varhaiskasvatusjärjestelmä, johon on integroitu Suomi.fi-viestit ja joka käyttää WS-rajapintaa. Organisaatiolla on jo ennestään olemassa Suomi.fi-viestien käyttölupa varhaiskasvatuspalveluille. Järjestelmätoimittaja tekee järjestelmään REST-siirtymän ja jatkossa organisaatio käyttää edelleen Suomi.fi-viestejä osana varhaiskasvatusjärjestelmää. Organisaation ei tarvitse hakea uutta käyttölupaa, koska palvelu pysyy samana, vaikka rajapinta taustalla vaihtuu.

Vaikka niihin palveluihin, jotka olette liittäneet Suomi.fi-viesteihin, ei tulisi muutoksia, Suomi.fi-viestien käyttöohjeisiin on tullut paljon uusia tarkennuksia. Varmistakaa siirtymän myötä, että jatkossa organisaationne käyttötapa on ohjeistuksien mukainen. Lisäksi REST-rajapinta tarjoaa uusia toiminnallisuuksia, joiden avulla voitte sujuvoittaa organisaationne asiakasprosesseja.

Tarkistakaa ainakin nämä asiat:

• Viestin tai ilmoituksen muotoilu: Suomi.fi kehittäjille -sivuston sivulta Sähköisen viestin ja ilmoituksen muotoilu löydät ohjeet ja esimerkit siihen, miten viesti ja siihen liittyvä ilmoitus muotoillaan niin, että asiakkaanne ymmärtävät saamansa viestin ja saavat asiansa hoidettua.
• Asiointipalvelujen ja Suomi.fi-viestien välinen suhde: Asiointipalveluiden ja Suomi.fi-viestien välistä suhdetta on tarkennettu. Monissa tilanteissa asiakasta palvelee parhaiten viesti, joka sisältää itsessään kaiken tarvittavan tiedon. Tarvittaessa voitte myös ohjata asiakkaan viestistä asiointipalveluunne. Tällöin viestisisällössä pitää olla linkki oikeaan kohtaan asiointipalvelussa ja ohjeistaa selkeästi, miten asiakkaan toivotaan siellä toimivan.
• Linkkien ja liitetiedostojen lähettäminen Suomi.fi-viesteihin on tietoturvallista toisin kuin sähköpostiohjelmissa. Suomi.fi-viesteihin ei voi tulla ulkopuolisilta tahoilta kalasteluviestejä eikä virustiedostoja, sillä lähettäjät on varmistettu ja lähetyksissä käytetään suojattua yhteyttä. Sähköpostiin menevissä ilmoituksissa ei saa olla linkkiä.
• Palvelun nimeäminen: Siirtymässä kannattaa myös tarkkaan arvioida olemassa olevan palvelun nimeä, joka näkyy asiakkaille. Palvelun nimen tulisi olla mahdollisimman selkeä ja esimerkiksi yhdistettävissä tiettyyn palveluun tai toimialaan. Palvelun nimi näkyy asiakkaalle esimerkiksi Uusi viesti -ilmoituksessa ja Suomi.fi-viestien postilaatikossa. Loppukäyttäjä näkee palvelun nimen myös silloin, kun hän kirjoittaa uutta viestiä organisaatiolle (jos organisaatio on mahdollistanut sen, että loppukäyttäjät voivat lähettää organisaatiolle viestejä). Hallinnollisen ylläpidon sivulta löytyy ohjeet organisaation tai palvelun nimen muuttamiseksi.

Huomioikaa myös muut monipuoliset toiminnallisuudet

REST-rajapinta tarjoaa kaikki vanhojen rajapintojen toiminnallisuudet ja lisäksi sinne on kehitetty kokonaan uusia toiminnallisuuksia. Suomi.fi-viestit on tarkoitettu erityisesti viranomaisten tiedoksiantojen lähetykseen, mutta palvelu mahdollistaa myös muiden asiointipolkuun liittyvien viestien lähettämisen kätevästi ja kustannustehokkaasti.

Esimerkiksi, jos lähetätte asiakkaillenne vastaanottokuittauksia tai väliaikatietoja asian käsittelyn vaiheesta, voitte rajata niiden lähettämisen ainoastaan sellaisille henkilöille, joille ne voi toimittaa sähköisesti. Lisäksi tällaisista viesteistä voi halutessaan kytkeä pois muistutukset lukemattomista viesteistä.

REST-rajapinnan uudet toiminnallisuudet mahdollistavat käyttötavan tai Suomi.fi-viestien käyttöön liittyvien prosessien päivittämisen. REST-rajapinnassa saman viestin voi esimerkiksi lähettää sisällöltään erilaisena sen mukaan, meneekö se vastaanottajalle sähköisenä viestinä vai paperipostilla. Paperipostiin menevässä kirjeessä voi vaikkapa olla tarkemmin ohjeet, miten asiakkaan tulee toimia paperimaailmassa, ja sähköisessä viestissä suora linkki jatkoasiointiin.

Tiivistettynä

1. Varmistakaa, onko organisaationne käytössä WS- tai SFTP-rajapinta.
2. Ottakaa yhteyttä ICT-asiantuntijaan tai ohjelmistotoimittajaan – onko haluttuun järjestelmään REST-tuki suunnitteilla ja millä aikataululla? Mitä toiminnallisuuksia aiotaan tukea jatkossa?
3. Aikatauluttakaa siirtymä hyvissä ajoin.
4. Käykää läpi REST-rajapinnan tarjoamat uudet toiminnallisuudet ja suunnitelkaa asiakasprosessinne uusiksi. Huolehtikaa myös hyvästä viestinnästä ja kouluttakaa asiakaspalvelijanne.
5. Pohtikaa, onko organisaatiossanne muita palveluita, jotka voisivat myös hyötyä Suomi.fi-viestien käyttöönotosta.

SMTP-rajapinnasta luopuminen ja REST-käyttöönotto

Jos organisaatiollanne on ollut käytössä SMTP-rajapinta (=sähköpostiliityntä) Suomi.fi-viestit ei jatkossa enää tarjoa sähköposti-integraatiota. Suomi.fi-viesteillä ei myöskään ole asiakasorganisaatiolle suunnattua käyttöliittymää palveluun. Alempana kerromme, mitä vaihtoehtoja on olemassa SMTP-rajapinnan tilalle.

Jos käytätte POST-lomakkeita, jotka tulevat organisaatiossanne SMTP-rajapinnalla sähköpostiin, olkaa yhteydessä lomakepalvelua tarjoavaan järjestelmätoimittajaan. Asiakkailta tulevat sähköiset lomakkeet voi ohjata jatkossa kulkemaan esimerkiksi suoraan asianhallintajärjestelmään tai asiointipalveluun.

Vaihtoehdot SMTP-rajapinnan tilalle

Organisaationne on hyvä käydä läpi, mihin SMTP-rajapintaa on tähän mennessä käytetty ja mitä jatkossa halutaan tilalle. Sivulle Valmisohjelmistot ja Viestien käyttöönotto on koottu Digi- ja väestötietoviraston tiedossa olevia asianhallintajärjestelmiä ja muita valmisohjelmistoja, jotka tarjoavat integraation Suomi.fi-viesteihin. Sivulla on myös vinkkejä Suomi.fi-viestien vaatimuksien huomioimiseksi järjestelmäkilpailutusten yhteydessä.

Organisaationne ei välttämättä tarvitse hakea uutta käyttölupaa, jos otatte Suomi.fi-viestit REST-rajapinnalla käyttöön samassa palvelussa.

Esimerkki: Organisaatio on käyttänyt SMTP-rajapintaa varhaiskasvatuspalveluihin. Nyt organisaatio ottaa varhaiskasvatusjärjestelmään Suomi.fi-viestien integraation REST rajapinnalla. Näin ollen organisaatio käyttää edelleen Suomi.fi-viestejä varhaiskasvatuspalveluihin. Organisaation ei tarvitse hakea uutta käyttölupaa, koska käyttökohteena on sama palvelu, vaikka taustalla rajapinta vaihtui ja tilalle tuli uusi järjestelmä.

Ohjelmistosta riippuen käyttöönottoprosessi vaihtelee hieman, mutta tärkeintä on olla yhteydessä valitsemaanne ohjelmistotoimittajaan ja tutustua huolellisesti erityisesti Hallinnollinen käyttöönotto -sivuun. Teknisen käyttöönoton osalta ohjelmistotoimittaja tukee teitä. Jos rakennatte REST-rajapinnan itse omaan järjestelmäänne, edetkää käyttöönoton ohjeiden mukaan ja olkaa tarvittaessa yhteydessä Suomi.fi-viestien Käyttöönottoihin (viestit-kayttoonotot@dvv.fi).

Jos siirtyminen REST-rajapintaan ei ole mahdollista

Ymmärrettävästi eteen voi tulla haasteita, jonka vuoksi REST-siirtymä ei onnistu tai organisaationne ei jostain muusta syystä pysty hyödyntämään Suomi.fi-viestejä.

Julkishallinnon organisaatioilla on ollut Suomi.fi-viestien käyttövelvollisuus vuodesta 2016 lähtien (Laki hallinnon yhteisistä sähköisen asioinnin tukipalveluista 571/2016). Käyttövelvoitetun organisaation on haettava poikkeuslupaa, jos Suomi.fi-viestejä ei perustellusta syystä voida enää käyttää.

Jos organisaatiollanne ei ole Suomi.fi-viestien käyttövelvoitetta ja haluatte lopettaa Suomi.fi-viestien käytön, riittää että teette kirjallisen ilmoituksen Suomi.fi-viestien käytön päättämisestä. Tarkemmat ohjeet löytyvät Suomi.fi-viestien käytön päättäminen -sivulta.

Digi ensin -hankkeen myötä Suomessa siirrytään vuoden 2026 alusta ensisijaisesti digitaaliseen viranomaisviestintään. Tällöin kaikille viranomaisten kanssa digitaalisesti asioiville henkilöille lähetetään viranomaisten päätökset ja muut tiedoksiannot sähköisesti Suomi.fi-viesteihin. Niille henkilöille, joilla ei vielä ole Suomi.fi-viestejä käytössä, palvelu tulee automaattisesti käyttöön, kun he tunnistautuvat jonkin viranomaisen sähköiseen asiointipalveluun. Tämä muutos pitää huomioida myös niissä organisaatioissa, jotka eivät lähetä tiedoksiantojaan asiakkailleen sähköisesti. Tällöin Suomi.fi-viestien käyttöön velvoitetun organisaation on poikkeusluvan lisäksi suunniteltava myös, miten se jatkossa lähettää ensisijaisesti sähköiset tiedoksiannot, kuten päätökset, jos tähän ei käytetä Suomi.fi-viestejä.

Suomi.fi-viestit saavuttaa digitaalisesti yhä useamman

Tällä hetkellä Suomi.fi-viestejä käyttää noin 1,5 miljoonaa kansalaista. Vuonna 2026 Suomi.fi-viestit tavoittaa digitaalisesti entistä suuremman osan kansalaisista (dvv.fi)Avautuu uuteen ikkunaan.. Jatkossa palvelun käyttäjinä ei ole ainoastaan kaikkein digikykyisimpiä henkilöitä, vaan käyttäjien digiosaaminen on vaihtelevampaa. Tämä on hyvä ottaa huomioon, kun muotoilette lähettämienne viestien sisältöä ja ohjeistatte käyttäjiä asiointiin.

Asiakaspolkujen selkeys ja sujuvuus digitaalisessa maailmassa on hyvä ottaa viimeistään nyt tarkasteluun sekä varmistaa jokaisen sujuva digitaalinen asiointi viranomaisten kanssa.

Ilmoittautumalla Digi ensin –hankkeen jakelulistalle (questback.com) Avautuu uuteen ikkunaan.varmistat, että saat aina ajantasaisen tiedon hankkeen etenemisestä.

Tehdään yhdessä parempaa viranomaisviestintää ja sujuvaa asiointia!

Suomi.fi-viestien palveluomistaja Maria Juka-Lahdenperä, Digi- ja väestötietovirasto