Learn how to upload Bulk Import Declaration data into Eurora’s system, add additional data, modify declaration data and view your declaration status.

Documentation

• Integration Environment API Documentation

• Production Environment API Documentation

STEP 1: Upload declarations file (POST)

• Purpose - “Upload import declarations file” endpoint must be used to send import declarations data to Eurora.

• API Documentation - Upload import declarations file

How to use the API:

1. The request body must contain KEY with name “file” and VALUE containing the attachment in JSON file structure.

2. 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.

3. Successful response returns the file UUID which can be used later to request the status of the file processing.

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:

1. This endpoint allows to filter the results based on different query parameters:

   1. uuid - file upload id returned in STEP 1

   2. status - file upload status

   3. createdFrom - date from which the file was uploaded

   4. createdUntil - date to which the files was uploaded

   5. page - specify the page number (when there are many results)

   6. 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:

1. The request must have the following parameters - timestamp, page and size.

2. To set up constant polling for the status updates, the endpoint should be used as follows:

   1. Every time the request is sent to the endpoint, the timestamp of the request should be stored in the system.

   2. 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.

3. Example API REQUEST URL

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:

1. The API REQUEST URL will utilize the declarationUuid from the import declaration data.

2. 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.

3. Allows uploading multiple file attachments.

Example API REQUEST URL

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.

• API Documentation - Add warehouse data to import declarations

How to use the API:

1. The body will utilize the transportDocumentNumber (given in goodsShipment → transportDocument → referenceNumber) from the shipment data.

2. All the declarations having the given transportDocumentNumber will be added the warehouse and previous document data.

3. 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.

4. Warehouse data is predefined in Eurora system. Correct warehouse should be defined in location - e.g. NL_OUDEMEER defines the following values:

   1. streetAndNumber - Breguetlaan 2

   2. postalCode - 1438 BB

   3. 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)