Klimarapportering

Generell informasjon

Endepunktet for innrapportering av klimarapport forventer at dataene blir innsendt som JSON. Klimarapport er et versjonert endepunkt og det er viktig at man setter header Ver til 1.0 som vist i eksemplene.

Endringslogg

DatoEndring
22.02.2024Lagt til eksempel for overskriving og fikset feil i swagger
17.11.2023Lagt til endringslogg

KontraktId

Kontrakt id hentes ut under kontrakt info ved å logge inn med en entreprenør eller superbruker i ELRAPP.

Metadata

Metadata endepunktet gir metadata for miljøklasse, enhet type, energikilde, målekilde og utkjørt lengde kilde. Metadatene må bli brukt ved innsending av en klimarapport. Metadataene består av feltene id og verdi, hvor id er ett heltall og verdi en string. Metadata for energikilder har et ekstra felt og det er enheten til energikilden. Det er tilfeller der flere energikilder har samme navn/verdi men hvor enhet er forskjellig. Ved innsending så er det id som blir brukt.

Eksempel

GET /klimarapportering/metadata HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0
{
    "klimarapportMiljoklasseDtos": [],
    "klimarapportEnhetTypeDtos": [],
    "klimarapportEnergiKildeDtos": [        
        {
            "id": 157, //heltall, unik ID fra ELRAPP som bli brukt ved innsending
            "verdi": "Hydrogen", //string 
            "enhet": "kg" //string
        },
    ],
    "klimarapportMalekildeDtos": [],
    "klimarapportUtkjortLengdeKildeDtos": [        
        {
            "id": 165, //heltall, unik ID fra ELRAPP som bli brukt ved innsending
            "verdi": "GPS" //string
        }
    ]
}

Metadata i dagens løsning

Miljøklasse

IdVerdi
128Euro 1
129Euro 2
130Euro 3
131Euro 4
132Euro 5
133Euro 6
1340 - motor under 19kW
135Trinn I
136Trinn II
137Trinn IIIA
138Trinn IIIB
139Trinn IV
196Ukjent miljøklasse

Enhettype

IdVerdi
140Beltegraver
141Hjulgraver
142Hjullaster
143Traktor
144Dumper
145Lastebil
146Varebil
147Personbil
148Annen
167Lastebil(3,5-12t)
168Lastebil(over 12t)

Energikilde

IdVerdiEnhet
149Bensinliter
150Biodiesel FAMEliter
151Biodiesel HVO 100liter
152Biodiesel annenliter
153Bioetanol E85liter
154Biogasskg
155ElektrisitetkWh
156Fossil dieselliter
157Hydrogenkg
158Naturgass CNGkg
159Naturgass CNGliter
160Naturgass LNGkg
161Naturgass LNGliter

Målekilde

IdVerdi
162Rådata
163Beregnet
164Avlest

Utkjørt lengde kilde

IdVerdi
165GPS
166Km-teller

Innsending

Endepunktet tar imot en liste og listen må minimum inneholde ett innslag.

Validering og avhengigheter

Det som blir innsendt blir validert, hvis innsendt datasett ikke er gyldig så returnerer vi BadRequest med et objekt som inneholder en eller flere feilmeldinger. Objektet består av "errorMsg" og "data", kun en av de vil ha verdi om gangen. "errorMsg" er en string som gir tilbake feilmelding og blir brukt når det er større eller mer generelle feil. "data" feltet inneholder listen av det dere sendte inn. Hvert element i listen kan ha en feilmelding i "errorsMsg", se eksempel under.

Obligtoriske felter er kontraktId, enhetType, miljoklasse, energikilde, mengde, maleKilde, fra og til. Det er noen andre felter som kan være obligatorisk og de beskrives under.

Det er noen felter som har avhengigheter til andre felter. Det vil si at hvis et felt har verdi så må dette andre feltet også ha verdi, eller at hvis et felt har verdi så kan ikke disse andre feltene ha verdi. utkjortLengde og utkjortLengdeKilde har en slik avhengighet der hvis et av feltene har verdi så må det andre feltet også ha en verdi. motorTidSekunder, utkjortLengde og utkjortLengdeKilde har en slik avhengighet hvis motorTidSekunder har verdi så kan ikke de to andre ha verdi og det samme gjelder motsatt. enhetId, kjoretoyregistreringsnummer og maskinRegisternummer har en slik avhengighet at hvis et av feltene har verdi så kan ikke de to andre ha verdi.

Eksempel feilmeldingsobjekt

{
    "errorMsg": null,
    "data": [
        {
            "id": 0,
            "kontraktId": 5377,
            "kjoretoyregistreringsnummer": null,
            "maskinRegisternummer": "jkdfn-gflk",
            "enhetId": null,
            "arsmodell": 0,
            "miljoklasse": 128,
            "enhetType": 147,
            "modellbetegnelse": null,
            "energikilde": 149,
            "mengde": 2,
            "maleKilde": 164,
            "utkjortLengde": null,
            "utkjortLengdeKilde": null,
            "motorTidSekunder": 33234,
            "fra": "2023-01-24T07:02:00",
            "til": "2023-01-24T08:00:00",
            "datoOpprettet": "0001-01-01T00:00:00",
            "errorsMsg": ""
        },
        {
            "id": 0,
            "kontraktId": 5377,
            "kjoretoyregistreringsnummer": null,
            "maskinRegisternummer": "jkdfn-gflk",
            "enhetId": null,
            "arsmodell": 0,
            "miljoklasse": 128,
            "enhetType": 147,
            "modellbetegnelse": null,
            "energikilde": 149,
            "mengde": 2,
            "maleKilde": 164,
            "utkjortLengde": null,
            "utkjortLengdeKilde": null,
            "motorTidSekunder": 33234,
            "fra": "2023-01-24T07:02:00",
            "til": "2023-01-24T08:00:00",
            "datoOpprettet": "0001-01-01T00:00:00",
            "errorsMsg": "Det er overlapp på en eller flere perioder på enhet med MaskinRegisternummer = jkdfn-gflk og energikilde = 149 i innsendt data"
        }
    ]
}

Hybride energikilder

Hvis en enhet er hybrid, altså enhet bruker mer enn en energikilde så må dette registreres en gang pr. energikilde. F.eks hvis en man skal rapportere for en hybrid bil med diesel og elektrisitet så blir det ett innslag for diesel og et innslag eleketrisitet.

Overlapp

Vi tillater ikke overlapp i det som sendes inn. Med overlapp så mener vi at en enhet med en type energikilde i en periode skal være unik. Når enhet nevnes så menes det enhetId, kjoretoyregistreringsnummer eller maskinRegisternummer. Vi sjekker overlapp i det som sendes inn samt opp mot allerede innsendte data. Hvis det blir sendt inn overlapp så returnerer vi BadRequest med en et objekt som inneholder en eller flere feilmeldinger, se Validering og avhengigheter.

f.eks så sendes det inn med enhetId = EC343SDpgfj, energiKilde = diesel og periode = 2023-01-01 08:00:00-09:00:00 og det allerede er sendt inn for enhetId = EC343SDpgfj, energiKilde = diesel og periode = 2023-01-01 07:30:00-08:30:00 så vil dette bli sett på som overlapp og innsendingen vil feile.

Eksempel innsending

POST /klimarapportering/{kontraktId} HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0
[
    {
        "id": 0, //heltall, unik id i elrapp, den settes av ELRAPP ved innsending, sett verdi til 0
        "kontraktId": 5377, //heltall, Kontraktens unike id i ELRAPP
        "enhetId": "0ffvdvjn2048ru", //string, Enhetens entreprenør- og kontraktsunike nummer(alfanumerisk, maks. 30 tegn) om kjøretøyregistreringsnummer eller nummer i maskinregisteret ikke finnes
        "enhetType": 146, //heltall, sier noe om type enhet, verdi hentes fra metadata
        "arsmodell": 2023, //heltall, årsmodell for enheten
        "miljoklasse": 128, //heltall, sier hvilken miljøklasse enheten har, verdi hentes fra metadata
        "modellbetegnelse": "Test, modellbetegnelse", //string, fritekst, ikke nødvendig å gjenta info som finnes i f.eks. kjøretøyregisteret
        "energikilde": 149, //heltall, hvilken energikilde enheten bruker, verdi hentes fra metadata
        "mengde": 2.0, //double, mengden drivstoff/energi brukt av enhet
        "maleKilde": 163, //heltall, målekilde for rapportert forbrukt mengde, verdi hentes fra metadata
        "utkjortLengde": 3.0, //double, hvor langt en enhet har kjørt, kan også bruke motorTidSekunder hvis lengde ikke er relevant,maks 8 desimaler
        "utkjortLengdeKilde": 165, //heltall, Kilde for rapportert utkjørt lengde, verdi hentes fra metadata
        "fra": "2023-01-22T08:02:00", //Fra dato og klokkeslett
        "til": "2023-01-22T08:03:00", // til dato og klokkeslett
        "errorsMsg": "" //Blir brukt til feilmelding fra ELRAPP når ugydlig data har blitt sendt inn, se pkt. Validering og avhengigheter
    },
    {
        "id": 0, //heltall, unik id i elrapp, den settes av ELRAPP ved innsending, sett verdi til 0
        "kontraktId": 5377, //heltall, Kontraktens unike id i ELRAPP
        "maskinRegisternummer": "ererj49df", //string, nummer i maskinregisteret (reginn.no)
        "enhetType": 146, //heltall, sier noe om type enhet, verdi hentes fra metadata
        "arsmodell": 2023, //heltall, årsmodell for enheten
        "miljoklasse": 128, //heltall, sier hvilken miljøklasse enheten har, verdi hentes fra metadata
        "energikilde": 149, //heltall, hvilken energikilde enheten bruker, verdi hentes fra metadata
        "mengde": 2.0, //double, mengden drivstoff/energi brukt av enhet
        "maleKilde": 163, //heltall, målekilde for rapportert forbrukt mengde, verdi hentes fra metadata
        "motorTidSekunder": 33234, //heltall, hvor lenge en enhet har blitt brukt, oppgis i sekunder
        "fra": "2023-01-22T08:02:00", //Fra dato og klokkeslett
        "til": "2023-01-22T08:03:00", // til dato og klokkeslett
        "errorsMsg": "" //Blir brukt til feilmelding fra ELRAPP når ugydlig data har blitt sendt inn, se pkt. Validering og avhengigheter
    },
    {
        "id": 0, //heltall, unik id i elrapp, den settes av ELRAPP ved innsending, sett verdi til 0
        "kontraktId": 5377, //heltall, Kontraktens unike id i ELRAPP
        "kjoretoyregistreringsnummer": "EE12345", //string, kjøretøyregistreringsnummer 
        "enhetType": 146, //heltall, sier noe om type enhet, verdi hentes fra metadata
        "miljoklasse": 128, //heltall, sier hvilken miljøklasse enheten har, verdi hentes fra metadata
        "energikilde": 149, //heltall, hvilken energikilde enheten bruker, verdi hentes fra metadata
        "mengde": 2.0, //double, mengden drivstoff/energi brukt av enhet
        "maleKilde": 163, //heltall, målekilde for rapportert forbrukt mengde, verdi hentes fra metadata
        "motorTidSekunder": 33234, //heltall, hvor lenge en enhet har blitt brukt, oppgis i sekunder
        "fra": "2023-01-22T08:02:00", //Fra dato og klokkeslett
        "til": "2023-01-22T08:03:00", // til dato og klokkeslett
        "errorsMsg": "" //Blir brukt til feilmelding fra ELRAPP når ugydlig data har blitt sendt inn, se pkt. Validering og avhengigheter
    },
    ...
]

Overskriving

Det er mulig å overskrive det som er allerede sendt inn. Dette gjøres ved å bruke samme endepunkt som for innsending men hvor parameter "overskriv" er satt til true. Denne verdien er satt til false som default. Ved overskriving så blir eksisterende data overskrevet der disse dataene er like: (enhetId eller maskinRegisternummer eller kjoretoyregistreringsnummer) og energikilde og periode (fra, til) samsvarer. Det er viktig å vite at så lenge det er noe overlapp i perioden så vil eksisterende data bli overskrevet. Data som blir overskrevet blir lagt i en historikk tabell.

Eksempel innsending med overskriving

POST /klimarapportering/{kontraktId}?overskriv=true HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0
[
    {
        "id": 0, //heltall, unik id i elrapp, den settes av ELRAPP ved innsending, sett verdi til 0
        "kontraktId": 5377, //heltall, Kontraktens unike id i ELRAPP
        "enhetId": "0ffvdvjn2048ru", //string, Enhetens entreprenør- og kontraktsunike nummer(alfanumerisk, maks. 30 tegn) om kjøretøyregistreringsnummer eller nummer i maskinregisteret ikke finnes
        "enhetType": 146, //heltall, sier noe om type enhet, verdi hentes fra metadata
        "arsmodell": 2023, //heltall, årsmodell for enheten
        "miljoklasse": 128, //heltall, sier hvilken miljøklasse enheten har, verdi hentes fra metadata
        "modellbetegnelse": "Test, modellbetegnelse", //string, fritekst, ikke nødvendig å gjenta info som finnes i f.eks. kjøretøyregisteret
        "energikilde": 149, //heltall, hvilken energikilde enheten bruker, verdi hentes fra metadata
        "mengde": 2.0, //double, mengden drivstoff/energi brukt av enhet
        "maleKilde": 163, //heltall, målekilde for rapportert forbrukt mengde, verdi hentes fra metadata
        "utkjortLengde": 3.0, //double, hvor langt en enhet har kjørt, kan også bruke motorTidSekunder hvis lengde ikke er relevant,maks 8 desimaler
        "utkjortLengdeKilde": 165, //heltall, Kilde for rapportert utkjørt lengde, verdi hentes fra metadata
        "fra": "2023-01-22T08:02:00", //Fra dato og klokkeslett
        "til": "2023-01-22T08:03:00", // til dato og klokkeslett
        "errorsMsg": "" //Blir brukt til feilmelding fra ELRAPP når ugydlig data har blitt sendt inn, se pkt. Validering og avhengigheter
    },
    ...
]

Uthenting

Det eksisterer et endeunkt for uthenting. Endepunktet gjør de mulig å hente pr. kontrakt pluss det er parametre for å begrense uthentingen til en periode eller spesifikk enhet.

parametre: fra, til, enhetId, kjoretoyregisternummer og maskinRegisternummer. Ingen av parameterne er obligatorisk og det er ingen avhengighet mellom parameterne heller. Hvis du ikke sender med noen parametere så vil endepunktet returnere alle elementene for den kontrakten

Eksempel

GET /klimarapportering/{kontraktId} HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0

Hent alle innrapporteringene for kontrakt med id = 4255

GET /klimarapportering/4255 HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0

Hent alle innrapporteringene for kontrakt med id = 4255 og enhetId = 'TestEnhet1'

GET /klimarapportering/4255?enhetId=TestEnhet1 HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0

Hent alle innrapporteringene for kontrakt med id = 4255 og der elementene enten har enhetID = 'TestEnhet1' eller kjoretoyregisternummer = 'EC12345'

GET /klimarapportering/4255?enhetId=TestEnhet1&kjoretoyregisternummer=EC12345 HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0

Eksempel på uthentet data:

[
    {
        "id": 13,
        "kontraktId": 4255,
        "kjoretoyregistreringsnummer": "EC12345",
        "maskinRegisternummer": null,
        "enhetId": null,
        "arsmodell": 2021,
        "miljoklasse": 128,
        "enhetType": 146,
        "modellbetegnelse": null,
        "energikilde": 149,
        "mengde": 2,
        "maleKilde": 163,
        "utkjortLengde": null,
        "utkjortLengdeKilde": null,
        "motorTidSekunder": 33234,
        "fra": "2023-01-22T08:02:00",
        "til": "2023-01-22T08:03:00",
        "errorsMsg": ""
    }
]

Sletting

Det er mulig å slette data. Dette gjøres ved å sende inn fra dato, til dato, enhetens id (kjoretoyregistreringsnummer, maskinRegisternummer eller enhetId. Kun en av de) og energikilde. Det er viktig å vite at data slettes så lenge det er noen form for overlapp på perioden som gis. Data som blir slettet legges i en egen historikk tabell. Hvis det ikke finnes noe som kan slettes så returneres 204 No content.

Eksempel

DELETE /klimarapportering/{kontraktId}?fra={fra_dato}&til={til_dato}&enhetId={enhetId}&energiKilde={energiKilde} HTTP/1.1
Content-Type: application/json
Authorization: ApiKey 1b9a1439-25ef-436e-8558-49ae982f9689
Ver: 1.0
Last Updated:
Contributors: Adrian Kreutz, Øyvind Gujord