VAT Validation — Qualifizierte UID-Validierung¶

Extension for Magento 2¶

Bedienungsanleitung¶

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Inhaltsverzeichnis¶

Abschnitt	Seite
1 Installation	3
2 Konfiguration	4
2.1 Allgemeine Einstellungen	4
2.2 Qualifizierte Pruefung	5
2.3 Endereco Einstellungen	6
2.4 Frontend Einstellungen	7
3 Validierte UID-Nummern	8
4 Admin: UID-Validierung im Kundenkonto	9
5 Frontend-Validierung	10
5.1 Qualifizierte Pruefung im Frontend	10
5.2 Unqualifizierte Pruefung im Frontend	11
6 Sonstige Informationen	11
7 REST-API	12
7.1 UID validieren	12
7.2 Validierte Ergebnisse (CRUD)	12

1 Installation¶

Voraussetzungen¶

Magento 2.4.7 oder hoeher (kompatibel mit 2.4.8)
PHP 8.1 oder hoeher

Basismodul¶

Das Basismodul stellt die Kernfunktionalitaet zur Verfuegung. Es ersetzt die Standard-UID-Validierung von Magento mit einer qualifizierten Validierung. Das Basismodul wird mit der Validierung ueber Endereco ausgeliefert.

composer require copex/module-vat-validation
bin/magento setup:upgrade

Frontend-Modul (optional)¶

Das Frontend-Modul ermoeglicht eine direkte "On the fly"-Validierung im Frontend (Checkout, Kundenregistrierung, Adressbearbeitung). Ist dies nicht gewuenscht, kann es weggelassen werden. Das Basismodul wird automatisch mit installiert.

composer require copex/module-vat-validation-frontend
bin/magento setup:upgrade

Optionale Validierungsdienste¶

Paket	Beschreibung
`copex/module-vat-validator-austria`	Validierung ueber das oesterreichische FinanzOnline
`copex/module-vat-validator-germany`	Validierung ueber das deutsche BFF-Online

2 Konfiguration¶

Die Konfiguration des Moduls finden Sie im Magento 2 Admin unter Stores > Configuration > Sales > Vat Validation.

2.1 Allgemeine Einstellungen¶

Modul-Version -- Zeigt die aktuell installierte Version des Moduls an. Diese Angabe dient zur Ueberpruefung, ob die installierte Version auf dem neuesten Stand ist.
Modul aktivieren -- Steuert, ob das UID-Validierungsmodul aktiv ist. Bei "Ja" wird die Validierung von Umsatzsteuernummern durchgefuehrt.
API-Typ -- Bestimmt, welcher externe Dienst zur Validierung der UID verwendet wird. Verfuegbare Optionen haengen von den installierten Modulen ab (Endereco, FinanzOnline, BFF-Online).
Kommentar fuer Validierung auf der Bestellung speichern -- Wenn aktiviert, wird das Validierungsergebnis direkt als Kommentar in der jeweiligen Bestellung dokumentiert.

Gueltige Validierung zwischenspeichern -- Bestimmt in Sekunden, wie lange ein validiertes Ergebnis zwischengespeichert wird (Standard: 86400 = 24 Stunden). Solange ein Eintrag in der Datenbank vorhanden ist, der noch nicht abgelaufen ist, werden die Resultate direkt aus der Datenbank verwendet und es erfolgen keine neuen Anfragen an den Validierungspartner.

2.2 Qualifizierte Pruefung¶

Bei der qualifizierten Pruefung wird die UID nicht nur auf formale Korrektheit ueberprueft, sondern auch mit den Unternehmensangaben abgeglichen. Damit eine UID als gueltig anerkannt wird, muessen die hinterlegten Informationen mit den Daten der Validierungsquelle uebereinstimmen.

Der Wert wird in Prozent angegeben und ist individuell pro Feld einstellbar:

Firmenname -- Uebereinstimmung des Firmennamens in Prozent
Strasse -- Uebereinstimmung der Strasse in Prozent
Ort -- Uebereinstimmung des Ortes in Prozent
Postleitzahl -- Uebereinstimmung der Postleitzahl in Prozent

Bei 0% findet keine qualifizierte Pruefung fuer das jeweilige Feld statt. Bei 100% muessen die eingegebenen Daten exakt den Daten entsprechen, mit denen die UID registriert ist. Ein Wert dazwischen erlaubt Tippfehler bzw. Variationen bei der Schreibweise.

Die UID selbst wird in jedem Fall auf Gueltigkeit ueberprueft. Abweichungen sind hier nicht zulaessig.

Hinweis zu zusaetzlichen Kosten: Durch die Nutzung der qualifizierten Validierung koennen je nach API-Typ zusaetzliche Kosten entstehen. Beim Anbieter Endereco fallen hier zum Beispiel zusaetzliche Kosten an. Moechten Sie zusaetzliche Kosten vermeiden, setzen Sie alle Optionen auf 0%.

2.3 Endereco Einstellungen¶

API URL -- Die URL des Endereco-Validierungsdienstes (Standard: https://endereco-service.de/rpc/v1)
API Key -- Ihr persoenlicher Endereco API-Schluessel

Falls Sie noch keinen API Key haben, koennen Sie diesen direkt bei Endereco beantragen: https://www.endereco.de/apikey-beantragen/

2.4 Frontend Einstellungen¶

Dieser Abschnitt ist nur sichtbar, wenn das Frontend-Modul (copex/module-vat-validation-frontend) installiert ist.

Anzeige im Checkout -- Bestimmt, ob die UID-Validierung waehrend des Bestellvorgangs im Checkout angezeigt wird. Bei "Ja" wird die Validierung nach der konfigurierten Verzoegerung per AJAX durchgefuehrt und fuer den Kunden sichtbar gemacht.
Fehler erzwingen -- Wenn auf "Ja" gesetzt, kann ein Kunde mit einer ungueltigen UID keinen Einkauf taetigen. Bei "Nein" ist der Kauf auch mit einer ungueltigen UID moeglich.
Checkout Tooltip Nachricht -- Eine Nachricht, die Kunden beim Checkout als Hinweis zur UID-Validierung angezeigt wird (z.B. "Wir validieren Ihre UID nach qualifizierten Kriterien.").
Anzeigen bei der Kundenregistrierung -- Legt fest, ob bei der Kundenregistrierung die UID-Validierung per AJAX angezeigt wird.
Anzeigen beim Bearbeiten der Kundenadresse -- Legt fest, ob beim Aendern der Kundenadresse die UID-Validierung per AJAX angezeigt wird.
Qualifizierte UID-Validierung im Frontend -- Steuert, ob die qualifizierte UID-Validierung direkt im Frontend durchgefuehrt wird. Bei "Nein" erfolgt die strengere Pruefung nur im Backend.
Verzoegerung -- Gibt an, wie lange (in Millisekunden) nach der Eingabe gewartet wird, bevor die UID-Validierung durchgefuehrt wird (Standard: 3000 ms = 3 Sekunden).

3 Validierte UID-Nummern¶

Die validierten Ergebnisse koennen im Admin unter Shops > Steuern > Validierte UID-Nummern eingesehen werden.

Jeder Eintrag kann in den Aktionen jederzeit erneut validiert oder aus der Datenbank geloescht werden.

Solange ein Eintrag in der Datenbank vorhanden ist, der noch nicht abgelaufen ist, werden die Resultate direkt aus der Datenbank verwendet und es erfolgen keine neuen Anfragen an den Validierungspartner (FinanzOnline, Endereco, BFF).

4 Admin: UID-Validierung im Kundenkonto¶

Qualifizierte UID-Daten koennen im Adminbereich bei einem Kunden durchgefuehrt werden. Editieren Sie dazu einen Kunden (im Admin unter Customers > All Customers) und klicken Sie auf die Schaltflaeche in der Kopfzeile: "UID-Nummer Validierung".

Es erscheint ein Popup mit einem Eingabefeld fuer die zu pruefende UID.

Mit Klick auf "Ueberpruefen" wird die UID-Nummer geprueft. Bei einer inkorrekten UID erhalten Sie das Ergebnis "Validierungsstatus: Invalid". Wird die UID als valide erkannt, haben Sie die Option, die Daten (sofern verfuegbar) auf eine vorhandene Adresse zu kopieren und automatisch am Kundenkonto abzuspeichern.

Falls der Kunde noch keine Standard-Rechnungs- oder Versandadresse hat, wird beim Kopieren automatisch eine neue Standard-Adresse angelegt.

5 Frontend-Validierung¶

Die Frontend-Validierung ist nur verfuegbar, wenn das Frontend-Modul (copex/module-vat-validation-frontend) installiert ist. Sie ermoeglicht dem Benutzer direktes Feedback auf seine UID-Eingabe im Checkout, bei der Kundenregistrierung und beim Bearbeiten der Kundenadresse.

5.1 Qualifizierte Pruefung im Frontend¶

Ist die qualifizierte Pruefung fuer das Frontend aktiviert, wird dies explizit angezeigt. Es erscheint ein zusaetzliches Icon bei erfolgreicher Validierung. Ausserdem werden Fehlermeldungen ausgegeben, welche Felder nicht uebereinstimmen.

5.2 Unqualifizierte Pruefung im Frontend¶

Bei der unqualifizierten Pruefung wird nur die formale Gueltigkeit der UID geprueft, ohne Abgleich mit den Adressdaten.

Gueltige UID mit Tooltip:

Ungueltige UID:

6 Sonstige Informationen¶

Wichtig -- Firmendaten hinterlegen: Damit die (qualifizierte) UID-Validierung korrekt funktioniert, muessen die Unternehmensdaten unter Stores > Configuration > General > General > Store Information vollstaendig und korrekt hinterlegt sein -- insbesondere die Geschaeftsadresse (Land, Strasse, PLZ, Ort) sowie die VAT Number (UID-Nummer Ihres Unternehmens). Diese UID wird als anfragende Partei an den Validierungsdienst uebermittelt; ist sie nicht oder falsch hinterlegt, kann die qualifizierte Pruefung nicht durchgefuehrt werden.

Fuer die Validierung der Adressen greift das Modul auf die Standardeinstellungen von Magento zurueck. Diese sind zu finden unter: Stores > Configuration > Sales > Tax.

Hinweis zum Bestellkommentar: Der automatische Eintrag des Validierungsergebnisses als Bestellkommentar setzt voraus, dass die UID-Daten an der Bestelladresse gespeichert werden. Ist das Frontend-Modul (copex/module-vat-validation-frontend) installiert, geschieht das automatisch. Bei einer Installation nur des Basismoduls muss zusaetzlich Magentos UID-Validierung bei Transaktionen aktiv sein: Stores > Configuration > Customer Configuration > Create New Account Options > Enable Automatic Assignment to Customer Group = Yes. Andernfalls wird das Ergebnis nur protokolliert (siehe Abschnitt 3), aber nicht an der Bestellung dokumentiert.

Steuerliche Behandlung von EU-Geschaeftskunden (Reverse-Charge) richten Sie ueber die Magento-Standardeinstellungen ein. Die offizielle Anleitung dazu finden Sie in der Adobe-Commerce-Dokumentation: Value added tax (VAT) und Taxes.

7 REST-API¶

Das Basismodul stellt eine REST-API bereit. Alle Endpunkte sind ueber Admin-Token (Integration) abgesichert und benoetigen die jeweilige ACL-Berechtigung.

7.1 UID validieren¶

POST /rest/V1/copex-vat-validation/validate — ACL: CopeX_VatValidator::validate

Ohne Adressdaten wird eine einfache Pruefung durchgefuehrt, mit Adressdaten die qualifizierte Pruefung.

Request:

{
  "vatId": "ATU12345678",
  "company": "ACME GmbH",
  "postcode": "1010",
  "city": "Wien",
  "street": "Ring 1"
}

Response:

{
  "vat_id": "ATU12345678",
  "is_valid": true,
  "vat_id_valid": true,
  "is_qualified": true,
  "request_success": true,
  "message": "UID-Nummer ist qualifiziert",
  "request_identifier": "VALIDATIONID-7",
  "request_date": "2026-06-19 09:00:00",
  "company": "ACME GmbH",
  "postcode": "1010",
  "city": "Wien",
  "street": "Ring 1",
  "country": "AT"
}

7.2 Validierte Ergebnisse (CRUD)¶

Methode	Endpunkt	ACL
GET	`/rest/V1/copex-vat-validation/results` (searchCriteria)	`CopeX_VatValidator::resource`
GET	`/rest/V1/copex-vat-validation/results/:id`	`CopeX_VatValidator::resource`
POST	`/rest/V1/copex-vat-validation/results` (anlegen/aktualisieren)	`CopeX_VatValidator::resource`
DELETE	`/rest/V1/copex-vat-validation/results/:id`	`CopeX_VatValidator::delete`

Lizenz¶

Proprietär — CopeX GmbH. Eine Lizenz pro produktiver Magento-Instanz. Test- und Entwicklungsumgebungen benötigen keine zusätzliche Lizenz.