Installationsanleitung für Magento2

Endereco Address Management Service Module (AMS)
Für Magento 2.2.x – 2.4.x

Release Notes:

Current release notes can be found on our Github page:

Release Notes zur aktuellen Version 1.2.0

Änderungen in dieser Version:
  • Added support for JavaScript-debugging
  • Added support for separate request/response-logging
  • Renamed “Base URL” to “API Endpoint” in configuration
  • Fixed house number bug. An empty house number was taken as string “null” in the selected address
  • Fixed city bug – city was not provided to API for address book entries
  • Added eMail check – at the moment it will display only warnings, no hard bounces yet

RELEASE-NEWSLETTER

Trage dich in unseren Release Newsletter then you will always be informed quickly when an update is made. 

Functional description

Endereco Address Management Services (AMS) is a simple and straightforward way to improve the quality of the address data entered by your customers. Incorrect addresses can be corrected directly by the customers through correction suggestions. The spelling of addresses is standardised . For this purpose, a two-stage process is integrated into the address forms, which ensures that the data is entered correctly via almost all input devices.

Step 1 - directly during the input

a) Adresseingabe-Assistent (In Entwicklung)

Suggestions for entered address fragments are displayed in an autocomplete function of street, postcode and city. This works on PCs, tablets and smartphones. Address entry is simplified, accelerated and the error rate is massively reduced.

b) Anredeprüfung (In Entwicklung)

The Endereco first name database with over 30,000 entries can recognise gender-specific first names and marks the corresponding salutation field of your webshop. Ambiguous or unknown names are ignored. Upper and lower case is automatically corrected.

c) Validation of the e-mail address

An entered e-mail address is checked for various characteristics in real time:

  • Valid syntax of the e-mail address
  • Valid country domain
  • Is the e-mail inbox registered and accessible?
  • Is the mailbox full or deliverable?
  • Is it a disposable address or SPAM e-mail address?

Step 2 - when submitting the form

a) AddressCheck

The address check validates entered address fields for validity in the overall context. For implausible entries, valid correction surcharges are automatically offered. The customer can choose between his entry and one of the correction thresholds.

DemoShop


Installation instructions

2.1 New installation of the module

Die Installation kann manuell oder über den Composer erfolgen

Option 1 – Manuelle Installation:

Lade den aktuellsten Release des Endereco AMS Moduls für Magento2 von GitHub down.

Option 2: Installation über den Composer

Hierfür einfach den Befehl unten ausführen.

composer require devcccc/magento2-address-validation

php bin/magento module:enable CCCC_Addressvalidation
php bin/magento setup:upgrade

//optional bei Produktivsystemen:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy

2.2 Update of the module

Um Endereco Client für Magento auf neuesten Stand zu bringen, rufen Sie einfach

//download des moduls
composer update devcccc/magento2-address-validation

//aktivieren des moduls
php bin/magento setup:upgrade

//optional bei Produktivsystemen:
bin/magento setup:di:compile
bin/magento setup:static-content:deploy

2.3 Aktivieren des Moduls im Magento Backend

Du kannst ganz einfach den Modul im Backend unter
Shops => Konfiguration CCCC Config => Address Validation: Endereco aktivieren

Request access data

3.1 Test Zugangzdaten

Das Modul funktioniert nur mit gültigen Zugangsdaten. Diese kannst du auf unsere Webseite unter //www.endereco.de/magento/ or directly by e-mail to info@endereco.de free of charge.

Du kannst dann das Modul inklusive alle Services 30 Tage unverbindlich testen.

3.2 Live access data

For the live access data we need two signed and approved contracts, namely provider contract and data processing contract. You will find both contracts in your installation package. Of course we will gladly send you the contracts again by e-mail.

About the data processing contract: For some services in which we process personal data of the customer or pass them on to third parties via interfaces according to the DSGVO, we need a data processing contract. For example, when it comes to an e-mail deliverability check or telephone number standardization. You will also find this in the installation package.

Please send both signed contracts to
info@endereco.de or by fax to: 0931 6639839-9 or by mail to us.
We need a release from the German Post, which can take about 2-3 days.

Endereco UG (limited liability)
Robert Rieser
Balthasar-Neumann-Str. 4b,
97236 Edge bag

Configuration of the module 

Hier findest du die Erläuterungen zu den einzelnen Moduleinstellungen und deren Funktionsweise im Backend des Magento2 Moduls.

4.1 Eingabe der Zugangsdaten und Grundeinstellungen

In den Moduleinstellungen kannst du nun die Zugangsdaten hinterlegen und die Grundeinstellungen konfigurieren.

Enable Integration:
Damit können alle Funktionen des Moduls für eine Webseite ein & ausgeschaltet werden.

Auth Key: Hier sollst du den von Endereco erhaltenen Api-Key hinterlegen. Achte darauf, dass hier keine Leerzeichen mit reinkopiert werden.

API URL: Diese sollte auf //endereco-service.de/rpc/v1 zeigen.

Optional können wir auch eine Staging URL bereitstellen, z.B. für das Testen neuer Funktionen.

Referer-Mode: hier sollte nur die Base-URL übermittelt werden. Ansonsten werden die zu prüfenden Adressen in Klartext über die URL an Endereco übermittelt.


4.2 Feldermatching

Die Endereco Adressprüfung arbeitet mit den Feldern

  • Country
  • Place
  • PLZ
  • Street
  • Hausnummer
  • Adresszusatz (Optional)

Diese müssen korrekt zugewiesen werden.

Du kannst für Straße + Hausnummer “street[0]” zuweisen oder getrennt, also

  • Straße: street[0] und
  • House number: street [0]

or

  • Straße: street[0] und
  • House number: street [1]

Endereco kann Straße und Hausnummer trennen, wenn sie in einem Feld übergeben werden und somit einzeln wieder zurückliefen. Das ist sinnvoll um z.B. zu erkennen, ob eine Hausnummer vergessen wurde. Dafür müssen wir auf Server-Seite die richtige Konfiguration setzen, um den Adress-Splitter zu aktivieren.

Weiterhin ist es möglich einen Adresszusatz zu erkennen und diesen von Straße und Hausnummer abzutrennen, falls er im falschen Feld hinterlegt wurde. (BETA)

4.3 Einzelne Funktionen aktivieren

Folgende Features kannst du aktuell nutzen:

  • Adressprüfung für Rechnungs- und Lieferadresse
  • E-mail verification

Adresscheck: prüft eine Adresse auf Korrektheit mit dem Absenden des Formulars (on Submit). 

Je nach Ergebnis werden dem Kunden unterschiedliche Informationen zurückgeliefert

  • Adresse korrekt – keine Änderung notwendig
  • Adresse normiert – nur kleine Änderungen
  • Adresse mit Korrekturvorschlag
  • Adresse mehrdeutig – Adressliste zur Auswahl
  • Adresse nicht gefunden Meldung
  • Adresse unvollständig

Force Valid Address: Hindert den Kunden am Checkout, wenn er keine von Endereco als gültig geprüfte Adresse hinterlegt. Dies ist im Zweifel nicht empfehlenswert, das z.B. durch Neubaugebiete oder andere Dinge wie Eingemeindungen usw. nicht von einer immer 100% vollständigen und aktuellen Datenbasis auszugehen ist.

E-Mail Check: Die E-Mail Adresse wird auf Syntax und Erreichbarkeit geprüft. Dabei wird neben der formal richtigen E-Mail auch z.B. die Länderdomain auf Gültigkeit geprüft sowie auf dem Mailserver eine MX Validieren durchgeführt. Die meisten E-Mail Server sind so konfiguriert, dass sie Auskunft über die Zustellfähigkeit und Erreichbarkeit eines E-Mail Postfaches geben.

Du kannst weiterhin entscheiden welche der Kunden-Adressen geprüft werden. 

  • Rechnungsadressen
  • Lieferadressen
  • Adressen des Adressbuches

Es wird immer beim Gang zum Checkout, d.h. bei Kunden mit Kaufabsicht geprüft. 

4.4 Entwicklereinstellungen

Folgende Einstellungen kannst du aktivieren:

  • Javascript-Debugging
  • Write Validation log
  • Write validation log
    Für jeden Request/Response wird ein eindeutiger Hash erzeugt, der im Log jeder Meldung vorangestellt wird – so lässt sich auch bei parallelen Anfragen leicht ermitteln, welche Meldungen zusammengehören.
  • Enable Javascript Debugging
    Es werden console.debug-Meldungen in der Entwicklerkonsole des Browsers protokolliert, an denen erkennbar ist, welche Operationen durchgeführt werden. Ausgehend von diesen Meldungen können dann auch entsprechende JavaScript-Breakpoints gesetzt werden.

Functional test 

Now, after selecting the country "Germany" and entering a postcode, you should receive suitable suggestions for the city. Suggestions should also appear when you enter the street.

Have fun using our module. We are looking forward to your feedback, suggestions and feedback. This is the only way we can optimize our services for you!

If you have any questions we will be happy to help you!
Simply send an e-mail to: info@endereco.de oder Tel: 0931 66 39 839 – 0
Your Endereco Team

Robert Rieser
CEO - Contact person for your inquiries

You still have questions or would like to discuss special requirements?

You can arrange a free meeting with our experts!

Extract of our customers

    References

    © Endereco UG (haftungsbeschränkt) - Gesellschaft für Master Data Quality Management - 2014 - 2021- Made with ♥ in Franconia