Tekninen kuvaus Huoneistotietojen tulostepalvelu

Yhteys palvelun ja asiakkaan välillä on SSL-suojattu (Secure Socket Layer, HTTPS-protokolla). Palveluun pitää kirjautua sisään antamalla käyttäjätunnus ja salasana. Käytössä on HTTP Basic Authentication -tunnistus, jonka on oltava mukana jokaisessa pyynnössä. Palvelu kerää hakuihin liittyviä tilasto- ja laskutustietoja palvelupyyntöjen perusteella käyttäjätunnuksittain jaoteltuna.

Tuloste pyydetään palvelusta HTTPS/GET-protokollaan perustuvalla kyselyllä. Kyselyyn sisältyvät parametrit, joiden mukaista tietoa haetaan. 

Loppukäyttäjien lokitus

Huoneistotietojen tulostepalvelun  palvelinjärjestelmässä tallennetaan lokeihin tietoa myös asiakassovelluksessa tunnistetusta loppukäyttäjästä, mikäli asiakassovellus välittää rajapintapalvelulle loppukäyttäjää identifioivan tunnisteen kunkin rajapintapyynnön yhteydessä. 

Teknisesti rajapintapalvelun kutsuissa tunniste tulee välittää HTTP-standardin mukaisena Request Header-kenttänä nimeltään "enduserid" ja jonka arvon tulee olla merkkijono (välilyönnit ei sallittuja, pituus max. 60 merkkiä).  Muutoin merkkijonon sisältö voi olla asiakassovelluksen määrittämä, mutta kuitenkin siten, että tarvittaessa tunnisteen perusteella on selvitettävissä loppukäyttäjä asiakassovelluksen ylläpitäjän toimesta.

Yleistä lisätietoa HTTP:n Request Header-kentistä: https://developer.mozilla.org/en-US/docs/Glossary/Request_header 

Lokitietojen siirron toimivuus on hyvä varmistaa ottamalla yhteyttä Maanmittauslaitokseen osoitteeseen verkkopalvelut@maanmittauslaitos.fi

Lisäksi lokitietoja tulee säilyttää kuuden vuoden ajan, jonka jälkeen ne tulee poistaa.

Osakehuoneistotuloste, laaja

Tuloste voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä. Tulosteella esitetään luonnollisista henkilöistä henkilötunnukset.

Tulosteen tarkemmat kuvaukset täällä 

Hakuparametrit

 Nimi ArvotLkmKuvaus
ytunnusy-tunnus1Yhtiön y-tunnus. Yhtiön pitää olla joko uusi (vuonna 2019 tai myöhemmin perustettu) yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään.
osakeryhmatunnusosakeryhmätunnus1Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva, syntyvä tai lakkaava.
langfi, sv-FI, sv0..1Parametrilla lang välitetään tieto, minkä kielinen tuloste halutaan hakea. Mahdollisia kielivaihtoehtoja ovat fi (suomi), sv-FI (ruotsi) ja sv (ruotsi). Parametri ei ole pakollinen. Jos parametria ei välitetä pyynnössä tai pyynnössä annettu parametri on muu kuin ohjeistettu suomen- tai ruotsinkielisen tulosteen parametri, palvelu palauttaa suomenkielisen tulosteen.

Esimerkit

https://htjws.nls.fi/htj/v1/tuloste/osakehuoneistotuloste/pdf?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052&lang=fi

 

Osakehuoneistotuloste, suppea 

Tuloste voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä. Tulosteella esitetään luonnollisista henkilöistä syntymäaika.

Tulosteen tarkemmat kuvaukset täällä

Hakuparametrit

 Nimi ArvotLkmKuvaus
ytunnusy-tunnus1Yhtiön y-tunnus. Yhtiön pitää olla joko uusi (vuonna 2019 tai myöhemmin perustettu) yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään.
osakeryhmatunnusosakeryhmätunnus1Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva, syntyvä tai lakkaava.
langfi, sv-FI, sv0..1Parametrilla lang välitetään tieto, minkä kielinen tuloste halutaan hakea. Mahdollisia kielivaihtoehtoja ovat fi (suomi), sv-FI (ruotsi) ja sv (ruotsi). Parametri ei ole pakollinen. Jos parametria ei välitetä pyynnössä tai pyynnössä annettu parametri on muu kuin ohjeistettu suomen- tai ruotsinkielisen tulosteen parametri, palvelu palauttaa suomenkielisen tulosteen.

Esimerkit

https://htjws.nls.fi/htj/v1/tuloste/osakehuoneistotuloste-suppea/pdf?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052&lang=fi

 

Osakeluettelo, julkinen

Tuloste voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä. Tulosteella esitetään yhtiön voimassa olevat, syntyvät ja lakkaavat osakeryhmät.

Hakuparametrit

 Nimi ArvotLkmKuvaus
ytunnusy-tunnus1Yhtiön y-tunnus. Yhtiön pitää olla joko uusi (vuonna 2019 tai myöhemmin perustettu) yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään.
langfi, sv-FI, sv0..1Parametrilla lang välitetään tieto, minkä kielinen tuloste halutaan hakea. Mahdollisia kielivaihtoehtoja ovat fi (suomi), sv-FI (ruotsi) ja sv (ruotsi). Parametri ei ole pakollinen. Jos parametria ei välitetä pyynnössä tai pyynnössä annettu parametri on muu kuin ohjeistettu suomen- tai ruotsinkielisen tulosteen parametri, palvelu palauttaa suomenkielisen tulosteen.

Esimerkit

https://htjws.nls.fi/htj/v1/tuloste/osakeluettelo-suppea/pdf?ytunnus=6583621-2&lang=fi

 

Ote osakeluettelosta, julkinen

Tuloste voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä. Tulosteella esitetään yhtiön yhden yksittäisen voimassa olevan, syntyvän tai lakkaavan osakeryhmän osakeluettelo tulostetta vastaavat tiedot:

  • Yhtiön tiedot
  • Osakeryhmän tiedot
  • Osakeryhmästä osakeluetteloon merkityt omistajat
  • Osakeryhmän osakeluettelossa esitettävät rajoitukset

Hakuparametrit

 Nimi ArvotLkmKuvaus
ytunnusy-tunnus1Yhtiön y-tunnus. Yhtiön pitää olla joko uusi (vuonna 2019 tai myöhemmin perustettu) yhtiö tai vanha yhtiö, joka on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään. Vain asunto-osakeyhtiöt ja keskinäiset kiinteistöosakeyhtiöt voivat kuulua huoneistotietojärjestelmään.
osakeryhmatunnusosakeryhmätunnus1Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva, syntyvä tai lakkaava.
langfi, sv-FI, sv0..1Parametrilla lang välitetään tieto, minkä kielinen tuloste halutaan hakea. Mahdollisia kielivaihtoehtoja ovat fi (suomi), sv-FI (ruotsi) ja sv (ruotsi). Parametri ei ole pakollinen. Jos parametria ei välitetä pyynnössä tai pyynnössä annettu parametri on muu kuin ohjeistettu suomen- tai ruotsinkielisen tulosteen parametri, palvelu palauttaa suomenkielisen tulosteen.

Esimerkit

https://htjws.nls.fi//htj/v1/tuloste/osakeluettelo-ote-suppea/pdf?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052&lang=fi

 

Sovellusversio 15.4.2025

Muutokset

Tulosteille on vaihdettu osakeryhmän voimaantulopvm sijaan osakeryhmän rekisteröintipvm. Rekisteröintipvm on se päivä, jolloin osakeryhmä on rekisteröity kaupparekisterissä. Rekisteröintipvm on tiedossa vain uusien yhtiöiden osakeryhmillä, jotka ovat perustettu 1.1.2019 tai sen jälkeen.

Vanhoilla yhtiöillä, jotka ovat perustettu ennen 1.1.2019 ei osakeryhmien rekisteröintipvm ole pääsääntöisesti tiedossa.

  • Suppea ja laaja osakeluettelo
  • Suppea ja laaja osakehuoneistotuloste
  • Ote osakeluettelosta

Sovellusversio 14.1.2025

Osakeryhmistä annettavaa tietopalvelua laajennettu: 

Tietopalvelua on laajennettu myös uusiin Kaupparekisterissä rekisteröityihin osakeryhmiin yhtiöissä, joissa on tehty yhtiöjärjestyksen muutos. Tällaisesta osakeryhmästä saa tietopalvelua heti sen rekisteröinnistä alkaen. 

Kaikista tuotteista voidaan pyytää tiedot huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta, syntyvästä ja lakkaavasta osakeryhmästä. 

Suunniteltu Sovellusversio 3.1.2024

  • Julkaistava tuote
    • Ote osakeluettelosta, julkinen

Sovellusversio 3.10.2023

  • Julkaistava tuote
    • Osakehuoneistotuloste, suppea

Sovellusversio 7.12.2021

  • Ruotsinkieliset tulosteet
    • Osakehuoneistotulosteen ja osakeluettelon saa ruotsinkielisenä hakuparametrilla lang=sv-FI tai lang=sv. Kaikilla muilla hakuparametrin arvoilla palvelu palauttaa suomenkielisen tulosteen.

Sovellusversio 25.5.2021

  • Kaupparekisterissä lakkaavien ja niiden sijaan syntyvien osakeryhmien käsittelyyn toteutetut muutokset
    • ks. tarkemmin Huoneistotietojen kyselypalvelu (REST)> Tekninen kuvaus> Versionhallinta
    • Osakehuoneistotulosteen saa voimassa olevasta ja lakkaavasta osakeryhmästä. Lakkaavalla osakeryhmällä esitetään varoitusteksti.
    • Osakeluettelossa esitetään yhtiön voimassa olevat ja lakkaavat osakeryhmät. Lakkaavilla osakeryhmillä esitetään varoitusteksti.
    • Yhtiöllä, jonka tietojen siirto kaupparekisteristä huoneistotietojärjestelmään ei ole ajantasalla, esitetään varoitusteksti.

Sovellusversio 16.3.2021

  • Osakehuoneistotuloste
    • osion "Hallinnoitavat tilat" otsikko tulostuu muodossa "Osakeryhmällä hallittavat tilat"

Sovellusversio 19.1.2021

  • Osakehuoneistotuloste
    • tulosteella on uusi osio "Hallinnoitavat tilat", jossa esitetään tiedot osakeryhmällä hallittavasta huoneistosta, autopaikasta ja muusta tilasta

Sovellusversio 1.10.2020

Julkaistut tuotteet:

  • Osakehuoneistotuloste, laaja
  • Osakeluettelo, julkinen

Palveluun kytkeytymiseen tai saatavuuteen sekä tietoliikenteeseen liittyvistä virhetilanteista palautetaan asiakassovellukselle virheilmoitus HTTP-virhekoodeina. Palvelu palauttaa seuraavia virhekoodeja:

VirhekoodiHTTP-tunnusSelitys
400Bad RequestHakupyyntö tai sen parametrit ovat virheellisiä.
401UnauthorizedPalvelu ei hyväksy asiakassovelluksen välittämää käyttäjätunnistetta.
404Not foundParametreilla ei löydy tietoa.
500Internal Server ErrorPyyntöä käsiteltäessä tapahtunut jokin odottamaton virhetilanne.

 

Aineisto

Koekäyttöympäristössä on vain pieni kuvitteellinen aineisto. Aineistossa on:

  • 6583621-2
    • vanha voimassa oleva asunto-osakeyhtiö
    • yhtiö on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään
    • yksi voimassa oleva osakeryhmä, jonka omistus perustuu edelleen osakekirjaan
    • kaikki kyselyt ja tulosteet palauttavat vastauksen
  • 4651585-1
    • vanha voimassa oleva asunto-osakeyhtiö
    • yhtiö on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään
    • kolme voimassa olevaa osakeryhmää, joilla kaikilla sähköinen omistuskirjaus
    • kaksi lakkaavaa osakeryhmää, joilla kaikilla sähköinen omistuskirjaus
    • kaikki kyselyt ja tulosteet palauttavat vastauksen
  • 8642123-5
    • vanha voimassa oleva keskinäinen kiinteistöosakeyhtiö
    • yhtiö on jo siirtänyt osakeluettelonsa huoneistotietojärjestelmään
    • kolme voimassa olevaa osakeryhmää, joilla kaikilla sähköinen omistuskirjaus
    • kaksi lakkaavaa osakeryhmää, joilla kaikilla sähköinen omistuskirjaus
    • yhtiön muutostietojen siirto kaupparekisteristä on estynyt ja yhtiön tiedot eivät ole ajantasaisia
    • kaikki kyselyt ja tulosteet palauttavat vastauksen
  • 8787078-8
    • vanha voimassa oleva asunto-osakeyhtiö
    • yhtiö ei ole vielä siirtänyt osakeluetteloaan huoneistotietojärjestelmään
    • ainoastaan yhtiöiden haku hakuehdoin palauttaa vastauksen
  • 6373566-1
    • lakannut asunto-osakeyhtiö
    • ainoastaan yhtiöiden haku hakuehdoin palauttaa vastauksen
  • 2513126-9
    • yhtiö on muuttanut yhtiömuotonsa asunto-osakeyhtiöstä tavalliseksi osakeyhtiöksi, eikä se siksi enää kuulu huoneistotietojärjestelmään
    • ainoastaan yhtiöiden haku hakuehdoin palauttaa vastauksen

Käyttöönotto

Verkkopalveluiden asiakastuesta voi pyytää sähköpostitse (verkkopalvelut(at)maanmittauslaitos.fi) oikeutta koekäyttöympäristöön. Viestistä tulisi käydä ilmi, minkälaista palvelua ollaan suunnittelemassa ja miten palvelusta saatuja tietoja on tarkoitus hyödyntää mahdollisessa tuotantokäytössä.

Tuotteet

Kaikki palvelun tuotteet ovat koekäytettävissä.

Tuotantopalvelussa olevasta tuotteen kyselyosoitteesta saa koekäyttöpalvelun osoitteen vaihtamalla osoitteen alkuun htjws.nls.fi -> htjwsint.nls.fi.

Esimerkiksi osakehuoneistotuloste, laaja:

https://htjwsint.nls.fi/htj/v1/tuloste/osakehuoneistotuloste/pdf?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052&lang=fi 

Muutokset

Koekäyttöympäristössä on saatavilla vain nykyinen versio eikä vanhoja versioita säilytetä.

Tulossa oleva suunniteltu koekäyttöympäristön päivitys marraskuu 2023. 

  • Julkaistava tuote
    • Ote osakeluettelosta

Osakehuoneistotuloste, suppea testattavissa 15.9.2023

  • Julkaistava tuote
    • Osakehuoneistotuloste, suppea

Viimeisin koekäyttöympäristön päivitys: 11.11.2021

  • Ruotsinkieliset tulosteet
    • Osakehuoneistotulosteen ja osakeluettelon saa ruotsinkielisenä hakuparametrilla lang=sv-FI tai lang=sv. Kaikilla muilla hakuparametrin arvoilla palvelu palauttaa suomenkielisen tulosteen.
Olet estänyt evästeet. Jos haluat antaa palautetta tästä sivusta, hyväksy kävijämittaus- ja analytiikkaevästeet.