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

Dato	Endring
22.02.2024	Lagt til eksempel for overskriving og fikset feil i swagger
17.11.2023	Lagt 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

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

Enhettype

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

Energikilde

Id	Verdi	Enhet
149	Bensin	liter
150	Biodiesel FAME	liter
151	Biodiesel HVO 100	liter
152	Biodiesel annen	liter
153	Bioetanol E85	liter
154	Biogass	kg
155	Elektrisitet	kWh
156	Fossil diesel	liter
157	Hydrogen	kg
158	Naturgass CNG	kg
159	Naturgass CNG	liter
160	Naturgass LNG	kg
161	Naturgass LNG	liter

Målekilde

Id	Verdi
162	Rådata
163	Beregnet
164	Avlest

Utkjørt lengde kilde

Id	Verdi
165	GPS
166	Km-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