Introduction

This document defines the activities necessary to integrate with Eurora system for submitting import declarations.

Integrating with Eurora

Take the following steps to integrate with the Eurora API:

1. Eurora will create your account and issue you an API key. You will need to use this API key as your X-Auth-Token header parameter whenever you make a query.

2. Choose the API endpoints you wish to integrate with (see descriptions below).

3. Integrate with the chosen endpoints in Eurora's Integration environment. Use our Integration environment to test the endpoints and send us test data.

4. After testing and confirming the process flows are working, integrate with the endpoints in Eurora's Production environment to start sending us live data.

Eurora's Integration environment API documentation can be found here.

Eurora's Production environment API documentation can be found here.

Process overview

Using Eurora system for submitting import declarations consists of the following steps:

1. Upload shipment data in Json format

2. Make sure the file was properly processed and data saved

3. Make sure all mandatory data elements were correctly provided

4. Add warehouse data to shipments

5. In the case of H1 shipments take additional steps:

   1. Edit declaration data if some data is missing

   2. Mark shipments as reviewed by broker

6. Make sure goods were released by customs

Sending shipment data to Eurora

Sending shipment data to Eurora consists of two steps. First, the client should upload Json file that contains all shipments that should be submitted to destination customs. The second step is to add goods location and previous document data when goods arrive at the destination warehouse.

Upload import declarations file (POST)

• URL:https://api.eurora.com/customs/v1/declarations/upload

• API documentation:  https://api.eurora.com/customs-core-external-v1#operation/uploadImportDeclarationsFile

• Purpose: This endpoint is used to upload shipment data to Eurora system. It can also be used for updating existing shipments in Eurora system. One file may contain information about multiple shipments.

• When to use: We recommend sending shipment data to Eurora once all the information has been gathered. This allows us to communicate any issues with the data before shipment is dispatched.  Goods location and previous document data should be provided when goods arrive at the destination. 

• Example: Client has gathered shipments that need to be delivered to the destination country. After ensuring all necessary data regarding these shipments has been gathered, the client's system composes a Json file that is sent to Eurora system using upload import declarations file endpoint.

Add warehouse data to import declarations (POST)

• URL:https://api.eurora.com/customs/v1/declarations/warehouse-data

• API documentation:  https://api.eurora.com/customs-core-external-v1#operation/addWarehouseDataToShipments_1

• Purpose: This endpoint is used to add goods location and previous document data to shipments when they arrive at the destination.

• When to use: Providing warehouse and previous document data should only be done in case the shipments have physically arrived at the named location. After this endpoint is called out and all validations pass, shipment data will be sent to destination customs.

• Example: Client has successfully uploaded shipments to Eurora system, and all shipments are in status “WAITING_FOR_ARRIVAL”. Goods arrive at the destination warehouse and logistics service provider communicates previous document number to the client. Client uses this endpoint to add previous document number and goods location data to these shipments.

Requesting status of uploaded data

After the Json file has been uploaded to Eurora system, clients should request the status of the uploaded file to make sure that Eurora system managed to process the content of the file without errors. If the file was structurally correct, clients should observe shipment status through processing to ensure that no problems occur.

Get uploaded bulk file statuses for import declarations files (GET)

• URL:https://api.eurora.com/customs/v1/declarations/bulk/file-status

• API documentation:  https://api.eurora.com/customs-core-external-v1#operation/getBulkUploadFileStatus_1

• Purpose: This endpoint is used to request uploaded file status to see if the file was successfully processed or not. This endpoint also returns a description of errors if they have occurred.

• When to use: Use this endpoint after the data has been uploaded to Eurora. Processing a large Json file could take up to an hour, therefore make requests until endpoint response contains status “DONE” (without any errors). If the endpoint returns an error, clients should correct the data in Json file and re-upload it to Eurora system.

• Example: Client has uploaded shipment file to Eurora system. To see whether the file was structurally correct, the client uses this endpoint to get the latest status of the uploaded file. The following statuses are possible:

  • PROCESSING - uploaded file is still being processed. The client should use this endpoint again after some time passes

  • ERROR - uploaded file was structurally incorrect or contained data elements that Eurora system did not manage to save. The client should correct the data and re-upload the file.

  • DONE - uploaded file was structurally correct or at least some of the shipments in the file were saved. When there was a problem while processing some shipments, an error message is returned.

Get import declarations with statuses updated after given timestamp (GET)

• URL:https://api.eurora.com/customs/v1/declarations/bulk/status

• API documentation: https://api.eurora.com/customs-core-external-v1#operation/getH7ShipmentStatus_1

• Purpose: This endpoint is used to retrieve latest shipment status after it is successfully uploaded to Eurora system.

• When to use: Use this endpoint when the Json file containing all the data has been successfully processed. Clients should use this endpoint throughout the processing to see what the latest status of their shipments is. After shipment gets its final status (GOODS_RELEASED_FINAL), the processing has finished and there is no need to retrieve the status anymore. 

• Example: Eurora system has successfully sent import declaration to destination customs. Customs has received the import declaration but has found errors in the data. Customs send a message that contains a list of validation errors back to Eurora. Get shipments with statuses updated after given timestamp endpoint must be used to receive validation errors found by customs. Based on this feedback from customs, client makes corrections in import declaration data and re-submits the declaration.

Get import declarations with statuses by transport document reference number (GET)

• URL: https://api.eurora.com/customs/v1/declaration/statuses-by-grouping
• API documentation: https://api.eurora.com/customs-core-external-v1#operation/getDeclarationStatusesByGrouping
• Purpose - Retrieve information about the import declarations data sorted by transport document reference number.
• When to use: Use this endpoint when the Json file containing all the data has been successfully processed. Clients can use this endpoint throughout the processing to see every declaration status within a particular transport document
• Example: Eurora system has successfully sent import declaration to destination customs. Customs has received the import declaration but has found errors in the data. Customs send a message that contains a list of validation errors back to Eurora. In order to get information about all declarations within one transport document number, get import declarations with statuses by transport document reference number endpoint must be used. The response of this endpoint gives information about the declarations that contained errors and also specified information about the errors. This information is necessary for the client to make corrections in the import declaration data and re-submit the declaration

Description of statuses returned by status API:

State diagram illustrating flow of passing through all statuses:

Additional steps for H1 shipments

To submit H1 declaration to customs some additional steps need to be taken. It may be necessary to add missing data elements to existing shipments. Before an H1 shipment is sent to customs, customs broker must confirm that all data is correct.

Mark import declaration as reviewed by broker (POST)

• URL:https://api.eurora.com/customs/v1/declarations/reviewed-by-broker

• API documentation:https://api.eurora.com/customs-core-external-v1#operation/markAsReviewedByBroker_1

• Purpose: This endpoint is used to confirm that H1 shipments contain all necessary data to be submitted to their destination customs.

• When to use: Use this endpoint after someone (customs broker) has reviewed the shipment data and added all necessary elements (if needed).

• Example: Goods location and previous document information has been added to an H1 shipment. In this case the shipment needs to be reviewed by the broker before it is submitted to destination customs. The customs broker checks the data and adds additional elements (e.g., supporting documents, additional commodity codes) using Edit import declaration data (PUT). After all data is checked, customs broker confirms that shipment data can be sent to destination customs.

Edit import declaration data (PUT)

• URL:https://api.eurora.com/customs/v1/declaration/edit

• API documentation: https://api.eurora.com/customs-core-external-v1#operation/editDeclarationData

• Purpose: This endpoint is used to edit existing shipment data. Eurora system allows editing most of the data elements that are stored for a single shipment.

• When to use: Use this endpoint when additional data elements must be added. Before editing a single shipment, it should be locked for editing.

• Example: Client uploaded multiple shipments to Eurora system. After processing all the shipments, Eurora system concluded that one shipment should be declared as H1 (e.g., H7 conditions were not met). Because H1 has more data elements, the client should edit the existing shipment so it could be declared as H1 declaration.

API Documentation