Tekninen dokumentaatio integraation toteuttajalle (rajapintaversio 12)

Palvelutietovarannon rajapintaversiot

PTV:n rajapintaversion 12 hakurajapinta on julkaistu tuotantoympäristössä betaversiona 03/2026.

Lue lisää arkkitehtuuriuudistuksesta ja suunnitelmasta rajapintaversioiden vaihdolle

Perustiedot PTV:n rajapinnasta

Palvelutietovarannossa on avoin REST/JSON-rajapinta. Tiedot annetaan vapaasti jatkohyödynnettäviksi CC0-lisenssillä, eli voit hyödyntää rajoituksetta.

Rajapintaversiosta 12 alkaen tarvitset API-avaimen sekä hakurajapinnan että tuontirajapinnan käyttöön.

Voit luoda API-avaimen itsepalvelussa. Avain on käytettävissä heti luomisen jälkeen. Kun otat avaimen käyttöön, ilmoita organisaatiosi yhteystiedot Digi- ja väestötietovirastolle. Yhteystietoja käytetään rajapinnan häiriöistä viestimiseen.
Lue API-avaimen käyttöohje rajapintaversiolle 12.

Organisaation ja palvelupaikan sijaintitiedoissa käytetään EPSG:3067-koordinaattijärjestelmää.

Kun toteutat uuden integraation, käytä aina uusinta saatavilla olevaa rajapintaversiota.

Hakurajapinta

Hakurajapinnan avulla voit hakea tietoja PTV:stä. Jos toteutat hakuintegraatiota, tutustu seuraaviin ohjeisiin:

• Lisätietoa hakuintegraation toteuttajalle (rajapintaversio 12)
• Siirtyminen rajapintaversiosta V11 versioon V12 (haku- ja tuontirajapinta)

Tuontirajapinta

Tuontirajapinnan avulla voit tuoda tietoja PTV:hen toisesta järjestelmästä. Tuontirajapinnan käyttö edellyttää erillistä käyttölupaa.
Jos toteutat tuonti-integraatiota, tutustu seuraaviin ohjeisiin:

• Lisätietoa tuonti-integraation toteuttajalle (rajapintaversio 12)
• Siirtyminen rajapintaversiosta V11 versioon V12 (haku- ja tuontirajapinta)
• 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. Rajapinnasta voit myös hakea palvelut kuvanneiden organisaatioiden tietoja.

Ennen kuin aloitat integraation toteuttamisen, perehdy huolellisesti:

• PTV:n konseptiin, joka kertoo, mikä Palvelutietovaranto on ja mihin sitä käytetään.
• Tietomallin yleiskuvaukseen, joka kuvaa PTV:n keskeiset käsitteet ja niiden väliset yhteydet.
• PTV:n loogiseen tietomalliinAvautuu uuteen ikkunaan., joka kuvaa tietomallin rakenteet ja niiden väliset suhteet tarkemmin.

Rajapintadokumentaatio Scalarissa

Rajapintakutsut ja niiden käyttöohjeet löydät ympäristökohtaisesti:  

• Asiakastestiympäristön rajapintadokumentaatio (Scalar) Avautuu uuteen ikkunaan.
• Tuotantoympäristön rajapintadokumentaatio (Scalar)Avautuu uuteen ikkunaan.

Rajapinnan kutsut on ryhmitelty rajapintadokumentaatiossa kahteen kokonaisuuteen: tietosisältöön ja referenssidataan.

Tietosisältö (core) sisältää seuraavien PTV:n sisältöjen rajapintakutsut:

• palvelut
• asiointikanavat
• liitokset
• organisaatiot
• pohjakuvaukset
• palvelukokonaisuudet

Referenssidata (reference data) sisältää

• koodistot
• luokitukset ja
• muut viitetiedot.

Rajapintakutsujen käyttö

• Hae tietoja GET-metodeilla
• Lisää tietoja POST-metodeilla
• Päivitä tietoja PUT-metodeilla
• Arkistoit tietoja DELETE-metodeilla

Käytä API-avainta kaikissa kutsuissa. POST-, PUT- ja DELETE-metodien käyttö edellyttää myös tuontirajapinnan käyttölupaa, ks. ohje Näin otan tuontirajapinnan (IN-rajapinta) käyttöön.

PTV:n lähdekoodi

PTV:n lähdekoodi ei ole tällä hetkellä julkisesti saatavilla GitHubista. Jos tarvitset lähdekoodia esimerkiksi integraation toteuttamisen tai teknisen selvitystyön tueksi, pyydä sitä osoitteesta ptv-tuki@dvv.fi.