Rajapinnan tekninen toteutus ja palvelun käyttö

VTJ-kyselyrajapinta on XML (SOAP)-protokollan mukaisia sanomia vastaanottava ja palauttava sovelluspalvelu (web service). Asiakasorganisaation tietojärjestelmä käynnistää VTJ-tietojen haun lähettämällä kyselysanoman palvelulle ja saa vastauksena haetut VTJ-tiedot vastaussanoman sisältönä. 

Yhteyden muodostaminen

Asiakasjärjestelmän ja väestötietojärjestelmän väliset kysely-yhteydet tunnistetaan ja suojataan pääasiassa palvelinvarmenteiden avulla. Tietojen siirto rajapinnan ja asiakasjärjestelmän välillä tapahtuu Internetin kautta HTTPS/TLS-suojattuna. Tietoliikenteen suojaus suositellaan toteutettavaksi TLS 1.2 protokollan mukaisesti (vähimmäisvaatimuksena TLS1.1).

Julkishallinnon organisaatiolta yhteyden muodostamisessa edellytetään Digi- ja väestötietoviraston tarjoaman Kansallisen 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ätte lisää tietoa täältä.

Rajapintasanomien muoto ja sisältö

VTJ-kyselyrajapinnan kautta on mahdollista hakea kaikkea väestötietojärjestelmän tietoa, ja siitä voidaan tarvittaessa räätälöidä uudenlaisia yhdistelmätietoja. 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).

Organisaationne käyttöön myönnettävän vastaussanoman tarkka muoto ja sen sisältämät VTJ-tiedot sovitaan käyttöön vaadittavan tietoluvan hakuprosessin yhteydessä. Kukin asiakasorganisaatio saa vastaussanomassa vain niitä tietoja haun kohteesta (kuten henkilö, huoneisto, rakennus tai kiinteistö), joihin sillä on oikeus. Pääsääntöisesti tietoja luovutetaan vain haun kohteen yksilöivällä tunnuksella, kuten henkilötunnuksella, sähköisellä asiointitunnuksella tai rakennustunnuksella. Mikäli asiakasorganisaation tehtävät sitä lain mukaan edellyttävät, voidaan tietoja hakea myös muilla kuin yksilöivillä hakukriteereillä.

Asiakasjärjestelmän velvoitteista

VTJ-kyselyrajapinnan käyttöoikeus myönnetään organisaatiokohtaisena. Luvan saaja vastaa siitä, että jälkikäteen on selvitettävissä henkilötasolla, kuka väestötietojärjestelmästä haettuja tietoja on saanut asiakasjärjestelmän kautta nähtäväkseen. Organisaatio, jolle oikeus sovelluskyselyyn on annettu, on velvollinen säilyttämään lokitiedot viideltä (5) vuodelta.

Luvan saaja vastaa myös asiakasjärjestelmän tietoturvallisuudesta ja jokaisen haetun tiedon käsittelyn lainmukaisuudesta ja käyttötarkoituksenmukaisuudesta. Oman tietojärjestelmän koko asiakas- tai muun rekisterin tietojen ajantasaisuuden tarkistus VTJ-kyselyrajapinnasta ei ole sallittua ilman poikkeuslupaa Digi- ja väestötietovirastolta. Jos tarpeenne on tämänkaltainen, soveltuvampi palvelu löytyy todennäköisesti asiakasrekisterien päivityspalveluista.

Tältä sivulta löytyvästä VTJ-kyselyrajapinnan palvelukuvaus -dokumentista löydät tarkemman kuvauksen palvelusta ja asiakasorganisaation velvoitteista

Toimikaa näin

Lukekaa lisää VTJ-kyselyrajapinnan käyttöönotosta Väestötietojärjestelmän hakupalvelut -sivulta.