Skip to content

Commit

Permalink
Datahub API documentation update based on the latest developments and…
Browse files Browse the repository at this point in the history 
… knowledge updates.
  • Loading branch information
@EinarArro
EinarArro committed Jun 8, 2023
1 parent 060dd67 commit 1b791e4
Show file tree
Hide file tree
Showing 23 changed files with 369 additions and 320 deletions.
30 changes: 15 additions & 15 deletions est/01-avp-kirjeldus-ja-infovahetuse-yldpohimotted.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,10 @@ Andmelattu andmete sisestajaid nimetatakse operaatoriteks, kelle ülesanded ja v
- **Võrguettevõtja** on elektriettevõtja, kes osutab võrguteenust võrgu kaudu ning kes **vastutab** oma võrgupiirkonna mõõtepunktide ja mõõteandmete kogumise ja edastamise eest Andmelattu. Iga võrguettevõtja on turuosaline oma võrgukadudega. Lisaks vastavalt seadusandlusele, kui turuosalisel ei ole avatud tarne lepingut, siis on tema avatud tarnijaks automaatselt tema võrguettevõtja või viimase poolt nimetatud müüja.
- **Liinivaldaja** kasutab elektrienergia edastamiseks otseliini ning kes **vastutab** oma liinipiirkonna mõõteandmete kogumise ja edastamise eest Andmelattu.
- **Suletud jaotusvõrk** osutab võrguteenust suletud jaotusvõrgu kaudu kaudu ning kes **vastutab** oma võrgupiirkonna mõõtepunktide ja mõõteandmete kogumise ja edastamise eest Andmelattu. Iga võrguettevõtja on turuosaline oma võrgukadudega. Suletud jaotusvõrgus edastatakse elektrienergiat geograafiliselt piiratud tootmiskoha, ärirajatise või ühisteenuste koha piires seal asuvatele äritarbijatele, kelle tegevus või tootmisprotsess on tehnilistel või ohutusega seotud põhjustel omavahel ühendatud, või mille kaudu edastatakse elektrienergiat peamiselt võrgu omanikule või võrguettevõtjale, kes seda võrku haldab, või nendega valitseva mõju kaudu seotud ettevõtjale.
- **Tootja** edastab oma mõõtepunkti(de)ga seotud andmed, kui ei oma liinivaldaja tegevusluba
- **Laadimispunkti operaator** haldab laadimispunkte, mille kaudu on võimalik laadida korraga ühte elektrisõidukit või vahetada korraga ühe elektrisõiduki aku
- **Tootja** edastab oma mõõtepunkti(de)ga seotud andmed, kui ei oma liinivaldaja tegevusluba.
- **Laadimispunkti operaator** haldab laadimispunkte, mille kaudu on võimalik laadida korraga ühte elektrisõidukit või vahetada korraga ühe elektrisõiduki aku.
- **Avatud tarnija** on elektri müüja või ostja, kes osutab kliendile avatud tarnet ehk müüb/ostab kas puudujääva/ülejääva elektrienergia koguse või müüb/ostab kogu mõõdetud elektrienergia koguse sõltuvalt poolte vahelisest kokkuleppest turuosalisega. Avatud tarnija sisestab Andmelattu avatud tarne lepingu andmed turuosalisega.
- **Nimetatud müüja** võrguettevõtja poolt valitud avatud tarnija, kes osutab võrguettevõtja asemel avatud tarne teenust võrguettevõtja teeninduspiirkonna klientidele, kellel puudub avatud tarne leping.
- **Nimetatud müüja** võrguettevõtja poolt valitud avatud tarnija, kes osutab võrguettevõtja asemel avatud tarne teenust võrguettevõtja teeninduspiirkonna klientidele, kellel puudub avatud tarne leping;
- **Bilansihaldur** on hierarhiliselt kõrgemal olev avatud tarnija, kellel on bilansileping süsteemihalduriga.
- **Agregaator** on tarbimise juhrimise teenuse osutaja ning edastab Andmelattu agregeerimislepingu info, tarbimise juhtimise mõõtepunkti ja andmed.
- **Süsteemihaldur** on Elering, tagab Eesti elektrisüsteemi bilansi, on avatud tarnijaks bilansilepingu sõlminud bilansihalduritele, haldab ja arendab elektrituruseaduse alusel Andmeladu.
Expand Down Expand Up @@ -118,7 +118,7 @@ Sõnumite struktuuride ja validatasioonide kirjeldused on leitavad [Swagger](htt

- Kohustuslikud (tärniga tähistatud) elemendid peavad olema alati lisatud. Elemendi puudumisel muutub
sõnum töötlematuks ja seda ei aktsepteerita vastuvõtval poolel.
- Osad elemendid on kohustuslikud ainult teatud juhtudel. Sellisel juhul on kohustuslikkuse reegel leitav sõnumi või elemendi kirjeldusest või käesolevatest dokumentidest
- Osad elemendid on kohustuslikud ainult teatud juhtudel. Sellisel juhul on kohustuslikkuse reegel leitav sõnumi või elemendi kirjeldusest või käesolevatest dokumentidest.
- Kui element ei ole kohustuslik, siis võib see puududa.
- Sõnumites kasutatakse vaikimisi UTF-8 kodeeringut.

Expand All @@ -130,8 +130,8 @@ sõnum töötlematuks ja seda ei aktsepteerita vastuvõtval poolel.

Liidestuval süsteemil on aadressi andmete edastamiseks 2 võimalust:

- saata Maaameti ADS süsteemi aadressi ID (ADR_ID)
- saata aadressi kirjeldus tekstilisel kujul
- saata Maaameti ADS süsteemi aadressi ID (ADR_ID).
- saata aadressi kirjeldus tekstilisel kujul.

Mõlemad korraga ei ole lubatud.

Expand Down Expand Up @@ -159,15 +159,15 @@ Aadressi sektsioon koosneb järgmistest atribuutidest:

Atribuutide selgitus:

|Atribuut|Selgitus|Näide|
|--------|--------|-----|
|adsId|Maaameti ADS süsteemi ADR_ID|2105345|
|county|Maakond|Harju maakond|
|municipality|Omavalitsus|Tallinn|
|locality|Asustusüksus (küla, alevik, alev, vallasisene linn) või linnaosa|Kesklinna linnaosa|
|streetAddress|Lähiaadress (väikekoht, maaüksuse nimi, tänav, aadressinumber, korteri või muu hooneosa number)|Pärnu mnt 8|
|postalCode|Postiindeks|10148|
|comment|Kommentaar|C1T|
| Atribuut | Selgitus | Näide |
|---------------|-------------------------------------------------------------------------------------------------|--------------------|
| adsId | Maaameti ADS süsteemi ADR_ID | 2105345 |
| county | Maakond | Harju maakond |
| municipality | Omavalitsus | Tallinn |
| locality | Asustusüksus (küla, alevik, alev, vallasisene linn) või linnaosa | Kesklinna linnaosa |
| streetAddress | Lähiaadress (väikekoht, maaüksuse nimi, tänav, aadressinumber, korteri või muu hooneosa number) | Pärnu mnt 8 |
| postalCode | Postiindeks | 10148 |
| comment | Kommentaar | C1T |

### Vastussõnumite koodid

Expand Down
3 changes: 1 addition & 2 deletions est/02-autentimine-ja-autoriseerimine.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Elering tagab, et turuosalise andmetele Andmelaost saavad ligipääsu vaid need

Ligipääsuõiguste üldpõhimõtted on järgmised:

1. Andmelao andmetele ligipääsuks tuleb Eleringiga sõlmida leping kõikidel elektriettevõtjatel ning energiateenuste osutajatel, kes taotlevad turuosalise andmetele ligipääsu
1. Andmelao andmetele ligipääsuks tuleb Eleringiga sõlmida leping kõikidel elektriettevõtjatel ning energiateenuste osutajatel, kes taotlevad turuosalise andmetele ligipääsu.
2. Võrgulepingu kliendile tagatakse juurdepääs kliendiportaali kaudu edastatavatele andmetele. Kliendil on õigus volituse andmise kaudu edastada oma mõõtepunkti ja mõõteandmeid teistele isikutele ja süsteemidele.

> **Warning**
Expand Down Expand Up @@ -239,7 +239,6 @@ Autentimiseks tuleb liidestuval süsteemi läbida järgmised sammud:
|Autentimispäringu saatmine /api/authenticate aadressil|Andmeladu valideerib hash võtme, loob sessiooni ja tagastab JWT tokeni, mis kehtib sessiooni pikkuse|
|JWT tokeni lisamine igale järgnevale API sõnumile|Andmeladu valideerib JWT tokeni. Kui puudub või kehtetu, siis tagastab veakoodi 401 (unauthorized). Kui valiidne, siis järgneb autoriseerimine, mille kohta loe järgmisest peatükist|


## API liideses autoriseerimine

Iga API päring sisaldab `marketParticipantContext` sektsiooni, kus API sõnumi saatja peab ära defineerima enda rolli ja päringu saatmise eesmärgi. Selle eesmärgiks on luua selge arusaam kes ja milleks sõnumeid saadab ja milline on andmete kasutamise eesmärk.
Expand Down
48 changes: 24 additions & 24 deletions est/03-kliendi-eic.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,21 @@ Andmeladu võimaldab registreerida nii Eesti kui ka välismaiseid füüsilisi ja

Kliendi andmete edastamiseks ja pärimiseks on loodud vastavad Andmelao teenused. Ettenähtud kasutamise protsess on järgmine:

- Võrguettevõtja saadab uue või muutunud kliendi sõnumi kasutades teenust `customer`
- Võrguettevõtja saadab uue või muutunud kliendi sõnumi kasutades teenust `customer`.
- Andmeladu salvestab kliendi andmed ning määrab kliendile EIC koodi.
- Õigustatud kasutaja pärib kliendi andmed `customer/search` teenusest
- Õigustatud kasutaja pärib uute ja muutunud klientide andmete uuendusi kasutades teenust `customer/changes`
- Õigustatud kasutaja pärib kliendi andmed `customer/search` teenusest..
- Õigustatud kasutaja pärib uute ja muutunud klientide andmete uuendusi kasutades teenust `customer/changes`.

## Masinliidese sõnumid

### Sõnumid

|Sõnum|Eesmärk|
|-----|-------|
|`POST /api/{version}/customer`|Võimaldab registreerida uut klienti.|
|`PUT /api/{version}/customer`|Võimaldab uuendada olemasoleva kliendi andmeid.|
|`POST /api/{version}/customer/search`|Võimaldab otsida registreeritud klienti.|
|`POST /api/{version}/customer/changes`|Võimaldab skaneerida klientide andmete uuendusi.|
| Sõnum | Eesmärk |
|----------------------------------------|--------------------------------------------------|
| `POST /api/{version}/customer` | Võimaldab registreerida uut klienti. |
| `PUT /api/{version}/customer` | Võimaldab uuendada olemasoleva kliendi andmeid. |
| `POST /api/{version}/customer/search` | Võimaldab otsida registreeritud klienti. |
| `POST /api/{version}/customer/changes` | Võimaldab skaneerida klientide andmete uuendusi. |

Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](https://test-datahub.elering.ee/swagger-ui/index.html) keskkonnast.

Expand All @@ -45,25 +45,25 @@ Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](http
### Sõnumite reeglid

- Kliendi andmeid on lubatud lisada või muuta ainult võrguettevõtjal
- Kliendi andmeid on lubatud lisada või muuta ainult võrguettevõtjal.
- Kui uue kliendi registreerimisel tuvastab Andmeladu, kas antud isik juba eksisteerib süsteemis:
- kui eksisteerib, siis tagastab Andmeladu sõnumi saatjale olemasoleva isiku EIC koodi ja kui sõnumis oli uusi andmeid, siis uuendab need (nt nimi)
- kui isikut veel ei eksisteeri, siis loob uue isiku, omistab EIC koodi ja tagastab EIC koodi
- Kui eksisteerib, siis tagastab Andmeladu sõnumi saatjale olemasoleva isiku EIC koodi ja kui sõnumis oli uusi andmeid, siis uuendab need (nt nimi).
- Kui isikut veel ei eksisteeri, siis loob uue isiku, omistab EIC koodi ja tagastab EIC koodi.
- Füüsilise isiku lisamisel või muutmisel järgmised andmed kohustuslikud:
- ees- ja perenimi
- riik
- isikukood, kui riigi väärtust on Eesti
- dokumendi number kui riigi väärtus ei ole Eesti ja isikukood puudub
- ees- ja perenimi;
- riik;
- isikukood, kui riigi väärtust on Eesti;
- dokumendi number kui riigi väärtus ei ole Eesti ja isikukood puudub.
- Juriidilise isiku lisamisel või muutmisel järgmised andmed kohustuslikud:
- nimetus
- riik
- Äriregistri kood, kui riigi väärtus on Eesti ja tegu ei ole saatkonnaga
- Muu identifikaator, kui tegu on välismaise ettevõttega või saatkonnaga
- Eesti isikukoodi puhul rakendub formaadi kontroll
- Välismaiste isikukoodide puhul formaadi kontrolli ei rakendu
- Riigi väärtuse edastamiseks kasutatakse [ISO standardi](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 2-tähelisi koode
- nimetus;
- riik;
- Äriregistri kood, kui riigi väärtus on Eesti ja tegu ei ole saatkonnaga;
- Muu identifikaator, kui tegu on välismaise ettevõttega või saatkonnaga.
- Eesti isikukoodi puhul rakendub formaadi kontroll.
- Välismaiste isikukoodide puhul formaadi kontrolli ei rakendu.
- Riigi väärtuse edastamiseks kasutatakse [ISO standardi](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 2-tähelisi koode.
- Uue kliendi registreerimisel peab `customerType + identityType + identityValue + extensionType(COUNTRY)` kombinatsioon peab olema unikaalne. Kui ei ole, siis on tegu olemasoleva kliendiga ning süsteem kohtleb lisamise päringut kui kliendi andmete uuendamise päringuna ning võimalusel uuendab kliendi andmed.
- Kliendi otsingu teenus tagastab ainult kliendi EIC koodi juhul, kui andmete pärijal puudub vastav õigus
- Kliendi otsingu teenus tagastab ainult kliendi EIC koodi juhul, kui andmete pärijal puudub vastav õigus.

> **Note**
> Andmete saatmise ja pärimise õigused on kirjeldatud dokumendis [Autentimine ja autoriseerimine](02-autentimine-ja-autoriseerimine.md)
66 changes: 33 additions & 33 deletions est/04-mootepunktid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,20 +20,21 @@
Mõõtepunkt on seade, mis mõõdab energia tarbimise ja tootmise koguseid teatud asukohas.

Andmeladu võimaldab registreerida kolme tüüpi mõõtepunkte:

1. Elektri mõõtepunkt;
2. Gaasi mõõtepunkt;
3. Agregeerimise mõõtepunkt;

Mõõtepunkte haldavad järgmised turuosalised:

- võrguettevõtja
- liinioperaator
- suletud jaotusvõrgu ettevõtja
- agregaator
- tootja
- laadimispunkti operaator
- salvestusjaama operaator
- gaasitankla operaator
- võrguettevõtja;
- liinioperaator;
- suletud jaotusvõrgu ettevõtja;
- agregaator;
- tootja;
- laadimispunkti operaator;
- salvestusjaama operaator;
- gaasitankla operaator.

Käesolevas dokumendis nimetatakse neid ühisnimetajaga **Mõõtepunkti haldur**.

Expand All @@ -45,9 +46,9 @@ Mõõtepunkti andmestik sisaldab järgmist teavet:
2. mõõtepunkti tüüp (virtuaalne, kaugloetav, kohtloetav);
3. energia tüüp (elekter või gaas)
4. mõõtepunkti asukoha aadress;
5. elektrimõõtepunkti metaandmestik
6. gaasimõõtepunkti metaandmestik
7. agregeerimismõõtepunkti metaandmestik
5. elektrimõõtepunkti metaandmestik;
6. gaasimõõtepunkti metaandmestik;
7. agregeerimismõõtepunkti metaandmestik.

> **Warning**
>
Expand All @@ -59,9 +60,8 @@ Mõõtepunkti haldur saab mõõtepunktide tehnilised andmed edastada Andmelattu

Mõõtepunkti andmete edastamiseks on loodud vastavad Andmelao teenused. Ettenähtud kasutamise protsess on järgmine:

- Vajadusel kasutab võrguettevõtja eelnevalt teenust `range` et leida vaba EIC kood mõõtepunkti registreerimiseks
- Võrguettevõtja saadab uue või muutunud mõõtepunkti sõnumi kasutades teenust `meter` või `gridagreementmeteringpoint`

- Vajadusel kasutab võrguettevõtja eelnevalt teenust `range` et leida vaba EIC kood mõõtepunkti registreerimiseks.
- Võrguettevõtja saadab uue või muutunud mõõtepunkti sõnumi kasutades teenust `meter` või `gridagreementmeteringpoint`.

### Veebiliides

Expand All @@ -72,12 +72,12 @@ Mõõtepunkti andmete edastamiseks on loodud vastavad Andmelao teenused. Ettenä

#### Sõnumid

|Sõnum|Eesmärk|
|-----|-------|
|`POST /api/{version}/eic/range`|Võimaldab pärida vaba(d) EIC koodi(d) omale eraldatud vahemikust|
|`POST /api/{version}/meter`|Võimaldab registreerida uue mõõtepunkti|
|`PUT /api/{version}/meter`|Võimaldab uuendada mõõtepunkti andmeid|
|`POST /api/{version}/gridagreementmeteringpoint`|Võimaldab registreerida mõõtepunkti koos võrgulepinguga korraga|
| Sõnum | Eesmärk | Märkus |
|--------------------------------------------------|------------------------------------------------------------------|--------------|
| `POST /api/{version}/eic/range` | Võimaldab pärida vaba(d) EIC koodi(d) omale eraldatud vahemikust | |
| `POST /api/{version}/meter` | Võimaldab registreerida uue mõõtepunkti | |
| `PUT /api/{version}/meter` | Võimaldab uuendada mõõtepunkti andmeid | |
| `POST /api/{version}/gridagreementmeteringpoint` | Võimaldab registreerida mõõtepunkti koos võrgulepinguga korraga | Pole MVP osa |

Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](https://test-datahub.elering.ee/swagger-ui/index.html) keskkonnast.

Expand All @@ -86,11 +86,11 @@ Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](http
#### Sõnumite reeglid

- Mõõtepunkti EIC kood peab jääma võrguettevõtja EIC koodide vahemikku
- Piirimõõtepunkt on mõõtepunkt, kus võrguettevõtja on võrguteenuse klient
- Mõõtepunkti EIC kood peab jääma võrguettevõtja EIC koodide vahemikku.
- Piirimõõtepunkt on mõõtepunkt, kus võrguettevõtja on võrguteenuse klient.
- Mõõtepunkti resolutsiooni reeglid on energia tüübist sõltuvad:
- Elektri puhul on resolutsioon täiendav info ja ei mõjuta mõõteandmete edastamist tulevikus vaid iseloomustab, kas mõõtepunkt suudab reaalsuses tarbimist mõõta 15 minuti, 1 tunni või lausa päeva täpsusega
- Gaasi puhul on resolutsioon rangelt seotud mõõteandmete resolutsiooniga. Näiteks kui mõõtepunkti resolutsioon on 1 päev, siis peavad ka edastatud mõõteandmed olema resolutsioonis 1 päev
- Elektri puhul on resolutsioon täiendav info ja ei mõjuta mõõteandmete edastamist tulevikus vaid iseloomustab, kas mõõtepunkt suudab reaalsuses tarbimist mõõta 15 minuti või 1 tunni täpsusega või on andmed võrguettevõtja poolt jaotatud ja prognoositud .
- Gaasi puhul on resolutsioon rangelt seotud mõõteandmete resolutsiooniga. Näiteks kui mõõtepunkti resolutsioon on 1 päev, siis peavad ka edastatud mõõteandmed olema resolutsioonis 1 päev.

> **Note**
> Andmete saatmise ja pärimise õigused on kirjeldatud dokumendis [Autentimine ja autoriseerimine](02-autentimine-ja-autoriseerimine.md)
Expand All @@ -103,12 +103,12 @@ Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](http

#### Sõnumid

|Sõnum|Eesmärk|
|-----|-------|
|`POST /api/{version}/meter/search`|Võimaldab otsida mõõtepunkte mõõtepunkti andmete alusel|
|`POST /api/{version}/meter/search/customer`|Võimaldab otsida mõõtepunkte kliendi andmete alusel|
|`POST /api/{version}/meter/export`|Võimaldab eksportida tingimustele vastavad mõõtepunktid|
|`POST /api/{version}/meter/changes`|Võimaldab skaneerida mõõtepunktide andmete uuendusi.|
| Sõnum | Eesmärk |
|---------------------------------------------|---------------------------------------------------------|
| `POST /api/{version}/meter/search` | Võimaldab otsida mõõtepunkte mõõtepunkti andmete alusel |
| `POST /api/{version}/meter/search/customer` | Võimaldab otsida mõõtepunkte kliendi andmete alusel |
| `POST /api/{version}/meter/export` | Võimaldab eksportida tingimustele vastavad mõõtepunktid |
| `POST /api/{version}/meter/changes` | Võimaldab skaneerida mõõtepunktide andmete uuendusi. |

Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](https://test-datahub.elering.ee/swagger-ui/index.html) keskkonnast.

Expand All @@ -120,6 +120,6 @@ Sõnumite struktuuride ja validatsioonide kirjeldused on leitavad [Swagger](http
> **Note**
> Andmete saatmise ja pärimise õigused on kirjeldatud dokumendis [Autentimine ja autoriseerimine](02-autentimine-ja-autoriseerimine.md)
1. Kui andmete pärijal puudub vajalik kliendi andmete nägemise õigus, siis otsingu teenus tagastab ainult EIC koodi.
2. Andmeladu väljastab mõõtepunkti andmed ilma aadressita, kui teostatakse võrgueeskirja §8 lg 5 järgset kontrolli.
3. Ligipääsuõiguste olemasolul väljastab Andmeladu kogu mõõtepunkti andmestiku
- Kui andmete pärijal puudub vajalik kliendi andmete nägemise õigus, siis otsingu teenus tagastab ainult EIC koodi.
- Andmeladu väljastab mõõtepunkti andmed ilma aadressita, kui teostatakse võrgueeskirja §8 lg 5 järgset kontrolli.
- Ligipääsuõiguste olemasolul väljastab Andmeladu kogu mõõtepunkti andmestiku.
Loading

0 comments on commit 1b791e4

Please sign in to comment.