Om tjenesten
Tjenesten brukes for digital fremlegging av sendinger. Alt gods som er forhåndsmeldt er pliktig også å fremlegge med melding til dette API-et. Fra mars 2023 omfatter det alle sendinger som fraktes med fly fra tredjeland, fra 3. juni 2024 gjelder det også maritime sendinger. Med tredjeland menes land utenfor EUs sikkerhetssone (EU, Sveits, Liechtenstein og Norge unntatt Svalbard). Den samme tjenesten kan brukes for felles fremlegging iht. forhåndsvarsling og melde- og opplysningsplikten. Fremlegging kan gjøres ved å sende en hel forflytningsdeklarasjon (ENS), en postsekk (receptacle) eller enkeltsendinger (House Consignment). Dersom en postsekk eller en forflytningsdeklarasjon fremlegges, vil alle enkeltsendingene som er forhåndsmeldt under denne bli ansett som fremlagt. Videre skal den som har fremlagt sendingene også bruke tjenesten for kontrolldirigering (routing) før godset eventuelt kan innpasseres. Når man fremlegger ICS2-sendinger er det kun routing av forsendelse (house consignment) som er relevant (for enkelte aktører kan tjenesten for routing på transportnivå bli aktuelt ifm. melde- og opplysningsplikten). Basert på resultatet fra dirigeringen skal sendingene som har fått signalet TO_CONTROL overleveres til avtalt kontrollsted. Sendinger skal ikke utleveres før signalet TO_ENTRY er mottatt.
Mer informasjon om ICS2:
- ICS2 på toll.no
- Guidancedokumenter fra EU
- Forskrift om inn- og utførsel av varer (vareførselsforskriften)
Bruksflyt
Fremleggingstjenestene skal kalles så fort forsendelsen er ankommet. Ved å sende med requestId på alle kall vil du som konsument kunne sikre at en forsendelse kun fremlegges én gang. Gjenbruk av samme requestId vil medføre valideringsfeil. Dette er kun en teknisk identifikasjon av hver enkelt tjenestekall. Status på alle requester kan hentes ut ved å bruke validation-statustjenesten.
Når en forsendelse er korrekt fremlagt kan kontrolldirigeringssignal hentes fra routing-tjenesten. Det vil si informasjon om hvorvidt sendingen må leveres til kontroll eller at den kan innpassere og utleveres til mottaker når øvrige tollprosedyrer er ferdigstilt. Kontrolldirigering gjøres kun på enkeltsendings-nivå (house consignment), men fremlegging på postsekk- eller ENS-nivå (Entry Summary Declaration) vil medføre at resultat skal hentes for alle enkeltsendinger som er forhåndsmeldt i den aktuelle postsekk eller ENS. Ved å bruke marker som input kan du enkelt hente ut endringer siden forrige uthenting.
Grensesnittbeskrivelse
Tjenestene er tilgjengelige over HTTPS, med autentisering via Maskinporten.
POST https://<env>/api/movement/presentation/v1/house-consignment
POST https://<env>/api/movement/presentation/v1/master-consignment
POST https://<env>/api/movement/presentation/v1/container
POST https://<env>/api/movement/presentation/v1/receptacle
POST https://<env>/api/movement/presentation/v1/entry-summary-declaration
GET https://<env>/api/movement/presentation/v1/validation-status
GET https://<env>/api/movement/routing/v1/house-consignment
der
-
<env> byttes ut med
- api.toll.no for produksjon
- api-test.toll.no for playground (testmiljø)
- {requestId} byttes ut med referansen som returneres ved POST/PUT/DELETE-kall
- {MRN} byttes ut med referansen som returneres fra ".../validation-status..."-endepunktene.
API-et er under utvikling i takt med behov i Tolletatens digitaliseringsprogram slik at vi på sikt har en komplett fremleggingstjeneste for alle plikter ved varers ankomst. Vi vil i størst mulig grad gjøre endringer bakoverkompatible, men dersom det skulle skje ikke-kompatible endringer vil tjenesten versjoneres og endringen formidles til konsumentene. Bakoverkompatible endringer legges til uten versjonsoppdatering eller varsling.
Har du spørsmål eller innspill til API-et, hører vi gjerne fra deg på epost digitoll@toll.no.
API-dokumentasjon
Kodeverk
Tollsteder - Customs Office of presentation CL141
Customs Office of Presentation valideres etter EU-kodeverk Reference Data & Customs Offices List (europa.eu)
Transportdokumenttype CL754
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:movement/entry.
Testing
For test kan playground-miljøet brukes.
Valideringen av innsendte meldinger inneholder blant annet en kontroll mot at oppgitte referanser til "Entry Summary Declaration", postsekk og fraktbrev eksisterer. I playground-miljøet har vi ikke integrasjon mot andre fagsystemer, så innholdet valideres mot en statisk liste som inneholder noen få verdier.
(Tabellen er bred, det er mulig du må scrolle for å se alt)
| Entry Summary Declaration MRN | Receptacle ID | TransportDocumentHouseLevel – documentNumber | TransportDocumentHouseLevel – type | ContainerId | Routing |
|---|---|---|---|---|---|
|
23NO00000000000001 |
GBASFZMLBKONAUN30001001019999 |
NO100000001MU |
N750 |
– |
TO_CONTROL |
|
23NO00000000000002 |
GBASFZMLBKONAUN30001001019999 |
NO100000002MU |
N750 |
– |
TO_ENTRY |
|
23NO00000000000003 |
– |
HC001 |
N740 |
– |
TO_ENTRY |
|
23NO00000000000003 |
– |
HC002 |
N740 |
– |
TO_CONTROL |
|
23NO00000000000004 |
– |
HC001 |
N703 |
– |
TO_CONTROL |
|
23NO00000000000004 |
– |
HC002 |
N703 |
– |
TO_ENTRY |
|
23NO00000000000005 |
– |
HC003 |
N714 |
JARU0000010 |
TO_CONTROL |
|
23NO00000000000005 |
– |
HC004 |
N714 |
JARU0000026 |
TO_ENTRY |
Dirigeringssignaler som man får hentet ut i playground-miljøet er også en statisk liste og vil være basert på de samme verdiene. Øvrige verdier vil gi valideringsfeil ved innsending.
Tilbakemeldinger og kontakt
Har du spørsmål eller innspill til API-et, hører vi gjerne fra dere på epost ics2-kontakt@toll.no