Tekninen dokumentaatio integraation toteuttajalle (rajapintaversio 12)
Beta - sisältö on keskenTämä sivu on alustava ja täydentyy kevään 2026 aikana V12-kehitystyön edetessä
Palvelutietovarannon rajapintaversiot
PTV:n rajapintaversion 12 hakurajapinta on julkaistu tuotantoympäristössä betaversiona 03/2026.
Lue lisää arkkitehtuuriuudistuksesta ja suunnitelmasta rajapintaversioiden vaihdolle
API-versio | 2026 | 2027 |
|---|---|---|
API-versio 11 | tuettu | poistuu käytöstä keväällä 2027 (alustava) |
API-versio 12 | hakurajapinnan(OUT) tuotantoympäristön metodit (betaversio) otetaan käyttöön 3/2026 | tuontirajapinnan (IN) 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ä integraation toteuttava organisaatio toimittaa yhteystiedot häiriöviestintää varten. Yhteystietojen toimittaminen tapahtuu API-avaimen käyttöönoton yhteydessä.
Sekä hakurajapinta (OUT) että tuontirajapinta (IN) edellyttävät rajapintaversiosta 12 alkaen API-avaimen käyttöä. API-avaimen voi luoda itsepalveluna ja se on heti käytettävissä.
API-avaimen käyttöohje (rajapintaversio 12)
Organisaation ja palvelupaikan sijaintitiedoissa käytetty karttakoordinaattistandardi on EPSG:3067.
Uutta integraatiota toteutettaessa tulee aina ottaa käyttöön uusin rajapintaversio.
Hakurajapinta
Hakurajapinta mahdollistaa tietojen hakemisen PTV:stä.
- Lisätietoa hakuintegraation toteuttajalle (rajapintaversio 12)
- Siirtyminen rajapintaversiosta V11 versioon V12 (hakurajapinta)
Tuontirajapinta
Tuontirajapinnan kautta on mahdollista tuoda PTV:hen tietoa toisesta järjestelmästä. Tämä edellyttää kuitenkin erillistä käyttölupaa.
- Lisätietoa tuonti-integraation toteuttajalle (rajapintaversio 12) (linkki tulossa)
- Siirtyminen rajapintaversiosta V11 versioon V12 (tuontirajapinta) (linkki tulossa)
- Käsittelysäännöt rajapintatiedon tulkintaan
- Näin otan tuontirajapinnan (IN-rajapinta) käyttöön
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
- Tietomallin yleiskuvaukseen, joka kuvaa PTV:n keskeiset käsitteet ja niiden väliset yhteydet
- PTV:n loogiseen tietomalliin Avautuu uuteen ikkunaan.
Rajapintadokumentaatio Scalarissa
Haku- ja tuontirajapintakutsut löytyvät tuotannon ScalaristaAvautuu uuteen ikkunaan., sekä asiakastestiympäristön ScalaristaAvautuu uuteen ikkunaan..
Rajapinnan kutsut on ryhmitelty kahteen kokonaisuuteen:
- Tietosisältö (core), joka sisältää Palvelutietovarannon tietosisällön (palvelu, asiointikanava, liitos, organisaatio, pohjakuvaus, palvelukokonaisuus) rajapintakutsut
- Referenssidata (reference data), joka koostuu koodistoista, luokituksista ja muusta viitetiedosta
GET-metodit mahdollistavat tietojen hakemisen, POST-metodit uusien tietojen lisäämisen ja PUT-metodit näiden tietojen päivittämisen. Kaikki metodit edellyttävät API-avaimen käyttöä. POST- ja PUT- metodien käyttö edellyttää myös IN-rajapinnan käyttölupaa.
Metodien tarkempaa käyttöä ohjeistetaan rajapintadokumentaatiossa Scalarissa.
Osa metodeista on rajattu vain ASTI-järjestelmän käyttöön.
PTV:n lähdekoodi
PTV:n lähdekoodi ei ole tällä hetkellä saatavissa Githubista. Mikäli PTV:n koodille on tarvetta, pyydä sitä osoitteesta ptv-tuki@dvv.fi.