VAT-Validation – Documentation

Application

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

VAT-Validation
VAT-Validation

Single Validation

The individual check makes it possible to carry out a check immediately by entering the relevant data. As a minimum, enter the VAT number to be checked. A simple check will be performed.

For a qualified check, you can specify the optional fields company name, street, postal code and city.

As of 01 January 2021, there is no written confirmation from the Federal Central Tax Office. You are responsible for archiving the verification of the records yourself. You can take the changed requirements into account via the archive function and the use of an audit-proof memory. We will be happy to help you with this!

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

Batch

Select a file and check it by pressing the “Check” button. This will start the check of the entire file. This generates the protocol in the background. The protocol can then be opened via the protocol button. This contains all check results of the individual data records. Depending on the size of the file, the verification process may take some time.

The name of the VAT registration number protocol file is automatically assigned and generated in the identical format as the submitted format. For example, if a file with the name “data.json” is passed, the name of the log file will be “data-log.json”.

Pre-Validation

Pre-checking a VAT registration number 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.

Qualified Validation Notes

If address data (company name, city, postal code or street) does not match during a qualified check, a simple check is automatically performed. In order to nevertheless receive information on valid confirmations as to whether values could not match, the corresponding information is appended at the end of the respective check data record, provided that a check was confirmed negatively from the qualified data.

Return Values BzSt

The return values are displayed and edited via the menu “Extras – Return values VAT”. The designation and number depends on the BZSt. Some systemic return values are output directly by the VAT-Validation. These are in the 900 number range. For more information, see the overview of result codes.

In addition to the standard return values, it is possible to enter processing notes. These are helpful, for example, for integration into a workflow. In this way, the person in charge receives assistance when processing the return values.

VAT-Validation Return Values BzSt
VAT-Validation Return Values BzSt

The description of the return values of the BZSt is not changeable. The return values are reset each time the program is started. Your editing instructions are retained in the process.

Placeholders in Edit Notes

So that you can enrich a note for editing with values from the respective check, a placeholder is inserted with a double click on it. The selection of the placeholders (so-called text markers) shows you the overview of the variables. These do not always have a value. This depends largely on the imported data and the return values of the BZSt.

Return Values VIES

The VIES/MIAS interface gives a smaller range of possible return values. In principle, only “valid” or “invalid” is returned. However, in case of interface errors you have the possibility to enter processing notes.

VAT-Validation return values VIES
VAT-Validation return values VIES

Raw Data Viewer

You can search the archive via the menu Extras – VAT registration number raw data viewer. To do so, enter the desired VAT registration number and press the Search button. All entries will be displayed in the results view. To have a closer look at an entry, click on the desired entry in the list of found entries. The query time, the original request string, the response time of the BZSt/VIES and the original response will be displayed. This way you can get the exact information when a VAT registration number was requested and with which result.

VAT-Validation Raw Data Viewer
VAT-Validation Raw Data Viewer

To ensure the authenticity of a record, we have created a so-called MD5 hash. This allows us to check the authenticity and protection against manipulation in the files.

As soon as a data record does not correspond to the checksum, this is indicated with the addition “(error)”.

Configuration

Via the main menu Extras – Settings VAT ID the settings for the software VAT-Validation are made. In these settings, you must also enter your VAT number for successful licensing.

General Settings

Your VAT ID

Your VAT number is entered on the “General” tab. This number is also used to check for a valid license.

VAT-Validation Settings VAT General
VAT-Validation Settings VAT General

If you have licensed more than one client, you can enter all VAT registration numbers using the “more VAT ID” button.

VAT-Validation Settings VAT Multiple VAT IDs
VAT-Validation Settings VAT Multiple VAT IDs

The selection in the main window will be updated accordingly.

Please note that you only enter licensed VAT ID.

All numbers are checked and if a registered VAT number is not licensed, this is interpreted as an invalid license.

Interface Selection

You have the option to choose between the interface of the Federal Central Tax Office or the EU (VIES/MIAS). For customers with a German VAT number, we recommend using the BZSt interface.

Archive

Via the VAT-Validation archive, we provide you with a function to meet the legal requirements of traceable storage of requests and responses. If the option is enabled, please still specify the appropriate directory in which all requests and responses will be 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 BzSt/VIES is saved. Even renewed attempts are stored and can quickly lead to an increase in the number of files.

Processing

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

VAT-Validation Settings VAT Processing
VAT-Validation Settings VAT Processing

Attempts

Via the entered value of the attempts you have the possibility to set the number of repetitions of a check. A retry can be triggered if the remote station of the Federal Central Tax Office is busy or your network connection results in 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 VAT registration number check (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 spaces are allowed in your master data when entering VAT registration 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 you are allowed to enter lowercase letters in your master data when entering the VAT registration number, this can lead to errors during the check. This setting gives you the possibility that the check ignores the upper and lower case and is automatically set to the correct format.

Clean up VAT ID

If this option is set, the cleaned VAT registration 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 VAT registration number is output without this incorrect spelling. When re-importing into your ERP system, the data record can thus be cleaned up.

Mark valid VAT ID as incorrect

In the event of an incorrect qualified query, the interface of the Federal Central Office automatically checks whether the VAT registration number is nevertheless correct (simple query). The return is marked as valid. If you want to prevent this, you can do so with this option. In the log files, this leads to error 900.

Character encoding of the output

With this setting you have the possibility to control the code page of the CSV output of the VAT registration number check. 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 encoding).

If the data records in the output file of the VAT-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 will solve display problems in most cases.

Background processing

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

VAT-Validation Background Processing
VAT-Validation Background Processing

Copy file name from import to export

If you have enabled this option, the identical name for the exported file will be used during processing.

Only output invalid VAT ID in export file

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

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

No headings in CSV export file

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

Directories

In order for the background processing to properly perform the file processing of the VAT-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 when the export file is repeatedly recognized as the file to be imported.

If the directories are not specified for the VAT-Validation, the background processing cannot be performed. If you have specified directories that do not exist yet, the software will try to create them at the first call. 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 background processing, open a command line in the directory where the ew_service_vat.exe file is located and call it with the --mode=auto parameter.

To use the European interface, add the --vies option.

The background processing will then process all VAT registration number files located in the import directory. A copy of the import file is always stored 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 VAT-Validation with the option --mode=auto can be scheduled via a repeating task or cronjob.

Parameter

Execute ew_service_vat --help and you will get the overview of all parameters of the VAT-Validation, which you can pass to the cli or service.

Usage of: ew_service_vat.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.
    --returncodesbzst   Writes the returncodes for BZSt to user dir.
    --returncodesvies   Writes the returncodes for VIES to user dir.
    --testmail          Send a testmail.
    --vies              Use VIES instead of BZSt.
    --validatefile      Check file, if structure is readable.
----------------------------------------------------------------------------

-h --help

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

-v --version

Returns the current installed version of the VAT-Validation.

--lang

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

--mode

The mode in which the VAT-Validation should be performed.

--dataobject

This parameter is necessary for a single check of a VAT number.

-i --inputfile

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

-o --outputfile

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

--returncodesbzst

This parameter creates a configuration file for the VAT-Validation to process the return values of the BZSt interface.

--returncodesvies

This parameter creates a configuration file for the VAT-Validation to process the return values of the VIES interface.

--testmail

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

--vies

This parameter specifies that the VIES interface is to be used and overwrites any deviating settings.

--validatefile

Check the import file of the VAT-Validation for its formal correctness beforehand.

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 VAT-Validation software offers you a possibility to check your entire database.

We take care to maintain compatibility when extending the CSV import interface of the VAT-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 ensure that the individual VAT registration number records belong to 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 VAT-Validation is the ‘|’ character (pipe). This can be changed in the settings. Bold field names are mandatory fields (the separator can be changed via settings).

Please note that all fields must be specified in the import file of the VAT-Validation, even if you only want to perform a simple check. The qualified check is currently only available for the BZSt interface.

Structure — CSV Import File

FieldFormatExample
Key_1String4711
Key_2String2
Own VATStringDE123456789
Foreign VATStringAT12345678
Company NameString 
LocationString 
Zip CodeString 
StreetString 

Example in the form of a CSV file:
4711|2|EN123456789|AT12345678|||… (other VAT validations)

Note

When creating the VAT registration number import file, please pay attention to the correct number of columns (8 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 CSV export file of the VAT-Validation contains the returned values of the individual checks.

FieldFormatExample
key1String4711
key2String2
ownvatStringDE123456789
foreignvatStringAT12345678
errorcodeString200
errorcode_descriptionStringThe requested VAT number is valid.
valid_fromString 
valid_toString 
errorcode_hintString 
timestampString2021-01-05 16:12:37
companyString 
townString 
zipString 
streetString 

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

4711|2|EN123456789|AT12345678|200|The requested VAT number is valid.|2019-11-05 14:35:43

The naming of the fields of the VAT-Validation within the CSV import or export file is in German. 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 VAT-Validation always includes an additional column containing the headings. Please keep this in mind for a possible automatic re-import of the check results.

JSON Interface

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

We take care to maintain compatibility when extending the JSON USt-IdNr check 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 VAT-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) empty.

Please note that all bold fields must be specified in the import file. Depending on the fields specified, a qualified check will be performed automatically. The qualified check is currently only available for the BZSt interface.

Structure — JSON Import File

KeyFormatExample
key1String4711
key2String2
ownvatStringEN123456789
foreignvatStringAT12345678
companyString 
townString 
zipString 
streetString 

Structure — JSON Export File

The JSON export file of the VAT-Validation contains the returned values of the individual checks, 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.

FieldFormatExample
key1String4711
key2String2
ownvatStringDE123456789
foreignvatStringAT12345678
errorcodeString200
errorcode_descriptionStringThe requested VAT number is valid.
valid_fromString 
valid_toString 
errorcode_hintString 
timestampString2021-01-05 16:12:37
companyString 
townString 
zipString 
streetString 

In contrast to XLSX or CSV, we have agreed on the pure English notation of the VAT-Validation keys 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 VAT-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 VAT-Validation offers you a possibility to check your entire database from your master data.

We take care to maintain compatibility (also with Microsoft Excel) when extending the XLSX VAT-Validation 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 VAT-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) blank.

Please note that all highlighted fields must be specified in the VAT registration number import file. Depending on the fields specified, a qualified check will be performed automatically. The qualified check is currently only available for the BZSt interface.

The names of the column headings of the VAT-Validation are searched for within the XLSX file during import and assigned during import. Please enter only one name at a time, e.g. “Company name” and not “Company,Company name”.

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, key_1String4711
key2, key_2String2
ownvat, own ust-idnr, ustid1StringEN123456789
foreignvat, foreign ust-idnr, ustid2StringAT12345678
company, company nameString 
town, placeString 
zip, zip codeString 
street, streetString 

Structure — XLSX Export File

The XLSX export file of the VAT-Validation contains the returned values of the individual checks, also in the same data format unless otherwise specified.

FieldFormatExample
key1String4711
key2String2
ownvatStringDE123456789
foreignvatStringAT12345678
errorcodeString200
errorcode_descriptionStringThe requested VAT number is valid.
valid_fromString 
valid_toString 
errorcode_hintString 
timestampString2021-01-05 16:12:37
companyString 
townString 
zipString 
streetString 

XLSX Versions

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

Our test scope for the VAT-Validation software includes 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.