API for dokumentopplasting

Om tjenesten

API-et støtter maskinell innsending av underlagsdokumenter.

Tolletaten gjør det nå mulig å sende inn all nødvendig underlagsdokumentasjon til deklarasjoner på forhånd, slik at den er tilgjengelig for Tolletaten før varene ankommer grensen. Dette kan bidra til redusert behov for å bli kontaktet i forbindelse med for eksempel dokumentkontroll, siden Tolletaten allerede har den nødvendige dokumentasjonen.
Vi ønsker at så mange som mulig av virksomhetene som deklarerer i Digitoll (mot ekspedisjonsenhetene 441002 og 441003), tar i bruk API-et for innsending av underlagsdokumentasjon knyttet til tolldeklarasjonen. Dokumenter som faktura, tillatelser, fraktregning, opprinnelsesdokumentasjon eller fraktbrev, kan sendes uoppfordret og på forhånd.
Dokumentene kan også sendes inn via API-et i de tilfellene hvor Tolletaten krever dokumentkontroll, om man ikke har sendt de på forhånd.

Dokumentene knyttes til tolldeklarasjonen i TVINN.
For å kunne bruke tjenesten må scope for autentisering mot Maskinporten settes til toll:goodsdeclaration/document.write

Grensesnittbeskrivelse

Tjenestene gjøres tilgjengelige som en REST-tjenester over HTTPS, med data på JSON-format.

Dersom du oppdager sikkerhetsutfordringer i våre løsninger ber vi deg ta kontakt; se her for info.

POST https://<env>/api/goodsdeclaration/document/v2/declaration-id/{DeklarasjonsID}/document

der <env> er

• api.toll.no for produksjon
• api-test.toll.no for playground (testmiljø)

og {DeklarasjonsID} byttes ut med TVINN deklarasjons-ID som angis på følgende format: "123456789-01092023-1" der første del er deklarantnummer, andre del deklarasjonsdato på format ddmmyyyy og tredje del sekvensnummer.

Se detaljert API-dokumentasjon her.

HTTP Request

Metode: POST
Endepunkt: /goodsdeclaration/document/v2/declaration-id/{DeklarasjonsID}/document

Headers

• Authorization: Bearer Token
  Tokenet som kreves er et Toll-signert JWT med scopet toll:goodsdeclaration/document.write fra Maskinporten (se beskrivelse av autentisering lenger ned på siden).

Body

• Media Type: Form Data
• Innhold:
  • metadata: {"declarationId": "Sett inn deklarasjons-id her", "documentType": "Sett inn dokumenttype her"}
  • file: Ditt dokument
• Dokumenttype må være en av
  • faktura
  • tillatelser
  • fraktregning
  • opprinnelsesdokumentasjon
  • fraktbrev
• Filtype må være en av
  • pdf
  • jpg
  • png
  • txt
  • doc
  • docx
  • xls
  • xlsx
• Maks 10MB i filstørrelse per vedlegg. Dersom vedlegget er større, må du dele denne opp i flere deler som hver er mindre enn 10MB.
• NB! Rekkefølgen på feltene i innholdet må være samme som oppgitt over

Eksempel i Postman

Body

Auth

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 dette API-et er toll:goodsdeclaration/document.write.