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

transportinformasjon fra Digitoll/MO-løsningene
data fra løsninger tilknyttet operatører på kontinentalsokkelen eller Svalbard (som ikke deklarer innførsel/utførsel via Tvinn-systemet)

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å

hvilke datafelter vi deler med deg som klient — dette kan være færre enn den totalen som ligger i dataskjemaet, og kommer an på samarbeidsavtaler og hjemler
hvilke varelinjer du får, normalt basert på varenummer — på samme måte klienttilpasset basert på avtaler og hjemler
- merk at det er avtalene som gjelder på publiseringstidspunktet som gjelder, normalt vil ikke utvidelser gis tilbakevirkende kraft, og dersom du som klient får snevrere hjemler, er det ditt ansvar å kaste data du allerede har mottatt, eller som ligger som hendelser publisert før endringen trådte i kraft
- tilsvarende kan tolltariffen endres over tid, vi vil ikke republisere eldre hendelser ved slike endringer

Omberegning, korreksjoner

Det skjer jevnlig at det kommer korreksjoner og omberegninger på tolldeklarasjoner. I slike tilfeller vil vi sende ut

slettehendelser på varelinjer som er fjernet eller endret på deklarasjonen (i praksis vil dette ofte være alle varelinjene på en deklarasjon, siden det ikke er noen nødvendig kobling på varelinjenivå mellom gammel og ny deklarasjon),
eventuelt etterfølgende opprettelseshendelser for varelinjer som er nye eller endret

I begge tilfeller vil vi 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 versjonene 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.

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/declaration/declaration-item-feed/v1/

<env> byttes ut med
- api.toll.no for produksjon
- api-test.toll.no for playground (testmiljø)

Se detaljert API-dokumentasjon her.

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": {
  }
}

Lenke til schemaet kommer senere her.

Hendelsestype (eventType)

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

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.
ITEM_ADDED benyttes for nye og endrede varelinjer, og inneholder naturlig nok både konvolutt- og datadelen fordi innholdet er ny informasjon.

Parametre

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

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)
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
skip=N for å hoppe over N forekomster som ellers ville vært med i utvalget – mest med av hensyn til kompatibilitet med oppslagstjenester
max=N for å be om et maks antall forekomster som er mindre eller lik (ikke større enn) maks antall for denne tjenesten

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

hvordan du kommer i gang med integrasjon via Maskinporten om du ikke har gjort det før, inkludert registreringsskjema for tilgang hos Tolletaten
tilgangsstyring for våre API-er
hvordan sette opp en klient for å autentisere via Maskinporten
drift og overvåking/feilsøking.

Scopet som benyttes for dette API-et er toll:declaration.feed.