Liityntätavan ja rajapintojen valinta

Suomi.fi-valtuuksia voi hyödyntää kahdella erilaisella teknisellä liittymistavalla. Toinen on Suomi.fi-palveluväylä ja toinen WebAPI-liityntä.

WebAPI-liityntä

Suomi.fi-palveluväylä:

Kumpi liityntätapa soveltuu parhaiten minun asiointipalveluuni?

  • Jos asiointipalvelussa halutaan mahdollistaa henkilön puolesta asiointi, suositeltavin liittymistapa on tällöin WebAPI-liityntä.
  • Jos asiointipalvelussa halutaan mahdollistaa sekä henkilön että yrityksen puolesta asiointi, suositeltavin liittymistapa on tällöin WebAPI-liityntä. Muutoin joudutaan rakentamaan integraatio 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ä, silloin ainoa vaihtoehto on Suomi.fi-palveluväylä.

Esimerkit asiointipoluista

WebAPI-liityntä

1. Tunnistaudutaan asiointipalveluun
2. Valitaan ”Toisen puolesta asiointi”
Istunto siirtyy Valtuudet-palvelun valintakäyttöliittymälle, josta valitaan kenen puolesta halutaan asioida

4. Valinnan jälkeen istunto palaa asiointipalveluun ja asiointi jatkuu valtiun päämiehen puolesta (henkilö tai yritys)

Suomi.fi-palveluväylä

1. Tunnistaudutuaan asiointipalveluun ja valitaan pudotusvalikosta yritys jonka puolesta halutaan asioida

Liityntätapojen arkkitehtuuriset erot

WebAPI-liityntä

Suomi.fi-palveluväylä

Asiakastestiympäristöön liittyminen

WebAPI-liityntä

Ilmoita Valtuuksien käyttöönottotiimille (valtuudet-kayttoonotot@vrk.fiWebAPI-liitynnän paluuosoite.  Se on asiointipalvelun osoite johon käyttäjän selainistunto ohjataan sen jälkeen kun hän on valinnut päämiehen Valtuudet-palvelun valintakäyttöliittymällä. Osoite voi olla testausvaiheessa localhost. Protokolla pitää olla https ja osoitteessa pitää olla osoitteen polku kokonaisuudessaan. Lisätietoja rajapintakuvauksessa (kpl 5.3): https://esuomi.fi/palveluntarjoajille/valtuudet/tekninen-aineisto/web-api-rajapinta-ja-valintakayttoliittyma/

Suomi.fi-palveluväylä

WebAPI-liitynnän kautta hyödynnettävät valtuuksien rajapintakyselyt

Rajapintakysely Syöte Vapaaehtoinen syöte Vastaus Vastausesimerkki
Delegate sessionId Lista päämiesten perustiedoista
Authorization asiamiehen hetu + päämiehen hetu issue (valtuuskoodin uri, voi olla useita Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu [{"result":"ALLOWED","reasons":[],"principal":{"personId":"120508A950F","name":"Kumpulainen Anni Emilia"}}]
AuthorizationList asiamiehen hetu + päämiehen hetu AuthorizationList-kutsu palauttaa tiedon kaikista valtuutustunnisteista, eli asioista, joissa asiamiehellä on asiointioikeus päämiehen puolesta. Mikäli asiat eivät ole rajattuja, esim. huoltajuussuhteen vuoksi, palautetaan erillisten asioiden sijaan ALL. [{"reasons":[],"roles":
["ALL",
"http://valtuusrekisteri.suomi.fi/sukuselvityksen_tilaaminen",
"principal":{"personId":"010132-998W","name":"Tuulispää Edelweiss"
}}]
OrganizationalRoles asiamiehen hetu y-tunnus
Haettavan organisaation tunniste (y-tunnus). Voi olla useita
OrganizationalRoles -kutsu palauttaa listan puolesta-asioijan organisaatioista ja niihin liittyvistä rooleista. [{"name":"Itä-Suomen Alihankkijat Oy","identifier":"2149444-1","complete":true,"roles": [ "TJ" "http://valtuusrekisteri.suomi.fi/tyonhakijatietojen_tarkastelu_ja_yhteydenotto_hakijoihin", "http://valtuusrekisteri.suomi.fi/tyontarjoajan_kuvauksen_paivitys" ]}]

Suomi.fi-palveluväylän kautta hyödynnettävät valtuuksien rajapintakyselyt

Rajapintakysely Syöte Vapaaehtoinen syöte Vastaus Vastausesimerkki
Authorization asiamiehen hetu + päämiehen hetu issue (valtuuskoodin uri, voi olla useita Päätöstieto onko puolesta-asiointi valitussa kontekstissa sallittu <response>
<authorization>ALLOWED</authorization>
</response>
AuthorizationList asiamiehen hetu + päämiehen hetu AuthorizationList-kutsu palauttaa tiedon kaikista valtuutustunnisteista, eli asioista, joissa asiamiehellä on asiointioikeus päämiehen puolesta. Mikäli asiat eivät ole rajattuja, esim. huoltajuussuhteen vuoksi, palautetaan erillisten asioiden sijaan ALL. <response>
<roles>
<role>ALL</role>
<role>http://valtuusrekisteri.suomi.fi/palkkatietojen_ilmoittaminen</role>
<roles>
</response>
OrganizationalRoles asiamiehen hetu y-tunnus
Haettavan organisaation tunniste (y-tunnus). Voi olla useita.
OrganizationalRoles -kutsu palauttaa listan puolesta-asioijan organisaatioista ja niihin liittyvistä rooleista. <response>
<organizationList>
<organization>
<organizationIdentifier>aaaaaaa-a</organizationIdentifier>
<name>Maanrakennus Ari Eerola T:mi</name>
<roles>
<role>NIMKO</role>
</roles>
</organization>
<organization>
<organizationIdentifier>bbbbbbb-b</organizationIdentifier>
<name>Rova Oy 1</name>
<roles>
<role>NIMKO</role>
</roles>
</organization>
</organizationList>
</response>
VersionroMitä tehtyPVM /Henkilö
1.0Sivu luotu12.12.2018 / EJ