Introduction #
The qualified VAT registration number check from endereco offers the possibility to check the validity and the correct connection between
- VAT no.
- Company name
- Company address
to ensure legally compliant use of the VAT ID number in commercial transactions with foreign companies. Based on this regular preliminary check, the validity for the recapitulative statement via Elster to the tax authorities is ensured.
In the case of transactions with foreign customers within the EU economic area, e.g. in e-commerce, VAT may only be deducted from the purchase price in the shopping cart if the recipient of the service has a valid and therefore qualified VAT ID number.
The service recipient can be both the invoice recipient and the recipient of the delivery. This may differ depending on the business model and the customer.
Problems that arise during the audit via the BZSt #
- The BZSt servers, via which a query is possible, often do not return any detailed information on the owner of the VAT ID number or any structured, automatically processable information such as a structured address object. This makes it difficult to fill in forms automatically.
- Various interfaces must be implemented for validation against different countries.
- The servers of the Federal Central Tax Office are offline during the evening/night hours.
- The servers are often overloaded and have a slow response time.
The advantages of querying via endereco #
- endereco enables the VAT ID number to be checked for over 40 countries via a standardized interface
- The address data is output in a structured form so that it can be transferred directly to the form fields.
- If the waiting time for external APIs, such as the Federal Central Tax Office, is too long, the data is returned from a cache that reflects the time of the last valid query. This means that the customer's onboarding process can always be completed and official certification can be requested again at a later date.
- An optional company name autocomplete can be used to automatically suggest the correct address data when a customer registers in the webshop or wants to complete a purchase process during check-out.
- endereco stores the queries in a permanent, unalterable log for 10 years. This means that requests to the authorities can be verified in a legally compliant manner.
How the connection works #
CompanyName Autocomplete #
Mit dieser Anfrage kann bei der Eingabe des Firmennamens der Datenstand aus dem Cache zum Ausfüllen des Formulars genutzt werden. Die Abrechnung erfolgt je Keystroke. Daher ist es sinnvoll, ein Caching (Timeout nach Stopp des Tippens) und eine Abfrage ab einer gewissen Zeichenlänge zu nutzen, oder die Abfrage mit einem „SUCHEN“ Button hinter dem Formuarfeld zu starten.
Example request - Company Name Autocomplete
{
"jsonrpc": "2.0",
"id": 1,
"method": "companyAutocomplete",
"params": {
"countryCode": "de",
"companyName": "endereco UG"
}
}Example response - Company Name Autocomplete #
{
"jsonrpc": "2.0",
"id": 1,
"result":
{ "predictions":
[ {
"vatId": "DE297464149",
"companyStatus": "active",
"companyName": "endereco UG (haftungsbeschränkt) Gesellschaft für Master Data Quality Management",
"companyAddressFull": "Balthasar-Neumann Str. 4b, 97236, Randersacker",
"companyAddressFormatted": {
"streetFull": "Balthasar-Neumann Str. 4b",
"additionalInfo": "",
"postCode": "97236",
"cityName": "Randersacker",
"country": "DE",
"street": "Balthasar-Neumann Str.", "houseNumber": "4b"
} },
{ "vatId": "DE357727031",
"companyStatus": "active",
"companyName": "Forst- u.Gartengeräte Eichelsdörfer GmbH",
"companyAddressFull": "Hafenstr. 37, 96052, Bamberg",
"companyAddressFormatted": {
"streetFull": "Hafenstr. 37",
"additionalInfo": "",
"postCode": "96052",
"cityName": "Bamberg",
"country": "DE",
"street": "Hafenstr.",
"houseNumber": "37"
} },
{ "vatId": "DE346845022",
"companyStatus": "active",
"companyName": "Ebert und Galle UG (haftungsbeschränkt)",
"companyAddressFull": "Rothenburger Str. 34, 91635, Windelsbach",
"companyAddressFormatted": {
"streetFull": "Rothenburger Str. 34",
"additionalInfo": "",
"postCode": "91635",
"cityName": "Windelsbach",
"country": "DE",
"street": "Rothenburger Str.",
"houseNumber": "34" } } ],
"status": [ "A2000", "company_multiple_variants" ]
} }Qualified VAT-ID Validation #
Compared to a simple check of the validity of a VAT registration number, the qualified check is much more comprehensive:
- .
The VAT ID no. to be checked is transferred as "vatId". The VAT ID no. of the requesting company is transferred as "requesterVatID".
In addition to matching the address and company name, the following data is also transferred for the qualified check:
-
- Eigene USt-IDNr.
- zu prüfender Firmenname (Inkl. rechtlicher Firmierung)
- Zu prüfendeUSt-IdNr.
- Zip code and city
-
- Street and house number
- ggf.optionale Parameter
timeout (Optionaler Parameter)
Die Wartezeit auf die jeweilige Behörde ist aktuell auf 60 Sek gesetzt. Wird die definierte Zeitspanne überschritten, so wird die Ausgabe aus dem Cache zurückgeliefert und nicht auf die Antwort der offiziellen API gewartet.
Gültige Werte sind zwischen 5 und 60 Sekunden.
allowCache (Optionaler Parameter)
Die endereco API ist für zwei Einsatzbereiche optimiert:
- Frontend Validierung im Checkoutprozess, wo innerhalb weniger Sekunden eine Antwort benötigt wird
- Backend Prozess, wo eine Offizielle Bestätigung des Bundeszentralamts für Steuern benötigt wird.
Diese Einsatzbereiche lassen sich durch die optionalen Parameter „allowCache“ und „Timeout“ optimal steuern.
Der Parameter „allowCache“ ermöglicht es festzulegen ob nur offizielle Bestätigungen vom Bundeszentralamt für Steuern erlaubt sein sollen, oder ob auch Antworten aus dem Cache erlaubt sein sollten.
allowCache=“true“ / „false“
Wir der Parameter nicht gesetzt, so werden keine Antworten aus dem Cache zurückgegeben (allowCache=false“)
Geplantes Features:
Straße kann auch als “companyStreet” und “companyHouseNumber” getrennt übergeben werden.
Dieses Feature ist optional und nicht verfügbar!
Example request for a qualified VAT registration number check #
For a qualified VAT ID check, the parameters
- vatId
- requesterVatId
- companyName
- companyPostalCode
- companyLocality
- CompanyStreetFull
necessary. The corresponding country is determined via the first digits of the VAT ID number to be queried.
If parameters are missing or invalid, the system automatically switches to a simple VAT ID check.
{
"jsonrpc": "2.0",
"id": 1,
"method": "vatIdCheck",
"params": {
"vatId": "DE 29746 4149",
"requesterVatID": "DE308900055",
"companyName": "endereco UG (haftungsbeschränkt) Gesellschaft für Master Data",
"companyPostalCode": "97234",
"companyLocality": "Randersacker",
"companyStreetFull": "Balthasar-Neumann-Strasse. 4 b"
}
}Example response of a qualified VAT registration number check #
Die Response ist in vier Teile untergliedert:
-
- predictions
This contains the official data record of the requested company. The address is returned in structured form. The address corresponds to the address stored in the commercial register and does not have to be correct from a postal point of view. An additional address check can be carried out to ensure postal deliverability. - Certification
This contains the part from the Federal Central Tax Office or the corresponding country-specific authority. If the certificate is included in the response, it is an official request in real time, within the set time limit. If the certificate is NOT included, the response comes from the cache and the request must be repeated at a later time in order to be able to prove an official verification request to the tax authority.
3. CertificationStatus
Hier wir die Quelle der Antwort zurückgeliefert. Entweder sie kommt vom Bundeszentralamt für Steuern oder aus dem Cache.
4. Status
The status of the transmitted fields is stored here:
- The validity of the VAT ID no.
(You can find an overview of all valid formats in different countries here)
- Information on possible adjustments to the VAT ID no.
- Comparison of the company name - input vs. found company name
- Comparison of the company address - input vs. company address found: both at address level and at individual field level.
- predictions
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"predictions": [
{
"vatId": "DE297464149",
"companyName": "endereco UG (haftungsbeschränkt) Gesellschaft für Master Data Quality Management",
"companyAddress": "Balthasar-Neumann Str. 4b, 97236, Randersacker",
"companyAddressFormatted": {
"streetFull": "Balthasar-Neumann Str. 4b",
"additionalInfo": "",
"postCode": "97236",
"cityName": "Randersacker",
"country": "DE",
"street": "Balthasar-Neumann Str.",
"houseNumber": "4b"
}
}],
"certification": {
"ErrorCode": "213",
"Date": "02.07.2024",
"Time": "12:54:21",
"Name": [],
"City": [],
"PostalCode": [],
"Street": [],
"Type": "BZST"
},
"certificationStatus": {
"source": "realtime"
},
"status": [
"vat_id_valid",
"vat_id_format_invalid",
"vat_id_body_needs_correction",
"vat_id_body_minor_correction",
"vat_id_company_name_partial_match",
"vat_id_company_postal_code_partial_match",
"vat_id_company_locality_match",
"vat_id_company_street_full_partial_match",
"vat_id_company_street_partial_match",
"vat_id_company_house_number_match",
"vat_id_company_address_partial_match"
]
}
}Logging:
The log of the proof of the checks is saved on our server and backed up regularly. It contains the requests with certificate, i.e. the officially valid requests, as well as the requests from the cache that need to be requested again.
The log is then exported at regular intervals and sent to the relevant customers for archiving.
Details:
Implementation details:
The query is included in our Postman Collection:
Download endereco Postman Collection
The requests are described on Github in our API documentation:
Error codes in the certificate:
Error codes are output in the certification section. These are taken 1:1 from the corresponding data provider and evaluate the validity of the requested VAT ID number.
The following status codes (ErrorCodes) are stored there for the VAT ID number:
| ErrorCode | Description |
|---|---|
| 200 | The requested VAT ID number is valid. |
| 201 | The requested VAT ID number is invalid. |
| 202 | The requested VAT ID number is invalid. It is not registered in the company file of the relevant EU member state. Note: Your business partner can find out his valid VAT ID number from the tax authority responsible for him. They may have to submit an application to have their VAT ID number entered in the database. |
| 203 | The requested VAT ID no. is invalid. It is only valid from ... (see field 'Gueltig_ab'). |
| 204 | The requested VAT ID no. is invalid. It was valid in the period from ... to ... (see field 'Gueltig_ab' and 'Gueltig_bis'). |
| 205 | Your request cannot currently be answered by the requested EU member state or for other reasons. Please try again later. In the event of repeated problems, please contact the Federal Central Tax Office - Saarlouis office. |
| 206 | Your German VAT ID 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. |
| 208 | A request is currently being processed by another user for the VAT ID number you have requested. Processing is therefore not possible. Please try again later. |
| 209 | The requested VAT ID number is invalid. It does not correspond to the structure that applies to this EU member state. (Structure of the VAT ID number of all EU countries) |
| 210 | The requested VAT ID number is invalid. It does not comply with the check digit rules that apply to this EU member state. |
| 211 | The requested VAT ID no. is invalid. It contains invalid characters (e.g. spaces, periods, hyphens, etc.). |
| 212 | The requested VAT ID number is invalid. It contains an invalid country code. |
| 213 | You are not authorized to request a German VAT ID number. |
| 214 | Your German VAT number is incorrect. It starts with 'DE' followed by 9 digits. |
| 215 | Your request does not contain all the information required for a simple confirmation request (your German VAT ID number and the foreign VAT ID number). Your request can therefore not be processed. |
| 216 | Your request does not contain all the necessary information for a qualified confirmation request (your German VAT ID number, the foreign VAT ID number, company name including legal form and location). A simple confirmation request was made with the following result: The requested VAT ID number is valid. |
| 217 | An error has occurred while processing the data from the requested EU member state. Your request can therefore not be processed. |
| 218 | A qualified confirmation is currently not possible. A simple confirmation request was made with the following result: The requested VAT ID number is valid. |
| 219 | An error occurred while performing the qualified confirmation request. A simple confirmation request was made with the following result: The requested VAT ID number is valid. |
| 221 | The request data does not contain all the necessary parameters or contains an invalid data type. Further information can be found in the notes on the Interface - Call. |
| 223 | The requested VAT ID number is valid. The print function is no longer available, as proof must be provided in accordance with UStAE § 18e.1. |
| 999 | It is currently not possible to process your request. Please try again later. |
