Liityntätavan ja rajapintojen valinta
Tässä artikkelissa esitellään Suomi.fi-valtuuksien kaksi teknistä liittymistapaa ja annetaan ohjeita sopivan liittymistavan valintaan. Liittymistavat ovat Web API -liityntä ja liityntäpalvelin- eli Palveluväylä-liityntä.
Henkilön puolesta asiointiin (HPA) käytetään yleensä aina Web API -liityntää. Yrityksen puolesta asiointiin (YPA) taas voidaan käyttää joko Web API- tai Palveluväylä-liityntää.
Web API -liityntä soveltuu sekä henkilön (HPA) että yrityksen puolesta asiointiin (YPA). Sen avulla valtuuskyselyiden toteuttaminen on helppoa ja nopeaa. Nopein käyttöönotto on toteutettu neljässä päivässä suunnittelusta tuotantoon.
Web API -rajapinta tarjoaa valintakäyttöliittymän toisen puolesta asioinnin kohteiden valintaan sekä REST-kyselyrajapinnat asiointioikeuskyselyiden tekemiseen. Rajapinnan kutsumisessa hyödynnetään REST-/JSON-rajapintoja, jotka on suojattu joko API Key- tai OAuth2 +API Key -suojauksella. Tutustu tarkemmin Web API -rajapintakuvaukseen.
Web API -liitynnässä päämiehen valinta tehdään aina Valtuudet-palvelun valintakäyttöliittymällä, johon käyttäjän istunto ohjataan asiointipalvelusta. Valinnan jälkeen käyttäjän istunto palaa takaisin asiointipalveluun.
Web API -liitynnän avulla Valtuudet-palvelun valtuustarkistuskyselyt tehdään julkisen internetin kautta, jolloin erilliselle liityntäpalvelimelle ei ole tarvetta. Rajapinnan kutsumisessa hyödynnetään REST-/JSON-rajapintoja.
Web API -liityntää hyödynnetään henkilön puolesta asioinnissa mm. Omaverossa ja Omakannassa.
Palveluväylän käyttäminen Valtuudet-palvelussa soveltuu lähinnä yrityksen puolesta asiointiin (YPA).
Palveluväylän käyttöönottoon on syytä varata huomattavasti enemmän aikaa kuin Web API -liityntään. Yleensä prosessissa kuluu useita kuukausia.
Käytettävä rajapinta tarjotaan Palveluväylän (X-Road 6) kautta. Palveluväylän hyödyntäminen Valtuudet-palvelussa edellyttää siis myös Palveluväylän käyttöönottoa, liityntäpalvelimen asennusta ja ylläpitoa sekä palomuuriavauksia. Tutustu Palveluväylän käyttöönottoon.
Valtuuskyselyt liikkuvat SOAP-sanomina järjestelmien välillä. Kyselyjä on mahdollista suorittaa käyttäjän huomaamatta.
Palveluväylän käyttäminen Valtuudet-palvelussa mahdollistaa päämiehen valinnan asiointipalvelun omalla käyttöliittymällä.
Tutustu tarkemmin seuraaviin rajapintakuvauksiin:
Palveluväylä-liitynnän käyttäminen Valtuudet-palvelussa edellyttää Palveluväylän käyttöönottoa, liityntäpalvelinta ja palomuuriavauksia. Palveluväylän sisäinen liikenne on julkisen internetin yli tapahtuvaa liityntäpalvelinten välistä liikennettä. Liityntäpalvelinten rajapintatoteutuksessa käytetään XML-kieleen pohjautuvaa SOAP-tietoliikenneprotokollaa.
Palveluväylää hyödynnetään liityntätapana yrityksen puolesta asioinnissa mm. Omaverossa.
Jos asiointipalvelussa halutaan mahdollistaa henkilön puolesta asiointi, suositeltavin liittymistapa on Web API -liityntä.
Jos asiointipalvelussa halutaan mahdollistaa sekä henkilön että yrityksen puolesta asiointi, suositeltavin liittymistapa on Web API -liityntä. Muutoin integraatio joudutaan toteuttamaan kahdella eri liittymistavalla.
Jos asiointipalvelussa halutaan mahdollistaa pelkästään yrityksen puolesta asiointi ja päämiehen valinta halutaan tehdä asiointipalvelun omalla käyttöliittymällä, ainoa vaihtoehto on Palveluväylä-liityntä.
Seuraavassa on kuvattu loppukäyttäjän asiointipolku, kun hän asioi asiointipalvelussa toisen puolesta. Ensimmäisessä esimerkissä näytetään, miten asiointi etenee Web API -liityntää käytettäessä. Toisessa esimerkissä taas kuvataan asiointia Palveluväylä-liityntää käytettäessä.
Asiointipolku Web API -liityntää käytettäessä
- Loppukäyttäjä tunnistautuu asiointipalveluun.
- Loppukäyttäjä valitsee ”Toisen puolesta asiointi”.
- Istunto siirtyy Valtuudet-palvelun valintakäyttöliittymälle. Siellä käyttäjä valitsee, kenen puolesta hän haluaa asioida.
- Valinnan jälkeen istunto palaa asiointipalveluun. Käyttäjä jatkaa asiointia valitsemansa päämiehen (henkilö tai yritys) puolesta.
Asiointipolku Palveluväylä-liityntää käytettäessä
- Käyttäjä tunnistautuu asiointipalveluun.
- Käyttäjä valitsee asiointipalvelun käyttöliittymällä yrityksen, jonka puolesta hän haluaa asioida.
- Valinnan jälkeen käyttäjä jatkaa asiointia valitsemansa yrityksen puolesta.
Web API -liityntä
Tee ensin käyttölupahakemusAvautuu uuteen ikkunaan..
Ilmoita Valtuudet-palvelun käyttöönottotiimille Web API -liitynnän paluuosoite. Se on organisaatiosi asiointipalvelun osoite, johon loppukäyttäjän selainistunto ohjataan, kun hän on valinnut päämiehen Valtuudet-palvelun valintakäyttöliittymällä.
Testausvaiheessa Web API -liitynnän paluuosoite voi olla localhost. Protokollan tulee olla HTTPS, jos osoite osoittaa muuhun kuin localhost-osoitteeseen.
Kun asiointipalvelu aloittaa OAuth-valtuutusprosessin, se välittää Valtuudet-palvelulle uudelleenohjausosoitteen, johon käyttäjän selain ohjataan päämiehen valinnnan jälkeen. Jotta paluupyynnön mukana välitettävä OAuth-avain ei päädy vääriin käsiin, Valtuudet-palvelu rajoittaa uudelleenohjauksen vain sille ennalta määriteltyihin osoitteisiin. Asiointipalvelun on toimitettava tieto täsmällisistä uudelleenohjausosoitteista Valtuudet-palvelulle liityntäprosessin yhteydessä.
Palveluväylä-liityntä
Kun organisaatiosi on ottanut Palveluväylän käyttöönsä, ilmoita Valtuudet-palvelun käyttöönottotiimille tarvittavat tiedot alijärjestelmästäsi:
- Member Class
- Member Code
- Subsystem Code