Transport, hovedforsendelser og forsendelser - hvordan sende inn meldinger

Sekvens for innsending av meldinger (POST)

Generelt fungerer innsending av informasjon slik at aktøren sender inn en melding (POST) og mottar en referanse (requestId). Ved å bruke den mottatte referansen kan aktøren spørre (GET) om resultat av innsendingen og ved suksess motta en permanent referanse til meldingen, utstedt av Tolletaten.

Dette gjøres på et eget endepunkt (/validation-status) i spørre-API-et (query API) linket til lengre nede på denne siden. Disse tjenestene er asynkrone og man må derfor spørre inntil man får svar.

Valideringsrespons vil vanligvis være tilgjengelig i løpet 1 til 2 sekunder, men det kan ta lenger tid i enkelttilfeller. Spørring gjøres på /validation-status-endepunktet, som vil returnere MRN ved suksess og en liste med valideringsfeil hvis de finnes.
Den permanente referansen blir kalt et Master Reference Number, forkortet MRN. MRN brukes når meldinger skal oppdateres eller kanselleres (put/delete) for å referere til tidligere innsendte meldinger.
Valideringsendepunktet vil også kunne returnere en liste med dokumentstatuser for å indikere manglende opplysninger.

Anbefalt metode for innsending er at aktøren sender inn alle meldinger for oppretting (POST) som er aktuelle, og så venter 1-2 sekunder før spørring om validering (query API) .

For eksempel: om man har 500 forsendelser for en hovedforsendelse på en transport, så sender man inn (POST) alle 500 meldingene om forsendelse, venter et par sekunder, ber om validering og får tilbake MRN og status for alle de 500 meldingene.

Dersom man får status 404 ved kall til valideringsendepunktet må man vente litt og spørre igjen. Det anbefales å lage en algoritme som gjør gjentatte forsøk, inntil valideringsrespons mottas.

Se API-dokumentasjon for detaljer om endepunktene.

Valideringsfeil

Se denne siden for oversikt over de vanligste valderingsfeilene man kan få med mulige årsaker / korreksjoner for disse.

Dersom en forsendelse skulle få dirigeringssignaler flere ganger, er det det siste dirigeringssignalet som gjelder. For eksempel er det mulig for en forsendelse å først få ENTRY_PENDING for i neste omgang å få TO_CONTROL. Dersom en forsendelse man har meldt ikke får dirigeringssignal når man forventer, betyr det som regel at Tolletaten ikke har hatt tilstrekkelig tid til å behandle meldingen om forsendelse. Aktøren må da holde tilbake forsendelsene til man får et dirigeringssignal for den.

Kodeverk

En oversikt over de ulike kodeverkene meldingsinnholdet valideres mot er å finne på en egen side. I skjemaene på API-ene vil det være angitt hvilke kodeverk datafeltene blir validert mot.

API: Dokumentinnsending

I tillegg til informasjonen om forsendelse som leveres gjennom movement-API-ene, kan det også sendes inn faktura for forsendelser der det allerede er sendt inn en tolldeklarasjon. Dokumentasjon på dette API-et finner du her: Dokumentopplastning-API.

Aktuelle eksempler

Vi har laget en kort oversikt over hvordan meldingsinnhold for forsendelser vil kunne se ut basert på hvilken tollprosedyre som benyttes. Eksemplene finner du her.
På den samme siden er det informasjon om testdata knyttet til tolldeklarasjoner som kan brukes i forbindelse med test av grensesnittet.

Autentisering – Datautveksling mellom næringslivet og Tolletaten

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 API-ene er dokumentert på hvert enkelt API.