VTJkysely-rajapinnan tekninen toteutus ja käyttö

Tälle sivulle on koottu teknistä tietoa VTJkysely-rajapinnasta. Yleisempää tietoa löydät VTJkysely-rajapinnan sivulta.

VTJkysely-rajapinta on XML (SOAP)-protokollan mukaisia sanomia vastaanottava ja palauttava sovelluspalvelu (web service). Asiakasorganisaation tietojärjestelmä lähettää VTJkysely-rajapinnan kautta kyselyn palveluun, josta palautuu vastaussanomana kyselyä vastaavat VTJ-tiedot.

Asiakasjärjestelmän ja väestötietojärjestelmän väliset kysely-yhteydet tunnistetaan ja suojataan pääasiassa palvelinvarmenteiden avulla. Tietojen siirto VTJkysely-rajapinnan ja asiakasjärjestelmän välillä tapahtuu Internetin kautta HTTPS/TLS-suojattuna. Tietoliikenteen suojauksessa tulee käyttää TLS 1.2 tai uudempaa suojausprotokollaa.

Julkishallinnon organisaatiolta yhteyden muodostamisessa edellytetään Digi- ja väestötietoviraston tarjoaman Suomi.fi-palveluväylän käyttöä. Velvoite on kirjattu lakiin hallinnon yhteisistä sähköisen asioinnin tukipalveluista. Muille organisaatiolle palveluväylän käyttö yhteysväylänä on valinnaista. Palveluväylän käyttöönoton yksityiskohdista löydät lisää tietoa Suomi.fi-sivustolta.

Organisaationne käyttöön myönnettävän tuotteen (vastaussanoman) sisältämät VTJ-tiedot sovitaan tietoluvan hakuprosessin yhteydessä. Kukin asiakasorganisaatio saa vastaussanomassa vain niitä tietoja haun kohteesta (kuten henkilö, huoneisto, rakennus tai kiinteistö), joihin sillä on oikeus.

Digi- ja väestötietovirastolla on valmiita tuotteita erilaisilla tietosisällöillä eri käyttötarkoituksiin. Mikäli organisaationne ei löydä tietotarpeisiinne sopivaa tuotetta, voidaan teille räätälöidä uusi tuote. Luettelon rajapinnan kautta tällä hetkellä saatavissa olevista henkilötiedoista ja niiden muodosta löydät tältä sivulta löytyvästä henkilötietokatalogista (XML Schema -muodossa).

Yleiskuvauksen rajapinnan teknisestä toiminnasta, kuten erilaisista haku- ja vastaussanomatyypeistä, löydät tältä sivulta ladattavissa olevasta sovellusrajapinnan tekninen kuvaus -dokumentista (WSDL-muodossa).

Pääsääntöisesti tietoja luovutetaan vain haun kohteen yksilöivällä tunnuksella, kuten henkilötunnuksella, sähköisellä asiointitunnuksella tai rakennustunnuksella. Tietoja voidaan hakea myös muilla kuin yksilöivillä hakukriteereillä, mikäli asiakasorganisaation tehtävät edellyttävät sitä lain mukaan.

Organisaation tulee hoitaa lokitus asianmukaisesti. Sovelluskyselyyn oikeuden saanut organisaatio on velvollinen säilyttämään lokitiedot viideltä (5) vuodelta. Organisaation on pystyttävä jälkikäteen kertomaan, kuka kyselyn on tehnyt (henkilötasolla), mitä tietoja on haettu ja milloin kysely on tehty (pp.kk.vvvv klo).

Luvan saaja vastaa myös asiakasjärjestelmän tietoturvallisuudesta ja jokaisen haetun tiedon käsittelyn lainmukaisuudesta ja että kyselyt ovat tietoluvan ehtojen ja myönnettyjen tuotteiden käyttötarkoituksen mukaisia.

Huomaa, että oman tietojärjestelmän koko asiakas- tai muun rekisterin tietojen ajantasaisuuden tarkistus VTJkysely-rajapinnasta ei ole sallittua. Jos tarpeenne on tämänkaltainen, soveltuvampi palvelu löytyy todennäköisesti asiakasrekisterien päivityspalveluista julkiselle sektorille tai yksityiselle sektorille.

VTJkysely-rajapinnan palvelukuvaus -dokumentista löydät tarkemman kuvauksen palvelusta ja asiakasorganisaation velvoitteista.