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(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:

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:

   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.
   
   
3. Example API REQUEST URL 

Description of statuses returned by status 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

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)

¹EXAMPLE

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.