Introduction
Learn how to upload Bulk Import Declaration data into Eurora’s system, add additional data, modify declaration data and view your declaration status.
Documentation
STEP 1: Upload declarations file (POST)
-
Purpose - “Upload import declarations file” endpoint must be used to send import declarations data to Eurora.
How to use the API:
API REQUEST URL - https://api.eurora.com/customs/v1/declarations/upload
NB! Ensure that you are using the Customs service.
-
The request body must contain KEY with name “file” and VALUE containing the attachment in JSON file structure.
-
The JSON file must contain import declaration data in the correct format. Description of the JSON file structure can be viewed from section Description of data elements.
-
Successful response returns the file UUID which can be used later to request the status of the file processing.
Providing warehouse (location of goods) and previous document data should only be done in case the shipments have physically arrived at the named location.
STEP 2: Get uploaded bulk file statuses for import declarations files (GET)
-
Purpose - Allows users to verify if there are any errors associated with the files uploaded.
-
API Documentation - Get uploaded bulk file statuses for import declarations files
How to use the API:
API REQUEST URL - https://api.eurora.com/customs/v1/declarations/bulk/file-status
NB! Ensure that you are using the Customs service.
-
This endpoint allows to filter the results based on different query parameters:
-
uuid - file upload id returned in STEP 1
-
status - file upload status
-
createdFrom - date from which the file was uploaded
-
createdUntil - date to which the files was uploaded
-
page - specify the page number (when there are many results)
-
size - page size
-
STEP 3(a): Get import declarations with statuses updated after given timestamp (GET)
-
Purpose - Retrieve the latest information about the import declarations data.
-
Step 3(a) is an analogue for step 3(b). The response of the endpoints is same but the difference is in the request parameters.
-
API Documentation - Get import declarations with statuses updated after given timestamp
How to use the API:
API REQUEST URL - https://api.eurora.com/customs/v1/declarations/bulk/status
NB! Ensure that you are using the Customs service.
-
The request must have the following parameters - timestamp, page and size.
-
To set up constant polling for the status updates, the endpoint should be used as follows:
a) Every time the request is sent to the endpoint, the timestamp of the request should be stored in the system.
b) Every new request should use the timestamp of the previous request, which results in returning all of the shipments that have been updated between the last request and the current request. - Example API REQUEST URL
GET https://api.eurora.com/customs/v1/declarations/bulk/status?timestamp=2021-10-22T08:22:00.000Z&page=0&size=0
STEP 3(b): Get import declarations with statuses by transport document reference number (GET)
-
Purpose - Retrieve information about the import declarations data sorted by transport document reference number.
-
Step 3(b) is an analogue for step 3(a). The response of the endpoints is same but the difference is in the request parameters.
How to use the API:
API REQUEST URL - https://api.eurora.com/customs/v1/declaration/statuses-by-grouping
NB! Ensure that you are using the Customs service.
-
The request must have the following parameters - transport document reference number, page and size.
-
The response will output information about each declaration of inserted transport document reference number. The information contains declaration ID-s, MRN, status, timestamp, account and message items.
-
Example API REQUEST URL
GET https://api.eurora.com/customs/v1/declaration/statuses-by-grouping?transportDocumentReferenceNumber=1122334455
Description of statuses returned by status API:
Status name |
Description
|
---|---|
RECEIVED |
Data has been saved from the input file to the database. |
PROCESSING |
Data is being processed. |
INCOMPLETE |
Shipment data is incomplete. There are missing fields in the declarations. |
INSUFFICIENT_DATA |
Necessary data for assigning customs country and declaration type is missing from the shipment data. Status and fields that need filling or fixing are shown. After fixing the fields with errors or filling out missing fields it is neccessary to upload updated data manifest. |
WAREHOUSE_ERROR |
Shipment is missing from the warehouse or otherwise undeclarable and has been removed from the list of shipments to be declared to customs. It is possible to assign this status by adding the external ID of the shipment into the list of undeclarable shipments in Add-warehouse-data-to-import-declarations-(POST) request. |
DECLARATION_TYPE_NOT_VALID |
Declaration type has been assigned that is not allowed to be used for the account, e.g. account is using only H7 declarations, but the validations have found that H7 is not possible to be submitted and H1 has been assigned instead. |
DECLARATION_TYPE_REQUEST_ERROR |
Declaration type assignment has failed due to technical error in internal service. Please contact Eurora support. |
WAITING_FOR_DOCUMENTS |
Shipment is missing supporting document attachments. |
WAITING_FOR_ARRIVAL |
Shipment is missing location of goods and/or previous document data that is expected to be supplied by the warehouse once the shipments arrive. |
WAITING_FOR_ARRIVAL_RFI |
The declaration is being controlled by the Customs (RFI -Request for Information) while in the same time the declaration is missing location of goods data that is expected to be supplied by the warehouse once the shipments arrive. This status is for pre-lodgement flow only. |
NEED_BROKER_ATTENTION |
Shipment is processed but before it can be sent to customs, the customs broker needs to review the data (H1 shipments) |
PROCESSED |
Internal processing of the shipment has finished. |
I_DECLARATION_REQUEST |
Declaration XML has been constructed. |
I_DECLARATION_RESPONSE |
An initial response if declaration has been sent to customs. |
I_TECHNICAL_ERROR |
Technical error in customs message processing |
I_DECLARATION_RESPONSE_TECHNICAL_ERROR |
Declaration submission to customs has failed. |
I_DECLARATION_RESPONSE_VALIDATION_NOT_OK |
Declaration validation in Customs has failed. Either some data was missing (xsd) or business validation errors. |
I_DECLARATION_RESPONSE_INITIAL_ACCEPT |
Received confirmation that declaration message was received by customs. |
I_DECLARATION_RESPONSE_ACCEPTED |
Customs has accepted the declaration. MRN is allocated. |
I_DECLARATION_RESPONSE_RFI |
Declaration is being controlled by customs. RFI - Request for Information |
I_DECLARATION_RESPONSE_GOODS_RELEASED |
Customs has released the goods for import. |
I_DECLARATION_RESPONSE_GOODS_RELEASED_RFI |
Customs has released the goods for import but still requires some documents to be sent. |
I_PRESENTATION_NOTIFICATION_REQUEST |
Goods have arrived at the border, informing customs via presentation notification. |
I_PRESENTATION_NOTIFICATION_RESPONSE |
An initial response if presentation notification has been sent to customs. |
I_PRESENTATION_NOTIFICATION_RESPONSE_TECHNICAL_ERROR |
Presentation notification submission to customs has failed. |
I_PRESENTATION_NOTIFICATION_RESPONSE_VALIDATION_NOT_OK |
Presentation notification validation in Customs has failed. Either some data was missing (xsd) or business validation errors. |
I_PRESENTATION_NOTIFICATION_RESPONSE_INITIAL_ACCEPT |
Received confirmation that presentation notification message was received by customs. |
I_PRESENTATION_NOTIFICATION_RESPONSE_ACCEPTED |
Customs has accepted the presentation notification. |
I_UNKNOWN |
Customs has responded with an unknown state that has not been handled by Eurora system. Please contact Eurora support. |
GOODS_RELEASED_FINAL |
Customs has released the goods and the processing of the declaration in Eurora system is finished. |
State diagram illustrating flow of passing through all statuses:
STEP 4: Upload import declarations supporting documents (POST)
-
Purpose - Allows users to upload supporting documents for the import declarations.
-
API Documentation - Upload import declarations supporting documents
How to use the API:
API REQUEST URL - https://api.eurora.com/customs/v1/declarations/{declarationUuid}/documents
NB! Ensure that you are using the Customs service.
-
The API REQUEST URL will utilize the declarationUuid from the import declaration data.
-
The body will utilize the supporting document reference number from the import declaration data and must be set as a KEY with the file attachment as the value.
-
Allows uploading multiple file attachments.
Example API REQUEST URL
POST https://api.eurora.com/customs/v1/declarations/0acac8b3-587f-4850-95a3-f1e13495baf4/documents
Description of Data Elements
This table contains all data elements that can be provided by the Customer. Required data elements are dependent on customs country and declaration type (H7/H1).
Explanation of the following table:
-
The first column contains all relevant data elements that are used in JSON file.
-
Occurrence indicates how many times this data group can be added to a single shipment.
-
1..1 means this data group can have one instance in a single shipment
-
1..n means this data group can have one or more instances in a single shipment
-
-
Format shows what kind of data type and length is expected. For example:
-
an2 - 2 alphanumeric characters, fixed length
-
an..22 - up to 22 alphanumeric characters
-
n1 - 1 numeric character, fixed length
-
n..16,6 - up to 16 numeric characters including maximum 6 decimals, a delimiter being allowed to float
-
-
Comment is used to describe what this data element should contain from the business perspective.
-
EUCDM refers to the data element number used in Unified Customs Code (UCC)
1EXAMPLE
Declaration consists of three goods items 9 packages in total. Goods items are:
T-shirts;
Jeans;
Mobile cases.
The first two goods items (T-shirts and jeans) are packed together in 5 cartons. The ‘Mobile cases’ are packed alone in 4 plastic boxes. Therefore, will have to declare the packaging details per goods as following:
Since the first two goods items are packaged together in the same cartons, the number of packages will be declared to the first goods item. For second goods item, the declared number of packages must be zero. As a pre-requisite the marksNumber of common packages that contain the two goods items must be the same (AB123456789).
STEP 5: Add warehouse and previous document data to import declarations
-
Purpose - This endpoint is used only in case the warehouse (location of goods) and previous document data was not provided in STEP 1. If warehouse and previous document data was provided in STEP 1, this step should be skipped.
Providing warehouse and previous document data should only be done in case the shipments have physically arrived at the named location. This also applies if all of the shipment data is sent in STEP 1.
API REQUEST URL - https://api.eurora.com/customs/v2/declarations/warehouse-data
NB! Ensure that you are using the Customs service.
-
The body will utilize the transportDocumentNumber (given in goodsShipment → transportDocument → referenceNumber) from the shipment data.
-
All the declarations having the given transportDocumentNumber will be added the warehouse and previous document data.
-
If there are shipments that were not delivered to the warehouse, but share the same transportDocumentNumber, then they have to be excluded from the declarations list by adding the externalId to shipmentsUndeclarable. The status of those declarations will be marked as WAREHOUSE_ERROR.
-
There is a list of externalIds of declarations to which warehouse data was not added in the response of the endpoint.
-
Warehouse data is predefined in Eurora system. Correct warehouse should be defined in location - e.g. NL_OUDEMEER defines the following values:
-
streetAndNumber - Breguetlaan 2
-
postalCode - 1438 BB
-
country - NL
-