Installationsanleitung für Magento 2 (Backend Adressvalidierung)

Dieses Modul wurde in enger Zusammenarbeit mit unserer Partneragentur Parc Network entwickelt. Parc Network ist eine erfahrene Magento-Agentur, die Shops bei Magento-Entwicklung, individuellen Erweiterungen und der Umsetzung komplexer Projekte unterstützt.

Funktionsbeschreibung #

Was leistet das Modul?

Anders als bei unseren Frontend-Modulen für Shopware, JTL & Co. läuft die Prüfung hier nicht während der Kundeneingabe im Checkout, sondern automatisiert im Nachgang – per Cronjob direkt in deinem Magento-Backend.

Das endereco Backend-Modul für Magento 2 prüft die Versandadressen deiner eingehenden Bestellungen automatisch im Hintergrund über die endereco API. Bestellungen mit problematischen Adressen werden zur manuellen Prüfung angehalten. So bleibt dein Fulfillment sauber und du vermeidest Zustellprobleme, bevor sie entstehen.

Kernfunktionen

Automatische Prüfung im Hintergrund

• Ein Cronjob prüft neue Bestellungen in deinem konfigurierten Bestellstatus
• Jede Versandadresse wird an die endereco API übergeben und ausgewertet
• Keine Kundeninteraktion nötig – die Prüfung läuft komplett automatisiert

Zuverlässige Sperrung bei Problemen

• Mehrdeutige oder fehlerhafte Adressen werden zur manuellen Prüfung angehalten
• Eindeutige Korrekturen kannst du optional automatisch übernehmen lassen
• Adressen mit Zusätzen (z. B. Wohnungsnummer) lassen sich gezielt immer zur Prüfung markieren

Nachvollziehbare Datenhaltung

• Originaladresse, API-Vorschlag und manuelle Korrektur werden getrennt gespeichert
• Alle Änderungen sind für Audits und CSV-Exporte jederzeit nachvollziehbar
• Frei konfigurierbarer CSV-Export direkt aus dem Bestellraster

Business-Nutzen für dich als Shop-Betreiber

• Weniger Zustellprobleme: Fehlerhafte Adressen werden erkannt, bevor die Ware verschickt wird
• Geringere Retourenquote: weniger unzustellbare Sendungen durch falsche oder unvollständige Adressen
• Weniger manueller Aufwand: kleinere Tippfehler und Formatierungsunterschiede korrigiert das Modul automatisch
• Volle Kontrolle: du entscheidest selbst, welche Fehlerarten zu einer Sperre führen und welche automatisch korrigiert werden
• Saubere Datenbasis: normierte, geprüfte Adressen stehen dir für CSV-Export und angebundene Systeme zur Verfügung

Funktionen im Detail #

So läuft die Prüfung ab

1. Ein Cronjob prüft in regelmäßigen Abständen neue Bestellungen in deinem konfigurierten Bestellstatus.
2. Jede Versandadresse wird an die endereco API zur Prüfung übermittelt.
3. Je nach Ergebnis passiert eines von zwei Dingen:
   • Die Bestellung wird zur Prüfung angehalten, wenn die Adresse mehrdeutig ist, einen Adresszusatz enthält oder einen kritischen Status zurückliefert, oder
   • die Adresse wird automatisch korrigiert, wenn das Ergebnis eindeutig ist und die automatische Überschreibung aktiviert ist.
4. Alle Ergebnisse werden in der Datenbank gespeichert – Originaladresse, API-Vorschlag und jede manuelle Korrektur.

Voraussetzungen #

• Magento 2.4 oder neuer
• Ein aktiver endereco-Account mit gültigem API-Key → API-Key hier anfordern
• Aktivierte Cronjobs in deiner Magento-Installation

Installation #

Hinweis für Live-Shops: Führe setup:upgrade auf einem produktiven Shop immer mit dem Flag –keep-generated aus:

php bin/magento setup:upgrade --keep-generated

Ohne dieses Flag löscht und baut Magento während des Updates den gesamten automatisch generierten Code neu auf. Das kann zu einer kurzen Downtime für deine Kunden führen. Das Flag sorgt dafür, dass der bestehende generierte Code erhalten bleibt und das Update ohne Unterbrechung läuft. Auf Entwicklungs- oder Staging-Umgebungen ist das Flag nicht notwendig.

Installation per ZIP-Datei

1. Entpacke die ZIP-Datei nach app/code/Parc.

2. Aktiviere das Modul:

php bin/magento module:enable Parc_AddressValidation

3. Spiele die Datenbank-Updates ein:

php bin/magento setup:upgrade

4. Leere den Cache:

php bin/magento cache:flush

Installation per Composer

1. Stelle das Modul über ein Composer-Repository bereit, zum Beispiel:

• privates Repository repo.magento.com
• öffentliches Repository packagist.org
• öffentliches GitHub-Repository als VCS

2. Füge das Composer-Repository hinzu:

composer config repositories.repo.magento.com composer https://repo.magento.com/

3. Installiere das Modul:

composer require parc/module-addressvalidation

4. Aktiviere das Modul:

php bin/magento module:enable Parc_AddressValidation

5. Spiele die Datenbank-Updates ein:

php bin/magento setup:upgrade

6. Leere den Cache:

php bin/magento cache:flush

Zugangsdaten anfordern #

Das Modul funktioniert nur mit einem gültigen API-Key, den du von uns bekommst. Falls du noch keinen erhalten hast, kannst du ihn hier kostenfrei beantragen: API-Key beantragen

Konfiguration des Moduls #

Die Konfiguration findest du anschließend im Magento Backend unter Stores → Configuration → endereco Backend Address Validation → Address Validation.

„Enabled“ – schaltet das Modul ein oder aus.

„API Key“ – dein endereco API-Key.

„Cron Schedule“ – legt fest, wie oft der Prüfjob läuft (Standard: */10 * * * *, also alle 10 Minuten). Achte darauf, dass das Intervall groß genug ist, damit ein Durchlauf abgeschlossen ist, bevor der nächste startet. Mehr dazu unter Cron-Intervall und parallele Durchläufe.

„Order Status“ – legt fest, welche Bestellstatus zur Prüfung herangezogen werden. Wähle die Status, die zu deinem Bestellprozess passen – typischerweise der Status, den neue Bestellungen vor Beginn der Auftragsabwicklung haben. Üblich sind Pending oder Processing. Mehrfachauswahl ist möglich.

„Validation Hold Status“ – der Status, auf den Bestellungen gesetzt werden, wenn sie manuell geprüft werden müssen. Wir empfehlen dafür einen eigenen Status. Siehe Eigenen Status für die Adressprüfung anlegen.

„Sharpness“ – legt fest, welche API-Statuscodes zum Anhalten einer Bestellung führen (Klassifizierung A/B/C). Ausführlich erklärt unter Sharpness – wann Bestellungen angehalten werden.

„Check additional info“ – wenn aktiviert, werden Bestellungen mit Adresszusatz (z. B. Wohnungsnummer) immer zur Prüfung angehalten.

„Auto-Overwrite Address“ – wenn aktiviert, werden eindeutige API-Korrekturen automatisch in die nativen Magento-Adressfelder zurückgeschrieben. Aktivieren solltest du diese Option, wenn deine Versand- oder Fulfillment-Erweiterung direkt auf die nativen Magento-Adressfelder zugreift (z. B. Straße, PLZ, Ort). So werden kleinere Korrekturen der API auch dort übernommen. Deaktiviert lassen kannst du sie, wenn du einen eigenen Versand-Connector nutzt, der die geprüfte Adresse unabhängig aus der Tabelle parc_addressvalidation oder dem CSV-Export dieses Moduls liest. In diesem Fall sind die nativen Felder irrelevant.

„CSV Column Mapping“ – legt fest, welche Felder im CSV-Export enthalten sind und aus welchen Datenbanktabellen sie stammen. Ausführlich erklärt unter CSV-Spalten-Mapping.

Technische Details #

Attribute

Das Modul speichert die Prüfdaten in der Tabelle parc_addressvalidation. Zu jeder Bestellung wird ein Datensatz angelegt, der drei Versionen der Versandadresse nebeneinander enthält.

Metadaten

Originaladresse (orig_*) – die vom Kunden im Checkout eingegebene Adresse

API-Vorschlag (api_*) – die von der endereco API vorgeschlagene Korrektur

Manuelle Korrektur (manu_*) – von einem Admin-Benutzer eingegebene Korrektur

Priorität beim Anwenden oder Exportieren einer Adresse: manuelle Korrektur → API-Vorschlag → Original.

Angehaltene Bestellungen prüfen

Wenn eine Bestellung wegen der Adressprüfung angehalten wird, kannst du sie direkt im Magento Admin prüfen und korrigieren:

1. Gehe zu Sales → Orders und öffne die Bestellung.
2. Oben auf der Bestelldetailseite siehst du die Rechnungs- und Versandadresse, so wie sie der Kunde eingegeben hat.
3. Scrolle zum Bereich Validated Shipping Address. Hier wird die Adresse mit dem API-Vorschlag vorausgefüllt und in einzelne Felder aufgeteilt angezeigt. Die API trennt Straßenname und Hausnummer automatisch, auch wenn der Kunde beides zusammen eingegeben hat (z. B. wird Balthasar-Neumann-Str. 4a in Balthasar-Neumann-Str. und 4a aufgeteilt):
   • Hausnummer
   • Straße
   • Postleitzahl
   • Ort
   • Adresszusatz
4. Prüfe die Felder und nimm bei Bedarf Korrekturen vor.
5. Nutze eine der drei Schaltflächen, um fortzufahren:

„Save“ – speichert deine Änderungen im Prüfdatensatz, ohne sie bereits auf die Bestellung anzuwenden.

„Save as shipping address“ – speichert deine Änderungen und übernimmt die Adresse sofort als Versandadresse der Bestellung.

„Restore orig. shipping address“ – verwirft API-Vorschlag und manuelle Korrektur und stellt die ursprünglich vom Kunden eingegebene Adresse wieder her.

6. Sobald die Adresse korrekt ist, klicke oben auf der Seite auf Unhold, um die Bestellung wieder in die Bearbeitung zu geben.

Priorität beim Unhold: Manuelle Korrektur → API-Vorschlag → Originaladresse

CSV-Export geprüfter Adressen

1. Gehe zu Sales → Orders.
2. Wähle über die Checkboxen die gewünschten Bestellungen aus.
3. Wähle im Actions-Dropdown Export Validated Addresses (CSV).
4. Die Datei wird mit den unter CSV Column Mapping konfigurierten Spalten heruntergeladen.

CSV-Spalten-Mapping

Der CSV-Export ist frei konfigurierbar – du legst selbst fest, welche Spalten in der Datei erscheinen und wie sie heißen. Das Mapping richtest du in zwei Schritten unter Stores → Configuration → endereco Backend Address Validation → Address Validation ein.

Schritt 1: Relevante Tabellen auswählen

Lege zunächst fest, aus welchen Datenbanktabellen der Export Daten ziehen darf. Drei Tabellen stehen zur Verfügung:

Du kannst eine oder alle drei Tabellen auswählen. Speichere diese Auswahl, bevor du weitermachst. Die hier gewählten Tabellen bestimmen, welche Spalten in Schritt 2 zur Verfügung stehen.

Schritt 2: Spalten-Mapping festlegen

Sobald die Tabellen ausgewählt sind, kannst du das Spalten-Mapping aufbauen. Jede Zeile im Mapping definiert eine Spalte in der CSV-Datei:

• Column Header – die Bezeichnung, die in der CSV-Kopfzeile erscheint (z. B. Order Number, Validated ZIP). Frei wählbar.
• Data – der Wert, der in dieser Spalte steht, wählbar aus einem Dropdown mit zwei Gruppen:

Gruppe 1 – Geprüfte Adressfelder

Liefern immer die beste verfügbare Adresse – manuelle Korrektur hat Vorrang vor dem API-Vorschlag.

Gruppe 2 – Direkte Datenbankspalten

Jede Spalte der in Schritt 1 gewählten Tabellen steht hier zur Verfügung, angezeigt als tabellenname.spaltenname (z. B. sales_order_grid.increment_id). So kannst du beliebige Bestelldaten neben der geprüften Adresse mit ausgeben.

Beispiel-Mapping

Dieses Mapping zeigt die ursprüngliche Versandadresse (zum Zeitpunkt der Prüfung) neben der besten geprüften Adresse – nützlich für einen Vorher-Nachher-Vergleich oder zur Anbindung eines externen Fulfillment-Systems.

Hinweis: Die orig_*–Felder erfassen die Versandadresse zu dem Zeitpunkt, an dem der Cron die Bestellung erstmals geprüft hat. Die validated-Felder liefern immer die beste verfügbare Adresse – manuelle Korrektur hat Vorrang vor dem API-Vorschlag.

Der CSV-Export verwendet ; als Spaltentrennzeichen.

Sharpness – wann Bestellungen angehalten werden #

Die Sharpness-Einstellung steuert, wie streng das Modul Adressen filtert. Eine Bestellung wird zur Prüfung angehalten, sobald eine der folgenden Bedingungen zutrifft:

1. Die API liefert einen Statuscode zurück, den du als kritisch markiert hast.
2. Die Adresse enthält einen Zusatz (z. B. Wohnungsnummer) und Check additional info ist aktiviert.
3. Die API liefert mehr als eine mögliche Adresse zurück (diese Regel ist immer aktiv und kann nicht deaktiviert werden).

Konfigurierbare Statuscodes

Die endereco API liefert für jede geprüfte Adresse eine Reihe von Statuscodes zurück. Du legst fest, welche dieser Codes als kritisch gelten. Bei jeder Bestellung, in der ein kritischer Code auftaucht, wird die Bestellung zur Prüfung angehalten.

Die verfügbaren Codes sind nach Adressbestandteil gruppiert:

Check additional info

Ist diese Option aktiviert, wird jede Adresse mit Zusatz (z. B. Wohnungsnummer, Stockwerk, c/o) unabhängig von den zurückgegebenen Statuscodes immer zur Prüfung angehalten.

Empfohlene Einstellung

Ein guter Ausgangspunkt, der schwerwiegende Probleme zuverlässig abfängt und gleichzeitig kleinere Korrekturen automatisch durchlässt:

Als kritisch markieren (Bestellung wird angehalten):

• address_not_found
• address_multiple_variants
• address_major_correction
• building_number_is_missing
• building_number_not_found

Nicht als kritisch markieren (automatische Korrektur, wenn Auto-Overwrite aktiv ist):

• address_minor_correction
• postal_code_minor_correction
• street_name_minor_correction
• building_number_minor_correction

So werden eindeutig falsche oder nicht zustellbare Adressen zur manuellen Prüfung markiert, während kleine Tippfehler oder Formatierungsunterschiede automatisch korrigiert werden – ganz ohne Aufwand für dein Team.

Eigenen Status für die Adressprüfung anlegen #

Standardmäßig kannst du den Magento-Status holded als Validation Hold Status verwenden. Wir empfehlen jedoch, einen eigenen Status anzulegen (z. B. Address Validation Pending), damit Bestellungen mit Adressproblemen klar von anderen angehaltenen Bestellungen getrennt sind. Das erleichtert das Filtern und den gezielten CSV-Export der betroffenen Bestellungen erheblich.

Schritt 1: Neuen Status anlegen

1. Gehe zu Stores → Settings → Order Status.
2. Klicke auf Create New Status und fülle die Felder aus:
   • Status Code – interner Bezeichner, klein geschrieben mit Unterstrichen, z. B. address_validation_pending. Kann nach dem Speichern nicht mehr geändert werden.
   • Status Label – die im Admin angezeigte Bezeichnung, z. B. Address Validation Pending.
3. Klicke auf Save Status.

Schritt 2: Status dem „On Hold“-Zustand zuordnen

1. Klicke auf Assign Status to State.
2. Lege fest:
   • Order Status – deinen neuen Status auswählen.
   • Order State – On Hold (holded) auswählen. Das ist notwendig, da das Modul intern den Bestellzustand auf holded setzt, wenn eine Bestellung angehalten wird.
   • Use Order Status as Default – nur aktivieren, wenn dieser Status den Standard-Hold-Status vollständig ersetzen soll.
3. Klicke auf Save Status Assignment.

Schritt 3: Modul konfigurieren

1. Gehe zu Stores → Configuration → endereco Backend Address Validation → Address Validation.
2. Setze Validation Hold Status auf deinen neuen Status (Address Validation Pending).

Von dem Modul angehaltene Bestellungen erscheinen nun unter einem eigenen Status. Das macht das Filtern im Bestellraster und gezielte CSV-Exporte deutlich einfacher.

Cron-Intervall und parallele Durchläufe #

Hinweis: Dies ist eine bekannte Einschränkung, die in einer zukünftigen Version behoben wird. Bis dahin gilt folgende Empfehlung.

Der Prüf-Cronjob verarbeitet in einem Durchlauf alle noch nicht geprüften Bestellungen. Ist das Intervall zu kurz gewählt und ein Durchlauf dauert länger als das Intervall, können mehrere Instanzen des Jobs parallel starten. Dabei kann es passieren, dass zwei Durchläufe dieselbe Bestellung gleichzeitig verarbeiten, was zu Folgendem führen kann:

• doppelte Einträge in der Tabelle parc_addressvalidation
• doppelte Bestellkommentare
• die Bestellung wird zweimal angehalten

Was du bis zur Behebung tun kannst:

Wähle das Cron-Intervall so, dass ein Durchlauf sicher abgeschlossen ist, bevor der nächste startet. Ein sicherer Ausgangspunkt sind 10 Minuten (*/10 * * * *). Bei hohem Bestellvolumen solltest du das Intervall weiter erhöhen.

Um ein sicheres Intervall abzuschätzen, prüfe unter System → Action Logs, wie lange die letzten Durchläufe gedauert haben, oder bitte deine Entwicklung, die cron_schedule-Tabelle für den Job parc_addressvalidation zu prüfen.

Konfiguration: Stores → Configuration → endereco Backend Address Validation → Address Validation → Cron Schedule.

Häufige Probleme #

Bestellungen werden nicht geprüft.

• Prüfe, ob das Modul unter Stores → Configuration → endereco Backend Address Validation → Address Validation aktiviert ist.
• Prüfe, ob dein API-Key korrekt hinterlegt ist.
• Stelle sicher, dass die Bestellungen den unter „Order Status“ konfigurierten Status haben.
• Prüfe, ob der Cron auf deinem Server läuft (im Zweifel bei deinem Hosting-Anbieter nachfragen).

Alle Bestellungen werden zur Prüfung angehalten.

• Prüfe deine Sharpness-Einstellung. Eine strengere Einstellung führt dazu, dass mehr Bestellungen markiert werden.
• Prüfe, ob Check additional info aktiviert ist und ob deine Kunden häufig Wohnungsnummern angeben.

Die korrigierte Adresse wird nach dem Entsperren nicht übernommen.

• Stelle sicher, dass du die Adresskorrektur gespeichert hast, bevor du die Bestellung entsperrt hast.

Viel Erfolg beim Einsatz unseres Moduls! Über Feedback, Anregungen und Rückmeldungen freuen wir uns – nur so können wir unsere Services für dich weiter verbessern.

Bei Fragen helfen wir gerne weiter! Einfach per E-Mail an: support@endereco.de oder Tel: 0931 66 39839 – 0

Dein endereco Team