Sovellusrajapintojen käyttöönotto

Johdanto

Tälle sivustolle kootaan aineistoa Kiinteistövaihdannan palvelun (KVP) rajapintaratkaisujen käyttöönoton vaatiman sovelluskehityksen, koekäytön ja lopullisen käyttöönoton tueksi. Sivustolla tapahtuvista muutoksista pidetään muutoshistoriaa muutosten seurannan helpottamiseksi. Tuotekohtaisilla alasivuilla ylläpidetään myös tuotekohtaiset tarkemmat muutoshistoriat.

Palautteet ja kysymykset osoitteeseen kvp-tuki@maanmittauslaitos.fi

Yleistä käyttötavoista ja rajapintapalveluista

Järjestelmä tarjoaa selainpohjaisen sovelluksen yksityishenkilöiden ja organisaatiokäyttäjien käytettäväksi. Kaikki järjestelmää käyttävät henkilöt tunnistetaan joko palveluun kirjauduttaessa tapahtuvan vahvan tunnistautumisen perusteella tai organisaatioiden tapauksessa tunnistautumispolun perusteella. Organisaatioiden käyttöä helpottamaan tarjotaan mahdollisuus rakentaa tunnistautumisintegraatio, jonka avulla organisaatio voi mahdollistaa käyttäjilleen kerta-kirjautumisperiaatteella (single sign-on) tapahtuvan käytön. Ohjeistus liittymisestä selainpohjaisen sovelluksen käyttäjäksi löytyy KVP tunnistautumisrajapinta kuvauksesta.

Selainpohjaisen käyttöliittymän lisäksi tarjotaan rajapintapalveluna asiakirjarajapintoja.
Asiakirjarajapintoja on kahden tyyppisiä:

  1. Sähköisten asiakirjojen luonnostelun (KVP:n ulkopuolella) mahdollistavat rajapinnat
  2. Kirjallisesti allekirjoitettujen hakemusasiakirjojen sähköisen toimituksen mahdollistava asiakirjarajapinta
Kaikkien KVP:n rajapintojen käyttö edellyttää sopimusta Maanmittauslaitoksen kanssa sekä integraation rakentamista palveluun.

Asiakirjarajapinnat

Kuva 1: Asiakirjarajapinnat mahdollistavat Maanmittauslaitoksen ulkopuolella tapahtuvan asiakirjojen luonnostelun. Asiakirjat voi lähettää palveluun luonnoksena jolloin muokkaus on mahdollista tai lukittuina jolloin asianomaisilla on ainoastaan mahdollisuus vahvistaa tai hylätä asiakirja. Lisäksi on mahdollisuus toimittaa kirjallisesti allekirjoitettu lainhuutohakemus joka menee suoraan vireille. Versiosta 6 lähtien voi lähettää uuden asiakirjatyypin Kiinnitysmuutos, joka on aina lukittu.

Sähköisten asiakirjojen luonnostelun (KVP:n ulkopuolella) mahdollistavat rajapinnat

Sähköisten asiakirjojen osalta periaatteena on, että rajapintojen avulla organisaatio voi lähettää asiakirja- tai valtakirjaluonnoksia yksityishenkilöille tai yrityksille. Saapuvan asiakirjan vastaanottajan tulee hyväksyä saapuva asiakirja, jonka jälkeen asiakirja siirtyy järjestelmään. Lähetettävän asiakirjan voi myös merkitä lukituksi, jolloin asiakirjaan ei voi tehdä palvelussa muutoksia vaan se on mahdollista ainoastaan hyväksyä tai hylätä.
Asiakirjaluonnoksien osalta rajapintojen käyttö vaatii, että palvelun käyttäjä yksilöi mihin kiinteistöön ja kenelle henkilölle asiakirja lähetetään (sekä muut asiakirjakohtaiset tiedot).

Asiakirjan vaiheet
Kuva 1: Asiakirjan käsittelyn eteneminen, tähdellä merkityt merkityt vain luovutuskirjalle. 03/2016 alkaen tilakysely ja valmiiden asiakirjojen lataus on saatavilla kaikille asiakirjatyypeille.

Kun toimihenkilö lähettää asiakirjan, niin vastaanottaja saa saapuvasta asiakirjasta viestin. Kun vastaanottaja kirjautuu järjestelmän selainpohjaiseen käyttöliittymään, niin saapuva asiakirja näkyy käyttäjän meneillä olevissa asioissa. Vastaanottaja pääsee näkemään saapuvan asiakirjan sisällön, jonka jälkeen hän voi tuoda asiakirjan järjestelmään. Toimihenkilö voi myös itse vastaanottaa asiakirjan KVP:ssa, mikäli asiakas on antanut toimihenkilölle valtuudet toimia puolestaan. Vastaanottajalle tarjotaan luovutuskirjan vastaanoton yhteydessä mahdollisuus antaa katseluoikeudet lähettäjälle.

Vastaanottamisen jälkeen asiakirjan käsittely etenee normaalien vaiheiden mukaisesti. Rajapinnan kautta on mahdollista seurata allekirjoitustilannetta sekä hakea valmiit asiakirjat kun kaikki osapuolet ovat allekirjoittaneet.

Lähettäjä voi myös muokata luonnosta ja lähettää uusia versioita samasta asiakirjasta KVP:uun. Uuden version lähettäminen on mahdollista kunnes asiakirja on vastaanotettu.

Asiakirjaluonnostelupalvelun käyttö on valinnaista, koska kaikki toimet voidaan hoitaa myös selainpohjaisessa sovelluksessa.

Tässä dokumentissa esitellään asiakirjanluonnostelupalvelun rajapinnat. Ulkoisen luonnostelupalvelun rakentamisessa voi lisäksi hyödyntää Uuden kirjaamisosan tietopalveluja rekisteriotteiden noutamiseksi rakenteellisessa muodossa.

Varsinainen allekirjoittaminen tapahtuu aina KVP:ssa. Asiakas voi valtuuttaa asiakirjan lähettäjän (tai muun henkilön / yrityksen) allekirjoittaman puolestaan. Lisäksi asiakirjarajapinta tarjoaa tiedon asiakirjan allekirjoitusten tilasta, sekä valmiin allekirjoitetun asiakirjan liitteineen yrityksen omaa arkistointia varten. Asiakirjarajapinnan kautta voi järjestelmään tuoda kaikki pakolliset ja valinnaiset tiedot, jotta asiakirjan voi ainoastaan käydä allekirjoittamassa järjestelmässä. Lisäksi käyttäjän tulee käydä sovelluksen kautta lisäämässä mahdolliset jälkikäteen toimitettavat liitteet kuten maksukuitit

Kirjallisesti allekirjoitettujen hakemusasiakirjojen sähköisen toimituksen mahdollistava asiakirjarajapinta

Kirjallisesti vahvistettujen asiakirjojen toimittaminen tulee mahdolliseksi 10/2016 alkaen (jolloin lainhuutohakemuksen lähettäminen tulee mahdolliseksi). Rajapinta tarjoaa mahdollisuuden välittää kaikki tiedot myös rakenteellisessa muodossa käsittelyn nopeuttamiseksi.

Kirjallisesti vahvistetut asiakirjat menevät suoraan vireille. Hakemusten tilaa on mahdollista kysyä tilarajapinnan avulla.

Rajapintojen jatkokehitys

Ajankohta Kuvaus
1.10.2014 Uuden sovellusversion myötä muutoksia rajapintoihin; nimiavaruus tullaan muuttamaan muuta MML:n nimiavaruutta vastaavaksi (xml.nls.fi/XML/Schema). Lisäksi mm kiinnityksen hakeminen useampaan osuuteen tulee mahdolliseksi
1.3.2015 Lakisääteinen laajempi version päivitys. Järjestelmään ollaan lisäämässä uusia toiminnallisuuksia kuten kiinteistön vaihtamista ja yhteiskiinnittämistä, näiden myötä tulee myös rajapintoihin muutoksia
3.6.2015 Panttikirjan siirtohakemusluonnoksen lähettäminen mahdollista. Lähetettävän asiakirjaluonnoksen voi lukita (pois lukien luovutuskirjat). Hakemus- tai asiointimaksun voi maksaa laskulla
2.12.2015 Asiakirjarajapinnan tilarajapintaskeeman päivitys
16.3.2016 Asiakirjarajapinnasta julkaistaan versio 2. Tilakysely ja valmiiden asiakirjojen lataus tulee mahdolliseksi kaikille asiakirjoille.
8.10.2016 Asiakirjarajapinnasta julkaistaan versio 3. Järjestelmään voi nyt toimittaa luovutuskirjan lukittuna. Lisäksi rajapinnan kautta tulee mahdollisuus toimittaa kirjallisesti allekirjoitettu lainhuutohakemus joka tulee suoraan vireille. Rajapintaversion 1 tuki päättyy.
31.5.2017 Asiakirjarajapinnasta julkaistaan versio 4. Versiosta 4 alkaen on mahdollista lähettää kiinnityshakemuksia (valmistelu ennakkoon). Uusia kirjallisia panttikirjoja ei voi enää pyytää. Rajapintaversion 2 tuki päättyy.
4.10.2017 Asiakirjarajapinnasta julkaistaan versio 5. Versiosta 5 alkaen on mahdollista lähettää maanvuokrasopimuksia. Rajapintaversion 3 tuki päättyy.
15.2.2018 Asiakirjarajapinnasta julkaistaan versio 6. Versiosta 6 alkaen on mahdollista tehdä yhteiskiinnityshakemus, kiinnityksen purkaminen sekä kiinnityksen kuolettaminen. Rajapintaversion 4 tuki päättyy.

Katso asiakirjarajapinnan uudet versiot sivulta tarkemmin asiakirjarajapinnan muutoksista.

Käytön kustannukset

Itse rajapintojen käytöstä ei peritä maksuja, vaan palvelua rahoitetaan asiointi- ja hakemusmaksuilla joita peritään tehtyjen toimien perusteella (luonnostelu on ilmaista). Integraattoreilta peritään vuosittainen integraatiomaksu.

Asiakirjan hakemus/asiointimaksun ja asiakirjaan kuuluvien kiinteistöjen rekisteriotteita voi ottaa halutessa lähettäjän laskulle. Lasku lähetetään v4 voimaantulon jälkeen vasta kun asiakirja on lopullinen KVP:ssä.

Sovelluksen käytön hinnoittelumalli ja euromääräiset kustannukset on kuvattu hinnastossa.

Organisaatiokäytön vaihtoehdot

  1. Selainkäyttö - valmiit tunnistautumistavat
    • Tunnistautumistavat
      • Organisaation edustajan tunnistaminen Suomi.fi-tunnisteella. Vaatii, että käyttäjillä on nimenkirjoitusoikeus rekisteröitynä PRH:ssa. Mahdollistaa organisaation kiinteistöjen myymisen.
      • Organisaation edustaja tunnistetaan Verohallinnon Katso-tunnisteella, jolloin käyttäjä toimii KVP:ssa toimivaltuutettuna. Katsotunnistautumisella vain rajoitettu käyttö mahdollista.
    • Soveltuu tilanteisiin, jolloin käyttö on satunnaista ja käyttäjiä on vähän
    • Käyttö on mahdollista heti
    • Kustannustehokas
      • ei vaadi investointeja
    • Käyttäjätunnusten hallinnointi tapahtuu Verohallinnon Katso-palvelun käyttäjähallintamenetelmiä noudattaen
    • Vaatii aina vahvan tunnistautumisen KVP:n - usein käytettynä työlästä
    • Voidaan käyttää ristiin kohdan 2 ja 3 kanssa
  2. Selainkäyttö - organisaatiokohtainen tunnistatumisrajapinnan käyttöönotto
    • Tunnistautuminen
      • Tunnistautuminen KVP-käyttöliittymään tapahtuu integroitavan rajapinnan avulla. Käyttäjä saa toimivaltuutusroolin kirjautuessaan sisään järjestelmään rajapinnan avulla.
    • Soveltuu tilanteeseen, jolloin käyttö on säännöllistä ja käyttäjiä on paljon
    • Käyttöönotto vaatii tunnistautumisintegraation toteuttamisen
    • Kustannustehokas
      • Investoinnit kohtuullisen pieniä saavutettuun hyötyyn verrattuna
    • Mahdollistaa Single sign-on kertakirjautumisen organisaation työasemilta
    • Käyttäjähallinta tapahtuu organisaation oman käyttäjähallinnan avulla
    • Organisaatiolla on velvollisuus säilyttää käyttäjätietoja ks. käyttäjän vastuut käyttöönoton jälkeen
  3. Rajapintakäyttö - asiakirjojen luonnostelurajapintojen käyttöönotto
    • Soveltuu tilanteeseen, jossa halutaan mahdollistaa joustava ja tehokas toiminta KVP:ssa
    • Käyttöönotto vaatii tunnistautumis- sekä asiakirjarajapintojen toteuttamisen
    • Edellyttää investointeja organisaation sisäisiin järjestelmiin sekä rajapintojen implementointiin asiakirjojen vapaamman luonnostelun mahdollistamiseksi
      • Saavutetaan suurin hyöty mahdollistamalla asiakirjojen luonnostelu organisaation omassa järjestelmässä ilman asiakkaan antamaa valtuutusta
    • Mahdollistaa Single sign-on kertakirjautumisen organiaation työasemilta
    • Mahdollistaa asiakirjaluonnostelun asiakkaan ympäristössä ja luonnosten viennin KVP:uun
    • Käyttäjähallinta tapahtuu organisaation oman käyttäjähallinnan avulla
    • Organisaatiolla on velvollisuus säilyttää käyttäjätietoja ks. käyttäjän vastuut käyttöönoton jälkeen
    • Edellyttää myös tunnistautumisrajapinnan toteuttamisen

Vaihtoehdot eivät ole toisiaan poissulkevia.

Käyttöönoton aikataulu

Järjestelmä otettiin käyttöön 1.11.2013. Järjestelmän käytön voi aloittaa koska tahansa. Ole yhteydessä Maanmittauslaitokseen, jos suunnittelet rajapintakäytön aloittamista.

Käyttäjähallinta

Tunnistautumisrajapinnan intekrointi mahdollistaa organisaatiolle Single Sign-on kirjautumisen Kiinteistövaihdannan palveluun. Organisaatio määrittää oman käyttäjähallintansa kautta siitä, kenellä organisaatiossa on oikeus käyttää Kiinteistövaihdannan palvelua.

Tunnistautumisirajapinnan kautta tulevien käyttäjien toimivaltuudet määräytyvät yrityskohtaisesti. Yritykset jaetaan toimialansa ja käyttötarkoituksen perusteella kolmeen eri rooliryhmään. Rooliryhmät ovat rahoituslaitos, kiinteistön välittäjä, yrityksen kiinteistövastaava.

Oikeudet rahoituslaitoksien toimivaltuutetuille, jotka tunnistautuvat tunnistusrajapinnan avulla:

  • Voi toimia katselijana/asiamiehenä yrityksen edustajana
  • Valtuuden käyttää KVP:ssä organisaatiolle annettuja valtakirjoja
  • Luonnostella ja allekirjoittaa valtakirjan turvin valtuuttajan puolesta
  • Katsella organisaation nimissä olevia panttikirjoja (sähköinen tai kirjallinen)
  • Laatia ja hyväksyä organisaation nimissä oleville panttikirjoille siirtohakemuksia sekä tehdä niihin liittyviä sitoumuksia
Oikeudet kiinteistönvälittäjien toimivaltuutetuille, jotka tunnistautuvat tunnistusrajapinnan avulla:

  • Voi toimia katselijana/asiamiehenä yrityksen edustajana
  • Valtuuden käyttää KVP:ssä organisaatiolle annettuja valtakirjoja
  • Luonnostella valtakirjan turvin valtuuttajan puolesta
Oikeudet yrityksen kiinteistövastaaville, jotka tunnistautuvat tunnistusrajapinnan avulla:

  • Voi toimia katselijana/asiamiehenä yrityksen edustajana
  • Valtuuden käyttää KVP:ssä organisaatiolle annettuja valtakirjoja
  • Luonnostella valtakirjan turvin valtuuttajan puolesta
  • Näkee yrityksen omistamat kiinteistöt ja panttikirjat
  • Voi luonnostella yrityksen kiinteistöomaisuuteen kohdistuvia toimia (allekirjoitus tulee tehdä Suomi.f-tunnistautumisella)
Tunnistautumisrajapinnani kautta tulevat saman yrityksen käyttäjät toimivat kaikki samalla käyttäjäroolitasolla.

Koekäyttö

KVP:n koekäyttö edellyttää käyttönottavalta organisaatiolta koekäyttösopimuksen solmimista maanmittauslaitoksen kanssa. Sopimuksen solmimisen yhteydessä organisaatiolle toimitetaan tarvittavat tiedostot ja sertifikaatit koekäytön aloittamiseksi. Koekäyttö varten on olemassa erillinen ympäristö, jossa yritys voi testata järjestelmän toimintaa vapaasti. Integraatioiden rakentamista varten tarjotaan käyttöön myös kehitysympäristö.

Tuotantokäyttö

KVP:n tuotantokäyttö edellyttää käyttönottavalta organisaatiolta sopimuksen solmimista maanmittauslaitoksen kanssa. Sopimuksen solmimisen yhteydessä organisaatiolle toimitetaan tarvittavat sertifikaatit koekäytön aloittamiseksi.

Sopimuksen solmimiseen liittyviä asioita täydennetään myöhemmin.

Organisaation velvollisuudet

Luonnostelurajapintojen käyttöönoton yhteydessä organisaatio vastaa oman käyttäjähallinnan ja -tunnistautumisen turvallisuudesta ja luotettavuudesta sekä sitoutuu säilyttämään käyttäjätiedot viranomaisselvityksiä varten määräajan.

Mahdollisten väärinkäytösten selvittämiseksi organisaation on pystyttävä selvittämään organisaation työntekijän oikea henkilöllisyys määräajan puitteissa, jos viranomainen tietoa pyytää. Rajapintakäyttäjän identiteetti selvitetään tunnistuspolun avulla.

Tunnistuspolku
Kuva 2: Tunnistuspolku kuvaa käyttäjän identiteetin selvittämisen tarvittaessa

Muutoshistoria

Kuvaus Pvm
Poistettu ensimmäisen käyttöönoton aikataulun kuvaus tarpeettomana 18.3.2014
Tarkennettu kustannusosiota, lisätty linkki hinnastoon 7.4.2014
Lisätty kuva asiakirjan vaiheista sekä kuvaus yrityskohtaisesta käyttäjäroolituksesta. Lisäksi tehty muita pienempiä parannuksia. 4.6.2014
Päivitetty jatkokehitysaikataulua 2.7.2015
Päivitetty v3 muutokset 4.3.2016
Päivitetty v4 muutokset 9.3.2017
Päivitetty v5 muutokset 18.5.2017
Päivitetty v6 muutokset 31.10.2017