DHL Api

DHL Datafactory ist eine Shop-Erweiterung welche die gleichnamige Schnittstelle der Deutschen Post verwendet um dem Kunden, bei Eingaben von Adressen, relevante Vorschläge aus deren Straßenverzeichnis anbietet. Dabei werden Informationen zur PLZ, dem Ort und der Straße berücksichtigt.

Konfiguration

Die Konfigurationstabelle "DHL Datafactory Konfiguration" findet sich standardmäßig im Bereich Shop → add in und dort in der Kachel DHL. API Benutzer und Passwort müssen von https://www.deutschepost.de/de/d/deutsche-post-direkt/datafactory.html bezogen werden. Es gibt hier auch die Optionen, die gesamte Funktion zu aktivieren / deaktivieren, die Funktion für einzelne Shop-Formulare zu aktivieren / deaktivieren und zu definieren ob die Felder umsortiert werden sollen.

Konfiguration Shop Formulare

Die Formulare wie das Adressbuch und die Benutzerdaten in der Registrierung, Mein Konto und dem Bestellprozess bedürfen keiner weiteren Konfiguration. Diese können in der Konfiguration aktiviert und deaktiviert werden. Falls jedoch Felder des Datensatzes für die Adressen oder die Benutzer mit einem Feld der Datenmodellierung ersetzt wird sollte die Konfiguration der erweiterbaren Formulare beachtet werden. Sonst würde hier die Konfiguration für die Zuordnung zu den Feldtypen wie PLZ verloren gehen.

Konfiguration erweiterbaren Formulare

Unterstützt werden hierbei das Kontaktformular und die .PIM Formulare v5.5.

Diese Formulare können diese Erweiterung für sich aktivieren indem sie Adressfelder mit der Datenmodellierung definieren und den verschiedenen Typen zuweisen. Diese Felder sollten, mit Ausnahme der Landauswahl und dem Feld für die Speicherung der manuellen Eingaben, ein Eingabefeld (einzeilig) sein. Die Softwarekonfiguration sollte wie folgt die folgenden Einstellungen für die verschiedenen Typen aufweisen.

Am Beispiel des Kontakformular:

{
  "dhlDatafactory": "postcode",
  "whitelist": [
    "contact"
  ]
}

{
  "dhlDatafactory": "city",
  "whitelist": [
    "contact"
  ]
}

{
  "dhlDatafactory": "street",
  "whitelist": [
    "contact"
  ]
}

{
  "dhlDatafactory": "houseNumber",
  "whitelist": [
    "contact"
  ]
}

{
  "dhlDatafactory": "country",
  "feature": "input/select.select/key/value",
  "enumerationPlugin": "shop/delivery",
  "enumerationFunction": "getEnumerationDeliveryCountrySelectIsoCode",
  "whitelist": [
    "contact"
  ]
}

{
  "blacklist": [
    "contact"
  ],
  "dhlDatafactory": "storage",
  "feature": "input/yaml.editable"
}

Für das Speichern der manuellen Eingaben siehe Manuelle Benutzereingabe.

Konfiguration Feld für das Land

Das Feld für das Land muss speziell konfiguriert sein. Es sollte ein Benutzerdefiniertes Feld sein mit folgender Konfiguration. Im Prinzip ist wichtig, dass die Werte keine IDs sind, sondern IsoCodes wie (DE, EN, etc).

{
  "dhlDatafactory": "country",
  "feature": "input/select.select/key/value",
  "enumerationPlugin": "shop/delivery",
  "enumerationFunction": "getEnumerationDeliveryCountrySelectIsoCode"
}

Felder umsortieren

Wenn diese Erweiterung aktiv ist, und im Falle der Shop Formulare auch diese Option aktiviert wurde, werden die betroffenen Felder im Formular umsortiert. Das zielt darauf ab, die Daten vom Kunden in der begünstigen Reihenfolge für die Schnittstelle abzufragen. Die Reihenfolge ist: Land, PLZ, Ort, Straße, Hausummer.

Bei den erweiterbaren Formularen wird das immer gemacht sobald diese Felder für diese Erweiterung definiert haben.

Manuelle Benutzereingabe - Diese Eingabe übernehmen

Dem Kunden wird die Möglichkeit gegeben, die Vorschläge zu ignorieren und seine eigene Eingabe zu übernehmen. Diese Funktion soll Fälle abdecken, bei denen die Schnittstelle keine ausreichende oder nur veraltete Vorschläge liefert. Wenn ein Kunde eine manuelle Eingabe vornimmt, wird dieses Feld farblich markiert und für weitere Schnittstellenabfragen ignoriert. Ausnahme dabei die PLZ.

Speichern der manuellen Eingaben

Damit die manuellen Eingaben an einem Datensatz gespeichert werden, muss ein spezielles Feld an dem Datensatz vorhanden sein. Dieses Feld sollte wie folgt konfiguriert sein.

Die Softwarekonfiguration sollte dann ähnlich wie folgt aussehen. Der Blacklist-Key catalogueform bezieht sich hier auf ein Formular das welches über Formulare im CMS nutzen auf der Seite platziert wurde. Wichtig ist hier "dhlDatafactory: storage" da diese Auszeichnung das Feld als Datenspeicher für die manuellen Benutzereingaben definiert.

{
  "blacklist": [
    "catalogueform",
    "contact"
  ],
  "dhlDatafactory": "storage",
  "feature": "input/yaml.editable"
}

Kundendatensätze und Adressen haben dieses Feld schon vorkonfiguriert sofern es nicht über die Datenmodellierung überschrieben wurde.

Layoutkonfiguration

Diese Erweiterung verwendet die UI-Komponente Autocomplete um die Vorschläge darzustellen. Diese kann in der Layoutkonfiguration angepasst werden.

Events

Diese Erweiterung registriert sich auf mehre Events anderen Erweiterungen.

dhlDatafactoryEvent

Interface: \brandbox\shop\dhlDatafactory\lib\event\dhlDatafactoryEventInterface
Adapter: \brandbox\shop\dhlDatafactory\lib\event\adapter\dhlDatafactoryEventAdapter

onUpdateStorage

dtoEventUpdateStorage