Korto näitude kauglugemise API

Näitude kauglugemise API eesmärgiks on pakkuda ühist andmeformaati erinevatelt teenusepakkujatelt näitude vastuvõtmiseks. API funktsionaalsus on piiratud näitude ja tarbitud koguste vastuvõtmisega; seadmete lisamine ja esmane seadistamine tuleb teha ühistu esindajal või halduril Korto Pro kaudu käsitsi.

Ühenduse detailid

Päringud käivad üle HTTPS ühenduse, API lõpp-punkti URL-id on järgmised:

Näidud tuleb saata POST päringuga, millel peavad olema järgmised päised:

  • Content-type: application/json
  • Authorization: Bearer TOKEN

TOKEN on teenusepakkujale määratud JWT formaadis autentimistoken. See on test ja live keskkondades erinev.

Lisaks toetab API päringus järgmiseid päiseid:

  • X-Client-ID: XXXX

XXXX on kliendi (ehk Korto mõistes ühistu) ID, kui kõik päringus olevad andmed käivad ühe kliendi seadmete kohta.

Andmeformaadi detailid

Päringu sisu on JSON formaadis, mis sisaldab üht või rohkemat kirjet. Iga kirje sisaldab omakorda üht loetud näitu või tarbitud kogust. Minimaalne komplekt andmeid, mille API vastu võtab, näeks välja järgmine:

[
    {
        "meter_id": "123",
        "client_id": "456",
        "value": 1.234,
        "value_type": "reading"
    },
    {
        ...
    }
]

Kirjes peavad sisalduma:

  • meter_id: arvesti identifikaator. Tegu on kokkuleppelise tunnusega, milleks võib olla arvesti seerianumber, andmebaasi ID teenusepakkuja või Korto süsteemis, või mingi muu väärtus, mis on ühistu piires unikaalne. Korteri numbri ja arvesti liigi kombinatsioon võib olla sobilik eeldusel, et ei ole tarvis saata näiteks üldarvestite näitusid või mitme maja korterite näitusid korraga.
  • client_id: kliendi (ehk Korto mõistes ühistu) ID; seda kuvatakse ühistu esindajale kauglugemise liidestuse aktiveerimise vormil. Kui päring sisaldab ainult ühe kliendi seadmete andmeid, võib selle tunnuse edastada ühekordselt X-Client-ID päises, mitte igas üksikus kirjes.
  • value: saadetav näit või kogus. Maksimaalne lubatud väärtus on 9999999,999. Komakohti võib olla kuni 3.
  • value_type: määrab, kas tegu on jooksva näiduga ("reading") või viimasest näidust saadik tarbitud kogusega ("consumption"). Lisaks võivad kirjetes sisalduda järgmised väljad:
  • value2: võimaldab ühe kirjega edastada kaks näitu. Mõeldud kasutamiseks olukorras, kus üks füüsiline seade mõõdab samaaegselt kaht erinevat kogust. Konkreetset kasutusjuhtu on täpsemalt kirjeldatud allpool.
  • unit: ühik, milles näit või kogus on mõõdetud. Kui see on väärtustatud, üritab API vajadusel koguse teisendada Korto süsteemis arvestile määratud ühikusse. Hetkel on toetatud energia (Wh, kWh, MWh) ja ruumala (l, m³) ühikute teisendamine.
  • time: ajahetk, millal näit on loetud, RFC3339 formaadis. Kasulik juhul, kui näidud edastatakse Kortole viivitusega. Puudumisel kasutatakse päringu vastuvõtmise ajahetke.

Kõiki võimalikke andmeid sisaldav kirje näeks välja järgmine:

[
    {
        "meter_id": "123",
        "client_id": "456",
        "value": 1.234,
        "value2": 5.678,
        "value_type": "reading",
        "time": "2020-12-14T00:00:08Z",
        "unit": "kWh"
    },
    {
        ...
    }
]

Välja value2 olemasolul on sellel ja value väljal juhtumipõhised tähendused:

  • Kahetariifse elektriarvesti puhul peab value sisaldama päevast ja value2 öist näitu.
  • Külma ja sooja vett mõõtva veearvesti puhul peab value sisaldama külma ja value2 sooja vee näitu.

Sellisel kujul andmete edastamise vajadus tuleneb sellest, et Korto süsteemis peavad öise ja päevase elektri ning sooja ja külma vee arvestid olema sisestatud eraldi. See, kas sellised näidud tuleks saata koos või eraldi kirjetes, sõltub sellest, kuidas on Kortos arvestite identifikaatorid seadistatud.

Päringute maht ja sagedus

Päringute mahule piiranguid seatud ei ole - näitusid saab vajadusel saata ühe seadme, ühe korteri seadmete, ühe maja/ühistu seadmete või mitme maja/ühistu seadmete kohta korraga. Näitude saatmise sagedus ei ole samuti piiratud, aga Korto salvestab iga seadme kohta maksimaalselt ühe näidu kuupäevas. Sama kuupäeva jooksul saadetud hilisem näit kirjutab varasema üle.

Päringu vastus

API tagastatavad vastused on JSON formaadis. Vastuses on üks väli errors, mis omakorda sisaldab nimekirja päringu töötlemisel tekkinud vigadest:

{
    "errors": [
        "Invalid token."
    ]
}

Vastuse HTTP olekukoodidel on järgmised tähendused:

  • 200 OK: päringu vastuvõtmine õnnestus. See ei tähenda, et kõikidest kirjetest õnnestus näidud salvestada. Kui mõne kirje lugemisel tekkis probleem (näiteks ei õnnestunud vastavat arvestit leida), on vigade nimekirjas vastav teade. Näiteks: "Record 1: meter with ID '12345' not found." Kõik vead ei pruugi olla näitude saatja poolelt lahendatavad, näiteks kui ühistu on mingi kuupäeva seisuga kulude jaotuse teinud, siis sellest varasema kuupäevaga näitusid enam saata ei saa. Selliseid vigu võib ignoreerida.
  • 400 Bad Request: päringu sisu oli vigane. Sisu valideeritakse JSON schema vastu ja võimalusel on vigade nimekirjas detailsem info. Näiteks: "JSON schema error at [0].meter_id: The property meter_id is required" Schema on võimalik alla laadida, tehes GET päringu API lõpp-punkti URL-i pihta. See päring ei vaja autentimistokenit.
  • 403 Forbidden: vigane autentimistoken. Vigade nimekirjas on reeglina üldsõnaline teade.
  • 503 Service Unavailable: Korto serveri plaanilised hooldustööd. Vigade nimekirjas on teade eeldatava algus- ja lõppkellaajaga. Reeglina toimuvad sellised hooldustööd kord kuus, vahemikus 23-00.

API-ga liidestumise protsess

API-ga liidestumiseks peaks teenusepakkuja ühendust võtma e-posti aadressil info@korto.ee. Seejärel väljastatakse talle API autentimistoken, esmalt testkeskkonna jaoks. Vajadusel on võimalik tekitada testkeskkonda sobivalt seadistatud näidisühistu ning võimaldada teenusepakkuja esindajale ligipääs.