Maskinell innrapportering av lakselusrapporter

API-et gjør det mulig for sluttbrukere å integrere innrapporteringen i egne systemer, og er et alternativ for de som ikke ønsker å rapportere manuelt via Altinn.

Publisert: 16.08.2023

Hvordan bruke APIet

Swagger-dokumentasjonen inneholder en detaljert beskrivelse av REST API-et, sammen med informasjon om JSON-skjemaet:

API-et gjenspeiler innholdet i Altinn-skjemaet som ligger til grunn for manuell rapportering, slik at samme veiledning for feltinnhold gjelder. Veiledningen til skjemaet finner du også i Mattilsynets veiledning om rapportering av lakselus.

Autentisering

Klientkall blir autentisert ved bruk av bearer access-token som genereres av Maskinporten, se beskrivelser på Digdir Docs (digdir.no). Alle som oppretter en integrasjon i Maskinporten har tilgang til utviklings- og produksjonsmiljøet.

Når du oppretter en integrasjon (OAuth2-klient) i Maskinporten, bruker du følgende scope for å få tilgang: mattilsynet:akvakultur.lakselusrapportering

Obligatoriske felt og rapportering

I utgangspunktet spesifiserer Swagger-skjemaet de påkrevde feltene, og APIet som helhet gjenspeiler det som blir rapportert i Altinn-skjemaet. Likevel er det noen felt APIet setter implisitt basert på rapporterte data, i stedet for å spørre eksplicit som en boolsk verdi. Dette gjelder følgende spørsmål som finnes i Altinn-skjemaet, men ikke i APIet:

Er det telt lus for uken det rapporteres for?
Er det gjennomført behandling mot lakselus i uken det rapporteres for?
Har du mistanke om resistens?
Har du motatt resultater fra følsomhetsundersøkelser i løpet av uken?

Hvis svaret på ett eller flere av disse spørsmålene er nei, utelates det tilhørende JSON-elementet i kallet. For eksempel, hvis du ikke har telt lus, sender du ikke JSON-elementet knyttet lakselustelling i API-kallet. I dette tilfellet vil mottakstjenesten tolke dette som at det ikke er telt lus den uken.

Statuskoder

Ved bruk av API-et kan du forvente følgende statuskoder:

201 CREATED: alt gikk som forventet, alle valideringsregler ble godkjent, og rapporten ble registrert.
400 BAD REQUEST: innsendt data støtte på en eller flere valideringsregler, og rapporteringen må justeres for å bli akseptert. API-et returnerer en detaljert feilmelding som forklarer hva som eventuelt må rettes.
401 UNAUTHORIZED: det er noe galt med "access-tokenet", som fører til at APIet ikke tillater at rapporten blir sendt inn. Typiske kilder til denne feilen kan være at "access-tokenet" er for gammelt, feil "scope" er konfigurert, eller man forsøker å bruke Maskinporten-integrasjonen fra utviklingsmiljøet i produksjon (eller omvendt).

Rapportering på vegne av andre virksomheter

Nytt lakselusskjema er tilgjengelig for alle, men en aktør som rapporterer på vegne av andre (betegnet som leverandør) må få delegert rapporteringsrettigheter i Altinn fra selskapet det skal rapporteres på vegne av (betegnet som konsument).

Konsumenter kan delegere API-tilgang til en annen part gjennom Altinn. Dermed kan leverandøren inkludere informasjon om hvilket selskap de rapporterer for ved innsending av lakselusskjema. Denne informasjonen er da verifisert og sikret og man kan da garantere at leverandøren har fått tilgang fra konsumenten til å rapportere på deres vegne.

Du finner full beskrivelse av delegering i Maskinporten med Altinn hos Digitaliseringsdirektoratet (digdir.no).

Delegering i Altinn (for konsument)

Bemyndiget ansatt hos API-konsument logger inn i Altinn, velger å representere foretaket, søker opp og delegerer API-tilgangen videre til leverandøren i portal-løsningen. Du finner mer detaljert veiledning hos Altinn (github.io).

Leverandør

Når konsumenten har delegert API-tilgangen til leverandør, kan leverandøren forespørre token fra Maskinporten. Du ser hvilke token som er tilgjgengelige på Maskinporten (digdir.no). Leverandøren må inkludere API-konsumentens organisasjonsnummer i consumer_org-claimet i JWT-grantet.

Vanlige spørsmål og svar

I lakselusrapporteringobjektet er det et felt som heter "referanse". Hva skal stå i dette feltet?

I dette feltet setter du en egengenerert og unik referanse som identifiserer rapporten din, eksempelvis en autogenerert UUID eller annen systemgenerert referanse. Vi bruker dette feltet for å øke sporbarheten og gjøre det enklere for begge parter å finne tilbake til enkeltrapporter.

I behandlingsobjektet er det et subobjekt kalt kombinasjonsbehandlinger. Hva er denne til?

Dette subobjektet er ment for å rapportere enkeltbehandlinger som består av flere behandlingsmetoder. Lakselusrapporteringsobjektet inneholder subobjektene "ikkeMedikamentellBehandlinger", "medikamentellBehandlinger" og "kombinasjonsBehandlinger". Mens de to førstnevnte tillater utelukkende rapportering av en behandling per objekt, kan en "kombinasjonsBehandling" bestå av en kombinasjon av flere "ikkeMedikamentellBehandlinger" og/eller "medikamentellBehandlinger".

I virkestoffobjektet er det et string felt kalt "Styrke". Hva er forventet her?

Det er mulig å se alle tillatte verdier i API swagger dokumentasjonen under "Schemas". For styrke er tillatte verdier MILLIGRAM_PER_GRAM, MILLIGRAM_PER_MILLILITER, GRAM_PER_KILO, MILLIGRAM_PER_KILO, og PROSENT.

Hvordan registreres bruk av rensefisk?

Bruk av rensefisk skal rapporteres i biomasserapporteringen til Fiskeridirektoratet. Lakselusrapporteringen gir derfor ikke mulighet til å rapportere bruk av rensefisk.

Andre spørsmål og feilmeldinger

Eventuelle spørsmål om maskinell rapportering og feilmeldinger kan sendes til team-akva@mattilsynet.no