Hyppää pääsisältöön

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. 

Osakehuoneistotuloste, laaja

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

Hakuparametrit

 Nimi 

 Arvot

Lkm

 Kuvaus

ytunnus

y-tunnus

1

Yhtiö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.

osakeryhmatunnus

osakeryhmätunnus

1

Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava.

lang

fi, sv-FI, sv

0..1

Parametrilla 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 (Ei vielä tuotannossa)

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

Hakuparametrit

 Nimi 

 Arvot

Lkm

 Kuvaus

ytunnus

y-tunnus

1

Yhtiö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.

osakeryhmatunnus

osakeryhmätunnus

1

Osakeryhmän osakeryhmätunnus. Osakeryhmän pitää olla voimassa oleva tai lakkaava.

lang

fi, sv-FI, sv

0..1

Parametrilla 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 ja lakkaavat osakeryhmät.

Hakuparametrit

 Nimi 

 Arvot

Lkm

 Kuvaus

ytunnus

y-tunnus

1

Yhtiö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.

lang

fi, sv-FI, sv

0..1

Parametrilla 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

 

Suunniteltu 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:

Virhekoodi HTTP-tunnus Selitys
400 Bad Request Hakupyyntö tai sen parametrit ovat virheellisiä.
401 Unauthorized Palvelu ei hyväksy asiakassovelluksen välittämää käyttäjätunnistetta.
404 Not found Parametreilla ei löydy tietoa.
500 Internal Server Error Pyyntöä 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 syyskuussa 2023. 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.