Lisätietoa IN-integraation toteuttajalle

PTV:ssä on käynnissä arkkitehtuuriuudistus, jonka osana julkaistaan rajapintaversio 12 ja siirtymäajan jälkeen ajetaan alas rajapintaversio 11. Otathan muutoksen huomioon suunnitellessasi uutta integraatiota!

Lue lisää arkkitehtuuriuudistuksesta ja suunnitelmasta rajapintaversioiden vaihdolle

Käyttölupahakemus

In-rajapinnan käyttöönotto edellyttää käyttölupahakemuksen tekemistä.

MIten otan käyttöön IN-rajapinnan

Ohjeita integraation toteuttamiseen

Kun Digi- ja väestötietovirasto on hyväksynyt käyttölupahakemuksen, organisaatiosi voi ryhtyä toteuttamaan integraatiota PTV:n asiakastestiympäristöä hyödyntäen. Asiakastestiympäriston tiedot löytyvät tämän sivun lopusta.

• IN-rajapinnan metodit SwaggerissäAvautuu uuteen ikkunaan.
• IN-rajapinnan metodit, rajapintaversio 11, Digi- ja väestötietovirasto (XLSX, 222,06 kt)Avautuu uuteen ikkunaan.

Integraatio tulee toteuttaa siten, että lähdejärjestelmässä tehtävät muutokset tuodaan vähintään kerran vuorokaudessa PTV:hen. Myös lähdejärjestelmästä poistuvat tiedot tulee poistaa PTV:stä vähintään kerran vuorokaudessa.

Tunnistautuminen rajapintaan

Käyttäjä tarvitsee voimassa olevan API-tunnuksen ja voimassa olevan tokenin voidakseen käyttää IN-rajapinnan metodeja tai OUT-rajapinnan metodeja, joiden käyttöoikeutta on rajattu.

IN-integraatiototeutus on aina organisaatiokohtainen. Organisaatiokohtainen käyttäjätunnus ja salasana lähetetään Suomi.fi-palveluhallinnan käyttövaltuushallinnan palvelimelle, joka palauttaa tunnistautumisessa tarvittavan tokenin.

Tunnistautuminen tuotantoympäristöön tokenin avulla

Tuotantoympäristön token sisältää tiedot käyttöoikeuksista ja rooleista sekä tokenin voimassaoloajan.

Token-linkki: https://palveluhallinta.suomi.fi/api/auth/api-loginAvautuu uuteen ikkunaan.

Tokenin voimassaolo on rajattu. Voimassaolo on kerrottu tokenin sisällä olevissa tiedoissa.

Tokenin parametrit

Headers:

• Content-Type:application/json

Body:

• username: user
• password: pwd
• apiUserOrganisation: organisation ID (vapaavalintainen)

Kutsu palauttaa serviceToken -parametrin.

Jos API-tunnus liittyy useaan organisaatioon, käyttäjän tulee antaa kutsussa Palveluhallinnan organisaatio ID käyttäen apiUserOrganisation parametria. Mikäli parametria ei anneta, token palauttaa Palveluhallinnassa aktiiviseksi organisaatioksi merkityn organisaation ID:n.

Kutsuesimerkki 1, API organisaatio-IDtä ei ole annettu

  "username":"username@domain.fi",

  "password":"validpassword"

}

Kutsuesimerkki 2, API organisaatio-ID annettu

{

  "username":"username@domain.fi",

  "password":"validpassword",

  "apiUserOrganisation": "9cb2abc6-5458-4811-bbdd-83f75ceeed25"

}

Response

{

  "serviceToken":"eyJhlsdlksd...."

}

Huomaathan, että Palvelutietovarannon tuotantoympäristön ja asiakastestiympäristön rajapinnan luvituksen (token) rakenteessa on eroja. Tuotantoympäristössä on apiUserOrganisation-kenttä, jota ei ole asiakastestiympäristössä.

Jos API-tunnus on liitetty useampaan kuin yhteen organisaatioon, luvituspyyntö voidaan kohdistaa haluttuun organisaatioon apiUserOrganisation-kentän avulla. Kenttään annetaan Suomi.fi-palveluhallinnan palauttama id.

Asiakastestiympäristössä token voidaan kytkeä ainoastaan yhteen organisaatioon, joten tokenia ei voida käyttää testaamiseen tilanteessa, jossa yhteen integraatioon liittyy useita organisaatioita.

Teknisen valmiuden testaus

Kun integraatio on toteutettu asiakastestiympäristöön, tulee organisaatiosi testata rajapintayhteyden toiminta (palomuuriavaukset, käyttöoikeudet jne.) asiakastestiympäristössä. Rajapintayhteys testataan aineistolla, jota ei aiemmin ole viety asiakastestiympäristöön esim. käyttöliittymän kautta. Teknisen valmiuden testauksessa testataan

• uusien aliorganisaatioiden, uusien palvelujen ja uusien asiointikanavien lisääminen ja muokkaaminen
• liitosten ja liitoksen lisätietojen lisääminen ja muokkaaminen
• tietokenttien oikeellisuus (tietomuodot, pituudet, pakollisuudet jne.).
• lähdejärjestelmästä poistuneiden tietojen arkistointi

Organisaatiosi pitää laatia testausraportti ja toimittaa se osoitteeseen ptv-tuki@dvv.fi.

Tietosisällön testaus

Jotta IN-integraatio voidaan testata ja viedä tuotantoon, myös tietosisällön tulee olla ajan tasalla ja vastata PTV:n laatuvaatimuksia. Edellytämme testausraporttia, josta datan laatu ja tietomallin mukaisuus käy ilmi.

Lue lisää tietosisällön testauksesta

Tee mahdolliset korjaukset ja tuotantoasennus 

DVV arvioi testausraporttien perusteella, voidaanko organisaatiollesi myöntää IN-rajapinnan tuotantotunnukset. Tämä voi vaatia useita iteraatiokierroksia. 

Kun testiraportit on hyväksytty, DVV toimittaa erikseen sovitusti asiakasorganisaatiolle tai sovellustoimittajalle käyttölupahakemuksessa yksilöityyn osoitteeseen API-käyttäjäoikeudet PTV:n tuotantoympäristöön. Tämän jälkeen voitte tehdä tuotantoasennuksen.