General

Profile


DHL Produkte und Services Oxid Modul

Dokumentation

ab Modul Version: 1.0.0
Shopversion: OXID ab 6.0

1. Funktionsumfang

Dieses Modul ermöglicht Ihnen eine Einbindung der DHL Produkte und Services für den Versand aus Deutschland und Österreich in Ihren Shop.

1.1 Versand

Die Versandservices umfassen aktuell die Erstellung von Versandlabels inklusive Filialrouting, Versandbestätigung, Beilegerretoure und die Überprüfung der Adresse auf Leitcodierbarkeit.

Labels können dabei einzeln, manuell im Batch oder automatisch über ein Consolenkommando erzeugt werden.

1.2 Wunschpaket

Dieses Modul ermöglicht Ihren Kunden zusätzlich einen zeitlich unabhängigen und örtlich flexiblen Empfang von Paketen. Dabei integriert das Modul die Suche nach Packstationen und Filialen (in Deutschland) in Ihren Shop und ermöglicht Ihren Kunden Pakete wann und wo Sie möchten zu empfangen.

Folgende Wunschpaket-Services bietet das Modul:

  • Suche nach Filialen und Packstationen
  • Angabe eines Wunschtags bzw. einer Wunschzeit
  • Angabe eins Wunschorts oder -nachbars

  

2. Support

Der First-Level-Support wird von DHL und der Second-Level-Support von mediaopt übernommen. Daher bitten wir Sie, Ihre Support-Anfrage an DHL zu richten. Nutzen Sie dafür die folgende E-Mail-Adresse: shopsoftware@deutschepost.de.

3. Installation

Vor einer Neuinstallation sichern Sie bitte die Daten Ihres Shops. Sollten Sie ein Update vornehmen wollen und das Modul zuvor individuell angepasst haben, sichern Sie bitte Ihre Änderungen. 
Sollten Sie Bedenken bezüglich der Installation des Moduls haben, lassen Sie diese von fachkundigem Personal vornehmen; gerne unterstützen wir Sie dabei. Dieses Modul wurde für die OXID Shop Editionen CE, PE, EE unter den o.g. Versionen entwickelt. Folgen Sie der Anleitung für einen problemlosen Betrieb. Sollte es Unklarheiten in den Installationsanweisungen geben, freuen wir uns über Ihr Feedback (support@mediaopt.de).

3.1 Dateien kopieren

  • Stellen Sie eine Verbindung z.B. via FTP zu Ihrem Webserver her.
  • Kopieren Sie den Inhalt des Verzeichnisses copy_this in das Stammverzeichnis ihres Shops.

3.2 Autoload hinzufügen

Bitte fügen Sie folgenden Eintrag in der composer.json Ihrer Oxid-Installation hinzu (source/composer.json):

"autoload": {
    "psr-4": {
      "Mediaopt\\DHL\\": "source/modules/mo/mo_dhl"
    }
  }

Führen Sie danach im gleichen Ordner folgenden Befehl aus:

composer dump-autoload

3.3 Modul aktivieren

Aktivieren Sie das Modul über die OXID Modulverwaltung.
 

 

3.4 Schreibrechte für die Logdatei

 

Zur Ablauf- und Fehlerdiagnostik protokolliert das Modul Ereignisse in Dateien mit dem Präfix "mo_dhl" im Ordner "/log". Stellen Sie daher bitte sicher, dass diese Dateien erstellt und bearbeitet werden können. Die Dateiberechtigungen können bspw. mit einem FTP-Client verwaltet werden.

3.5 Eintragen des API-Schlüssels für Google Maps

Siehe Google Maps-Einstellungen.

3.6 Registrierung bei DHL

Um neben den Wunschpaket Services auch die Versand-Services nutzen zu können, ist ein Zugang zum DHL Geschäftskundenportal erforderlich. Darüber hinaus müssen Sie für die Versandabwicklung über das Geschäftskundenportal freigeschaltet sein - in diesem Fall ist der Menüpunkt Versandabwicklung sichtbar. Bitte kontaktieren Sie für die Freischaltung Ihren DHL Kundenberater.

3.7 Gewählte Wunschpaketservices in Bestätigungsmail anzeigen

In der E-Mail zur Bestellbestätigung werden die Wunschpaket-Informationen standardmäßig entfernt.
Die Informationen werden in die Smarty-Variablen moEmpfaengerservicesPreferredTime, moEmpfaengerservicesPreferredLocation, moEmpfaengerservicesPreferredNeighbour bzw. moEmpfaengerservicesPreferredDay geschrieben.
Bei Bedarf können die Informationen hiermit in das gewünschte E-Mailtemplate wieder eingebunden werden.

4. Konfiguration

Die Angabe der DHL Kundennummer (EKP) ist erforderlich, um das DHL-Wunschpaket gemäß den Gegebenheiten in Ihrer Region anbieten zu können.

Wenn Sie darüber hinaus auch die DHL-Versandservices nutzen wollen, müssen Sie auch die Zugangsdaten für das Geschäftskundenportal eintragen.

Wichtig: Wenn Sie die Versand-Services testen möchten, können Sie den Haken "Nutze Testing-Webservice" aktivieren, den Benutzernamen und Passwort leer lassen und als EKP "2222222222" eintragen.

Damit das Modul eingesetzt werden kann, muss ein gültiger API-Schlüssel für Google Maps vorliegen (vgl. Google Maps-Einstellungen).
Außerdem muss, da dieses Modul für Packstationen und Filialen vorgesehen ist, eine Lieferung nach Deutschland möglich sein.

4.1 Versand

Hier können Sie den Versand konfigurieren, inklusive der Gewichtsermittlung, der Absenderdaten und der genutzten Services.

  • Nur leitcodierbare Adressen zulassen: Aktivieren Sie die Checkbox, wenn Versandetiketten nur für Adressen erstellt werden sollen, die seitens DHL als leitcodierbar gelten. Für nicht-leitcodierbare Adressen berechnet DHL in der Regel einen Aufschlag.
  • Gewichtermittlung:
    • Standardgewicht (in kg): Die hier eingetragenen Gewichte werden beim Erstellen der Versandetiketten verwendet, falls die automatische Gewichtsberechnung deaktiviert wird oder (bei aktivierter Gewichtsberechnung) für keinen Artikel innerhalb der Bestellung ein Gewicht gepflegt ist.
    • Paketgewicht automatisch berechnen: Ist dieses Feld aktiviert, werden die Paketgewichte automatisch auf Basis der Gewichte der enthaltenen Artikel sowie der prozentualen und fixen Gewichtsaufschläge berechnet.
    • Prozentualer Gewichtsaufschlag für Füllmaterial: Prozentualer Gewichtsaufschlag für Verpackungsmaterial auf Basis der Summe der Artikelgewichte, wenn die automatische Gewichtsberechnung aktiviert ist.
    • Gewichtsaufschlag für Verpackungsmaterial (in kg): Fester Gewichtsaufschlag in Kilogramm für Verpackungsmaterial, wenn die automatische Gewichtsberechnung aktiviert ist.
  • Absenderdaten: Tragen Sie hier die Adresse ein, die als Absender für die Versandlabelgenerierung genutzt werden soll
  • Versand-Services:
    • Filialrouting: Durch Aktivierung wird eine Sendung bei Unzustellbarkeit (z.B. Empfänger nicht ermittelbar) automatisch in die nächstgelegene Postfiliale weitergeleitet.
    • Alternative E-Mail-Adresse für das Filialrouting (optional): Geben Sie hier Ihre E-Mail-Adresse an, wenn Sie als Versender die Abholinformation erhalten möchten.
    • Automatische Paketankündigungen aktivieren: Sollte die Kunden-E-Mail-Adresse an DHL übermitteln werden, so wird Ihm von DHL eine Paketankündigung geschickt.
    • Kunden-E-Mail-Adresse an DHL übermitteln: Legen Sie fest, ob die E-Mail Adresse des Kunden an DHL übermittelt werden soll. Bei der Option Auf Kundenwunsch übermitteln erscheint, im Frontend bei jeder Versandart, der ein DHL-Produkt zugewiesen wurde, eine entsprechende Checkbox im Checkout-Prozess, sodass der Kunde über die Weitergabe seiner E-Mail-Adresse selbst entscheiden kann. Dies ist die empfohlene Einstellung gemäß der DSGVO.
    • GoGreen: GoGreen ist ein Service von DHL, bei dem die durch den Transport entstehenden Treibhausgase durch Klimaschutzprojekte ausgeglichen werden (Attraktiver Preis: 0,02 € zzgl. MwSt. zusätzlich zum Paketpreis). Wird der Haken gesetzt, so wird im Frontend angezeigt, dass für den Versand mit DHL GoGreen verwendet wird. Bitte aktivieren Sie dieses Feld nur, wenn auch in den Einstellungen bei DHL für den Versand GoGreen aktiviert ist.

4.2 Retoure

Hier können Sie einstellen, ob zusätzlich zum Versandlabel auch immer ein Beilegerretourelabel erzeugt werden soll. Außerdem können Sie die Adresse für den Rückversand eintragen.

  • Beilegerretoure: Aktivieren Sie die Checkbox, wenn bei der Versandlabelgenerierung auch ein Beilegerretourelabel erzeugt werden soll
  • Retoure-Empfängerdaten: Hier können Sie entweder einstellen, dass die gleiche Adresse wie beim Versender für das Versandlabel genutzt werden kann oder aber eine alternative Adresse angeben.

4.3 Standortsuche

  • Maximale Trefferanzahl: Hier können Sie die maximale Anzahl an Treffern eines Suchergebnisses auswählen.
  • API-Schlüssel: Dieses Modul nutzt Google Maps um die Suchergebnisse darzustellen. Daher ist es erforderlich, einen API-Schlüssel für Google Maps zu erzeugen und diesen unter dem Punkt "Standortsuche" einzutragen. Weitere Informationen zur Erzeugung eines solchen Schlüssels finden Sie unter dem folgenden Link: https://developers.google.com/maps/documentation/javascript/get-api-key?hl=de#key
  • Sofern Sie Ihren Kunden den Direktversand an Postfilialen oder Paketshops anbieten möchten, beachten Sie bitte folgenden Passus der Leistungsbeschreibung von DHL Paket (Anlage zum Geschäftskundenvertrag): „Der Absender stellt sicher, dass er berechtigt ist, der DHL die E-Mail-Adressen seiner Kunden zum Zwecke der Paketankündigung zu übergeben.

4.4 Wunschpaket

Hier können Angaben zu Uhrzeiten und Aufpreisen gemacht werden.

Berechnung angezeigter Wunschtage im Frontend

Der Wunschtagliegt zum Zeitpunkt der physischen Übergabe der Sendung an DHL mindestens zwei und maximal 6 Werktage in der Zukunft und darf kein Sonn- oder Feiertag sein.

Cut-off time
Die Cut-off time bestimmt den Zeitpunkt, zu dem eine Sendung noch am selben Tag physisch bei DHL eingeliefert resp. von DHL abgeholt werden kann. Wurde die Cut-off time zum Zeitpunkt der Bestellung im Shop überschritten, wird dieser Tag bei der Berechnung des ersten möglichen Wunschtages nicht berücksichtigt. Der frühstmögliche angezeigte Wunschtag im Frontend ist somit vor der Cut-off time der Bestelltag + zwei Werktage, nach der Cut-off time der Bestelltag + drei Werktage.

Bearbeitungszeit
Wurde im Backend eine Bearbeitungszeit (preparation time for deliveries) zwischen einem und drei Werktagen eingestellt, verschiebt sich der Tag der physischen Übergabe an DHL um die Anzahl der hier konfigurierten Werktage. Von diesem Übergabetag ausgehend liegen die im Frontend angezeigten Werktage mindestens zwei und maximal 6 Werktage in der Zukunft. Die Voreinstellung der Bearbeitungszeit ist 0.

Ausgeschlossene Tage zur physischen Übergabe an DHL
Im Backend besteht die Möglichkeit, standardmäßig bestimmte Wochentage für die physische Übergabe des Pakets an DHL auszuschließen, falls beispielsweise samstags nie eine Abholung oder Einlieferung stattfindet. An den optional auszuwählenden Werktagen findet also (zusätzlich zu Sonn- und Feiertagen) keine Übergabe von Paketen an DHL statt. Diese Angabe wird in die Berechnung der angezeigten Wunschtage im Frontend einbezogen.

Lieferzeit
Die zu den Artikeln in Shopware hinterlegte Lieferzeit findet keinen Eingang in die Berechnung des frühestmöglichen Wunschtages. Besonders hohe Lieferzeiten können jedoch bewirken, dass die Wunschtag-Option nicht angeboten werden kann.

Werktage
Als Werktage gelten die Tage von Montag bis Samstag, Sonntage und bundesweite Feiertage werden bei der Bearbeitungszeit und der Berechnung möglicher Wunschtage übersprungen.

Frontend
Die Darstellung im Frontend beginnt mit dem ersten möglichen Wunschtag und umfasst die darauffolgenden vier Tage; Sonn- und Feiertage werden hier nicht angezeigt.

4.5  Verfahrens- und Teilnahmenummern

Verfahren: dieses bezeichnet DHL Produkte, die für den Versand genutzt werden. Nähere Informationen zum Thema DHL Produkte finden Sie hier.

Teilnahme-Nummer: diese ermöglicht die Untergliederung von Abrechnungen nach Standorten, Saisongeschäft oder unterschiedlichen Konditionen. Auch der umweltfreundliche Versand mit GoGreen wird als separate Teilnahme hinterlegt. Die Teilnahme ist 2-stellig numerisch von 00 bis 99 oder alphanumerisch von AA bis ZZ. Sie wird vom DHL Vertrieb vergeben. Zu jedem DHL Produkt (Verfahren) kann ein Händler ein oder mehrere Teilnahmen verwenden. Es empfiehlt sich daher, dass die Anzahl der Teilnahmen bei der Konfiguration der Schnittstelle variabel zu halten.

4.6 Separate Deaktivierbarkeit

Alle Services lassen sich einzeln aktivieren resp. deaktivieren. So können Sie sicherstellen, dass bspw. sensible Bestellungen bei der Zustellung in die richtigen Hände gelangen oder große Warensendungen nicht an Packstationen versendet werden.

4.7 Logging

Jeder auftretende Fehler wird in Logdateien protokolliert (Loglevel: ERROR). Falls sie zusätzliche Informationen benötigen, können Sie das Loglevel INFO wählen. Für die Fehlerbehebung empfiehlt sich das Loglevel DEBUG anzuheben. Diese Logdateien können Sie selbstverständlich herunterladen indem Sie auf den Namen der Logdatei klicken.

4.8 Tracking

Bitte beachten Sie, dass das Plugin zu Reportingzwecken ein Tracking-Pixel enthält.
Das Pixel trackt die Shop-URL und zählt die gebuchten Wunschpaketservices.
Hiermit werden keine personenbezogenen und personenbeziehbare Daten erhoben oder verarbeitet.
Um den jeweiligen Tracking-Mechanismus zu deaktivieren, muss der Inhalt der Datei  "views/blocks/base_js.tpl" bzw. "views/blocks/head_meta_robots.tpl" durch [{$smarty.block.parent}] ersetzt werden.

4.9 E-Mails mit Informationen zu ausgewählten Wunschpaket-Features

Standardmäßig werden die Informationen zu Wunschtag, Wunschzeit, Wunschort und Wunschnachbar in versendeten E-Mails nicht dargestellt. Sie können allerdings über die Variable moEmpfaengerservicesPreferredTime, moEmpfaengerservicesPreferredLocation, moEmpfaengerservicesPreferredNeighbour bzw. moEmpfaengerservicesPreferredDay in das entsprechende E-Mail-Template integriert werden.

4.10. Ausschluss von Zahlungs- und Versandarten sowie Versandkostenregeln

Das Modul gibt Ihnen die Möglichkeit bestimmte Zahlungs- und Versandarten sowie Versandkostenregeln vom DHL Versand auszuschließen. Dies können Sie im neuen DHL Reiter des jeweiligen Objektes tun.

Dadurch können Sie verhindern, dass bestimmte Zahlsarten für Bestellungen über DHL verwendet werden oder aber Versandarten als nicht DHL-Versand markieren.

Da ein an eine Packstation oder Filiale adressiertes Paket nur von DHL zugestellt werden kann, kann man Versandarten ausschließen, falls die Lieferadresse eine Packstation oder Filiale ist. Dazu hakt man das jeweilige Kontrollkästchen ab. Analogerweise kann man auch Zahlarten ausschließen. Wir empfehlen, bei Verwendung des Wunschpaket Plugins die Zahlarten "Nachnahme" und "Vorauskasse" zu deaktivieren, da "Nachnahme" mit Wunschort und Packstation nicht kompatibel und "Vorauskasse" nicht mit dem Wunschtag kompatibel ist.

Hinweis: Versandkostenregeln können Produkte und Kategorien zugeordnet werden.
Ohne eine manuelle Zuordnung von Produkten oder Kategorien, werden implizit alle Produkte und Kategorien einer Versandkostenregel zugeordnet.
Um den Ausschluss von Versandarten für das DHL Modul sicherzustellen, sollte jeder Versandkostenregel, welche ausschließlich zum Versand via DHL gehört, mindestens ein Produkt oder eine Kategorie zugeordnet sein.

Darüber hinaus haben Sie bei Versandarten die Möglichkeit das zugehörige DHL-Produkt (z.B. DHL Paket) auszuwählen und die dazugehörige Teilnahmenummer.

Die Teilnahmenummern der verschiedenen DHL Produkte entsprechen jeweils den letzten zwei Stellen der zugehörigen Abrechnungsnummern. Sie finden Ihre Abrechnungsnummern im DHL Geschäftskundenportal unter dem Menüpunkt Vertragsdaten im Tab Vertragspositionen.

5. Versandlabelerzeugung

Es stehen Ihnen verschiedene Optionen zur Verfügung, um Versandlabel zu erzeugen.

5.1 Einzelnen Label erzeugen

Wenn Sie das Versandlabel einer einzelnen Bestellung erstellen möchten, können Sie dies direkt im DHL-Reiter der Bestellung tun. Dort werden Ihnen auch bereits erstellte Labels angezeigt.

5.2 Indivuduelles Versandlabel erstellen

Im gleichen Tab haben Sie auch die Möglichkeit ein induviduelles Versandlabel erstellen. Dabei können Sie die Eingabewerte wie beispielsweise die Adresse oder das Paketgewicht vor dem Absenden bearbeiten.

5.3 Versandlabel in der DHL Spapelverabeitung

Sollten Sie mehrere Versandlabel gleichzeitig erstellen lassen wollen, so können Sie diese unter DHL Stapelverarbeitung auswählen und dann für alle gewählten Bestellungen Label erstellen lassen.

5.4 Automatische Versandlabelerstellung

Es gibt auch die Möglichkeit, Versandlabel automatisch erstellen zu lassen. Dies passiert über einen Kommandozeilenbefehl, den Sie auf Ihrem Server ausführen lassen müssen. Wir empfehlen, diesen Befehl über einen Cronjob regelmäßig ausführen zu lassen.

Bei dem Befehl stehen Ihnen zusätzliche Parameter zur Verfügung, um nur bezahlte Bestellung zu berücksichtigen oder nur Bestellungen mit bestimmten Status.

6. CSV-Export

In der DHL Stapelverarbeitung gibt es die Option eines CSV-Export, in dem die ausgewählten Bestellungen als CSV-Datei exportiert werden, die dann im Geschäftskundenportal importiert werden kann.
Die Sendungsdaten in der CSV-Datei enthalten, wenn möglich, eine Abrechnungsnummer.
Diese Abrechnungsnummer setzt sich aus der EKP, einer Verfahrens- und einer Teilnahmenummer zusammen.
Die EKP wird global gesetzt; Verfahrens- und Teilnahmenummern werden mit Versandarten verknüpft.
Dies wird über "Erweiterungen > Module > DHL Wunschpaket (zu Hause + Standorte) > Einstell." konfiguriert.
Wenn eine Bestellung abgeschlossen wird, wird die konfigurierte EKP sowie die mit der gewählten Versandart verknüpfte Verfahrens- bzw. Teilnahmenummer in die Bestellung übernommen.
Diese Informationen können nachträglich über "Bestellungen verwalten > Bestellungen > DHL" geändert werden.
Wenn einer Bestellung die Information über EKP, Verfahrens- oder Teilnahmenummer fehlen, wird diese ergänzt, sofern eine EKP konfiguriert bzw. eine Verfahrens- oder Teilnahmenummer mit der Versandart verknüpft ist.

 

7. Datenschutz-Grundverordnung (EU-DSGVO)

 

Im Rahmnen der Erfassung der Lieferadresse speichert das Modul personenbezogene Daten zum Wunschnachbarn oder Wunschort in einem Kommentarfeld an der jeweiligen Bestellung.
Im Frontend wird vom Eingabefeld Wunschnachbar zum Standard-Datenschutztext verlinkt, ggf. ist dort eine Ergänzung erforderlich.