Installation für Agenturen

Bemerkung

Diese Seite richtet sich an Agenturen und technische Shop-Administratoren. DHL-Zugänge, Moduleinstellungen und der tägliche Arbeitsablauf stehen unter Bedienung für Shop-Betreiber.

Verwenden Sie ausschließlich das Paket, das zur eingesetzten OXID-Hauptversion passt.

Paketauswahl

Shop

Modultechnik

Zielverzeichnis

Installationsart

OXID 6 ab 6.1

Smarty-Paket

source/modules/ecs/DhlPaket

Moduldateien kopieren, Namespace registrieren und Modulkonfiguration installieren

OXID 7 ab 7.1

Twig-Paket

vendor/ecs/dhlpaket

Moduldateien kopieren, Namespace registrieren und Modul über oe-console installieren

Warnung

Die Pakete für OXID 6 und OXID 7 sind nicht austauschbar. Verwenden Sie das beim Kauf für Ihre OXID-Hauptversion bereitgestellte Paket: Smarty für OXID 6 beziehungsweise Twig für OXID 7.

Vorbereitung

Vor der Installation benötigen Sie:

  • ein vollständiges Backup von Shopdateien und Datenbank,

  • ein Test- oder Staging-System,

  • Composer- und Konsolenzugriff im Hauptverzeichnis des Shops,

  • Schreibrecht für das Shopprojekt und für ein neues Verzeichnis direkt oberhalb von source,

  • die PHP-Erweiterung cURL und ausgehenden HTTPS-Zugriff auf die DHL-API,

  • vollständige Absenderdaten in den OXID-Shop-Stammdaten sowie

  • für den späteren Funktionstest einen DHL-API-Key und die Zugangsdaten eines DHL-Systembenutzers.

Das OXID-7-Paket erlaubt laut composer.json PHP 8.0 bis 8.4. Zusätzlich müssen die Anforderungen der eingesetzten OXID-Version und des jeweiligen Modulpakets erfüllt sein.

Tipp

Legen Sie für die DHL-API einen eigenen Systembenutzer an. Verwenden Sie keinen persönlichen Zugang einer einzelnen Mitarbeiterin oder eines einzelnen Mitarbeiters.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das Twig-Paket vollständig nach:

vendor/ecs/dhlpaket

Im Zielverzeichnis müssen mindestens metadata.php, composer.json, services.yaml sowie die Ordner src, views und assets vorhanden sein. Achten Sie auf die exakte Groß- und Kleinschreibung.

2. Namespace registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\DhlPaket\\": "vendor/ecs/dhlpaket/src/"

Vorhandene Namespaces bleiben erhalten. Ein vollständiger Ausschnitt kann so aussehen:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "vendor/vorhandener/anbieter/modul/src/",
            "Ecs\\DhlPaket\\": "vendor/ecs/dhlpaket/src/"
        }
    }
}

Der Eintrag gehört nicht in vendor/ecs/dhlpaket/composer.json. Bei dieser manuellen Installation ist kein zusätzlicher Eintrag unter require nötig.

3. Autoloader und Modul installieren

Führen Sie im Hauptverzeichnis des OXID-Shops aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/dhlpaket
vendor/bin/oe-console oe:module:activate ecs_dhlpaket
vendor/bin/oe-console oe:cache:clear

Alternativ kann das Modul nach oe:module:install im Shop-Admin unter Erweiterungen ‣ Module aktiviert werden.

4. OXID-7-Installation kontrollieren

Prüfen Sie:

  • eComStyle.de: DHL-Paket ist sichtbar und aktiv.

  • Die Moduleinstellungen werden vollständig angezeigt.

  • Bestellungen verwalten ‣ DHL-Paket lässt sich ohne Template- oder JavaScriptfehler öffnen.

  • CSS und JavaScript des Moduls werden geladen.

  • Das Verzeichnis ecs_dhlpaket_labels/shop_<SHOPID> wurde direkt oberhalb von source angelegt und ist für den PHP-Prozess beschreibbar.

  • DHL Verbindung testen liefert in der gewählten Umgebung eine Antwort.

OXID 7 aktualisieren

Deaktivieren Sie das Modul für den Dateiaustausch, ersetzen Sie den kompletten Ordner vendor/ecs/dhlpaket durch das aktuelle OXID-7-Paket und führen Sie anschließend aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/dhlpaket
vendor/bin/oe-console oe:module:activate ecs_dhlpaket
vendor/bin/oe-console oe:cache:clear

OXID 6 installieren

Das OXID-6-Paket verwendet Smarty und liegt im klassischen Modulverzeichnis.

1. Moduldateien kopieren

Kopieren Sie das Verzeichnis DhlPaket aus dem Smarty-Paket vollständig nach:

source/modules/ecs/DhlPaket

Übernehmen Sie die Groß- und Kleinschreibung aus dem Paket exakt. Prüfen Sie vor dem Fortfahren, dass dessen metadata.php, composer.json, PHP- Klassen, Smarty-Views und Assets vollständig vorhanden sind.

2. Namespace registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\DhlPaket\\": "./source/modules/ecs/DhlPaket/"

Mit einem bereits vorhandenen Namespace:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "./source/modules/vorhandenes/modul/",
            "Ecs\\DhlPaket\\": "./source/modules/ecs/DhlPaket/"
        }
    }
}

Der Eintrag gehört in die Projekt-composer.json. Ein zusätzlicher require-Eintrag ist nicht nötig.

3. Autoloader und Modulkonfiguration installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/DhlPaket
vendor/bin/oe-console oe:module:activate ecs_dhlpaket

Leeren Sie anschließend die temporären Shopdateien beziehungsweise den OXID-Cache mit dem in dieser OXID-6-Umgebung vorgesehenen Verfahren.

4. OXID-6-Installation kontrollieren

Prüfen Sie:

  • Modul, Einstellungen und Admin-Menüpunkt sind sichtbar.

  • Smarty-Admin und Storefront öffnen ohne Templatefehler.

  • Modul-Assets sind erreichbar.

  • Das shopbezogene Labelverzeichnis oberhalb von source ist vorhanden und beschreibbar.

  • Verbindungstest und Testlabel funktionieren.

OXID 6 aktualisieren

Deaktivieren Sie das Modul für den Dateiaustausch, ersetzen Sie den kompletten Ordner source/modules/ecs/DhlPaket durch das aktuelle OXID-6-Paket und führen Sie aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/DhlPaket
vendor/bin/oe-console oe:module:activate ecs_dhlpaket

Leeren Sie danach die temporären Shopdateien.

Aktivierung, Daten und Deaktivierung

Das Modul legt keine eigenen Datenbanktabellen oder -felder an. Bei der Aktivierung:

  • wird das Labelverzeichnis angelegt,

  • wird der OXID-Template-Cache geleert und

  • werden die Datenbankansichten aktualisiert.

Die Label-Metadaten werden als JSON und die von DHL gelieferten Dokumente als Base64-Dateien gespeichert:

<Shopprojekt>/ecs_dhlpaket_labels/shop_<SHOPID>/

Das Verzeichnis liegt außerhalb des öffentlichen source-Verzeichnisses und wird je Shop-ID getrennt. Trackingnummern stehen zusätzlich kommasepariert im OXID-Standardfeld oxorder.OXTRACKCODE; der Versandstatus verwendet oxorder.OXSENDDATE und der Bestellordner oxorder.OXFOLDER.

Bei Deaktivierung leert das Modul den Template-Cache und aktualisiert die Datenbankansichten. Labeldateien, Metadaten, Trackingnummern, Moduleinstellungen, Bestellordner und Versanddaten bleiben erhalten. Sichern Sie diese Daten vor jedem Update.

Warnung

Löschen Sie ecs_dhlpaket_labels nicht ungesichert. Die im Modul angebotenen Druckfunktionen benötigen diese lokalen Dateien. Eine endgültige Bereinigung muss mit Aufbewahrungs-, Nachweis- und Datenschutzvorgaben des Shop-Betreibers abgestimmt werden.

Technische Abnahme

Führen Sie mindestens folgende Tests in der Sandbox durch:

  1. Verbindung mit korrekten und testweise falschen Zugangsdaten prüfen.

  2. Deutsche Bestellung mit vollständiger Lieferadresse öffnen.

  3. Gewicht aus mehreren Positionen einschließlich Verpackungsgewicht prüfen.

  4. Je ein Label für DHL Paket und DHL Kleinpaket erstellen und öffnen.

  5. Eine Packstation-Adresse mit Packstations- und Postnummer testen.

  6. Eine internationale EU- und eine Nicht-EU-Bestellung prüfen; bei der Nicht-EU-Bestellung auch das Zollpapier kontrollieren.

  7. Trackinglink, manuelle Versandmail und automatischen Mailversand separat testen.

  8. Ein Testlabel stornieren und danach lokale Labelanzeige, Trackingcode und Versanddatum kontrollieren.

  9. Mehrere Labels für eine Bestellung sowie die gezielte Stornierung eines einzelnen Labels testen.

  10. Mandanten beziehungsweise Subshops getrennt kontrollieren, falls genutzt.

Der Verbindungstest allein genügt nicht als Abnahme. Er prüft Erreichbarkeit und Authentifizierung nur grob; erst ein erfolgreich erstelltes und bei DHL sichtbares Testlabel bestätigt den vollständigen Ablauf.

Fehlerbehebung für Agenturen

Technische Fehlerbilder

Problem

Prüfung

Modul oder Admin-Menü fehlt.

Paketpfad, PSR-4-Eintrag, composer dump-autoload, passenden Installationsbefehl, Aktivierung, Adminrechte und Cache prüfen.

Admin-Seite bleibt leer oder ungestaltet.

Bereitstellung von assets/js/ecs_dhlpaket.js und assets/css/ecs_dhlpaket.css, Browserkonsole sowie Netzwerkfehler prüfen.

DHL-API ist nicht erreichbar.

cURL, DNS, TLS-Zertifikate, Firewall und ausgehenden HTTPS-Zugriff auf api-sandbox.dhl.com beziehungsweise api-eu.dhl.com prüfen.

HTTP 401.

Umgebung, API-Key, Systembenutzer und Passwort müssen zum selben Sandbox- oder Produktivzugang gehören.

Label wird erstellt, später aber nicht gefunden.

Eigentümer und Schreibrechte von ecs_dhlpaket_labels/shop_<SHOPID> sowie freien Speicherplatz prüfen. Das Modul unterdrückt Dateisystemfehler bei der Aktivierung.

Versandmail schlägt fehl.

OXID-Mailkonfiguration, Empfängeradresse, Shop-Absender, Spam-Ordner und source/log/oxideshop.log prüfen.

Nicht-EU-Label wird abgelehnt.

Artikelgewicht, Bezeichnung, Wert, Währung, Versandkosten und Empfängerland prüfen. Der Modulcode übermittelt keine separate Zolltarifnummer oder ein Ursprungsland; erforderliche Ergänzungen mit DHL und dem Modulverantwortlichen klären.

Übergabe an den Shop-Betreiber

Übergeben Sie nach der Abnahme:

  • Link zur Bedienungsanleitung,

  • die ausgewählte DHL-Umgebung und den Verantwortlichen für Zugangsdaten,

  • freigegebene DHL-Produkte, Druckformat, Paketmaße und Verpackungsgewicht,

  • Regelung zur Kunden-E-Mail-Übermittlung und Versandmail,

  • Prozess für Stornierung und Kontrolle im DHL-Geschäftskundenportal,

  • Aufbewahrungs- und Löschregel für lokale Labeldateien sowie

  • Verantwortlichkeiten für Zollprüfung und Versandnachbearbeitung.