Einführung #
Die qualifizierte USt-IdNr.-Prüfung von endereco bietet die Möglichkeit, die Gültigkeit sowie den richtigen Zusammenhang zwischen
- USt-IdNr.
- Firmenname
- Firmenanschrift
zu prüfen, um eine rechtskonforme Verwendung der USt-IdNr. im Handelsgeschäft mit ausländischen Firmen sicherzustellen. Basierend auf dieser regelmäßigen Vorprüfung wird die Gültigkeit für die zusammenfassende Meldung über Elster an die Finanzbehörden sichergestellt.
Bei Geschäften mit ausländischen Kunden innerhalb des EU-Wirtschaftsraums, z.B. im E-Commerce, darf nur dann die Umsatzsteuer im Warenkorb vom Kaufpreis abgezogen werden, wenn der Leistungsempfänger eine gültige und damit qualifiziert geprüfte USt-IdNr. besitzt.
Der Leistungsempfänger kann sowohl der Rechnungsempfänger als der Belieferte sein. Das kann sich je nach Geschäftsmodell und Besteller unterscheiden.
Probleme, die bei der Prüfung über das BZSt auftreten #
- Die Server des BZSt, über die eine Abfrage möglich ist, geben oft keine detaillierten Informationen zum Inhaber der USt-IdNr. sowie auch keine strukturierten, automatisiert verarbeitbaren Informationen wie ein strukturiertes Adressobjekt zurück. Damit ist ein automatisiertes Befüllen von Formularen nur schwer möglich.
- Es sind verschiedenen Schnittstellen für die Validierung gegen verschiedene Länder zu implementieren.
- Die Server des Bundeszentralamtes für Steuern sind während der Abend-/Nachtstunden offline.
- Die Server sind oft überlastet und haben eine langsame Responsezeit.
Die Vorteile der Abfrage über endereco #
- endereco ermöglicht die Prüfung der USt-IdNr. für über 40 Länder über eine einheitliche Schnittstelle
- Die Adressdaten werden in strukturierter Form ausgegeben, sodass sie direkt in die Formularfelder übernommen werden können.
- Ist die Wartezeit auf externe APIs, wie z.B. dem Bundeszentralamt für Steuern, zu lang, so werden die Daten aus einem Cache zurückgegeben, der den Zeitpunkt der letzten gültigen Abfrage wiedergibt. So kann der Onboardingprozess des Kunden immer abgeschlossen werden, und die offizielle Zertifizierung kann zu einem späteren Zeitpunkt nochmals angefragt werden.
- Über einen optionalen Firmennamen-Autocomplete können die richtigen Adressdaten automatisch vorgeschlagen werden, wenn sich ein Kunde im Webshop registriert oder im Check-out einen Kaufprozess abschließen möchte.
- endereco speichert die Abfragen in einem permanenten, unveränderbaren Log für 10 Jahre ab. Damit können die Anfragen an die Behörden rechtskonform nachgewiesen werden.
So funktioniert die Anbindung #
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.
Beispiel-Request – Company Name Autocomplete
{
"jsonrpc": "2.0",
"id": 1,
"method": "companyAutocomplete",
"params": {
"countryCode": "de",
"companyName": "endereco UG"
}
}Beispiel-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" ]
} }Qualifizierte USt-IdNr. Prüfung #
Gegenüber der einfachen Prüfung einer USt-IdNr. auf Gültigkeit wird die qualifizierte Prüfung wesentlich umfangreicher durchgeführt:
- .
Es wird die zu prüfende USt-IdNr. als “vatId” übergeben. Die USt-IdNr. der anfragenden Firma wird als “requesterVatID” übergeben.
Zum Abgleich der Adresse und des Firmennamens werden für die qualifizierte Prüfung zusätzlich noch folgende Daten übergeben:
-
- Eigene USt-IDNr.
- zu prüfender Firmenname (Inkl. rechtlicher Firmierung)
- Zu prüfendeUSt-IdNr.
- PLZ und Ort
-
- Straße und Hausnummer
- 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!
Beispiel Request für eine Qualifizierte USt-IdNr. Prüfung #
für eine qualifizierte USt-IdNr.-Prüfung sind die Parameter
- vatId
- requesterVatId
- companyName
- companyPostalCode
- companyLocality
- CompanyStreetFull
notwendig. Das zugehörige Land wird über die ersten Ziffern der abzufragenden USt-IdNr. ermittelt.
Fehlen Parameter oder sind Parameter ungültig, so wird automatisch auf eine einfache USt-IdNr.-Prüfung gewechselt.
{
"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"
}
}Beispiel Response einer qualifizierten USt-IdNr. Prüfung #
Die Response ist in vier Teile untergliedert:
-
- predictions
Hier ist der offizielle Datensatz der angefragten Firma enthalten. Die Adresse wird in strukturierter Form zurückgeliefert. Die Adresse entspricht der im Handelsregister hinterlegten Adresse, und muss nicht postalisch korrekt sein. Dafür kann ein Adresscheck zusätzlich durchgeführt werden, um eine postalische Zustellbarkeit sicherstellen zu können. - Certification
Hier ist der Teil des Bundeszentralamtes für Steuern oder der entsprechenden landesspezifischen Behörde enthalten. Ist das Zertifikat in der Antwort enthalten, so ist es eine offizielle Anfrage in Echtzeit, innerhalb des gesetzten Timelimits. Ist das Zertifikat NICHT enthalten, kommt die Antwort aus dem Cache und die Anfrage muss zu einem späteren Zeitpunkt nochmals wiederholt werden, um eine offizielle Prüfanfrage gegenüber der Finanzbehörde nachweisen zu können.
3. CertificationStatus
Hier wir die Quelle der Antwort zurückgeliefert. Entweder sie kommt vom Bundeszentralamt für Steuern oder aus dem Cache.
4. Status
Hier ist der Status zu den übermittelten Feldern hinterlegt:
– Die Gültigkeit der USt-IdNr.
(Einen Überblick aller gültige Formate in verschiedenen Ländern findest du hier)
– Informationen zu mögliche Anpassungen der USt-IdNr.
– Vergleich des Firmennamens – Eingabe vs. gefundener Firmenname
– Vergleich der Firmenadresse – Eingabe vs. gefundene Firmenadresse: sowohl auf Adressebene als auch auf Einzelfeldebene.
- 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:
Das Log über den Nachweis der Prüfungen wird auf unserem Server gespeichert und regelmäßig gesichert. Er enthält die Anfragen sowohl mit Zertifikat, also die offiziell gültigen Anfragen, als auch die Anfragen aus dem Cache, die nochmals angefragt werden müssen.
Das Log wird dann im regelmäßigen Turnus exportiert und an die entsprechenden Kunden zur Archivierung übermittelt.
Details:
Details zur Implementierung:
Die Abfrage ist in unserer Postman Collection enthalten:
endereco Postman Collection herunterladen
Die Anfragen sind auf Github in unserer API-Dokumentation beschrieben:
Error Codes im Zertifikat:
Im Teil der Zertifikation werden Errorcodes ausgegeben. Diese sind 1:1 vom entsprechenden Datenprovider übernommen, und bewerten die Gültigkeit der abgefragten USt-IdNr.
Dort sind folgende Statuscodes (ErrorCodes) für die USt-IdNr. hinterlegt:
| ErrorCode | Beschreibung |
|---|---|
| 200 | Die angefragte USt-IdNr. ist gültig. |
| 201 | Die angefragte USt-IdNr. ist ungültig. |
| 202 | Die angefragte USt-IdNr. ist ungültig. Sie ist nicht in der Unternehmerdatei des betreffenden EU-Mitgliedstaates registriert. Hinweis: Ihr Geschäftspartner kann seine gültige USt-IdNr. bei der für ihn zuständigen Finanzbehörde in Erfahrung bringen. Möglicherweise muss er einen Antrag stellen, damit seine USt-IdNr. in die Datenbank aufgenommen wird. |
| 203 | Die angefragte USt-IdNr. ist ungültig. Sie ist erst ab dem … gültig (siehe Feld ‚Gueltig_ab‘). |
| 204 | Die angefragte USt-IdNr. ist ungültig. Sie war im Zeitraum von … bis … gültig (siehe Feld ‚Gueltig_ab‘ und ‚Gueltig_bis‘). |
| 205 | Ihre Anfrage kann derzeit durch den angefragten EU-Mitgliedstaat oder aus anderen Gründen nicht beantwortet werden. Bitte versuchen Sie es später noch einmal. Bei wiederholten Problemen wenden Sie sich bitte an das Bundeszentralamt für Steuern – Dienstsitz Saarlouis. |
| 206 | Ihre deutsche USt-IdNr. ist ungültig. Eine Bestätigungsanfrage ist daher nicht möglich. Den Grund hierfür können Sie beim Bundeszentralamt für Steuern – Dienstsitz Saarlouis – erfragen. |
| 208 | Für die von Ihnen angefragte USt-IdNr. läuft gerade eine Anfrage von einem anderen Nutzer. Eine Bearbeitung ist daher nicht möglich. Bitte versuchen Sie es später noch einmal. |
| 209 | Die angefragte USt-IdNr. ist ungültig. Sie entspricht nicht dem Aufbau der für diesen EU-Mitgliedstaat gilt. (Aufbau der USt-IdNr. aller EU-Länder) |
| 210 | Die angefragte USt-IdNr. ist ungültig. Sie entspricht nicht den Prüfziffernregeln die für diesen EU-Mitgliedstaat gelten. |
| 211 | Die angefragte USt-IdNr. ist ungültig. Sie enthält unzulässige Zeichen (wie z.B. Leerzeichen oder Punkt oder Bindestrich usw.). |
| 212 | Die angefragte USt-IdNr. ist ungültig. Sie enthält ein unzulässiges Länderkennzeichen. |
| 213 | Sie sind nicht zur Abfrage einer deutschen USt-IdNr. berechtigt. |
| 214 | Ihre deutsche USt-IdNr. ist fehlerhaft. Sie beginnt mit ‚DE‘ gefolgt von 9 Ziffern. |
| 215 | Ihre Anfrage enthält nicht alle notwendigen Angaben für eine einfache Bestätigungsanfrage (Ihre deutsche USt-IdNr. und die ausl. USt-IdNr.). Ihre Anfrage kann deshalb nicht bearbeitet werden. |
| 216 | Ihre Anfrage enthält nicht alle notwendigen Angaben für eine qualifizierte Bestätigungsanfrage (Ihre deutsche USt-IdNr., die ausl. USt-IdNr., Firmenname einschl. Rechtsform und Ort). Es wurde eine einfache Bestätigungsanfrage durchgeführt mit folgenden Ergebnis: Die angefragte USt-IdNr. ist gültig. |
| 217 | Bei der Verarbeitung der Daten aus dem angefragten EU-Mitgliedstaat ist ein Fehler aufgetreten. Ihre Anfrage kann deshalb nicht bearbeitet werden. |
| 218 | Eine qualifizierte Bestätigung ist zur Zeit nicht möglich. Es wurde eine einfache Bestätigungsanfrage mit folgendem Ergebnis durchgeführt: Die angefragte USt-IdNr. ist gültig. |
| 219 | Bei der Durchführung der qualifizierten Bestätigungsanfrage ist ein Fehler aufgetreten. Es wurde eine einfache Bestätigungsanfrage mit folgendem Ergebnis durchgeführt: Die angefragte USt-IdNr. ist gültig. |
| 221 | Die Anfragedaten enthalten nicht alle notwendigen Parameter oder einen ungültigen Datentyp. Weitere Informationen erhalten Sie bei den Hinweisen zum Schnittstelle – Aufruf. |
| 223 | Die angefragte USt-IdNr. ist gültig. Die Druckfunktion steht nicht mehr zur Verfügung, da der Nachweis gem. UStAE zu § 18e.1 zu führen ist. |
| 999 | Eine Bearbeitung Ihrer Anfrage ist zurzeit nicht möglich. Bitte versuchen Sie es später noch einmal. |
