Dokumentation

Configuration

Via the main menu Extras – Settings VAT the settings for the module VAT-ID-Check are made. For successful licensing, you must also enter your VAT ID number in these settings (even if you do not actively use the module yourself).

General settings

Your VAT-ID

Your VAT-ID is entered on the tab card. This number is also used to check for a valid license.

If you have licensed several clients, you can enter all VAT ID numbers using the “Additional VAT ID Number” button.

The selection in the main window is updated accordingly.

Please note that you only enter licensed VAT ID numbers. All numbers are checked and if a registered VAT ID number is not licensed, this is interpreted as an invalid license.

Interface Selection

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

Processing

On the tab card you have the possibility to define some settings. These are taken into account during processing. These settings are described below.

Trials

If no connection can be established to the BZSt server or no checks can be performed at the moment (e.g. due to load, timeout, etc.), the number of renewed attempts to check the data record is set here.

separator

The separator is only relevant for the import of CSV files (whether batch or background processing). The data is split into individual values using this separator and prepared for checking. When you set the separator to occur in your master data, take this into account. A comma or semicolon may appear in a company name and lead to an error in processing.

Space character

If blanks are allowed in your master data when entering the VAT ID number, this can lead to errors in the query. This setting allows you to ignore them during the query.

Capital and small letters

If lower case letters are allowed in your master data when entering the VAT ID number, this can lead to errors in the query. This setting enables you to ignore these errors during the query.

Clean up VAT-ID

If this option is set, the cleaned VAT-ID (spaces, upper and lower case) is returned. This means that in log files (these have the same structure as the imported CSV file) the VAT ID number is output without this incorrect spelling. An import into your ERP system can thus be corrected at the same time.

mark valid VAT registration number as incorrect

The interface of the Federal Central Office automatically checks whether the VAT ID number is still correct (simple query) in the event of an incorrect qualified query. The return is marked as valid. If you wish to prevent this, you have the option of doing so with this option.

Background Processing

Background processing enables you to execute the VAT-ID-Check module automatically at regular intervals. Some settings must be made in advance.

accept file name

As soon as this option is set, the output file with the same name is created in the specified export directory. Please note that already existing files will be overwritten.

Output invalid VAT ID only

This option allows you to output only invalid numbers to the export file. If e-mail dispatch has been activated, the administrator receives only these entries from the imported file.

Directories

The directories must be specified here so that background processing can perform file processing correctly. Please note that the directories must be different, otherwise an endless loop of checks may occur.

If these directories are not specified, background processing cannot be performed. If non-existent directories are specified, they are created immediately before the first run.

debug

The settings, which can only be changed via the debug mode, should only be done after consultation with us. Therefore we will not go into the possibilities at this point. If we ask you in a support case to activate the debug mode, you will find the possibility for the VAT-ID-Check here.

Application

The VAT-ID examination module is divided into two areas. The single query and the batch processing.

Individual enquiry

The individual check enables you to carry out a check immediately when you enter the relevant data. As a minimum, enter the VAT ID number to be checked. A simple query is carried out.

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

To receive a written confirmation (which is sent directly by the Federal Central Tax Office), you can activate the option “Printed confirmation via BZSt”.

In the individual query, the test results are not output to a file. This application view is used for quick verification, e.g. when passing on VAT ID numbers by telephone in order to check their validity. Files are processed using batch processing or background processing.

Batch processing

Select a file and check it by pressing the “Check” button. This will start the check of the whole file. This creates the log in the background. The protocol can then be opened via the protocol button. This contains all test results of the individual data records. Depending on the size of the file, the process of checking takes some time.
The structure of the import file (CSV) is described in more detail in the next section.

Notes on qualified queries

If the address data (company name, city, postcode or street) do not match in a qualified query, a simple query is automatically carried out. In order to still receive the information whether values could not match in the case of valid responses, the corresponding information is appended to the end of the respective test data record if a negative response was received from the qualified data.

Import files

CSV

By using a simple CSV file, the VAT-ID-Check module offers you the possibility to check your entire database.
We make sure that compatibility is maintained when the interfaces are extended.

To ensure that the individual data records belong to your master data, you have the option of specifying up to two unique keys in the import file. These are returned in the export file.

The default separator of the individual elements is the ‘|’ character (pipe). This can be changed in the settings. Field names in bold are mandatory fields (the separator can be changed via settings).
Please note that all fields must be specified in the import file, even if you only want to perform a simple query.

structure – import file

FieldFormatExample
key_1String4711
key_2String2
Own VAT-IDStringDE123456789
Foreign VAT-IDStringAT12345678
Company nameString
locationString
PostcodeString
StreetString
PrintString (yes/no)no

Example in the form of a CSV file:
4711|2|DE123456789|AT12345678|||||||No3
… (further VAT-ID examinations)

construction – export file

The export file contains the returned values of the individual queries.

FieldFormatExample
key_1String4711
key_2String2
Own VAT-IDStringDE123456789
Alien VAT-IDStringAT12345678
ResultCodeString200
ResultTextStringThe requested VAT number is valid.
valid_abDate, dd.mm.yyyy
valid_bisDate, dd.mm.yyyy
Qualified feedbackString
TimestampDate + Time2019-11-05 14:35:43

Example in the form of a CSV file (with standard separator):
4711|2|DE123456789|AT12345678|200|The requested VAT number is valid.|||2019-11-05 14:35:43

Return values BZSt

The return values are displayed and edited via the “Extras – Returnvalues VAT-ID” menu. The name and number depend on the VAT. Some systemic return values are output directly by the VAT-ID-Check. These are in the 900 number range. Further information can be found in the overview of the result codes.
In addition to the standard return values, you can also enter processing instructions. These are useful, for example, for integration into a workflow. This provides the clerk with assistance in processing the return values.

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

Placeholders in machining instructions

A placeholder is inserted with a double click on it so that you can enrich a note for processing with values from the respective query. The selection of the placeholders (so-called highlighters) shows you the overview of the variables. These do not always have a value. This depends 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. In case of interface errors, however, you have the option of entering processing notes.

Background processing

Background processing cannot be started from the user interface. To start background processing, open a command line in the directory where the file ew_vat_service.exe is located and call it with the parameter “-auto”. To use the European interface, add the “-vies” option.

Background processing processes all files 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 with the -auto option can be scheduled via a repetitive task or cronjob.

cli application

As already mentioned in the background processing, the ew_vat_service.exe can be operated via the command line. All tasks of the interface can also be called with the corresponding parameters. If you want to see all parameters provided by the cli application, execute them as usual without specifying a parameter. You get the complete overview.

Configuration files

The configuration files are in json format and can also be edited manually. Please only use editors that can perform a syntax check to avoid malfunctions. We always recommend using the configuration interface.

Result codes (as of 08.09.2019)

CodeDescription
200The requested VAT number is valid.
201The requested VAT number is invalid.
202The requested VAT number is invalid. It is not registered in the entrepreneur file of the EU member state concerned.
Hint:
Your business partner can obtain his valid VAT ID number from the tax authority responsible for him. He may have to submit an application in order for his VAT number to be included in the database.
203The requested VAT number is invalid. It is only valid as of ….
204The requested VAT number is invalid. It was valid from … to ….
205Your request cannot currently be answered by the requested EU Member State or for any other reason. Please try again later. In case of repeated problems
please contact the Federal Central Tax Office – Saarlouis Office.
206Your German VAT number is invalid. A confirmation request is therefore not possible. You can find out the reason for this from the Federal Central Tax Office – Saarlouis Office.
207You were granted the German VAT ID number exclusively for the purpose of taxing the
intra-community acquisition. You are therefore not entitled to make confirmation requests.
208The VAT ID number you requested is currently being requested by another user. Processing is therefore not possible. Please try again later.
209The requested VAT number is invalid. It does not correspond to the structure valid for this EU member state.
210The requested VAT number is invalid. It does not comply with the check digit rules that apply to this EU member state.
211The requested VAT number is invalid. It contains invalid characters.
212The requested VAT number is invalid. It contains an invalid country code.
213The query of a German VAT number is not possible.
214Your German VAT number is incorrect. It starts with ‘DE’ followed by 9 digits.
215Your request does not contain all necessary information for a simple confirmation request (your German VAT number and the foreign VAT number).
Your request can therefore not be processed.
216Your request does not contain all necessary information for a qualified confirmation request (your German VAT number, foreign VAT number, company name including legal form and location).
A simple confirmation request was carried out with the following result:
The requested VAT ID number is valid.
217An error occurred during processing of data from the requested EU Member State. Your request can therefore not be processed.
218A qualified confirmation is currently not possible. A simple confirmation request was performed with the following result:
The requested VAT ID number is valid.
219An error occurred while executing the qualified confirmation request. A simple confirmation request was executed with the following result:
The requested VAT ID number is valid.
220An error occurred when requesting the official confirmation message. You will not receive a letter.
221The request data does not contain all necessary parameters or an invalid data type.
900The checked VAT number is valid, but the data passed for the qualified query are not correct.
997Please make sure that all VAT-IDs are entered in capital letters.
998A processing of your inquiry is currently not possible. Please try again later.
999A processing of your inquiry is currently not possible. Please try again later.
The error code 999 is also used to display error messages during the automatic check (start parameter “-auto”).

 

Wir benutzen Cookies um die Nutzerfreundlichkeit der Webseite zu verbessen. Durch Ihren Besuch stimmen Sie dem zu.