Web-API istunnon siirtäminen
Istunnon siirto -ominaisuus on tarkoitettu käyttäjän valintakäyttöliittymässä tekemien puolesta-asioitavien osapuolien valintojen siirtämiseen asiointipalvelulta toiselle.
Tällöin käyttäjän ei itse tarvitse suorittaa puolesta-asioitavan osapuolen valintaa uudelleen siirtyessään asiointipalvelusta toiseen. Siirto on käytettävissä HPA- ja YPA -Web API -istunnoille.
Siirron suorittaminen
1. Istunnon siirto henkilön puolesta asioinnissa suoritetaan seuraavasti. Muuttuvia arvoja sisältävät kutsuparametrit on kuvattu taulukossa esimerkkikutsun alla.
2. Asiointipalvelu aloittaa istunnon tavanomaisesti kutsumalla rekisteröintirajapintaa, ohjaamalla käyttäjänä valitsemaan puolesta asioitava ja vaihtamalla tämän jälkeen väliaikaisen tunnisteen OAuth access tokeniksi.Istunnon aloittanut asiointipalvelu pyytää siirtotunnisteen valtuuksien palvelulta kutsumalla siirron aloittavaa rajapintaa:
GET /service/hpa/user/transfer/token/{sessionId}Parametrin nimi | Parametrin sijainti | Parametrin arvo |
|---|---|---|
sessionId | URL-parametri | Alkuperäisesssä rekisteröitymisessä palautunut istuntotunniste. |
X-AsiointivaltuudetAuthorization | Otsake | Tarkistesumma. |
3. Palautunut siirtotunniste (transferToken) välitetään toiselle asiointipalvelulle, joka suorittaa oman rekisteröintinsä käyttäen saatua siirtotunnistetta:
GET /service/hpa/user/register/transfer/{transferToken}/{clientId}/{delegateId}=requestId={requestId}Parametrin nimi | Parametrin sijainti | Parametrin arvo |
|---|---|---|
transferToken | URL-parametri | Web-API:n ensimmäiselle asiointipalvelulle palauttama siirtotunniste. |
clientId | URL-parametri | Toisen asiointipalvelun käyttäjätunnus. |
delegateId | URL-parametri | Asiamiehenä toimivan käyttäjän tunniste. Sama molemmissa palveluissa. |
requestId | URL-parametri | Pyynnön yksilöivä tunniste. Esim. UUID. |
X-AsiointivaltuudetAuthorization | Otsake | Tarkistesumma. |
4. Käyttäjä uudelleenohjataan authorize-osoitteeseen, josta käyttäjä palautuu suoraan palvelun paluuosoitteeseen ilman puolesta-asioitavan valintaa:
GET /oauth/authorize?client_id={clientId}&response_type=code&requestId={requestId}&user={user}&scope=read&state={state}&redirect_uri={redirectUri}&lang={lang}Parametrin nimi | Parametrin sijainti | Parametrin arvo |
|---|---|---|
clientId | URL-parametri | Toisen asiointipalvelun käyttäjätunnus. |
requestId | URL-parametri | Pyynnön yksilöivä tunniste. Esim. UUID. |
user | URL-parametri | Rekisteröinnistä palautunut tunniste (userId). |
state | URL-parametri | Asiointipalvelun sisäinen tunniste transaktiolle. Esim UUID. |
redirect_uri | URL-parametri | Asiointipalvelun osoite, johon käyttäjä ohjataan siirron jälkeen. |
lang | URL-parametri | Valinnaisena parametrinä käyttöliittymän kieli: fi, sv tai en. |
5. Asiointipalvelu vaihtaa jälleen paluun yhteydessä saamansa väliaikaisen tunnisteen OAuth access tokeniksi:
POST /oauth/token?grant_type=authorization_code&redirect_uri={redirectUri}&code={code}Parametrin nimi | Parametrin sijainti | Parametrin arvo |
|---|---|---|
redirectUri | URL-parametri | Uudelleenohjauksessa aiemmin välitettu osoite, johon juuri palattiin. |
code | URL-parametri | Uudelleenohjauksen jälkeen asiointipalveluun välitettu koodi (authorization_code). |
Authorization | Otsake | Käyttäjätunnus ja salasana. |
6. Alkuperäisen asiointipalvelun kautta valittu päämies on nyt valittuna myös toisessa asiointipalvelussa.
Siirron voi suorittaa vastaavasti myös yrityksen puolella asionnissa.
Huomioitavaa
Istunnon siirtoa käytettäessa on huomioitava seuraavat asiat:
- Istunnot alustetaan käyttäen samaa asiamiestunnistetta, eli asiamiehen on oltava vahvasti tunnistautunut molempiin asiointipalveluihin.
- Asiamiehen asiointioikeus on tarkastettava uudelleen siirron jälkeen.
- Asiointipalveluiden asetusten on oltava riittävän samankaltaisia jotta asiointioikeustarkastus voi onnistua siirron jälkeen.
- Kaikkien esivalittujen puolesta asioitavien yritysten tulee palautua myös toisen asiointipalvelun säännöstöllä puolesta-asioitavien joukkoon, jotta siirto ei keskeytyisi valintakäyttöliittymään.
- Jos käytetään ulkomaalaisten henkilöiden tai ulkomaisten yritysten tunnisteita, tulisi niiden olla molempien palveluiden asetuksissa ja asiointipalveluiden käsiteltävissä.
- Valintojen siirto ei muuta alkuperäistä istuntoa.
- Siirto on suoritettava ennen kuin alkuperäinen istunto on päätetty unregister-kutsulla.
- Siirtotunniste on voimassa minuutin ajan. Mikäli siirtotunniste ennättää aikautua ennen sen rekisteröintiä, esitetään käyttäjälle roolivalinta uudelleenohjauksen yhteydessä.