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.
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.
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
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
Versiohallinta
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 koekäyttöympäristön päivitys: xx.xx.xxxx
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.