EORI-Validation – Documentation

Application

The EORI-Validation software is divided into two sections. The single query and the batch processing.

EORI-Validation
EORI-Validation

Single Validation

The single check makes it possible to execute a check immediately by entering the EORI number.

With the single check there is no output of the check results to a file. This application view is used for quick checking, e.g. when EORI numbers are transmitted by telephone, in order to check their validity. Files are processed using batch processing or background processing.

If the EORI number is correct, you will receive all the information reported back by the interface in the other fields. In case of an error, you will receive the exact feedback of the EORI interface from EOS.

Batch

Select a file or drag and drop it to the “Import file” field and check it by pressing the “Check button”. This will start the verification of the entire file. This will generate the protocol in the background. The protocol can then be opened by clicking on the protocol button. This contains all check results of the individual data records. The process of checking takes some time depending on the size of the file.

The name of the EORI protocol file is automatically assigned and generated in the identical format as the transferred format. For example, if a file with the name “data.json” is passed, the name of the log file is “data-log.json”.

Pre-Validation

Pre-checking an EORI import file can help you to check the format and the number of records found without performing an audit. The file will be analyzed and the result will be displayed to you with a message.

Configuration

The main menu Extras – Settings EORI number is used to make the settings for the EORI-Validation.

General Settings

EORI-Validation - Settings General
EORI-Validation – Settings General

Archive

Via the archive of the EORI-Validation, we provide you with a function to meet the legal requirements of traceable storage of requests and responses. If the option is activated, please still specify the appropriate directory in which all requests and responses are stored. If you are subject to the legal requirements to store each request, please select a location that is regularly backed up and, if necessary, protected against modification by third parties. For this, please ask your IT department to configure such a storage location for you.

Please note that every request to the Economic Operator Systems (EOS) is saved. Even retries are saved and can quickly grow in number of files.

Processing

You have the possibility to define some settings for the EORI-Validation on the tab card. These will be taken into account during processing. These settings are described in detail below.

EORI-Validation - Settings Processing
EORI-Validation – Settings Processing

Attempts

Via the entered value of the attempts you have the possibility to set the number of retries of a check. A retry can be triggered if the remote station of the EOS is busy or your network connection leads to a timeout. Each attempt, if enabled, is stored in the audit log.

Delimiter

The separator is only relevant for the import of CSV files for the EORI-Validation (regardless of whether batch processing or background processing). The data is split into individual values based on this separator and prepared for checking. Please consider when setting the separator to an occurrence in your master data. A comma or a semicolon can possibly occur in a company name and lead to an error in the processing. We have defined the pipe character “|” as default. For JSON and XLSX this separator is not necessary.

Spaces

If blanks are allowed in your master data when entering EORI numbers, this can lead to errors during the check. This setting gives you the possibility that these are ignored during the check.

case-sensitive

If the entry of lower case letters is allowed in your master data when entering EORI numbers, this can lead to errors during the check. This setting gives you the possibility that during the check the upper and lower case letters are ignored and set to the correct format automatically.

Clean EORI Number

If this option is set, the cleaned EORI number (spaces, upper and lower case) will be returned in the export file. This means that in log files (these have the same structure as the imported CSV file) the EORI number is output without this incorrect spelling. When re-importing into your ERP system, the data record can thus be cleaned up.

Character encoding of the output

With this setting you have the possibility to control the code page of the CSV output of the EORI-Validation. UTF-8 is specified here by default. If the CSV file is further processed with Microsoft Excel, it is recommended to use Win1252 (this corresponds to the ANSI coding).

If the data records in the output file of the EORI-Validation are not displayed correctly in your text editor or in Microsoft Excel, for example with umlauts, please also set this parameter to a different one than the one currently set for you. This solves display problems in most cases.

Background processing

Background processing allows you to use the EORI-Validation software periodically and automatically. Some settings have to be made in advance for this.

EORI-Validation - Background Processing
EORI-Validation – Background Processing

Only output invalid EORI number to export file

With this option you have the possibility that only invalid EORI numbers are output to the export file. If e-mail dispatch has been activated, the clerk will accordingly also receive only these entries from the imported file.

Especially in case of large amounts of data or very regular EORI checks, this can save the mailbox of the user or the released group.

No headings in CSV export file

Activate this option so that no headers are output in the CSV export file of the EORI-Validation.

Directories

So that the background processing can properly perform the file processing of the EORI-Validation, please specify completely for all necessary directories. Please note that the directories must be different from each other so that, for example, an endless loop of checks does not occur if the export file is repeatedly recognized as the file to be imported.

If the directories are not specified for the EORI-Validation, background processing cannot be performed. If you have specified directories that do not yet exist, the software will try to create them the first time it is called. If the necessary rights are not available or the creation fails, you will receive a corresponding message.

Command Line Interface (cli)

The background processing cannot be started from the user interface. To start the background processing, open a command line in the directory where the file ew_service_eori.exe is located and call it with the parameter --mode=auto.

The background processing thus processes all EORI files that are located in the import directory. A copy of the import file is always saved in the backup directory and the finished check result is stored in the export directory. Individual processing steps are recorded in the log directory.

The call for the EORI-Validation with the --mode=auto option can be scheduled via a repeating task or cronjob. Running the processing in the background may take some time. This depends directly on the European Commission interface.

Parameter

Run ew_service_eori --help and you will get the overview of all parameters of the EORI-Validation that you can pass to the cli or service.

Usage of: ew_service_eori.exe [options]
----------------------------------------------------------------------------
-h  --help              Show this help
-v  --version           Version Return the version information.
    --lang              Language (de,en). Overwrites settings.
    --mode              Set the validation mode (single, batch, auto).
    --dataobject        JSON object for single validation mode.
    --inputfile         Input ImportData file for batch validation.
    --outputfile        Output file for batch validation.
    --testmail          Send a testmail.
    --validatefile      Check file, if structure is readable.
    --returncodeseori   Writes the returncodes for EORI to user dir.
----------------------------------------------------------------------------

-h --help

View all the necessary parameters that support the cli of the EORI-Validation.

-v --version

Outputs the current installed version of the EORI-Validation.

--lang

This parameter allows you to specify or override the language of the EORI-Validation.

--mode

The mode in which the EORI-Validation is to be performed.

--dataobject

This parameter is necessary in case of a single check of an EORI number.

-i --inputfile

Use this parameter to specify the file with data to be imported for the EORI-Validation.

-o --outputfile

The export file for the EORI-Validation is specified with this parameter. It is important that this is not identical to the import file.

--testmail

From the EORI-Validation, test sending a test e-mail. After processing a file, an email can be sent to you at the end.

--validatefile

Check the EORI-Validation import file for formal correctness beforehand.

--returncodeseori

This parameter creates a configuration file for the EORI-Validation to edit the return values of the EOS interface.

Outputs of the command line interface (cli)

All outputs are in JSON format and vary according to your return values.

CSV Interface

We recommend using the XLSX or JSON import interfaces.

By using a simple CSV file, the EORI-Validation software provides you with a way to check your entire data set.

We take care to maintain compatibility when extending the CSV import interface of the EORI-Validation software. This means that you can always use the latest version without generating additional effort when integrating it into your ERP system.

In order to guarantee the affiliation of the individual EORI data records in your master data, you have the option of specifying up to two unique keys in the import file. These will be returned in the export file and can be used for re-import into your ERP system. You can also leave these two fields (Key_1 and Key_2) blank.

The default separator of the individual elements for the EORI-Validation is the ‘|’ character (pipe). This can be changed via the settings. Bold field names are mandatory fields (the separator can be changed via settings).

Since the EORI interface also returns the name and address, we will also enable a check of your stored data and extend the CSV interface in a future release of the EORI-Validation.

Please note that all fields must be specified in the import file of the EORI-Validation, even if you do not use Key_1 and Key_2.

Structure — CSV Import File

FieldFormatExample
Key_1String4711
Key_2String2
EORIStringEN123456

Example in the form of a CSV file:
4711|2|EN123456… (further EORI-Validations)

Note

When creating the EORI import file, please pay attention to the correct number of columns (3 columns). This note is important for possible errors during import when using CSV. In the future we will support other import formats that do not have this restriction.

Structure — CSV Export File

The EORI-Validation CSV export file contains the returned values of each validation.

KeyFormatExample
key1String4711
key2String2
eoriStringDE123456
nameStringSample Company
addressString 
streetStringSample Street 1
postalCodeString12345
cityStringVillage of Samples
countryStringGermany
statusString0
statusDescrStringValid
errorReasonString 
requestdateString 

Example in the form of a CSV file (with standard delimiter):

4711|2|EN123456|Sample Company||Sample Street 1|12345|Sample Village|Germany|0|Valid||

The naming of the fields of the EORI-Validation within the CSV import or export file is done in German language. In the course of the extension of the import formats, these will be internationalized, i.e. we will keep the field names in English in the future. However, we have considered a configuration of the field names in order to increase flexibility.

The output of the export file in CSV format of the EORI-Validation always includes an additional column containing the headings. Please take this into account in case of a possible automatic re-import of the check results.

JSON Interface

With the import interface for JSON files, the software EORI-Validation offers you a possibility to check your entire data set from your master data.

We make sure that compatibility is always maintained when extending the JSON EORI interface. This means that you can always use the latest version without generating additional effort when integrating it into your ERP system.

In order to be able to uniquely assign a JSON data record from your ERP system in the EORI-Validation, you have the option of specifying up to two unique keys in the import file. These will be returned in the export file and can be used for re-import into your ERP system. However, you can also leave these two fields (key1 and key2) blank. They are not necessary for processing.

Since the EORI interface also returns the name and address, in a future release of the EORI-Validation we will also enable a check of your stored data and extend the JSON interface.

Please note that all bold fields must be specified in the import file.

Structure — JSON Import File

KeyFormatExample
key1String4711
key2String2
eoriStringEN123456

Example in the form of a JSON file with two entries:

[
{
"key1": "a",
"key2": "b",
"eori": "EN123456"
},
{
"key1": "a",
"key2": "b",
"eori": "EN789012"
}
]

Structure — JSON Export File

The EORI check JSON export file contains the returned values of each check, also in the same data format unless otherwise specified. Please note that the JSON interface outputs all available fields and thus represents the most complete format.

KeyFormatExample
key1String4711
key2String2
eoriStringDE123456
nameStringSample Company
addressString 
streetStringSample Street 1
postalCodeString12345
cityStringVillage of Samples
countryStringGermany
statusString0
statusDescrStringValid
errorReasonString 
requestdateString 

Example in the form of a JSON file (with standard delimiter):

[
{
"eori": "EN123456";
"status": "0",
"StatusDescr": "Valid",
'name' means 'sample company';
"street": "Sample Street 1",
"PostalCode": "12345",
"city": "Musterdorf",
"country": "Germany",
"requestdate": "30/01/2021",
"key1": "4711",
"key2": "2"
}
]

In contrast to XLSX or CSV, we have agreed on the pure English notation of the keys of the EORI-Validation within JSON. This allows us to avoid runtime errors in case of an incorrect conversion from the beginning.

Please note that the fields in the export file of the EORI-Validation are not always output in the same order as specified in the table above.

XLSX Interface

With the import interface for Microsoft Excel (XLSX) file, the software EORI-Validation offers you a possibility to check your entire data set from your master data.

We take care to maintain compatibility (also with Microsoft Excel) when extending the XLSX EORI interface. This means that you can always use the latest version without generating additional effort when integrating it into your ERP system.

In order to be able to uniquely assign an XLSX data record from your ERP system in the EORI-Validation, you have the option of specifying up to two unique keys in the import file. These will be returned in the export file and can be used for re-import into your ERP system. However, you can also leave these two fields (Key_1 and Key_2) empty.

Since the EORI interface also returns the name and address, in a future release of the EORI-Validation we will also enable a check of your stored data and extend the XLSX interface.

Please note that all highlighted fields must be specified in the EORI import file.

The EORI-Validation column header labels will be searched within the XLSX file during import and mapped during import. Please enter only one designation at a time, e.g. “key1” and not “key1,key_1”.

The upper and lower case of the column headers is not relevant for the import.

Structure — XLSX Import File

Column header (1st row!)FormatExample
key1 or key_1String4711
key2 or key_2String2
EORIStringEN123456

Structure — XLSX Export File

The XLSX export file of the EORI-Validation contains the returned values of each check, also in the same data format unless otherwise specified.

KeyFormatExample
key1String4711
key2String2
eoriStringDE123456
nameStringSample Company
addressString 
streetStringSample Street 1
postalCodeString12345
cityStringVillage of Samples
countryStringGermany
statusString0
statusDescrStringValid
errorReasonString 
requestdateString 

XLSX Versions

We support all XLSX versions up to and including the latest version of Office 365 in the EORI-Validation software. Please understand that we will no longer support older versions (XLS).

Our test scope for the EORI-Validation software includes very many different variants of how a Microsoft Excel document can look like. Nevertheless, we could not test all functions and possibilities. If you encounter a problem when importing XLSX files, please contact us and send us one or two test data sets so that we can help you quickly.