Om tjenesten

Datadelingstjenesten er en uthentingstjeneste for deklarasjonsdata. Den er generell og uten aggregering, slik at konsumenter selv kan prosessere, summere, og sammenstille deklarasjonsdata etter behov.

Tjenesten er kun tilgjengelig for sektormyndigheter / samarbeidspartnere som har en avtale med Tolletaten om deling av slike data.

Tjenesten tilbyr en serie av hendelser, hvor én hendelse omhandler én varelinje med tilhørende informasjon fra deklarasjonen. For en deklarasjon med flere varelinjer vil derfor samme deklarasjonsinformasjon gjentas i hver hendelse som gjelder varelinjene for denne deklarasjonen. Hendelser publiseres når etatens behandling er ferdig (typisk når varen er frigitt, men også når omberegninger/endringer er ferdigbehandlet), ikke underveis i behandlingen, og ikke i sanntid. Det er også viktig å merke seg at tjenesten per nå ikke omfatter

Grensesnittbeskrivelse

Generelt om den hendelsesbaserte tjenesten

Tjenesten er designet som en "feed" eller hendelsesstrøm uten noen teoretisk ende, som returnerer et antall hendelser i hvert kall. Det legges ikke opp til long polling eller tilsvarende utvidelser, vi antar at jevnlige kall til tjenesten vil være et enkelt og velfungerende for denne type tjeneste.

Som klient velger du i utgangspunktet selv hvor ofte du kaller tjenesten (innenfor gitte rammer), du oppgir normalt ID for den siste forekomsten du kjenner til (heretter kalt "markør"), og vil få data nyere enn markøren. Siden det er en begrensning på antall hendelser som returneres per kall, kan det hende du trenger å kalle tjenesten flere ganger før du er ajour. Gitt tjenestenes natur, ber vi deg derfor også avstemme hyppigheten på kall til mengden data du mottar, dersom vi opplever at klientene poller for ofte, må vi vurdere å innføre maskinelle begrensninger på dette, men håper i utgangspunktet å slippe. Basert på forventet initielt datavolum, vil vi anta at ca én gang per minutt (og så umiddelbart flere kall dersom max antall returneres) vil være et sted å starte.

Tjenesten vil sitte på historiske data over en periode/tidsvindu, et bestemt antall måneder. Hvor mange måneder kan endre seg i fremtiden. Merk også at det vil være ulike hendelsestyper, hvor noen kan ta data ut av totalen — det er forventet at du som klient holder orden på dette. Det er ikke meningen at dette skal benyttes som en oppslagstjeneste, normalmønsteret skal være at du som klient henter hver hendelse kun én gang, og lagrer det du trenger hos deg selv. Muligheten for å "spole tilbake" er der for å dekke driftsforstyrrelser og uventede situasjoner. Som klient må du også kunne tåle tilfeldige duplikater av data, vi anbefaler at du sitter på en oversikt over ID-er på mottatte hendelser minst like lenge som nevnte tidsvindu, så du kan filtrere bort eventuelle duplikater. Dette kan være en ulempe for deg, men vi gjør dette for å lettere kunne parallellisere våre tjenester i takt med behov for ytelse.

Datastrømmen er ikke sanntidsoppdatert med henblikk på data Tolletaten mottar. Regn med at det kan være i størrelsesorden 1 times forsinkelse mellom vår ferdigstilling og påfølgende publisering av hendelser.

Det er ditt ansvar som konsument å definere, hjemle og følge opp hvor gamle data du sitter på. Tolletaten vil ikke sende slettemeldinger på gamle data, siden konsumentenes hjemler kan være ulike.

Utvalgsbegrensninger per konsument

Vi vil kunne sette begrensninger både på

Endringsmelding (omberegning), korreksjoner

Det skjer jevnlig at det kommer endringsmeldinger (tidligere kalt omberegninger), det vil si korreksjoner på ferdigbehandlede tolldeklarasjoner. I slike tilfeller vil vi sende ut

  1. slettehendelser for alle varelinjer på gammel deklarasjon
  2. etterfølgende opprettelseshendelser for alle varelinjer på ny deklarasjon

I begge tilfeller vil det kun bli sendt hendelser for de varelinjene som er innenfor ditt utvalg.

Slettehendelsene vil peke tilbake på hendelsen den sletter. Opprettelseshendelsene vil peke tilbake på foregående og opprinnelig deklarasjon (dersom det er flere endringer på en deklarasjon over tid, kan disse to være forskjellige). En eller begge av disse kan være ukjente for deg som klient, det kan jo være at disse tidligere deklarasjonene ikke hadde varelinjer som var innenfor ditt utvalg. Merk at det kan skje at det kan komme "endringer" som munner ut i samme nå-tilstand som før-tilstand — dette kan skje dersom det kommer endringer på informasjon som ikke inngår i ditt datasett (eller for den del i noen av klientens datasett), men som likevel trigger ny publisering og nye ID-er.

Nye versjoner

Det kan i noen spesielle tilfeller skje at det blir sendt en ny versjon av en deklarasjon som har blitt sendt før og som ikke er helt ferdigbehandlet enda. I slike tilfeller vil vi i likhet med for endringsmeldinger (omberegninger) sende ut

  1. slettehendelser for alle varelinjer i gammel versjon av deklarasjonen
  2. etterfølgende opprettelseshendelser for alle varelinjer i ny versjon av deklarasjonen

I begge tilfeller gjelder det også her at det kun vil bli sendt hendelser for de varelinjene som er innenfor ditt utvalg.

Slettehendelsene vil peke tilbake på hendelsen den sletter. Opprettelseshendelsene vil derimot ikke ha noen referanse til forrige versjon av deklarasjon. Merk at også for nye versjoner kan det skje at det kan komme "endringer" som munner ut i samme nå-tilstand som før-tilstand som nevnt for endringsmeldinger i forrige avsnitt.

Tekniske detaljer

Det returneres maksimalt 1.000 hendelser per kall. Du kan som konsument velge å motta færre, men ikke flere, hendelser i et gitt kall.

Strukturen på data som returneres kan variere, men vil være på JSON-format. Vi vil beskrive formater med JSON Schema. Datastrukturene vil også være beskrevet i OpenAPI-spesifikasjoner (Swagger) i testmiljøet, men ikke i produksjon.

Tjenesten er basert på REST over HTTPS og er tilgjengelig på: 

GET https://<env>/api/goodsdeclaration/goodsitem/v1/stream

Se detaljert API-dokumentasjon her.

Eksempel: 

GET https://api-test.toll.no/api/goodsdeclaration/goodsitem/v1/stream?...

JSON-schema

Kort forklart vil en hendelse bestå av en konvolutt-del og en data-del. Konvolutt-delen vil inneholde metainformasjon om hendelsen med bl.a. en hendelses-ID og et tidspunkt for når hendelsen ble opprettet. Data-delen vil inneholde informasjon om den aktuelle varelinjen med tilhørende deklarasjonsinformasjon, hvor feltnavnene skal være på tilnærmet EUCDM-format. 

{
  "metadata": {
    "eventId": "aec5b761-fa41-456a-97c0-950800aab20e",
    "created": "2026-01-19T17:29:10Z",
    "eventType": "ITEM_ADDED"
  },
  "data": {
  }
}

Skjemaet ligger foreløpig på toll-goodsdeclaration-goodsitem-stream-schema.json, med en eksempelfil her: toll-goodsdeclaration-goodsitem-stream-example.json,
denne adressen kan bli forandret.

Hendelsestype (eventType)

Som klient må du anta at det kan tilkomme nye hendelsestyper på en deklarasjon over tid.

  1. ITEM_REMOVED benyttes for varelinjer som er fjernet fra deklarasjon (eller fra ditt scope som klient), de kommer også før ITEM_ADDED for endrede varelinjer. Denne hendelsen inneholder kun konvoluttdelen, med en hendelses-ID for varelinjen som er endret/fjernet, det forventes at du som klient har oppbevart ID.
  2. ITEM_ADDED benyttes for nye og endrede varelinjer, og inneholder naturlig nok både konvolutt- og datadelen fordi innholdet er ny informasjon.
  3. ITEM_ADDED_NO_HISTORY benyttes for nye og endrede varelinjer for en deklarasjon som har en historikk som strekker seg lengre tilbake enn det datadelingsløsningen kjenner til (se kommentar under). I likhet med ITEM_ADDED inneholder den både konvolutt- og datadel.

Mer om ITEM_ADDED_NO_HISTORY

ITEM_ADDED_NO_HISTORY er en event-type som indikerer en ny hendelse hvor datadelingsløsningen ikke har kjennskap til tidligere historikk knyttet til deklarasjonen. Dette i motsetning til hendelser av typen ITEM_ADDED hvor tidligere historikk er kjent.

ITEM_ADDED_NO_HISTORY vil kunne forekomme i en av følgende tilfeller

  1. Hendelsen gjelder en endringsmelding (tidligere kalt omberegning) for en deklarasjon som er eldre enn historikken i datadelingsløsningen
  2. Hendelsen gjelder en ny versjon av en deklarasjon som er eldre enn historikken i datadelingsløsningen

Normalt skal det for endringsmeldinger og nye deklarasjonsversjoner leveres ITEM_REMOVED-hendelser knyttet til deklarasjonen eller versjonen som blir erstattet. Dette for å hindre at samme deklarasjonsinformasjon skal telle flere ganger i datagrunnlaget. Slike hendelser blir derimot ikke generert for hendelser av type ITEM_ADDED_NO_HISTORY siden datadelingsløsningen da ikke har kjennskap til hvilke hendelser som skal erstattes.

Forskjellen mellom hendelser med event-type ITEM_ADDED og ITEM_ADDED_NO_HISTORY er altså at førstnevnte vil generere nødvendige slettehendelser av typen ITEM_REMOVED, mens sistnevnte ikke vil det. Konsumentene av datadelingsløsningen må dermed vurdere om hendelser av typen ITEM_ADDED_NO_HISTORY skal tas med i datagrunnlaget deres eller ikke.

Etter som tiden går og historikken i datadelingsløsningen blir lengre, vil det imidlertid bli færre og færre hendelser av denne typen.

Parametre

Vi har et sett av parametere som er standard for slike API-er:

  1. last=ID angir ID for den siste forekomsten konsumenten har sett (markøren) – returnert datasett vil fortsette etter denne; merk:
    • den angitte forekomsten vil ikke være med i datasettet
    • det er ingen garanti for at ID-er i kall er en monotont voksende serie uten hull, tvert om må det antas at det ikke er det – vi bruker UUID-er
    • dersom ingen forekomst med angitt ID finnes, returneres status 404 (Not found)
  2. timestamp=YYYYMMDDTHHmmssZ – denne kan brukes i stedet for foregående dersom ID ikke er kjent, og angir tidsstempel for publisering, forekomster med tidsstempel >= denne verdien vil komme med i resultatet. Merk:
    • avhengig av parameterverdi kan man risikere overlapp eller hull i forhold til tidligere kall
    • som nevnt er det en "aldersgrense" på eldste forekomst, det er altså ingen garanti for at det faktisk finnes data like gammel som gitt parameter
  3. skip=N for å hoppe over N forekomster som ellers ville vært med i utvalget – mest med av hensyn til kompatibilitet med oppslagstjenester
  4. max=N for å be om et maks antall forekomster som er mindre eller lik (ikke større enn) maks antall for denne tjenesten

Det er obligatorisk å oppgi enten last eller timestamp.

Returverdier

200 OK — kallet er OK – dog kan det hende at datasettet som returneres er tomt, det kan skje dersom parametere er OK, men det ikke finnes nye data iht inngitte parametere; merk også at det kan være flere data tilgjengelige enn det som er returnert i dette kallet, dersom antall hendelser er lik maksgrensen (enten gitt av tjenesten eller av parameter max) bør tjenesten kalles på nytt for å hente neste bolk, dette signaleres altså ikke via returstatus

401 Unauthorized — benyttes dersom klienten ikke er autentisert riktig, dvs enten ikke har autentisert seg via Maskinporten, eller ikke har avtaler for å få utlevert data på denne tjenesten

404 Not found — dersom en ukjent ID er angitt som parameter last

Autentisering

Våre API-er benytter Maskinporten for identitets- og tilgangsstyring. På siden Maskinporten - Tolletaten finner du informasjon bl.a. om

Scopet som benyttes for dette API-et er toll:goodsdeclaration/goodsitem.stream.