Information and Messages
The APIs support the submission of information related to the notification and information obligation for mail, express, air freight, road vehicles, and ferries in accordance with the Goods Transport Act ยง 2-3 and the regulations on the import and export of goods.
The submission APIs are divided into 3 different messages:
- one for submitting information about transport
- one for submitting information about master consignment
- one for submitting information about consignments
The messages are submitted separately and
independently of each other in terms of both order
and sender. The transport message must, at border
crossing, contain a list of tracking numbers for all
master consignments and/or consignments that will be
on the transport. Note that consignments can be
linked to transport directly or via master
consignment on the same transport.
Consignment
is linked to the master consignment or to the
transport:
- by specifying the master consignment's waybill number in the consignment message (can be used by all except postal operators)
- by the transport containing a list of consignments (can be used by all except postal operators)
Submission Sequence – Synchronous and Asynchronous Response
See also documentation here: mo-vei.html#hvordanSende, this is the same for all modes of transport.
In general, the submission of information works so
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, if successful, receive a
permanent reference to the message, issued by
Norwegian Customs. This is done at a separate
endpoint (/validation-status) in the query API
linked further down this page. These services are
asynchronous, and you must query until you get a
response. Validation response is 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
permanent reference, a Master Reference Number (MRN)
upon success, and a list of validation errors if
any.
Example of submission sequence for consignment (house consignment). The pattern is the same for the other messages, master consignment, and transport.
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, see mo-kodeverk.html#incompleteDocumentationReason. The recommended method for submission is for the actor to submit all relevant messages for creation (POST), then wait 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 couple of seconds, request validation, and get back MRN and status for all 500 messages. If you get status 404 when calling the validation endpoint, you need to wait a bit and query again. It is recommended to create an algorithm that makes repeated attempts until the validation response is received.
