Kehittäjän opas

Palveluväylän palveluiden käyttöönottoBeta - sisältö on kesken

Saat parhaat ohjeet tilanteeseesi, kun vastaat ensin kysymyksiin oppaan aloitussivulla.

Tutustu Suomi.fi-palveluväylään

Mikä on Suomi.fi-palveluväylä?

Suomi.fi-palveluväylä on palvelu, jonka avulla eri organisaatiot voivat siirtää tietoa toistensa järjestelmien välillä tietoturvallisesti. Organisaatiot voivat

hyödyntää toistensa tarjoamia palveluita ja tietovarantoja
tarjota omia palveluitaan muiden käyttöön.

Palvelun tuottaa Digi- ja väestötietovirasto.

Voit lukea asiakastarinoistammeAvautuu uuteen ikkunaan. esimerkkejä siitä, miten eri organisaatiot ovat hyötyneet Palveluväylän käyttöönottamisesta.

Tutustu lisäksi Palveluväylän palvelukuvaukseenAvautuu uuteen ikkunaan. ja Palveluväylän esittelyvideoon YoutubessaAvautuu uuteen ikkunaan..
Tutustu myös Palveluväylän kautta tarjottaviin palveluihin LiityntäkatalogissaAvautuu uuteen ikkunaan..

Palveluväylän ja sen palveluiden käyttöönotto on Palveluväylään liittyvän organisaation tai sen teknisen välitoimijan vastuulla. Tutustu huolellisesti Palveluväylän tekniseen yleiskuvaukseenAvautuu uuteen ikkunaan..

Palveluväylän käyttö edellyttää aina Palveluväylän käyttöluvan hakemista. Lisäksi Palveluväylän kautta tarjottavien palveluiden käyttöönotto voi edellyttää palvelukohtaisten käyttölupien hankkimista. Lisätietoja lupakäytännöistä antaa kutakin palvelua tarjoava organisaatio.
Palveluväylän käyttö vaatii omien tietojen, liityntäpalvelimen ja mahdollisten palveluiden ylläpitoaAvautuu uuteen ikkunaan.. Myös ylläpito on Palveluväylää käyttävän organisaation tai välitoimijan vastuulla.
Saat lisätietoa käyttöön liittyvistä velvoitteista Palveluväylän käyttöehdoistaAvautuu uuteen ikkunaan..

Päivitetty: 19.1.2024

Palveluväylän käyttöönottoprosessi

Suomi.fi-palveluväylän käyttöönotto on monivaiheinen prosessi, joka sisältää sekä hallinnollisia että teknisiä toimenpiteitä. Tutustu yleiskuvaan prosessin vaiheista ja käyttöluvista, joita organisaatiosi täytyy eri vaiheissa hakea.

Hallinnollinen suunnittelu

Tutustu ja suunnittele

Tekninen suunnittelu

Tutustu ja suunnittele

Valitse Palveluväylän liityntäpalvelinratkaisu

Valitse sopivin ratkaisu yhdessä teknisen toteuttajan kanssa.

Vaihtoehdot ovat

oma liityntäpalvelin
yhteinen liityntäpalvelin
ulkoistettu liityntäpalvelin.

Lue tarkemmin liityntäpalvelinratkaisusta.

Jos toteutatte oman liityntäpalvelimen, valmistele alustapalvelin teknisesti

Asenna ja määrittele alustapalvelin.

Hae käyttölupaa Palveluväylän testiympäristöön

Lähetä käyttölupahakemus Palveluväylän testiympäristöön Suomi.fi-palveluhallinnassaAvautuu uuteen ikkunaan..

Lue käyttöluvan hakemisesta tarkemmin.

DVV myöntää käyttöluvan testiympäristöön

DVV myöntää organisaatiollesi käyttöluvan Palveluväylän testiympäristöön ja Palveluväylän ylläpito (palveluvayla@palveluvayla.fi) lähettää sähköpostitse asennusohjeet tekniselle yhteyshenkilölle.

Liity Palveluväylän testiympäristöön

Kun käyttölupahakemus on hyväksytty, organisaatiosi voi liittyä testiympäristöön. Tee seuraavat toimenpiteet saamiesi ohjeiden mukaisesti:

Avaa palomuurit
Asenna liityntäpalveluohjelmisto
Määrittele liityntäpalvelin
Lisää alijärjestelmä
Liitä asiakasjärjestelmä liityntäpalvelimelle
Lisää mahdolliset palvelusi liityntäpalvelimelle
Ota sovitinpalvelu tarvittaessa käyttöösi

Lue testiympäristöön liittymisestä tarkemmin.

Kuvaile organisaatiosi ja palvelusi Testiliityntäkatalogiin

Kuvaile organisaatiosi ja tarjoamanne palvelut Palveluväylän TestiliityntäkatalogiinAvautuu uuteen ikkunaan..

Testaa Palveluväylän testiympäristössä

Kun organisaatiosi on liittynyt onnistuneesti testiympäristöön, testaa yhteys Palveluväylään:

Testaa yhteys Palveluväylään
Testaa viestiketjun toimivuus
Testaa viestinvälitystä metapalveluiden avulla
Korjaa testeissä huomatut virheet

Lue testaamisesta tarkemmin.

Hae käyttölupaa Palveluväylän tuotantoympäristöön

Kun testiympäristössä tehdyt testit on käyty läpi ja virheet korjattu, voitte siirtyä tuotantoympäristöön.

Hae käyttölupaa Palveluväylän tuotantoympäristöön Suomi.fi-palveluhallinnassaAvautuu uuteen ikkunaan..

DVV myöntää käyttöluvan tuotantoympäristöön

DVV myöntää organisaatiollesi käyttöluvan Palveluväylän tuotantoympäristöön ja Palveluväylän ylläpito (palveluvayla@palveluvayla.fi) lähettää sähköpostitse asennusohjeet tekniselle yhteyshenkilölle.

Siirry Palveluväylän tuotantoympäristöön

Kun käyttölupa tuotantoympäristöön on myönnetty, toista samat tekniset toimenpiteet kuin testiympäristöön liityttäessä.

Lue tarkemmat ohjeet tuotantoympäristöön siirtymisestä.

Kuvaile organisaatiosi ja palvelusi Liityntäkatalogiin

Kuvaile organisaatiosi ja tarjoamanne palvelut Palveluväylän LiityntäkatalogiinAvautuu uuteen ikkunaan..

Käyttöönottoprosessi on valmis

Palveluhallinnassa on välitoimijaominaisuus, jonka avulla IT-toimittaja voi täyttää Suomi.fi-palveluväylän käyttölupahakemukset esimerkiksi kunnan tai hyvinvointialueen puolesta ja lähettää ne tälle hyväksyttäviksi.

Välitoimijamalli helpottaa käyttölupahakemusten täyttämistä tilanteissa, joissa asiakas ei itse tunne parhaiten hakemusten teknisiä yksityiskohtia.

Päivitetty: 23.4.2024

Palveluväylän tekniset lähtökohdat

Suomi.fi-palveluväylän tiedonvälitys perustuu X-Road-teknologiaan, jota kehittää Nordic Institute for Interoperability Solutions. Tiedot liikkuvat salattuna julkisessa internetissä. Tietojen välitys perustuu erillisiin fyysisiin tai virtuaalisiin liityntäpalvelimiin.

Tiedot salataan tiedonsiirron ajaksi TLS (SSL) -salausprotokollalla, ja kaikki tieto allekirjoitetaan varmenteilla. Liityntäpalvelinten rajapintatoteutuksessa käytetään XML-kieleen pohjautuvaa SOAP (Simple Object Access Protocol) -tietoliikenneprotokollaa tai REST-arkkitehtuuria.

Tutustu ensin näihin:

Lisätietoa löydät myös seuraavista:

Palveluväylän usein kysytyt kysymyksetAvautuu uuteen ikkunaan.
Palveluväylän tukiartikkelitAvautuu uuteen ikkunaan.
Palveluväylän käyttöönoton video-ohjeet, 5-osainen videosarja Palveluväylään liittymisestä YoutubessaAvautuu uuteen ikkunaan.
X-Roadin dokumentaatio GitHubissa (englanniksi)Avautuu uuteen ikkunaan.
X-Road Playground (englanniksi)Avautuu uuteen ikkunaan.. Tutustu ja testaa X-Road-ohjelmiston toimintaa.
X-Road Academy (englanniksi)Avautuu uuteen ikkunaan.. Tutustu X-Roadin koulutusmateriaaleihin ja kursseihin.

Päivitetty: 8.2.2024

Palveluväylän ympäristöt

Suomi.fi-palveluväylä toimii kolmessa eri ympäristössä.

Huomioi, että tarvitset kaikkiin ympäristöihin erilliset liityntäpalvelimet, eli fyysiset tai virtuaaliset palvelimet, joiden kautta viestit kulkevat.

Kehitysympäristössä käytetään keksittyjä organisaatioita ja dataa. Voit kokeilla Palveluväylän toimintaa kehitysympäristössä ilman velvoitteita liittyä testi- tai tuotantoympäristöön.

Kehitysympäristöön voivat liittyä myös yksityishenkilöt. Jos haluat liittyä Palveluväylän kehitysympäristöön yksityishenkilönä, saat tarvittavat liittymistiedot Palveluväylän tuelta osoitteesta palveluvayla@palveluvayla.fi

Kehitysympäristössä käytetään ympäristöä ylläpitävän operaattorin omia varmenteita, joiden hankkiminen onnistuu sähköpostitse. Saat varmenteet lähettämällä vapaamuotoisen hakemuksen osoitteeseen palveluvayla@palveluvayla.fi.

Saat lisää tietoa liityntäpalvelinohjelmiston asentamisesta kehitysympäristöön liityttäessä erillisestä tukiartikkelista.

Sinun on aina liityttävä testiympäristöön ennen tuotantoympäristöön liittymistä. Voit kokeilla Palveluväylään liittymistä ja palvelun toimintaa testiympäristössä.

Testiympäristöön voivat liittyä suomalaiset ja ulkomaiset tunnistetut organisaatiot, joilla on Y-tunnus. Testiympäristössä käytetään oikeita organisaatioita, mutta keksittyä dataa.

Testiympäristöön liittyminen vaatii käyttöluvan Digi- ja väestötietovirastolta. Lue ohjeet sivulta Lähetä käyttölupahakemus Suomi.fi-palveluväylän testiympäristöön.

Tuotantoympäristö on Palveluväylän varsinainen toimintaympäristö, johon voit siirtyä vasta kun olet ensin liittynyt onnistuneesti testiympäristöön.

Tuotantoympäristöön voivat liittyä suomalaiset ja ulkomaiset tunnistetut organisaatiot, joilla on Y-tunnus. Tuotantoympäristön organisaatiot ja data ovat aitoja.

Tuotantoympäristöön liittyminen vaatii käyttöluvan Digi- ja väestötietovirastolta. Lue ohjeet sivulta Lähetä käyttölupahakemus Suomi.fi-palveluväylän tuotantoympäristöön.

Päivitetty: 28.3.2025

Yleistä Palveluväylän liityntäpalvelinratkaisusta

Ennen kuin voit aloittaa käyttöönoton, organisaatiollasi pitää olla erillinen fyysinen tai virtuaalinen palvelin eli liityntäpalvelin, jonka avulla Palveluväylään liitytään. Pohdi suunnitteluvaiheessa, mikä ratkaisu sopii organisaatiollesi parhaiten.

Oman liityntäpalvelimen käyttäminen: Organisaatiosi asentaa liityntäpalvelinohjelmiston sekä huolehtii liityntäpalvelimen ylläpidosta itse.
Liityntäpalvelinratkaisun ostaminen ulkopuoliselta palveluntarjoajalta: Organisaatiosi ulkoistaa liityntäpalvelinohjelmiston asentamisen sekä liityntäpalvelimeen liittyvät ylläpitotyöt jollekin ulkoiselle palveluntarjoajalle.
Jaetun liityntäpalvelimen käyttäminen: Sovitte jonkin Palveluväylään liittyneen organisaation kanssa, että hyödynnätte heidän olemassa olevaa liityntäpalvelintaan. Voitte myös pystyttää toisen organisaation kanssa uuden yhteisen liityntäpalvelimen.

Päivitetty: 28.3.2025

Tekniset rajapinnat: SOAP vai REST

Palveluväylän kautta tarjottavat palvelut voivat perustua joko SOAP-protokollan mukaiseen tiedonsiirtoon tai tiedon esitysmuodosta riippumattomaan REST-arkkitehtuurimalliin.

Jos organisaatiosi aikoo tarjota Palveluväylässä palveluitaan muille, mieti, tuleeko organisaatiosi käyttämään SOAP- vai REST-rajapintoja tietojen välittämiseen. Myös molempien käyttäminen on mahdollista. Rajapinnan muoto vaikuttaa jonkin verran käyttöönottoprosessiin.

Palveluväylään liittymisen kannalta suurin ero SOAP- ja REST-palveluiden välillä on se, että SOAP-palvelut tarvitsevat pääsääntöisesti erillisen sovitinpalvelun, mutta REST-palvelut eivät.

REST (Representational State Transfer) on HTTP-protokollaan perustuva arkkitehtuurimalli ohjelmointirajapintojen toteuttamiseen. REST ei rajaa rajapinnoissa käytettyä teknologiaa tai tiedon esitysmuotoa.

Yleisin REST-sovelluksissa käytetty tiedonesitysmuoto on tällä hetkellä JavaScript Object Notation (JSON), mutta myös muun muotoisia REST-palveluita on mahdollista lisätä Palveluväylään.

REST on SOAPia kevyempi ratkaisu, koska se on kevyemmin standardisoitu.

Päivitetty: 19.1.2024

Sovitinpalvelu

Sovitinpalvelu on liityntäpalvelimen ja tietojärjestelmän väliin sijoittuva komponentti, joka sovittaa organisaatiosi järjestelmän palvelut Palveluväylän käyttämän X-Road-tiedonsiirtoprotokollan mukaiseen muotoon.

Et tarvitse sovitinpalvelua, jos:

SOAP-palvelu on suunniteltu ja toteutettu nimenomaan Palveluväylää varten ja Palveluväylän asettamia vaatimuksia noudattaen tai
organisaatiosi käyttää REST-rajapintoja tiedonsiirtoon.

Jos organisaatiosi käyttää olemassa olevia SOAP-rajapintoja tiedon tarjoamiseen Palveluväylän kautta, on sovitinpalvelu tarpeen. Palveluväylän käyttöönotto edellyttää, että siihen liitettävä tietojärjestelmä pystyy lähettämään ja vastaanottamaan SOAP-sanomia Palveluväylän käyttämän X-Road-tiedonsiirtoprotokollan edellyttämässä muodossa.

SOAP-sanomiin on sisällytettävä tietyt tiedonsiirtoprotokollan määrittelemät otsikkotiedot. Lisäksi kysely- ja vastausparametrit on sisällytettävä SOAP-sanoman body-osaan protokollan määrittelemällä tavalla.

Sovitinpalvelu ei ole liityntäpalvelinohjelmiston mukana tuleva valmiskomponentti, vaan se on toteutettava jokaiselle liitettävälle järjestelmälle erikseen. Sovitinpalvelun suunnittelu ja toteutus on siis organisaatiosi vastuulla.

Lue lisää sovitinpalvelun toteutuksesta GitHubista (englanniksi).Avautuu uuteen ikkunaan.

Päivitetty: 19.1.2024

Oletko tyytyväinen tämän sivun sisältöön?

Muistilista

Digitalisoi asiointipolkusi

Tehosta tiedonhallintaa

Paranna palveluiden laatua

Turvaa tietosi

Jaa, avaa ja hyödynnä tietoa

Tehosta tiedonhallintaa

Turvaa tietosi

Kehitä vastuullisesti

Jaa, avaa ja hyödynnä tietoa

Tutustu Suomi.fi-palveluväylään

Mikä on Suomi.fi-palveluväylä?

Mitä mahdollisuuksia Suomi.fi-palveluväylä tarjoaa?

Mitä velvollisuuksia Palveluväylän käyttäjällä on?

Palveluväylän sanasto

Palveluväylän käyttöönottoprosessi

Hallinnollinen suunnittelu

Tekninen suunnittelu

Valitse Palveluväylän liityntäpalvelinratkaisu

Jos toteutatte oman liityntäpalvelimen, valmistele alustapalvelin teknisesti

Hae käyttölupaa Palveluväylän testiympäristöön

DVV myöntää käyttöluvan testiympäristöön

Liity Palveluväylän testiympäristöön

Kuvaile organisaatiosi ja palvelusi Testiliityntäkatalogiin

Testaa Palveluväylän testiympäristössä

Hae käyttölupaa Palveluväylän tuotantoympäristöön

DVV myöntää käyttöluvan tuotantoympäristöön

Siirry Palveluväylän tuotantoympäristöön

Kuvaile organisaatiosi ja palvelusi Liityntäkatalogiin

Käyttöönottoprosessi on valmis

Mistä saan tukea käyttöönoton eri vaiheissa?

Tekninen toimittaja välitoimijana Suomi.fi-palveluhallinnassa

Palveluväylän tekniset lähtökohdat

Tutustu tarkemmin Palveluväylän teknisiin lähtökohtiin

Palveluväylän ympäristöt

Kehitysympäristö (FI-DEV)

Testiympäristö (FI-TEST)

Tuotantoympäristö (FI)

Yleistä Palveluväylän liityntäpalvelinratkaisusta

Oman liityntäpalvelimen toteutuksen tekniset valinnat

Tekniset rajapinnat: SOAP vai REST

Mikä on SOAP?

Mikä on REST?

Sovitinpalvelu

Sovitinpalvelun toteuttaminen SOAP-rajapintapalveluille

Oletko tyytyväinen tämän sivun sisältöön?