Skip to content

Ulkoinen energiatodistusrajapinta

Jump to bottom
Juho Leinonen edited this page Jan 3, 2024 · 49 revisions

Johdanto

Energiatodistusrekisterissä on laskentaohjelmistoja varten ulkoinen rajapinta, josta voi lähettää uuden energiatodistuksen (luonnos) järjestelmään.

Rajapinnan testaus ja kokeilu pitää ensisijaisesti tehdä testiympäristössä: https://private.testi.energiatodistusrekisteri.fi/. Laskentaohjelmiston valmistaja voi pyytää ARA:lta (sähköposti: energiatodistus@ara.fi) yleisen testitunnuksen testiympäristöön.

Rajapinta

Rajapinta on versiokohtainen ja löytyy poluista:

  • /api/external/energiatodistukset/2013
  • /api/external/energiatodistukset/2018

Rajapinta on käytettävissä ympäristöissä:

Energiatodistus lähetetään palveluun https/post-pyyntönä, jossa energiatodistuksen tiedot on json-muodossa (utf-8):

POST /api/external/energiatodistukset/2018 HTTP/1.1
Authorization: Basic bGFhdGlqYUBzb2xpdGEuZmk6YXNkZmFzZGY=
Content-Type: application/json
{ ... }

Käyttäjätunnistus perustuu http/basic-menetelmään. Käyttäjätunnus on laatijan sähköpostiosoite ja salasana laatijan määrittämä tiedonsiirron salasana. Nämä tiedot löytyvät laatijan omista tiedoista.

Jokaisella energiatodistusversiolla on oma json-muotoinen tietosisältö, jonka skeemat löytyvät:

Skeeman rakenne

Skeema on kehitetty pelkästään tämän rajapinnan dokumentointiin. Skeema määrittää suoraan energiatodistuksen json-muotoisen aineiston rakenteen: jos attribuutin arvo on objekti tai vektori niin se on skeemassa objekti tai vektori. Jos taas arvo on perustietotyyppi niin se on määritetty muodossa:

"Tyyppi [Tarkenne] [?]" esim. "String [1, 6300]?"

Tyyppi määrittää json-perustietotyypin:

  • Integer: kokonaisluku esim. 1
  • Number: desimaaliluku esim. 1.1
  • String: merkkijono esim. "test"
  • Boolean: true/false esim. true

Tarkenteella rajoitetaan edelleen mahdollista sisältöä

  • String [min, max] - Merkkijono, jonka pituus on välillä min, max
  • Number [min, max] - Desimaaliluku, jonka arvo on välillä min, max (max = 9999999999)
    • ⚠️ Skeemassa olevien staattisten raja-arvojen lisäksi numeroarvoon voi liittyä dynaamiset virhe- ja varoitusraja-arvot
  • Integer EntityId - Numeromuotoinen viite johonkin toiseen käsitteeseen esim. Integer YritysId
  • String LocalDate - ISO 8601 päivämäärä - YYYY-MM-DD
  • Int Year - vuosiluku 0 - 9999
  • String Rakennustunnus - rakennustunnus ks. funktio: valid-rakennustunnus?

Lopussa oleva kysymysmerkki tarkoittaa että arvo voi olla tyhjä (null) tai attribuutin voi jättää kokonaan pois. Jos lopussa ei ole kysymysmerkkiä, niin arvo on pakollinen.

Luokittelut

Energiatodistuksen tiedoissa on viitteitä luokittelutietoon. Viitteenä käytetään numeromuotoista tunnistetta. Tiedon tyyppi on muotoa: Integer *Id. Näiden luokittelujen kuvaukset ja tunnisteiden merkitys on saatavilla julkisesta rajapinnasta:

Käyttötarkoitus

Käyttötarkoituksen kuvaamiseen on kaksitasoinen versiokohtainen luokittelu:

  1. Käyttötarkoitusluokat:
  1. Alakäyttötarkoitusluokat:

Energiatodistuksen käyttötarkoitus kuvataan määrittämällä mihin alakäyttötarkoitukseen energiatodistus kuuluu:

{ perustiedot: { kayttotarkoitus: String AlakayttotarkoitusluokkaId }}

Viitteet muuhun tietoon

Energiatodistuksen tiedoissa on viitteitä muuhun rekisterissä olevaan tietoon:

  • Integer YritysId - laskutettavan yrityksen tunnus
  • Integer LaskutusosoiteId - laskutusosoitteen tunnus, joka on joko laskutettavan yrityksen tunnus tai -1 joka tarkoittaa henkilökohtaista laskutusta.
  • Integer EnergiatodistusId - korvattavan energiatodistuksen tunnus
  • String Postinumero - postinumero merkkijono (5-merkkiä sisältää etunollat), joka viittaa järjestelmässä oleviin postinumeroihin

Palvelun vastaus

Jos energiatodistuksen luonti onnistuu niin järjestelmä vastaa:

HTTP/1.1 201 Created
Location: /api/external/energiatodistukset/2018/id
{"id":id,"warnings":[]}

jossa id on uuden energiatodistus-luonnoksen tunnus. Onnistunut luonti voi sisältää varoituksia jos joidenkin lukuarvojen varoituksen raja-arvot on ylittynyt. Esimerkki vastauksesta jossa on varoitus:

{"id":11,"warnings":[{"property":"lahtotiedot.ilmanvaihto.paaiv.sfp","value":5,"min":0,"max":2.5}]}

Varoituksia voi olla listassa n kpl.

Varoitus

Varoituksen tiedot:

  • property: polku ko. tietoon energiatodistusaineistossa
  • value: annettu virheellinen arvo
  • min, max: sallitut arvot on välillä min - max

Virheet

Virhetilanteessa 4xx tai 5xx energiatodistusta ei tallenneta. Vastauksen status 4xx tarkoittaa että pyynnön sisällössä on jotakin väärin. Status 5xx tarkoittaa taas jotakin odottamatonta virhetilannetta itse palvelussa.

Tunnistautuminen epäonnistui 401

HTTP/1.1 401 Unauthorized

Tämä tarkoittaa että käyttäjätunnus/salasana on väärin tai http/basic-tiedoissa on jotakin muuta vikaa.

Virheelliset energiatodistustiedot 400

Energiatodistuksen tiedosta tarkistetaan ensin vastaako tiedot skeemaa ja tämän jälkeen tarkistetaan muut mahdolliset virheet. Virhevastaus on muotoa:

HTTP/1.1 400 Bad Request
{ "type": "NNN", "message": "XXX"}

Virheen muut tiedot riippuvat virheen tyypistä. Virheen message-kenttä on tarkoitettu sovelluskehittäjillä vian selvittämiseen.

Virhetyypit ja virheiden tietosisältö:

Tyyppi Kuvaus Sisältö
reitit.coercion/request-coercion Tiedon rakenne tai sisältö ei vastaa skeemaa. On suositeltavaa toteuttaa laskentaohjelmisto niin että laatija ei voi syöttää tietoa joka ei ole skeeman mukaista. errors: kuvaus virheestä, value: lähetetyt tiedot, schema: tiedon skeema, joka on määritetty sisäisessä koneluettavassa muodossa
invalid-value Jonkun attribuutin numeroarvo rikkoo dynaamista virheraja-arvoa. Mille tahansa numeroarvolle on järjestelmässä mahdollista dynaamisesti määrittää virhe- ja varoitusraja-arvot, jotka ovat tarkemmat kuin skeemassa määritetyt yleiset raja-arvot. Tämä virhe sisältää samat tiedot kuin varoitus. Näiden tietojen perusteella laskentaohjelmisto voi näyttää virheilmoituksen niin että se kohdistuu virheelliseen tietoon.
invalid-sisainen-kuorma Sisäisessä kuormassa on virheellisiä arvoja, joita ei voi käyttää valitulle käyttötarkoitusluokalle. valid-kuorma: sallitut arvot sisäiseen kuormaan
invalid-laskutusosoite Laskutusosoitetta ei ole olemassa tai se ei ole enää laatijan käytettävissä
invalid-replace Korvattu energiatodistus tieto on virheellinen TODO: tarkemmat tiedot, jotta laskentaohjelmisto voisi näyttää virheen paremmin käyttäjälle.
foreign-key-violation Jotakin tunnistetta vastaavaa tietoa ei ole olemassa TODO: tarkemmat tiedot, jotta laskentaohjelmisto voisi näyttää virheen paremmin käyttäjälle.
Clone this wiki locally