Tekninen dokumentaatio 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
Palvelutietovarannon rajapintaversiot
Tällä hetkellä käytössä on PTV:n rajapintaversio 11. Rajapintaversioon 11 ei tule enää tehdä uusia integraatioita.
API-versio | 2025 | 2026 | 2027 |
|---|---|---|---|
API-versio 11 | tuettu | tuettu | poistuu käytöstä keväällä 2027 (alustava) |
API-versio 12 | OUT-rajapinnan tuotantoympäristön metodit (betaversio) otetaan käyttöön | IN-rajapinnan metodit otetaan käyttöön keväällä 2027 (alustava) |
Perustiedot PTV:n rajapinnasta
Palvelutietovarannossa on avoin REST-/JSON-rajapinta. Tiedot annetaan vapaasti jatkohyödynnettäviksi CC0-lisenssillä, eli tietoja voi hyödyntää rajoituksetta. Digi- ja väestötietovirasto kuitenkin edellyttää, että jokainen integraation toteuttava organisaatio ilmoittaa integraatiosta osoitteeseen ptv-tuki@dvv.fi ja toimittaa yhteystiedot häiriöviestintää varten.
OUT-rajapinta mahdollistaa tietojen hakemisen ilman kirjautumista tai käyttölupaa.
Lisätietoja OUT-integraation toteuttajalle
IN-rajapinnan kautta on mahdollista tuoda PTV:hen tietoa toisesta järjestelmästä. Tämä edellyttää kuitenkin erillistä käyttölupaa.
Lisätietoja IN-integraation toteuttajalle
Organisaation ja palvelupaikan sijaintitiedoissa käytetty karttakoordinaattistandardi on EPSG 3067.
Uutta integraatiota toteutettaessa tulee aina ottaa käyttöön uusin rajapintaversio.
Tietomalli
Palvelutietovaranto sisältää asiakaslähtöisesti kuvatut palveluiden tiedot ja niihin liittyvien asiointikanavien tiedot sekä näiden väliset liitostiedot. Tämän lisäksi voi hakea palvelut kuvanneiden organisaatioiden tietoja. Ennen kuin alat toteuttaa integraatiota, perehdy huolellisesti PTV:n konseptiin ja tietomalliin.
Osa Palvelutietovarannon sisältämistä tiedoista on ihmislukijalle tarkoitettuja tekstimuotoisia kuvauksia, osa metadataa.
PTV:ssä käytettävät koodistot, Digi- ja väestötietovirasto (XLSX, 14,02 kt)Avautuu uuteen ikkunaan.
PTV:n tuotanto-Swagger
OUT- ja IN-rajapintojen metodit löytyvät SwaggeristäAvautuu uuteen ikkunaan.. Metodit on ryhmitelty kahdeksaan eri aihealueeseen
- CodeList/Koodistot
- Common/Yleiset
- Connection/Liitos
- GeneralDescription/Pohjakuvaus
- Organization/Organisaatio
- Service/Palvelu
- ServiceChannel/Asiointikanava
- ja ServiceCollection/Palvelukokonaisuus.
GET-metodit mahdollistavat tietojen hakemisen, POST-metodit uusien tietojen lisäämisen ja PUT-metodit näiden tietojen päivittämisen. POST-ja PUT-metodien käyttö edellyttää IN-rajapinnan käyttölupaa.
Palveluiden tietoja on mahdollista hakea myös aluetiedon, kohderyhmän, palveluluokan, palvelutyypin ja toimialaluokan perusteella.
Metodien tarkempaa käyttöä ohjeistetaan Swaggerissä.
Osa metodeista on rajattu vain DVV:n omaan käyttöön ja osa ASTI-järjestelmän käyttöön.
PTV:n lähdekoodi
PTV:n lähdekoodi ei ole tällä hetkellä ole saatavissa Githubista. Mikäli PTV:n koodille on tarvetta, pyydä sitä osoitteesta ptv-tuki@dvv.fi.