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.
Kyselyt ja esimerkit
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.
Tulosteen tarkemmat kuvaukset täällä
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
Tuloste voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä. Tulosteella esitetään luonnollisista henkilöistä syntymäaika.
Tulosteen tarkemmat kuvaukset täällä
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
Ote osakeluettelosta, julkinen
Tuloste voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä. Tulosteella esitetään yhtiön yhden yksittäisen voimassa olevan 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 | 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/osakeluettelo-ote-suppea/pdf?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052&lang=fi
Versiohallinta
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
Virheiden hallinta
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. |
Koekäyttöympäristö
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.