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: Get import declarations with statuses updated after given timestamp (GET)
-
Purpose - Retrieve the latest information about the import declarations data.
-
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:
-
Every time the request is sent to the endpoint, the timestamp of the request should be stored in the system.
-
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
Description of statuses returned by this API:
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
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.
How to use the API:
API REQUEST URL - https://api.eurora.com/customs/v1/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.
-
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
-
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)