Tietorajapinta [REST]
- 1 Tietorajapinta (REST)
- 2 Tietorajapinnan yleiset tekniset tiedot
- 3 DH-1000 Tietojen noutaminen tietorajapinnan kautta
- 4 DH-1000 Käyttöpaikan tietojen noutaminen
- 5 DH-1001 Sopimustietojen noutaminen
- 6 DH-1002 Aikasarjatietojen noutaminen
- 7 DH-1003 Valtuutustietojen noutaminen
- 8 DH-1005 Asiakastietojen noutaminen
- 9 DH-1006 Organisaation tietojen noutaminen
Tietorajapinta (REST)
Tietorajapinta on REST/HTTP-rajapinta. Tietorajapinta mahdollistaa datahubissa olevien tietojen haun esimerkiksi suoraan markkinaosapuolen loppuasiakkaillensa tarjoamaan online-palveluun. Tietorajapinnan kautta ei voi ilmoittaa tietoja datahubiin. Markkinaosapuolet voivat itse päättää haluavatko tätä rajapintaa hyödyntää omassa toiminnassaan.
Osapuolten oikeudet tietoihin otetaan huomioon samojen sääntöjen mukaisesti sekä tietorajapinnan että tapahtumarajapinnan osalta. Osapuoli voi hakea vain tietoja, joihin osapuolella on oikeus sopimuksen perusteella tai asiakkaan valtuuttamana.
Mikäli osapuolilla on tarve hakea isompaa tietomäärää kerralla, esimerkiksi verratakseen datahubissa olevaa tietoa oman järjestelmänsä tietoihin, tulee tähän tarkoitukseen käyttää datahubin tarjoamia kontrolliraportteja. Näitä raportteja voidaan ajaa ajastetusti esim. yöaikaan häiritsemättä muuta päivittäistä toimintaa.
Tietorajapinta tarjoaa seuraavanlaiset tietohaut:
Käyttöpaikkatietojen haku
Käyttöpaikan sopimustietojen haku
Käyttöpaikan mittaustietojen haku
Käyttöpaikan valtuutustietojen haku
Asiakkaan asiakastietojen haku
Osapuolitietojen haku: Osapuolitietojen osalta voidaan hakea kaikkien osapuolten tiedot kerralla.
Tietosuojan varmistamiseksi hakuun tulee syöttää aina myös asiakkaan tunnus, jonka kanssa sopimus on tehty. Yhden asiakkaan tunnus riittää myös siinä tapauksessa, jos sopimuksella on useampi asiakas.
Datahubin tietorajapinnan käyttö on kuvattu osiossa DH-1000 Tietojen noutaminen tietorajapinnan kautta.
Suositukset rajapinnan käytöstä
Tietorajapintaa ei ole tarkoitettu massahakujen tekemiseen. Tietorajapinnalla tiedot haetaan aina yksilöiden tietokokonaisuus kerrallaan. Tämä tarkoittaa sitä, että haussa ilmoitetaan esim. haettavan käyttöpaikan tietojen käyttöpaikkatunnus. Mikäli haluttaisiin hakea useamman käyttöpaikan tietoja yhdellä kertaa, on tapahtumarajapinta tehokkaampi tapa tietojen hakuun.
Tapahtumarajapinnan etu on myös siinä, että tietoihin tapahtuvista muutoksista datahub välittää automaattisesti tiedon siihen oikeutetuille osapuolille. Tietorajapinnan käyttäjän on erikseen osattava hakea muuttunut tieto.
Rajaukset rajapinnan käyttöön
Tietorajapintaa hyödyntäen ei voi ilmoittaa tietoja datahubiin.
Tietorajapinnan kautta ei löydy käyttöpaikkatunnuksen selvitystapahtuman kaltaista toiminnallisuutta. Haettava tieto on aina yksilöitävä, eli haussa on annettava aina esim. haettavan käyttöpaikan käyttöpaikkatunnus tai asiakkaan asiakastunnus.
Tietorajapinta ei tue toimeksiantoja osapuolten välillä.
Palveluntarjoajan roolissa toimivalla osapuolella tulee aina olla asiakkaan antama valtuutus, ennen kuin osapuoli voi hakea tietoja. Valtuutus on aina asiakas- ja käyttöpaikkakohtainen.
Esimerkkejä rajapinnan käytöstä
Tietorajapintaa voidaan käyttää esimerkiksi silloin, kun ulkopuolinen rekisteröity osapuoli (kolmas osapuoli tai muu markkinaosapuoli) kehittää ja luo uusia palveluita. Kolmannen osapuolen palvelu voi olla esimerkiksi mobiilisovellus, jonka avulla loppukäyttäjä voi nähdä kaikkien käyttöpaikkojen tiedot riippumatta siitä, millä verkkoalueella käyttöpaikat sijaitsevat. Tällainen edellyttää aina asiakkaan ilmoittamaa valtuutusta datahubiin. Asiakastietoja hakiessa tulee aina ilmoittaa haettavan asiakkaan asiakastunnus. Datahub tarkistaa, onko hakijalla oikeus asiakkaan tietoihin ja palauttaa tiedot vain, jos oikeus on voimassa.
Esimerkkejä hauista:
Haetaan asiakastiedot, GetCustomerData (DH-1005)
Tiedettävä asiakastunnus (HeTu, Y-tunnus)
Tietojen saamiseksi on oltava oikeus tietoihin (sopimus tai valtuutus)
Palauttaa käyttöpaikat, joihin asiakkaalla on sopimukset
Tietorajapinnan yleiset tekniset tiedot
Viestintä
Integraatio on REST-pohjainen verkkopalvelu, joka käyttää HTTP-protokollan POST-menetelmää.
GET-menetelmä poistuu käytöstä Datahub-version 2.6 käyttöönoton yhteydessä.
Rajapinta käyttää todennuksessa asiakasvarmenteita.
Seuraavassa taulukossa on lueteltu pakolliset määritteet, jotka tarvitaan liittymäyhteyden avaamiseen.
Nimi | Tyyppi | Velvoite | Arvo |
|---|---|---|---|
Yhteys: Asiakkaan varmenne | Varmenne | Pakollinen | Asiakkaan antama varmenne |
Yhteys: Protokolla | Merkkijono | Pakollinen | HTTPS (TLS 1.2 tai TLS 1.3) |
Yhteys: Portti | Merkkijono | Pakollinen | 443 |
Päätepiste
Päätepiste POST-menetelmällä
Rajapinnassa on vain yksi päätepiste, jota kutsutaan halutun toiminnon aktivoimiseksi. Päätepisteen URL-osoitteessa on seuraava rakenne:
https://{palvelin}/rest/FGR/{funktio}Päätepiste GET-menetelmällä
Rajapinnassa on vain yksi päätepiste, jota kutsutaan halutun toiminnon aktivoimiseksi. Päätepisteen URL-osoitteessa on seuraava rakenne:
https://{palvelin}/rest/FGR/{funktio}?organisationUser={OrganisaationKäyttäjä}&suodatin01={suodatin01}&suodatin02={suodatin02}&…Parametrit
Parametrit POST-menetelmässä
Otsikkoparametrit:
Nimi | Tyyppi | Velvoite | Arvo |
HTTP: Method | Merkkijono | Pakollinen | POST |
HTTP: Accept | Merkkijono | Pakollinen | application/json |
Polun parametrit:
Nimi | Tyyppi | Velvoite | Arvo |
{Funktio} | Merkkijono | Pakollinen | Katso osio DH-1000. |
Kyselymerkkijonon parametrit:
POST-menetelmässä ei parametrejä.
Parametrit GET-menetelmässä
Otsikkoparametrit:
Nimi | Tyyppi | Velvoite | Arvo |
HTTP: Method | Merkkijono | Pakollinen | GET |
HTTP: Accept | Merkkijono | Pakollinen | application/json |
Polun parametrit:
Nimi | Tyyppi | Velvoite | Arvo |
{Funktio} | Merkkijono | Pakollinen | Katso osio DH-1000. |
Kyselymerkkijonon parametrit:
Nimi | Tyyppi | Velvoite | Arvo |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen | Organisaatiokohtainen. Määrittää, että Fingridin luomalla rekisteröidyllä Datahubin B2B-käyttäjällä on tiettyjä käyttäjärooleja B2B-viestinnässä. |
{Suodattimet} | {Vaihtelee} | {Vaihtelee} | Tarvittaessa toiminnoissa voi olla useita et-merkillä erotettuja suodattimia. Esimerkki: customerIdentification=1234&meteringPointEAN=12345&ViewDate=2019-10-14T21:00:00ZKäytettävä suodatin määräytyy toiminnon mukaan. Lisätietoja löytyy osiosta DH-1000. Huomaa, että suodattimissa isot ja pienet kirjaimet ovat merkitseviä: (meteringPointEAN vs. MeteringpointEAN). Väärä kirjainkoko aiheuttaa HTTP 400 Bad Request -virheen. |
Vastaussanoma
Vain julkiset tiedot (organisaation tiedot) tai tiedot, joiden osalta toimijalla on sopimus (myynti/verkko/valtuutus), palautetaan. Kun käyttäjä antaa parametreja sellaisten tietojen valtuutussuodattimien kanssa, jotka eivät johda vastaustietoihin, palautetaan tyhjä JSON-objekti vahvistusvirheiden sijasta.
Tyhjien attribuuttien osalta datahub ei lähetä tyhjää elementtiä, mutta sen sijaan se ei lähetä elementtiä.
Esimerkki datahubista tulevasta JSON-vastaussanomasta:
{"GetAccountinPointDataResponse": {
"MeteringPoints": [{
"MeteringPointEAN": "640102010000532598",
"AccountingPointSubType": "AQ01"
},
{
"MeteringPointEAN": "640102010005902686",
"AccountingPointSubType ": "AQ02"
}]
}
}Tietojen kelpoisuus
Kaikki kelpoisuustarkistukset tehdään NäkymänPäivämäärä-kenttään pohjautuvien tietojen tilan perusteella. Toiminnoissa, joissa NäkymänPäivämäärä ei ole syöttökenttänä, käytetään nykyistä päivämäärää ja aikaa.
Tietojen valtuuttaminen
Datahub tarkistaa kaikkien tietopyyntöjen osalta, onko toimijalla asianmukainen valtuutus pyydettyihin tietoihin. Säännöt määritetään toimintokohtaisesti. Pääsy tietoihin, joiden osalta toimijalla ei ole aktiivista (vahvistettua) sopimusta tai valtuutusta, ei ole sallittu, ellei sitä ole nimenomaisesti mainittu prosessissa.
Vahvistettu sopimus tai valtuutus voi olla joku seuraavista sopimus- tai valtuutustyypeistä:
Koodi | Kuvaus |
AP01 | Energiaraportointi |
AP02 | Tarjouspyyntö |
AP03 | Tarjouskilpailu sopimuksesta palveluna |
AP04 | Tarjouspyyntö (ei pääsyä mittaustietoihin) |
AP05 | Tarjouskilpailu sopimuksesta palveluna (ei pääsyä mittaustietoihin) |
AP07 | Energiaraportointi ja sopimustiedot |
11 | Verkkosopimus |
12 | Myyntisopimus |
Tekniset tiedot
Tietorajapinta ei tue yleismerkkihakuja.
Tietorajapinta ei ole kielitietoinen. Se näyttää tiedot sellaisina kuin ne on tallennettu datahubiin.
Esimerkiksi toimialuekoodeja ei käännetä, vaan B2B-rajapinnan tavoin ne ilmoitetaan koodeina. Numeroiden ja päivämäärien osalta näkyy oletusarvoinen XML-/JSON-muoto.
Kaikki tietorajapinnan kellonajat näkyvät UTC-aikana. Esimerkiksi ”2019-05-14T12:30:00Z” on paikallinen Suomen aika ”2019-05-14T15:30:00”
Arvojen yksikkökoodeina käytetään SI-järjestelmään perustuvia tunnuksia: esimerkiksi kW, MW, kWh, MWh, kvar, Mvar, kvarh, mvarh ja Mvarh.
Sanomatunnuksina käytetään UUID-tunnuksia (Universally Unique Identifiers).
Suodattimien arvot voidaan syöttää tekstipohjaisiin tietokenttiin isoilla ja pienillä kirjaimilla. Haku ei erottele isoja ja pieniä kirjaimia.
Yleinen käyttömalli
Käyttöpaikkatunnuksella ja asiakastunnuksella saa haettua:
Prosessi | Kuvaus | Huomautus |
Käyttöpaikan tiedot | Käyttöpaikan tietojen noutaminen. GetAccountingPointDataPosttai GetAccountingPointData | |
Sopimuksen tiedot (JVH tai myyjä) | Luettelon näyttäminen sopimuksista, joita asiakkaalla on tai oli sen osapuolen osalta, jonka portaalia asiakas käyttää. GetContractDataPosttai GetContractData | |
Aikasarjatiedot | Asiakkaan aikasarjatietojen näyttäminen. Mieluiten osapuoli tallentaa tunnin / 15 minuutin raaka-arvot välimuistiin rajoittaakseen vuorovaikutusta datahubin kanssa ja välittääkseen kootut tiedot asiakkaalle. GetTimeSeriesDataPosttai GetTimeSeriesData | |
Valtuutustiedot (palveluntarjoaja tai myyjä) | Luettelon näyttäminen valtuutuksista, joita asiakkaalla on tai oli sen osapuolen osalta, jonka portaalia asiakas käyttää. GetAuthorisationDataPosttai GetAuthorisationData | |
Asiakastiedot | Sisäänkirjautumisen jälkeen asiakastietojen sekä asiakassopimusten ja käyttöpaikkojen liitettyjen metatietojen noutaminen. GetCustomerDataPosttai GetCustomerData |
DH-1000 Tietojen noutaminen tietorajapinnan kautta
Tässä luvussa kuvataan tietorajapinnan resurssit, syöttöparametrit ja vastaukset. Jokaisella resurssilla on oma taulukko, joka sisältää tiedot tarvittavista parametreista ja suoritetuista validoinneista sekä pyyntöpolkuesimerkin.
Resurssia kuvaavan taulukon jälkeen on taulukko, jossa esitetään vastauksen sisältö. Taulukon tarkoitus on ainoastaan esittää resurssin palauttamat tiedot. Sen ei ole tarkoitus vastata tarkasti vastauksen rakennetta.
DH-1000 Käyttöpaikan tietojen noutaminen
POST-menetelmä
Resurssin kuvaus | |||
|---|---|---|---|
Määritelmä | Rajapinta käyttöpaikan tietojen pyytämistä varten | ||
Polun parametrit | |||
{funktio} | GetAccountingPointDataPost | ||
Sanoman parametrit | |||
Nimi | Tyyppi | Velvoite | Huomautus |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
|
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
|
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
|
{NäkymänPäivämäärä} | Päivämäärä ja aika | Pakollinen | Päättyneissä sopimuksissa käytetään ContractEndDate-parametria. Vahvistetuissa sopimuksissa käytetään CurrentDateTime-parametria. |
Kelpoisuussäännöt | |||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva sopimus (myynti-/verkkosopimus tai valtuutussopimus) asiakkaan kanssa katselupäivänä. | |||
Vastaus | |||
Käyttöpaikan tiedot | |||
Esimerkkipyyntö | |||
https://{palvelin}/rest/FGR/GetAccountingPointDataPostSanoman sisältö: {
"GetAccountingPointDataRequest": {
"organisationUser": "{OrganisaationKäyttäjä}",
"Filters": {
"meteringPointEAN": "{KäyttöpaikanEAN}",
"customerIdentification": "{AsiakkaanTunnus}",
"ViewDate": "{NäkymänPäivämäärä}"
}
}
} | |||
GET-menetelmä
GET-menetelmä poistuu käytöstä version 2.6 käyttöönoton yhteydessä.
Resurssin kuvaus | |||
|---|---|---|---|
Määritelmä | Rajapinta käyttöpaikan tietojen pyytämistä varten | ||
Polun parametrit | |||
{funktio} | GetAccountingPointData | ||
Kyselymerkkijonon parametrit | |||
Nimi | Tyyppi | Velvoite | Huomautus |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
|
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
|
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
|
{NäkymänPäivämäärä} | Päivämäärä ja aika | Pakollinen | Päättyneissä sopimuksissa käytetään ContractEndDate-parametria. Vahvistetuissa sopimuksissa käytetään CurrentDateTime-parametria. |
Kelpoisuussäännöt | |||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva sopimus (myynti-/verkkosopimus tai valtuutussopimus) asiakkaan kanssa katselupäivänä. | |||
Vastaus | |||
Käyttöpaikan tiedot | |||
Esimerkkipyyntö | |||
https://{palvelin}/rest/FGR/GetAccountingPointData?organisationUser={OrganisaationKäyttäjä}&meteringPointEAN={KäyttöpaikanEAN}&customerIdentification={AsiakkaanTunnus}&ViewDate={NäkymänPäivämäärä} | |||
Palautetut käyttöpaikan tiedot
DH-1000 – Get accounting point data return | |
|---|---|
Nimi | Pakollisuus |
AccountingPoints | 0..1 |
AccountingPointType | 1..1 |
AccountingPointSubtype | 1..1 |
ElectricPower | 0..1 |
EnergyCommunityIdentifier | 0..1 |
EnergyCommunityName | 0..1 |
FuseSize | 0..1 |
IsHeatingDependentOnElectricity | 0..1 |
IsReactiveEnergyTimeSeriesAvailable | 0..1 |
IsRemotelyConnectable | 1..1 |
IsRemotelyReadable | 0..1 |
Latitude | 0..1 |
Longitude | 0..1 |
MeteringGridAreaCode | 1..1 |
MeteringMethod | 0..1 |
MeteringPointEAN | 1..1 |
MeteringPointStatus | 1..1 |
MeteringTimeDivision | 1..1 |
MeteringTimeStep | 1..1 |
MeterNumber | 0..1 |
UserGroup | 0..1 |
EstimatedYearlyUsages | 0..1 |
EstimatedYearlyUsage1 | 0..1 |
EstimatedYearlyUsage2 | 0..1 |
MeteringPointAddresses | 1..8 |
AddressType | 1..1 |
Apartment | 0..1 |
BuildingNumber | 0..1 |
CountryCode | 1..1 |
Language | 1..1 |
PostalCode | 1..1 |
PostOffice | 1..1 |
StairwellIdentification | 0..1 |
StreetName | 0..1 |
MeteringPointDevices (ControlledLoad) | 0..n |
ControlledLoadName | 0..1 |
ControlLimits | 0..1 |
Description | 0..1 |
DeviceType | 1..1 |
MaximumPower | 0..1 |
MaximumPowerUnit | 0..1 |
Timings | 0..1 |
MeteringPointDevices (ProductionDevice) | 0..n |
DeviceType | 1..1 |
MaximumPower | 0..1 |
MaximumPowerUnit | 0..1 |
ProductionDeviceName | 1..1 |
ProductionType | 1..1 |
MeteringPointDevices (StorageDevice) | 0..n |
Capacity | 0..1 |
CapacityUnit | 0..1 |
DeviceType | 1..1 |
MaximumPower | 0..1 |
MaximumPowerUnit | 0..1 |
StorageDeviceName | 1..1 |
StorageDeviceType | 1..1 |
DH-1001 Sopimustietojen noutaminen
POST-menetelmä
Resurssin kuvaus | ||
|---|---|---|
Määritelmä | Rajapinta sopimustietojen noutamista varten | |
Polun parametrit | ||
{funktio} | GetContractDataPost | |
Sanoman parametrit | ||
Nimi | Tyyppi | Velvoite |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
Kelpoisuussäännöt | ||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva sopimus (myynti- tai verkkosopimus) asiakkaan kanssa pyynnön esittämisen aikaan. Myös tulevaisuudessa alkavat sopimukset ja sopimukset, jotka ovat päättyneet 6 viikon sisällä ennen pyynnön ajankohtaa, palautetaan | ||
Vastaus | ||
Sopimustiedot, jotka ovat voimassa pyynnön esittämisen aikaan. | ||
Esimerkkipyyntö | ||
https://{palvelin}/rest/FGR/GetContractDataPostSanoman sisältö: {
"GetContractDataRequest": {
"organisationUser": "{OrganisaationKäyttäjä}",
"Filters": {
"meteringPointEAN": "{KäyttöpaikanEAN}",
"customerIdentification": "{AsiakkaanTunnus}",
}
}
} | ||
GET-menetelmä
GET-menetelmä poistuu käytöstä version 2.6 käyttöönoton yhteydessä.
Resurssin kuvaus | ||
|---|---|---|
Määritelmä | Rajapinta sopimustietojen noutamista varten | |
Polun parametrit | ||
{funktio} | GetContractData | |
Kyselymerkkijonon parametrit | ||
Nimi | Tyyppi | Velvoite |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
Kelpoisuussäännöt | ||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva sopimus (myynti- tai verkkosopimus) asiakkaan kanssa pyynnön esittämisen aikaan. Myös tulevaisuudessa alkavat sopimukset ja sopimukset, jotka ovat päättyneet 6 viikon sisällä ennen pyynnön ajankohtaa, palautetaan. | ||
Vastaus | ||
Sopimustiedot, jotka ovat voimassa pyynnön esittämisen aikaan. | ||
Esimerkkipyyntö | ||
https://{palvelin}/rest/FGR/GetContractData?organisationUser={OrganisaationKäyttäjä}&meteringPointEAN={KäyttöpaikanEAN}&customerIdentification={AsiakkaanTunnus} | ||
Palautetut myyntisopimuksen tiedot
DH-1001 – Get contract data return for sales agreement | |
|---|---|
Nimi | Pakollisuus |
Agreements | 0..n |
AgreementEndDate | 0..1 |
AgreementIdentification | 1..1 |
AgreementStartDate | 1..1 |
AgreementStatus | 1..1 |
AgreementType | 1..1 |
ContactMethod | 1..1 |
CustomerNote | 0..1 |
FixedTermEndDate | 0..1 |
FixedTermStartDate | 0..1 |
InvoicingChannel | 1..1 |
InvoicingMethod | 1..1 |
IsDeliveryAgreement | 1..1 |
IsFixedTermAgreement | 1..1 |
IsInterruptionCritical | 1..1 |
IsSpecialTerminationAgreement | 1..1 |
MarketRole | 1..1 |
MeteringPointEAN | 1..1 |
OrganisationIdentifier | 1..1 |
ReasonForAgreementEnd | 0..1 |
ReasonForAgreementStart | 1..1 |
SpecialTerminationPeriod | 0..1 |
TerminationPeriodStartDate | 0..1 |
TerminationPeriodEndDate | 0..1 |
AgreementContacts | 0..n |
ContactPersonType | 1..1 |
EmailAddress | 0..1 |
FamilyName | 0..1 |
GivenName | 0..1 |
OtherName | 0..1 |
TelephoneNumber | 0..1 |
InvoiceAddresses (PostalInvoicingAddress) | 1..1 |
AddressNote | 0..1 |
Apartment | 0..1 |
BuildingNumber | 0..1 |
CountryCode | 1..1 |
InvoicingAddressType | 1..1 |
POBox | 0..1 |
PostalCode | 1..1 |
PostOffice | 1..1 |
StairwellIdentification | 0..1 |
StreetName | 0..1 |
InvoiceAddresses (ElectronicInvoicingAddress) | 0..1 |
BuyerReference | 0..1 |
ElectronicInvoicingAddress | 1..1 |
InvoicingAddressType | 1..1 |
OperatorIdentification | 1..1 |
InvoiceAddresses (OtherInvoicingAddress) | 0..1 |
EmailAddress | 0..1 |
InvoicingAddressType | 1..1 |
TelephoneNumber | 0..1 |
Products | 0..n |
ProductCode | 1..1 |
ProductName | 1..1 |
ProductNameLanguage | 1..1 |
Palautetut verkkosopimuksen tiedot
DH-1001 – Get contract data return for grid agreement | |
|---|---|
Nimi | Pakollisuus |
Agreements | 0..n |
AgreementEndDate | 0..1 |
AgreementIdentification | 1..1 |
AgreementStartDate | 1..1 |
AgreementStatus | 1..1 |
AgreementType | 1..1 |
ContactMethod | 1..1 |
CustomerNote | 0..1 |
InvoicingChannel | 1..1 |
InvoicingMethod | 1..1 |
IsDeliveryAgreement | 1..1 |
IsInterruptionCritical | 1..1 |
MarketRole | 1..1 |
MeteringPointEAN | 1..1 |
OrganisationIdentifier | 1..1 |
ReasonForAgreementEnd | 0..1 |
ReasonForAgreementStart | 1..1 |
TaxCategory | 1..1 |
AgreementContacts | 0..n |
ContactPersonType | 1..1 |
EmailAddress | 0..1 |
FamilyName | 0..1 |
GivenName | 0..1 |
OtherName | 0..1 |
TelephoneNumber | 0..1 |
InvoiceAddresses (PostalInvoicingAddress) | 1..1 |
AddressNote | 0..1 |
Apartment | 0..1 |
BuildingNumber | 0..1 |
CountryCode | 1..1 |
InvoicingAddressType | 1..1 |
POBox | 0..1 |
PostalCode | 1..1 |
PostOffice | 1..1 |
StairwellIdentification | 0..1 |
StreetName | 0..1 |
InvoiceAddresses (ElectronicInvoicingAddress) | 0..1 |
BuyerReference | 0..1 |
ElectronicInvoicingAddress | 1..1 |
InvoicingAddressType | 1..1 |
OperatorIdentification | 1..1 |
InvoiceAddresses (OtherInvoicingAddress) | 0..1 |
EmailAddress | 0..1 |
InvoicingAddressType | 1..1 |
TelephoneNumber | 0..1 |
Products | 1..n |
ProductCode | 1..1 |
ProductName | 1..1 |
ProductNameLanguage | 1..1 |
DH-1002 Aikasarjatietojen noutaminen
POST-menetelmä
Resurssin kuvaus | |||
|---|---|---|---|
Määritelmä | Rajapinta valitun käyttöpaikan mittaustietojen pyytämiseen | ||
Polun parametrit | |||
{funktio} | GetTimeSeriesDataPost | ||
Sanoman parametrit | |||
Nimi | Tyyppi | Velvoite | Huomautus |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
|
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
|
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
|
{JaksonAlku} | Aikaleima | Pakollinen | Aikasarjojen alku |
{JaksonLoppu} | Aikaleima | Pakollinen | Aikasarjojen loppu |
{MittauksenAika-askel} | Merkkijono(25) | Valinnainen |
|
{TuotteenTyyppi} | Teksti(25) | Valinnainen | 8716867000030 = pätöenergia 8716867000047 = loisenergia (kaikki) |
{Lukematyyppi} | Merkkijono(4) | Valinnainen | BN01 = Mitattu BN02 = Netotettu BN03 = Energiayhteisö Jos tyyppiä ei anneta, palautetaan kaikkien tyyppien sarjat. |
Kelpoisuussäännöt | |||
Pyynnön esittäneellä osapuolella olisi oltava voimassa oleva sopimus (myynti-, verkko- tai valtuutussopimus) asiakkaan kanssa pyynnön koko tietojaksolta (alkamisaika -> päättymisaika). Sopimuskauden ulkopuolisia tietoja ei palauteta. | |||
Vastaus | |||
Valitun käyttöpaikan valitun aikavälin mittaustiedot valitun aika-askeleen mukaan. Myös loisenergia palautetaan, jos nämä mittaukset ovat käytettävissä käyttöpaikasta. (Huomautus: puuttuvat mittarin data-arvot pyydetyltä aikaväliltä aiheuttavat aukkoja aikajanaan.) Jos pyynnössä ei anneta aikasarjatyyppiä, sekä pätö- että loisenergian aikasarjat palautetaan. Aika-askeleen syöttöparametriin sovelletaan seuraavia sääntöjä:
| |||
Esimerkkipyyntö | |||
https://{palvelin}/rest/FGR/GetTimeSeriesDataPostSanoman sisältö: {
"GetTimeSeriesDataRequest": {
"organisationUser": "{OrganisaationKäyttäjä}",
"Filters": {
"meteringPointEAN": "{KäyttöpaikanEAN}",
"customerIdentification": "{AsiakkaanTunnus}",
"periodStartTS": "{JaksonAlku}",
"periodEndTS": "{JaksonLoppu}",
"resolutionDuration": "{MittauksenAika-askel}",
"productType": "{TuotteenTyyppi}",
"readingType": "{Lukematyyppi}"
}
}
} | |||
GET-menetelmä
GET-menetelmä poistuu käytöstä version 2.6 käyttöönoton yhteydessä.
Resurssin kuvaus | |||
Määritelmä | Rajapinta valitun käyttöpaikan mittaustietojen pyytämiseen | ||
Polun parametrit | |||
{funktio} | GetTimeSeriesData | ||
Kyselymerkkijonon parametrit | |||
Nimi | Tyyppi | Velvoite | Huomautus |
{organisationUser} | String | Mandatory |
|
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
|
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
|
{JaksonAlku} | Aikaleima | Pakollinen | Aikasarjojen alku |
{JaksonLoppu} | Aikaleima | Pakollinen | Aikasarjojen loppu |
{MittauksenAika-askel} | Merkkijono(25) | Valinnainen |
|
{TuotteenTyyppi} | Teksti(25) | Valinnainen | 8716867000030 = pätöenergia 8716867000047 = loisenergia (kaikki) |
{Lukematyyppi} | Merkkijono(4) | Valinnainen | BN01 = Mitattu BN02 = Netotettu BN03 = Energiayhteisö Jos tyyppiä ei anneta, palautetaan kaikkien tyyppien sarjat. |
Kelpoisuussäännöt | |||
Pyynnön esittäneellä osapuolella olisi oltava voimassa oleva sopimus (myynti-, verkko- tai valtuutussopimus) asiakkaan kanssa pyynnön koko tietojaksolta (alkamisaika -> päättymisaika). Sopimuskauden ulkopuolisia tietoja ei palauteta. | |||
Vastaus | |||
Valitun käyttöpaikan valitun aikavälin mittaustiedot valitun aika-askeleen mukaan. Myös loisenergia palautetaan, jos nämä mittaukset ovat käytettävissä käyttöpaikasta. (Huomautus: puuttuvat mittarin data-arvot pyydetyltä aikaväliltä aiheuttavat aukkoja aikajanaan.) Jos pyynnössä ei anneta aikasarjatyyppiä, sekä pätö- että loisenergian aikasarjat palautetaan. Aika-askeleen syöttöparametriin sovelletaan seuraavia sääntöjä:
| |||
Esimerkkipyyntö | |||
https://{palvelin}/rest/FGR/GetTimeSeriesData?organisationUser={OrganisaationKäyttäjä}&meteringPointEAN={KäyttöpaikanEAN}&customerIdentification={AsiakkaanTunnus}&periodStartTS={JaksonAlku}&periodEndTS={JaksonLoppu}&resolutionDuration={MittauksenAika-askel}&productType={TuotteenTyyppi}&readingType={Lukematyyppi} | |||
Palautetut mittaustiedot
DH-1002 – Get time series data return | |
Nimi | Pakollisuus |
TimeSeries | 0..n |
MeteringPointEAN | 1..1 |
PeriodEndTS | 1..1 |
PeriodStartTS | 1..1 |
ProductType | 1..1 |
ReadingType | 1..1 |
ResolutionDuration | 1..1 |
UnitType | 1..1 |
Observations | 1..n |
PeriodStartTime | 1..1 |
Quality | 1..1 |
Quantity | 1..1 |
DH-1003 Valtuutustietojen noutaminen
POST-menetelmä
Resurssin kuvaus | ||
|---|---|---|
Määritelmä | Rajapinta valtuutustietojen pyytämistä varten | |
Polun parametrit | ||
{funktio} | GetAuthorisationDataPost | |
Sanoman parametrit | ||
Nimi | Tyyppi | Velvoite |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
Kelpoisuussäännöt | ||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva valtuutus asiakkaan kanssa pyynnön esittämisen aikaan. | ||
Vastaus | ||
Valtuutustiedot, jotka ovat voimassa pyynnön esittämisen aikaan. | ||
Esimerkkipyyntö | ||
https://{palvelin}/rest/FGR/GetAuthorisationDataPostSanoman sisältö: {
"GetAuthorisationDataRequest": {
"organisationUser": "{OrganisaationKäyttäjä}",
"Filters": {
"meteringPointEAN": "{KäyttöpaikanEAN}",
"customerIdentification": "{AsiakkaanTunnus}"
}
}
} | ||
GET-menetelmä
GET-menetelmä poistuu käytöstä version 2.6 käyttöönoton yhteydessä.
Resurssin kuvaus | ||
|---|---|---|
Määritelmä | Rajapinta valtuutustietojen pyytämistä varten | |
Polun parametrit | ||
{funktio} | GetAuthorisationData | |
Kyselymerkkijonon parametrit | ||
Nimi | Tyyppi | Velvoite |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
{KäyttöpaikanEAN} | Merkkijono(18) | Pakollinen |
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
Kelpoisuussäännöt | ||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva valtuutus asiakkaan kanssa pyynnön esittämisen aikaan. | ||
Vastaus | ||
Valtuutustiedot, jotka ovat voimassa pyynnön esittämisen aikaan. | ||
Esimerkkipyyntö | ||
https://{palvelin}/rest/FGR/GetAuthorisationData?organisationUser={OrganisaationKäyttäjä}&meteringPointEAN={KäyttöpaikanEAN}&customerIdentification={AsiakkaanTunnus} | ||
Palautetut valtuutustiedot
DH-1003 – Get authorisation data return | |
|---|---|
Nimi | Pakollisuus |
Agreements | 0..n |
AgreementEndDate | 1..1 |
AgreementStartDate | 1..1 |
AgreementStatus | 1..1 |
AgreementType | 1..1 |
AuthorisationDescription | 0..1 |
AuthorisationReason | 1..1 |
MarketRole | 1..1 |
MeteringPointEAN | 1..1 |
OrganisationIdentifier | 1..1 |
DH-1005 Asiakastietojen noutaminen
POST-menetelmä
Resurssin kuvaus | ||
|---|---|---|
Määritelmä | Rajapinta asiakastietojen pyytämistä varten | |
Polun parametrit | ||
{funktio} | GetCustomerDataPost | |
Sanoman parametrit | ||
Nimi | Tyyppi | Velvoite |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
Kelpoisuussäännöt | ||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva sopimus tai valtuutus asiakkaan kanssa pyynnön esittämisen aikaan. Myös tulevaisuudessa alkavat sopimukset ja sopimukset, jotka ovat päättyneet 6 viikon sisällä ennen pyynnön ajankohtaa, palautetaan. | ||
Vastaus | ||
Asiakastiedot, luettelo asiakkaan sopimuksista sekä mittauspisteen tunnus ja osoite, jotka ovat voimassa pyynnön esittämisen aikaan. | ||
Esimerkkipyyntö | ||
https://{palvelin}/rest/FGR/GetCustomerDataPostSanoman sisältö: {
"GetCustomerDataRequest": {
"organisationUser": "{OrganisaationKäyttäjä}",
"Filters": {
"customerIdentification": "{AsiakkaanTunnus}",
}
}
} | ||
GET-menetelmä
GET-menetelmä poistuu käytöstä version 2.6 käyttöönoton yhteydessä.
Resurssin kuvaus | ||
|---|---|---|
Määritelmä | Rajapinta asiakastietojen pyytämistä varten | |
Polun parametrit | ||
{funktio} | GetCustomerData | |
Kyselymerkkijonon parametrit | ||
Nimi | Tyyppi | Velvoite |
{OrganisaationKäyttäjä} | Merkkijono | Pakollinen |
{AsiakkaanTunnus} | Merkkijono(50) | Pakollinen |
Kelpoisuussäännöt | ||
Pyynnön esittäneellä osapuolella on oltava voimassa oleva sopimus tai valtuutus asiakkaan kanssa pyynnön esittämisen aikaan. Myös tulevaisuudessa alkavat sopimukset ja sopimukset, jotka ovat päättyneet 6 viikon sisällä ennen pyynnön ajankohtaa, palautetaan. | ||
Vastaus | ||
Asiakastiedot, luettelo asiakkaan sopimuksista sekä mittauspisteen tunnus ja osoite, jotka ovat voimassa pyynnön esittämisen aikaan. | ||
Esimerkkipyyntö | ||
https://{palvelin}/rest/FGR/GetCustomerData?organisationUser={OrganisaationKäyttäjä}&customerIdentification={AsiakkaanTunnus} | ||
Palautetut asiakastiedot
DH-1005 – Get customer data return | ||
|---|---|---|
Nimi | Pakollisuus | Huomautus |
Customers | 0..1 |
|
AdditionalIdentification | 0..1 |
|
CompanyName | 0..1 |
|
CustomerIdentification | 1..1 |
|
CustomerIdentificationType | 1..1 |
|
CustomerSubtype | 1..1 |
|
CustomerType | 1..1 |
|
DateOfBirth | 0..1 |
|
EmailAddress | 0..1 |
|
FamilyName | 0..1 |
|
GivenName | 0..1 |
|
IsInformationRestricted | 1..1 |
|
Language | 1..1 |
|
MiddleNames | 0..1 |
|
TelephoneNumber | 0..1 |
|
CustomerPostalAddress | 1..1 |
|
AddressNote | 0..1 |
|
Apartment | 0..1 |
|
BuildingNumber | 0..1 |
|
CountryCode | 1..1 |
|
POBox | 0..1 |
|
PostalCode | 1..1 |
|
PostOffice | 1..1 |
|
StairwellIdentification | 0..1 |
|
StreetName | 0..1 |
|
Agreements | 1..n |
|
AgreementEndDate | 0..1 |
|
AgreementStartDate | 1..1 |
|
AgreementStatus | 1..1 |
|
AgreementType | 1..1 |
|
MeteringPoint | 1..1 | Sopimukseen liittyvä käyttöpaikka |
MeteringPointEAN | 1..1 |
|
MeteringPointStatus | 1..1 |
|
MeteringPointAddress | 1..1 | Käyttöpaikan pääosoite |
AddressNote | 0..1 |
|
Apartment | 0..1 |
|
BuildingNumber | 0..1 |
|
CountryCode | 1..1 |
|
Language | 1..1 |
|
PostalCode | 1..1 |
|
PostOffice | 1..1 |
|
StairwellIdentification | 0..1 |
|
StreetName | 0..1 |
|