Rekisteripalvelun Rest-rajapintojen käyttö

Tunnuslukujen haku Rest-rajapintojen kautta tapahtuu kaksivaiheisesti. Ensiksi haetaan kaikki palvelusta löytyvät aineistotiedot. Tulosjoukko on valinnan mukaan joko json- tai xml-muotoinen. Tulosjoukon tunnistetiedoilla (ytunnus, raportointikokonaisuus jne) valitaan haluttu aineisto ja tulosjoukkoon valmiiksi koostetulla Url-osoitteella saadaan kyseiseen aineistoon liittyvät tunnusluvut. Valmiissa tunnuslukujen hakuosoitteissa käytetään samaa siirtomuotoa, jolla haettiin kaikki aineistotkin eli jos kaikki aineistot on pyydetty xml-formaatissa niin ko aineistolistauksessa olevat Url-osoitteet on myös parametroitu xml-pohjaisia tunnuslukulistauksia varten. Tunnusluvut hakeva Url-osoite on helppo muodostaa koneellisestikin. Näin joudutaan toimimaan jos valmiin tunnuslukuhaun oletusarvoja (kuten tarkistustapausten kielisyyttä) halutaan muuttaa.

Aineistohaun tuloksissa on seuraavat tiedot:

  • Y-tunnus
  • Raportointikokonaisuus
  • Raportointikausi
  • Hyväksyntävaihe
  • Hyväksymisaika
  • Url-osoite tunnuslukuja varten

Tunnuslukuhaun tuloksissa on seuraavat tiedot:

  • Y-tunnus
  • Raportointikokonaisuus
  • Osakokonaisuus
  • Raportointikausi
  • Hyväksyntävaihe
  • Hyväksymisaika (hyvaksyntapvm)
  • Taksonomia
  • Tunnusluku (taksonomian mukainen numerokoodi)
  • Tunnusluvun arvo
  • Tarkastushavainnon ilmoitus
  • Tarkastushavainnon tarkennus
  • Tarkastushavainnon vakavuus
  • Kieli

Rajapinnan nykyisessä versiossa on tuettuna hyväksymisvaiheet ja rajapinnan kieliversiot. Alla kuvattuna molempien rajapintahakujen osoitemuodot.

Huom! Poikkeama korkokulujen summauksen tileillä 6200-6299 kaudella 2022C03

Kauden 2022C03 KKNR taksonomian summahierarkiassa on virhe korkokulujen summauksessa. Summahierarkia jättää tilin 6255 Korkokulut lainoista ulkopuolisilta summaamatta korkokuluihin (6200-6299 Korkokulut). Poikkeamasta tarkemmin.

Tämä virhe vaikuttaa myös tilikauden ylijäämä (alijäämä) summaukseen.

Aineistotietojen haku (ei TOLT)

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/aineistot

Osoitemuoto englanniksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/collection

Osoitemuoto ruotsiksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/samling

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml, xbrl tai ixbrl
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/aineistot

TOTL-aineistotietojen haku

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/tolt-aineistot

Osoitemuoto englanniksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/tolt-collection

Osoitemuoto ruotsiksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/tolt-samling

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml tai xbrl
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/tolt-aineistot

Tiettyyn aineistoon kuuluvien tunnuslukujen haku

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/dokumentti/<hyväksyntävaihe suomeksi>/<raportointikokonaisuus>/<ytunnus>/<kausi>

Osoitemuoto ruotsiksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/dokument/<hyväksyntävaihe ruotsiksi>/<raportointikokonaisuus>/<ytunnus>/<kausi>

Osoitemuoto englanniksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/document/<hyväksyntävaihe englanniksi>/<raportointikokonaisuus>/<ytunnus>/<kausi>

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml
  • Hyväksyntävaihe (fi): alustava, hyvaksytty, lopullinen, jalkikorjattu
  • Hyväksyntävaihe (sv): preliminar, godkant, slutlig, efterreviderat
  • Hyväksyntävaihe (en): initial, approved, final, afterwards_revised
  • Raportointikokonaisuus: ktas, kknr jne (ei tolt)
  • Ytunnus on kunnan ytunnus. Esimerkiksi 000162-0
  • Kausi: esim. 2019
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/dokumentti/alustava/9000162-0/2016

Aikaisemmin Url-poluissa oli mukana kielikoodi, mutta nykyisessä rajapinnassa kieli määräytyy automaattisesti Url-kutsujen mukaan (avainsanoina: aineistot, collection, samling, dokumentti, document, dokument).

Tietyn TOLT-aineiston haku

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/tolt-dokumentti/<hyväksyntävaihe suomeksi>/<ytunnus>/<kausi>

Osoitemuoto ruotsiksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/tolt-dokument/<hyväksyntävaihe ruotsiksi>/<ytunnus>/<kausi>

Osoitemuoto englanniksi: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/tolt-document/<hyväksyntävaihe englanniksi>/<ytunnus>/<kausi>

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml
  • Hyväksyntävaihe (fi): alustava, hyvaksytty, lopullinen, jalkikorjattu
  • Hyväksyntävaihe (sv): preliminar, godkant, slutlig, efterreviderat
  • Hyväksyntävaihe (en): initial, approved, final, afterwards_revised
  • Ytunnus on kunnan ytunnus. Esimerkiksi 000162-0
  • Kausi: esim. 2019
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/tolt-dokumentti/alustava/9000162-0/2016

Suoriteperusteinen kuntien ja kuntayhtymien neljännesvuosiraportointi

Tilastokeskusta varten kerätään myös ns. suoriteperusteiset kuntien ja kuntayhtyminen neljännesvuosiraportointiin käytettävät tunnusluvut. Näitä lukuja ei pidä sekoittaa yllä kuvatun dokumentti-rajapinnan kautta saataviin kuntien ja kuntayhtymien neljännesvuosiraportoinnissa käytettäviin lukuihin (kknr). Suoriteperusteisia "korjauslukuja" on paljon vähemmän kuin varsinaisia kknr-lukuja, joten rajapinnasta saadaan kerralla kaikki tietokannan suoriteperusteiset tunnusluvut. Rajapinta on suomenkielinen

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/<versio>/<formaatti>/suoriteperusteiset-tunnusluvut

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/rest/v1/json/suoriteperusteiset-tunnusluvut

Suojattujen aineistotietojen haku

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/<versio>/<formaatti>/aineistot?key=api_avain_merkkijono_tähän

Osoitemuoto englanniksi: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/<versio>/<formaatti>/collection?key=api_avain_merkkijono_tähän

Osoitemuoto ruotsiksi: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/<versio>/<formaatti>/samling?key=api_avain_merkkijono_tähän

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml, xbrl tai ixbrl
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/v1/json/aineistot?key=xyzrthjk....

Kaikki suojattujen aineistojen rajapinnat ovat IP-rajattuja ja vaativat ns. api avaimen. Avaimet ovat organisaatio- ja raportointikokonaisuuskohtaisia (esim. TOTT ja KKTPP). Pääsyä suojattuihin rajapintoihin haetaan Valtiokonttorista ottamalla yhteyttä osoitteeseen kuntadata@valtiokonttori.fi. Oikeudet ovat voimassa vain määräajan ja voimassaoloajan jälkeen tulee hakea uudet pääsyoikeudet.

Organisaatioilla voi olla useita api avaimia. Kullakin api avaimella on pääsyoikeus vain tiettyyn raportointikokonaisuuteen. Aineistohaku suodattaa näyttämänsä aineiston avainten oikeuksien perusteella.

Suojattujen aineistohakujen tuloksissa on mukana valmis Url-osoite, mutta näistä osoitteista puuttuu api avainten osuus. Käyttäjien pitää lisätä api avain annettujen Url-osoitteiden loppuun joko manuaalisesti tai ohjelmallisesti, jotta annettu haku toimisi.

Suojattujen tunnuslukujen haku

Osoitemuoto: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/<versio>/<formaatti>/dokumentti/<hyväksyntävaihe suomeksi>/<raportointikokonaisuus>/<ytunnus>/<kausi>?key=api_avain_merkkijono_tähän

Osoitemuoto ruotsiksi: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/<versio>/<formaatti>/dokument/<hyväksyntävaihe ruotsiksi>/<raportointikokonaisuus>/<ytunnus>/<kausi>?key=api_avain_merkkijono_tähän

Osoitemuoto englanniksi: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/<versio>/<formaatti>/document/<hyväksyntävaihe englanniksi>/<raportointikokonaisuus>/<ytunnus>/<kausi>?key=api_avain_merkkijono_tähän

Kulmasulkeilla on vain merkitty osoitemuodon parametriosat. Kyseisiä merkkejä ei tule käyttää todellisissa osoitteissa.

  • Versio: v1
  • Formaatti: json, xml
  • Hyväksyntävaihe (fi): alustava, hyvaksytty, lopullinen, jalkikorjattu
  • Hyväksyntävaihe (sv): preliminar, godkant, slutlig, efterreviderat
  • Hyväksyntävaihe (en): initial, approved, final, afterwards_revised
  • Raportointikokonaisuus: ktas, kknr jne (ei tolt)
  • Ytunnus on kunnan ytunnus. Esimerkiksi 000162-0
  • Kausi: esim. 2019
  • Esimerkki: https://prodkuntarest.westeurope.cloudapp.azure.com/srest/v1/json/dokumentti/alustava/9000162-0/2016?key=xyzrthjk....

Hakutuloksiin on json- ja xml-muodoissa liitetty haun statustietoja esimerkiksi tunnistautumisvirheiden selvittämiseksi. Xbrl- ja ixbrl-sisällöt taas on tuotettu valmiiksi etukäteen ja näitä formaatteja ei voi paketoida samalla tavalla kuin edellä mainittuja formaatteja ilman että sisältöformaatti rikkoutuisi, mutta näissäkkin tapauksissa annetaan erillisiä xml-muotoisia virheilmoituksia tunnistautumisongelmiin liittyen. Luotettavimmin virhetilanteet on ohjelmallisesti tunnistettavissa http-protokollan statuskoodeilla.