Tekninen kuvaus Huoneistotietojen kyselypalvelu (REST)

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.

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

Loppukäyttäjien lokitus

Kiinteistötietojen 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

Aineistot ja tuotteet

Tuotteet

Yhtiöiden haku hakuehdoin
Osakeryhmien haku hakuehdoin
Yhtiön perustiedot
Osakeryhmän perustiedot
Osakeryhmän hallintakohteet
Osakeryhmän omistajat (Suppea ja laaja)
Osakeryhmän panttaukset (Suppea ja laaja)
Osakeryhmän rajoitukset (Suppea ja laaja)
Koodistot
Tiedotteet

Tuotteiden yhteiset

Skeemat
Koodistot (Päivitetty 23.5.2023)
Tietojen kuvaukset (Päivtetty 23.5.2023)

Kyselyt ja esimerkit

Yhtiöiden haku hakuehdoin

Rakenteessa esitetään yhtiöiden suppeat perustiedot.

Tällä kyselyllä saadaan tietää, onko yhtiö huoneistotietojärjestelmässä. Huoneistotietojärjestelmässä olevista yhtiöistä palautetaan vastauksessa tieto 'osakeluetteloOsakehuoneistorekisterissa' arvolla true. Vain huoneistotietojärjestelmässä olevista voimassa olevista yhtiöistä voidaan pyytää muita kyselyjä ja tulosteita.

Yhtiöistä, jotka on perustettu ennen 1.1.2019 ja jotka eivät vielä ole siirtäneet osakeluetteloaan huoneistotietojärjestelmään, kysely voi palauttaa vastauksena joko rakenteen, jossa osakeluetteloOsakehuoneistorekisterissa=false, tai virhekoodin 404 Not found.

Hakuparametrit

Nimi	Arvot	Lkm	Kuvaus
ytunnus	y-tunnus	1	Yhtiön y-tunnus.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/yhtiot/haku?ytunnus=6583621-2

Esimerkkivastaus

Osakeryhmien haku hakuehdoin

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä. Rakenteessa esitetään osakeryhmien suppeat perustiedot jokaisesta yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä.

Tällä kyselyllä saadaan tietää, perustuuko osakeryhmän omistus osakekirjaan vai huoneistotietojärjestelmään kirjattuun sähköiseen merkintään. Vastauksessa palautetaan tieto 'sahkoinenOmistusmerkinta' arvolla false, jos omistus perustuu edelleen osakekirjaan, ja arvolla true, jos omistus perustuu sähköiseen merkintään.

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.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/haku?ytunnus=6583621-2

Esimerkkivastaus

Yhtiön perustiedot

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevasta voimassa olevasta yhtiöstä. Rakenteessa esitetään tulosteiden osiossa "Yhtiö" esiintyvät tiedot.

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.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/yhtiot/perustiedot?ytunnus=6583621-2

Esimerkkivastaus

Osakeryhmän perustiedot

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä. Rakenteessa esitetään tulosteiden osiossa "Osakeryhmä" esiintyvät tiedot.

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.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/perustiedot?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052

Esimerkkivastaus voimassa oleva

Esimerkkivastaus lakkaava

Osakeryhmän hallintakohteet

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä. Rakenteessa esitetään osakehuoneistotulosteen osiossa "Osakeryhmällä hallittavat tilat" esiintyvät tiedot.

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.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/hallintakohteet?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052

Esimerkkivastaus voimassa oleva

Esimerkkivastaus lakkaava

Osakeryhmän omistajat

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä. Rakenteessa esitetään osakehuoneistotulosteen osiossa "Omistusoikeudet" esiintyvät tiedot. Osakehuoneistotulosteen kuvauksen löydät täältä

Kyselyssä palautetaan kaikki osakeryhmälle rekisteröidyt omistukset tilassa: vireillä, voimassa oleva, ehdollinen, ei lainvoimaisesti ratkaistut sekä tieto mahdollisesti vireillä olevasta omistuksen korjaamisesta.

Tuotteesta on saatavilla suppea ja laaja versio. Suppeassa palautetaaan henkilöstä nimi, syntymäaika ja mahdollinen kuolinpäivä. Laajassa palautetaan henkilöstä nimi, henkilötunnus ja mahdollinen kuolinpäivä

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.

Esimerkit

Suppea: https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/omistajat-suppea?ytunnus=4651585-1&osakeryhmatunnus=OHU34KRC6GTL5S12

Esimerkkivastaus hyväksytty omistuksen rekisteröinti

Laaja: https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/omistajat-laaja?ytunnus=4651585-1&osakeryhmatunnus=OHU34KRC6GTL5S12

Esimerkkivastaus hyväksytty omistuksen rekisteröinti

Esimerkkivastaus ehdollinen omistuksen rekisteröinti

Esimerkkivastaus hyväksytty omistuksen rekisteröinti saaja kuolinpesä

Esimerkkivastaus hyväksytty omistuksen rekisteröinti turvakielto

Esimerkkivastaus omistuksen rekisteröinti vireillä

Osakeryhmän panttaukset

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä. Rakenteessa esitetään osakehuoneistotulosteen osiossa "Panttioikeudet" esiintyvät tiedot. Osakehuoneistotulosteen kuvauksen löydät täältä

Kyselyssä palautetaan kaikki osakeryhmälle rekisteröidyt panttaukset tilassa: vireillä, voimassa oleva, jätetty lepäämään, ei lainvoimaisesti ratkaistut.

Kyselyssä palautetaan tiedot myös mahdollisista vireillä olevista panttauksen korjaamisista sekä muuttamis-ja poistamisasioista.

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.

Esimerkit

Suppea:https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/panttaukset-suppea?ytunnus=5063373-8&osakeryhmatunnus=OHXPPQMXD6U3P243

Esimerkkivastaus panttauksen rekisteröinti hyväksytty

Laaja: https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/panttaukset-laaja?ytunnus=5063373-8&osakeryhmatunnus=OHXPPQMXD6U3P243

Esimerkkivastaus panttauksen rekisteröinti hyväksytty

Esimerkkivastaus panttauksen rekisteröinti jätetty lepäämään ja uusi panttaus vireillä

Osakeryhmän rajoitukset

Tiedot voidaan pyytää huoneistotietojärjestelmässä olevan yhtiön voimassa olevasta ja lakkaavasta osakeryhmästä. Rakenteessa esitetään osakehuoneistotulosteen osioissa "Vallintarajoitukset" ja "Muut rajoitukset" esiintyvät tiedot. Osakehuoneistotulosteen kuvauksen löydät täältä

Kyselyssä palautetaan kaikki osakeryhmälle merkityt rajoitukset tilassa: vireillä, voimassa oleva, ei lainvoimaiset ratkaisut.

Kyselyssä palautetaan tiedot myös mahdollisista vireillä olevista rajoituksen korjaamisista ja poistamisasioista.

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.

Esimerkit

Suppea: https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/rajoitukset-suppea?ytunnus=6116537-8&osakeryhmatunnus=OHPS2FUFRXS48R7

Laaja: https://htjws.nls.fi/htj/v1/kysely/osakeryhmat/rajoitukset-laaja?ytunnus=6116537-8&osakeryhmatunnus=OHPS2FUFRXS48R7

Esimerkkivastaus osakeluettelon siirrossa ilmoitettu rajoitus

Esimerkkivastaus hakemuksesta merkitty rajoitus

Esimerkkivastaus rajoituksen merkitseminen vireillä

Koodistot

Rakenteessa esitetään koodistojen nimet ja koodiarvot.

Hakuparametrit

Ei hakuparametreja.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/koodistot

Esimerkkivastaus

Tiedotteet

Rakenteessa esitetään palvelun käyttöön liittyvät voimassa olevat tiedotteet, kuten tiedot tulossa olevista käyttökatkoista tai uusien käyttöehtojen julkaisemisesta.

Hakuparametrit

Ei hakuparametreja.

Esimerkit

https://htjws.nls.fi/htj/v1/kysely/tiedotteet

Esimerkkivastaus

Versiohallinta

Sovellusversio 9.5.2023

Muutokset

Osakeryhmän omistajat
- uusi kyselypalvelutuote joka sisältää osakehuoneistotulosteella osiossa 'Omistusoikeudet' esitettäviä tietoja. Tuotteesta tarjotaan suppea ja laaja versio. Suppeassa kyselyssä palautetaan henkilöiden syntymäaika ja laajassa kyselyssä palautetaan henkilöturvatunnus.
- Kyselyt ja esimerkit löytyvät täältä
Osakeryhmän panttaukset
- uusi kyselypalvelutuote joka sisältää osakehuoneistotulosteella osiossa 'Panttioikeudet' esitettäviä tietoja. Tuotteesta tarjotaan suppea ja laaja versio. Suppeassa kyselyssä palautetaan henkilöiden syntymäaika ja laajassa kyselyssä palautetaan henkilöturvatunnus.
- Kyselyt ja esimerkit löytyvät täältä
Osakeryhmän rajoitukset
- uusi kyselypalvelutuote joka sisältää osakehuoneistotulosteella osiossa 'Vallintarajoitukset' ja 'Muut rajoitukset' esitettäviä tietoja. Tuotteesta tarjotaan suppea ja laaja versio. Suppeassa kyselyssä palautetaan henkilöiden syntymäaika ja laajassa kyselyssä palautetaan henkilöturvatunnus.
- Kyselyt ja esimerkit löytyvät täältä
Koodistomuutos
- koodistoon lisätty uusi Osakeryhman_huomio -koodisto
  - Sisältää 6 eri koodiarvoa
    - "koodisto": "OSAKERYHMAN_HUOMIO",
      
              "koodi": "1",
      
              "seliteFi": "Turvakielto tai yhteystietojen luovutuskielto",
      
              "seliteSv": "Spärrmarkering el. förbud mot utlämning av kontaktuppgifter",
      
              "voimassaoloAlkaa": "01.01.2023"
    -         "koodisto": "OSAKERYHMAN_HUOMIO",
              "koodi": "2",
      
              "seliteFi": "Osakkeiden muoto on osakekirja",
      
              "seliteSv": "Aktierna är i form av aktiebrev",
      
              "voimassaoloAlkaa": "01.01.2023"
    -         "koodisto": "OSAKERYHMAN_HUOMIO",
              "koodi": "3",
      
              "seliteFi": "Yhtiöjärjestys on muuttunut. Tiedot eivät ole huoneistotietojärjestelmässä ajan tasalla.",
      
              "seliteSv": "Bolagsordningen har ändrats. Uppgifterna är inte uppdaterade i bostadsdatasystemet.",
      
              "voimassaoloAlkaa": "01.01.2023"
    -         "koodisto": "OSAKERYHMAN_HUOMIO",
              "koodi": "4",
      
              "seliteFi": "Rajoituksen korjaaminen, vireillä",
      
              "seliteSv": "Rättelse av begränsning, anhängig",
      
              "voimassaoloAlkaa": "01.01.2023"
    -         "koodisto": "OSAKERYHMAN_HUOMIO",
              "koodi": "5",
      
              "seliteFi": "Panttauksen korjaaminen, vireillä",
      
              "seliteSv": "Rättelse av pantsättning, anhängig",
      
              "voimassaoloAlkaa": "01.01.2023"
    -         "koodisto": "OSAKERYHMAN_HUOMIO",
              "koodi": "6",
      
              "seliteFi": "Omistuksen korjaaminen, vireillä",
      
              "seliteSv": "Rättelse av ägande, anhängig",
      
              "voimassaoloAlkaa": "01.01.2023"

Sovellusversio 25.5.2021

Muutokset

Kaupparekisterissä lakkaavien ja niiden sijaan syntyvien osakeryhmien käsittelyyn toteutetut muutokset
- Kaupparekisterissä tehdyssä yhtiöjärjestyksen muutoksessa lakanneet osakeryhmät säilyvät huoneistotietojärjestelmän tietopalvelussa niin kauan, kunnes kaikki lakkaavaan osakeryhmään liittyvät oikeudet on tarpeellisilta osin siirretty osakeryhmän sijaan tulleelle uudelle osakeryhmälle.
- Kaupparekisterissä tehdyssä yhtiöjärjestyksen muutoksessa syntyvät osakeryhmät eivät tule huoneistotietojärjestelmän tietopalveluun ennen kuin osakeryhmään liittyvän lakkaavan osakeryhmän oikeudet on siirretty syntyvälle osakeryhmälle.
- Huoneistotietojärjestelmässä otetaan käyttöön jokaiseen osakeryhmään liittyvä osakeryhmän tila, joka voi olla jokin seuraavista
  - voimassa oleva
  - lakkaava
    - kaupparekisterissä osakeryhmä voi olla jo lakannut, mutta huoneistotietojärjestelmässä sitä vielä esitetään siihen saakka, kunnes kaikki siihen liittyvät oikeudet on siirretty syntyvälle osakeryhmälle
  - syntyvä
    - kaupparekisterissä osakeryhmä voi olla jo syntynyt, mutta huoneistotietojärjestelmässä sitä ei vielä esitetä ennen kuin sille on siirretty kaikki tarpeelliset lakkaavan osakeryhmän oikeudet
    - syntyviä osakeryhmiä ei esitetä tietopalvelussa
  - lakannut
    - aikaisemmin voimassa ollut osakeryhmä mutta nyt jo sekä kaupparekisterissä että huoneistotietojärjestelmässä lakannut osakeryhmä
    - lakanneita osakeryhmiä ei esitetä tietopalvelussa
- Aikaisemmin ilmoitetut skeemamuutokset ks. 19.1.2021 ja 16.2.2021
- Uusi skeemamuutos
  - Osakeryhmän hallintakohteet
    - lisätty uusi elementti "lakkaamispvm"
- Muutokset kyselypalvelutuotteissa
  - Osakeryhmien haku hakuehdoin
    - "olotila"
      - ks. yllä osakeryhmän tila
  - Osakeryhmän perustiedot
    - "olotila"
      - ks. yllä osakeryhmän tila
    - "voimaantulopvmOsakehuoneistorekisterissa"
      - pvm, jolloin osakeryhmä on tullut huoneistotietojärjestelmän tietopalveluun
      - pvm on yleensä se pvm, jolloin uusi osakeryhmä on rekisteröity kaupparekisterissä
      - jos osakeryhmän tila on ensin ollut huoneistotietojärjestelmässä syntyvä ja siihen liittyvät oikeudet on siirretty vastaavalta lakkaavalta osakeryhmältä, pvm on myöhäisempi kuin kaupparekisteristä saatu rekisteröintipvm ja pvm kertoo, milloin osakeryhmän tila on muuttunut syntyvästä voimassa olevaksi
      - vanhojen yhtiöiden osakeryhmillä voimaantulovpm on osakeluettelon siirron hyväksymispvm
    - "lakkaamispvmOsakehuoneistorekisterissa"
      - pvm, jolloin osakeryhmä poistui huoneistotietojärjestelmän tietopalvelusta
      - toistaiseksi tietopalvelussa ei esitetä lakanneita osakeryhmiä, joten pvm:ää ei käytännössä esiinny tietopalvelussa
  - Osakeryhmän hallintakohteet
    - "lakkaamispvm"
      - hallintakohteet voivat olla lakanneita silloin, kun osakeryhmä ja siihen liittyvät hallintakohteet ovat jo lakanneet kaupparekisterissä tehdyssä yhtiöjärjestyksen muutoksessa
      - vain lakkaaviin osakeryhmiin liittyvät hallintakohteet voivat olla lakanneita
  - Yhtiöiden haku hakuehdoin
    - "ajantasainen"
      - yhtiön muutostietojen siirron ajantasaisuus esitetään vain silloin, kun tiedot eivät ole ajantasalla
      - yhtiön tiedot eivät ole ajantasaisia, jos
        yhtiön muutostietojen siirto kaupparekisteristä huoneistotietojärjestelmään on jostain teknisestä syystä estynyt
        
        kaupparekisterissä tapahtuneen sulautumisen tai jakautumisen tietojen siirto huoneistotietojärjestelmään on kesken
  - Yhtiön perustiedot
    - "ajantasainen"
      - yhtiön muutostietojen siirron ajantasaisuus esitetään vain silloin, kun tiedot eivät ole ajantasalla
      - yhtiön tiedot eivät ole ajantasaisia, jos
        yhtiön muutostietojen siirto kaupparekisteristä huoneistotietojärjestelmään on jostain teknisestä syystä estynyt
        
        kaupparekisterissä tapahtuneen sulautumisen tai jakautumisen tietojen siirto huoneistotietojärjestelmään on kesken

Kaikki skeemat zip-pakettina

Sovellusversio 16.2.2021

Muutokset

Osakeryhmän perustiedot
- päähallintakohteen käyttötarkoitus esitetään samalla tavalla kuin tuotteessa Osakeryhmän hallintakohteet
  - lisätty uusi yläelementti "paakayttotarkoitus"
  - käyttötarkoituksen 999=Muu yksikielinen seliteteksti tulostetaan elementtiin "selite"
Skeemamuutokset, jotka liittyvät myöhemmin keväällä käyttöönotettavaan muutokseen kaupparekisterissä lakkaavien osakeryhmien käsittelyssä
- Yhtiöiden haku hakuehdoin
  - lisätty uusi elementti "ajantasainen"
- Yhtiön perustiedot
  - lisätty uusi elementti "ajantasainen"

Kaikki skeemat zip-pakettina

Sovellusversio 19.1.2021

Muutokset

Kaikki skeemat
- Skeemoja muutetaan niiltä osin, missä skeemoissa estetään ylimääräisten kenttien käyttäminen sanomissa. Kyseinen rajoitus muutetaan, jotta tietopalvelujen kehittämistä voidaan tehdä ketterästi rikkomatta mahdollista skeemavalidointia jokaisen lisätyn kentän johdosta.
  - Skeemoissa on korvattu "additionalProperties": false -määre "additionalProperties": true -määreellä.
Skeemamuutokset, jotka liittyvät myöhemmin keväällä käyttöönotettavaan muutokseen kaupparekisterissä lakkaavien osakeryhmien käsittelyssä
- Osakeryhmien haku hakuehdoin
  - lisätty uusi elementti "olotila"
- Osakeryhmän perustiedot
  - lisätty uudet elementit "olotila", "voimaantulopvmOsakehuoneistorekisterissa", "lakkaamispvmOsakehuoneistorekisterissa"
Osakeryhmän hallintakohteet
- uusi kyselypalvelutuote, joka sisältää osakehuoneistotulosteen uutta tuloste-osiota vastaavat tiedot osakeryhmällä hallittavasta huoneistosta, autopaikasta ja muusta tilasta

Kaikki skeemat zip-pakettina

Sovellusversio 8.12.2020

Muutokset

Kaikki skeemat
- Skeemoista on korvattu KoodiArvoDto-objekti uudella extKoodiArvoDto-objektilla. Näiden objektien erona on koodisto-arvojen listauksen (enum) vaihtuminen pelkäksi merkkijonoksi. Muutos on tehty, jotta koodistoja voidaan lisätä HTJ taustajärjestelmiin ilman, että skeemasta tarvitsee aina tehdä uutta versiota.

Kaikki skeemat zip-pakettina

Sovellusversio 10.11.2020

Muutokset

Koodistot
- lisätty tulosrakenteeseen uudet tiedot sisaltoseliteFi, sisaltoseliteSv, lainkohtaFi ja lainkohtaSv

Kaikki skeemat zip-pakettina

Sovellusversio 1.10.2020

Kaikki skeemat zip-pakettina

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
1815350-7
- vanha voimassa oleva asunto-osakeyhtiö
- yhtiö on siirtänyt osakeluettelonsa huoneistotietojärjestelmään
- yhtiöllä on osakeryhmiä, joilla kaikilla omistus perustuu edelleen osakekirjaan
- kaikki kyselyt ja tulosteet palauttavat vastaukset

0498222-4
- Yhtiö on siirtänyt osakeluettelonsa huoneistotietojärjestelmään
- Kaikki kyselyt ja tulosteet palauttavat vastaukset

Testiaineiston kuvaus (excel) (Excel tiedoston saa avattua valitsemalla linkin päällä "Avaa linkki uudessa ikkunassa" ja tämän jälkeen viemällä hiiren osoittimen osoiterivin loppun ja painamalla enter)

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 osakeryhmän perustiedot:

https://htjwsint.nls.fi/htj/v1/kysely/osakeryhmat/perustiedot?ytunnus=6583621-2&osakeryhmatunnus=OHH88072226R4052

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: x.x.xxxx

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

Uudet kyselyrajapinnat Osakeryhmän omistajat suppea ja Osakeryhmän omistajat laaja. Kts kuvaukset täältä

Aikaisemmat koekäyttöympäristön päivitykset:

21.3.2023

Koodistoon lisätty uusi Osakeryhmän huomiot -koodisto
- Sisältää 6 eri koodiarvoa (Koodiston kuvaukset luettavissa "Aineistot ja tuotteet" - osiosta.)

Uudet kyselyrajapinnat Osakeryhmän rajoitukset suppea ja Osakeryhmän rajoitukset laaja. Kts. kuvaukset täältä
- Skeemat lisätään toukokuu 2023 loppuun mennessä "Aineistot ja tuotteet" -osioon

Uudet kyselyrajapinnat Osakeryhmän panttaukset suppea ja Osakeryhmän panttaukset laaja. Kts. kuvaukset täältä
- Skeemat lisätään toukokuu 2023 loppuun mennessä "Aineistot ja tuotteet" -osioon

1.2.2021

Kaupparekisterissä lakkaavien ja niiden sijaan syntyvien osakeryhmien käsittelyyn toteutetut muutokset
- Kaupparekisterissä tehdyssä yhtiöjärjestyksen muutoksessa lakanneet osakeryhmät säilyvät huoneistotietojärjestelmän tietopalvelussa niin kauan, kunnes kaikki lakkaavaan osakeryhmään liittyvät oikeudet on tarpeellisilta osin siirretty osakeryhmän sijaan tulleelle uudelle osakeryhmälle.
- Kaupparekisterissä tehdyssä yhtiöjärjestyksen muutoksessa syntyvät osakeryhmät eivät tule huoneistotietojärjestelmän tietopalveluun ennen kuin osakeryhmään liittyvän lakkaavan osakeryhmän oikeudet on siirretty syntyvälle osakeryhmälle.
- Huoneistotietojärjestelmässä otetaan käyttöön jokaiseen osakeryhmään liittyvä osakeryhmän tila, joka voi olla jokin seuraavista
  - voimassa oleva
  - lakkaava
    - kaupparekisterissä osakeryhmä voi olla jo lakannut, mutta huoneistotietojärjestelmässä sitä vielä esitetään siihen saakka, kunnes kaikki siihen liittyvät oikeudet on siirretty syntyvälle osakeryhmälle
  - syntyvä
    - kaupparekisterissä osakeryhmä voi olla jo syntynyt, mutta huoneistotietojärjestelmässä sitä ei vielä esitetä ennen kuin sille on siirretty kaikki tarpeelliset lakkaavan osakeryhmän oikeudet
    - syntyviä osakeryhmiä ei esitetä tietopalvelussa
  - lakannut
    - aikaisemmin voimassa ollut osakeryhmä mutta nyt jo sekä kaupparekisterissä että huoneistotietojärjestelmässä lakannut osakeryhmä
    - lakanneita osakeryhmiä ei esitetä tietopalvelussa
- Aikaisemmin ilmoitetut skeemamuutokset ks. 4.1.2021 ja 1.2.2021
- Uusi skeemamuutos
  - Osakeryhmän hallintakohteet
    - lisätty uusi elementti "lakkaamispvm"
- Muutokset kyselypalvelutuotteissa
  - Osakeryhmien haku hakuehdoin
    - "olotila"
      - ks. yllä osakeryhmän tila
  - Osakeryhmän perustiedot
    - "olotila"
      - ks. yllä osakeryhmän tila
    - "voimaantulopvmOsakehuoneistorekisterissa"
      - pvm, jolloin osakeryhmä on tullut huoneistotietojärjestelmän tietopalveluun
      - pvm on yleensä se pvm, jolloin uusi osakeryhmä on rekisteröity kaupparekisterissä
      - jos osakeryhmän tila on ensin ollut huoneistotietojärjestelmässä syntyvä ja siihen liittyvät oikeudet on siirretty vastaavalta lakkaavalta osakeryhmältä, pvm on myöhäisempi kuin kaupparekisteristä saatu rekisteröintipvm ja pvm kertoo, milloin osakeryhmän tila on muuttunut syntyvästä voimassa olevaksi
      - vanhojen yhtiöiden osakeryhmillä voimaantulovpm on osakeluettelon siirron hyväksymispvm
    - "lakkaamispvmOsakehuoneistorekisterissa"
      - pvm, jolloin osakeryhmä poistui huoneistotietojärjestelmän tietopalvelusta
      - toistaiseksi tietopalvelussa ei esitetä lakanneita osakeryhmiä, joten pvm:ää ei käytännössä esiinny tietopalvelussa
  - Osakeryhmän hallintakohteet
    - "lakkaamispvm"
      - hallintakohteet voivat olla lakanneita silloin, kun osakeryhmä ja siihen liittyvät hallintakohteet ovat jo lakanneet kaupparekisterissä tehdyssä yhtiöjärjestyksen muutoksessa
      - vain lakkaaviin osakeryhmiin liittyvät hallintakohteet voivat olla lakanneita
  - Yhtiöiden haku hakuehdoin
    - "ajantasainen"
      - yhtiön muutostietojen siirron ajantasaisuus esitetään vain silloin, kun tiedot eivät ole ajantasalla
      - yhtiön tiedot eivät ole ajantasaisia, jos
        yhtiön muutostietojen siirto kaupparekisteristä huoneistotietojärjestelmään on jostain teknisestä syystä estynyt
        
        kaupparekisterissä tapahtuneen sulautumisen tai jakautumisen tietojen siirto huoneistotietojärjestelmään on kesken
  - Yhtiön perustiedot
    - "ajantasainen"
      - yhtiön muutostietojen siirron ajantasaisuus esitetään vain silloin, kun tiedot eivät ole ajantasalla
      - yhtiön tiedot eivät ole ajantasaisia, jos
        yhtiön muutostietojen siirto kaupparekisteristä huoneistotietojärjestelmään on jostain teknisestä syystä estynyt
        
        kaupparekisterissä tapahtuneen sulautumisen tai jakautumisen tietojen siirto huoneistotietojärjestelmään on kesken

1.2.2021

Osakeryhmän perustiedot
- päähallintakohteen käyttötarkoitus esitetään samalla tavalla kuin tuotteessa Osakeryhmän hallintakohteet
  - lisätty uusi yläelementti "paakayttotarkoitus"
  - käyttötarkoituksen 999=Muu yksikielinen seliteteksti tulostetaan elementtiin "selite"
Skeemamuutokset, jotka liittyvät myöhemmin keväällä käyttöönotettavaan muutokseen kaupparekisterissä lakkaavien osakeryhmien käsittelyssä
- Yhtiöiden haku hakuehdoin
  - skeemaan on lisätty uusi elementti
    - ajantasainen
- Yhtiön perustiedot
  - skeemaan on lisätty uusi elementti
    - ajantasainen

4.1.2021

Kaikki skeemat
- Skeemoja muutetaan niiltä osin, missä skeemoissa estetään ylimääräisten kenttien käyttäminen sanomissa. Kyseinen rajoitus muutetaan, jotta tietopalvelujen kehittämistä voidaan tehdä ketterästi rikkomatta mahdollista skeemavalidointia jokaisen lisätyn kentän johdosta.
  - Skeemoissa on korvattu "additionalProperties": false -määre "additionalProperties": true -määreellä.
Skeemamuutokset, jotka liittyvät myöhemmin keväällä käyttöönotettavaan muutokseen kaupparekisterissä lakkaavien osakeryhmien käsittelyssä
- Osakeryhmien haku hakuehdoin
  - lisätty uusi elementti "olotila"
- Osakeryhmän perustiedot
  - lisätty uudet elementit "olotila", "voimaantulopvmOsakehuoneistorekisterissa", "lakkaamispvmOsakehuoneistorekisterissa"
Osakeryhmän hallintakohteet
- uusi kyselypalvelutuote, joka sisältää osakehuoneistotulosteen uutta tuloste-osiota vastaavat tiedot osakeryhmällä hallittavasta huoneistosta, autopaikasta ja muusta tilasta

23.11.2020

Kaikki skeemat
- Skeemoista on korvattu KoodiArvoDto-objekti uudella extKoodiArvoDto-objektilla. Näiden objektien erona on koodisto-arvojen listauksen (enum) vaihtuminen pelkäksi merkkijonoksi. Muutos on tehty, jotta koodistoja voidaan lisätä HTJ taustajärjestelmiin ilman, että skeemasta tarvitsee aina tehdä uutta versiota.

26.10.2020

Koodistot
- lisätty tulosrakenteeseen uudet tiedot sisaltoseliteFi, sisaltoseliteSv, lainkohtaFi ja lainkohtaSv

14.9.2020

Yhtiöiden haku hakuehdoin ja Osakeryhmien haku hakuehdoin
- kyselyosoitteeseen lisätty "/haku", esimerkiksi https://htjws.nls.fi/htj/v1/kysely/yhtiot -> https://htjws.nls.fi/htj/v1/kysely/yhtiot/haku

3.9.2020

Tiedotteet
- uusi tuote, joka palauttaa tietoja palvelun käytöstä, mm. tiedot tulossa olevista käyttökatkoista sekä uusien käyttöehtojen julkaisemisesta

3.8.2020

Osakeryhmän perustiedot
- palauttaa huoneiston ja muun tilan ensisijaisen käyttötarkoituksen
- palauttaa osakesarjalla mahdollisesti olevan tarkenteen

27.5.2020

Osakeryhmän perustiedot
- hallintakohdetyyppi esitetään koodistona
- muutos katunimien esittämiseen eri kielillä
Koodistot
- palauttaa hallintakohdetyypin koodiarvot selitteineen

7.5.2020

Koekäyttöympäristö julkaistu