Transport, Master Consignments and Consignments - How to Submit Messages
Sequence for Submitting Messages (POST)
Generally, the submission of information works such that the actor sends a message (POST) and receives a reference (requestId). By using the received reference, the actor can query (GET) the result of the submission and upon success receive a permanent reference to the message, issued by Norwegian Customs.
This is done at a dedicated endpoint
(/validation-status) in the query API
linked further down on this page. These services are
asynchronous and therefore one must query until a
response is received.
Validation responses are usually available within
1 to 2 seconds, but it may take longer in some cases. Querying is done
at the /validation-status endpoint, which will
return the MRN upon success and a list of validation errors
if any.
The permanent reference is called a Master Reference
Number, abbreviated MRN. MRN is used when messages need to
be updated or canceled (put/delete) to refer to
previously submitted messages.
The validation endpoint can also return a list of
document statuses to indicate missing information.
The recommended method for submission is that the actor submits all messages for creation (POST) that are relevant, and then waits 1-2 seconds before querying for validation (query API).
For example: if you have 500 consignments for a master consignment on a transport, you submit (POST) all 500 consignment messages, wait a few seconds, query for validation, and receive the MRN and status for all 500 messages.
If you receive a 404 status when calling the validation endpoint, you must wait a bit and query again. It is recommended to create an algorithm that makes repeated attempts until a validation response is received.
See API documentation for details on the endpoints.
Validation Errors
See this page for an overview of the most common validation errors you may encounter with possible causes/corrections for them.
If a consignment receives routing signals multiple times, the last routing signal is the one that applies. For example, it is possible for a consignment to first receive ENTRY_PENDING and then receive TO_CONTROL. If a consignment you have reported does not receive a routing signal when expected, it usually means that Norwegian Customs has not had sufficient time to process the consignment message. The actor must then hold back the consignments until a routing signal is received for it.
Code Lists
An overview of the various code lists that the message content is validated against can be found on a separate page. In the schemas on the APIs, it will be indicated which code lists the data fields are validated against.
API: Document Submission
In addition to the consignment information provided through the movement APIs, invoices for consignments where a customs declaration has already been submitted can also be sent. Documentation for this API can be found here: Document Upload API.
Relevant Examples
We have created a brief overview of how consignment
message content might look based on the customs
procedure used.
Examples can be
found here.
On the same page, there is information about test
data related to customs declarations that can be
used in connection with interface testing.
Authentication – Data Exchange between Businesses and Norwegian Customs
Our APIs use Maskinporten for identity and access management. On the page Maskinporten - Norwegian Customs you will find information about
- how to get started with integration via Maskinporten if you have not done so before, including the registration form for access at Norwegian Customs
- access management for our APIs
- how to set up a client to authenticate via Maskinporten
- operation and monitoring/troubleshooting.
The scope used for the APIs is documented on each individual API.
