VibeFox DHL Africa for PrestaShop — Hilfe
Anforderungen
PrestaShop: 8.0 bis 9.x.
PHP: 8.0 oder neuer mit der cURL-Erweiterung. Das Modul lässt sich auf älteren PHP-Versionen oder ohne cURL nicht installieren. DHL XML Services benötigen außerdem die PHP-Erweiterung SimpleXML.
DHL-Express-Konto (nur für Live-Tarife): Live-Tarife verwenden die MyDHL API. Sie benötigen Ihre DHL-Express-Kontonummer und MyDHL-API-Zugangsdaten: einen API-Schlüssel und ein API-Secret. Beantragen Sie diese im DHL Developer Portal (MyDHL API, "Get access") oder bei Ihrem DHL-Express-Kundenbetreuer. Konten, die noch DHL-XML-Services-Zugangsdaten (Site ID und Passwort) haben, können diese stattdessen verwenden. Wenn Sie nur Ersatzpreise nutzen, brauchen Sie keine DHL-Zugangsdaten.
VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.
Installation
1. Gehen Sie im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls aus.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox DHL Africa in der Modulliste und klicken Sie auf Configure.
3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Wählen Sie die DHL API, geben Sie API-Schlüssel, API-Secret und Ihre DHL-Kontonummer ein. Lassen Sie Test mode eingeschaltet, solange Sie Testzugangsdaten verwenden. Geben Sie die Adresse Ship from ein. Wird Ihr DHL-Konto nicht in der Standardwährung Ihres Shops abgerechnet, legen Sie DHL quote currency und Exchange rate fest. Optional legen Sie Länderpreise und einen Ersatzbetrag fest (siehe Konfiguration). Klicken Sie auf Save.
Bei der Installation legt das Modul den Versanddienst DHL Express mit dem Lieferzeittext DHL Express courier an. Der Versanddienst wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Lieferzeit, Logo und Größenlimits können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis kommt immer vom Modul.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox DHL Africa > Configure. Sie gelten für alle Zonen des Versanddienstes. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern leert außerdem die zwischengespeicherten DHL-Tarife. Preise und Gewichte akzeptieren ein Dezimalkomma oder einen Dezimalpunkt.
Warnungen oben auf der Seite zeigen an, wenn Live-Tarife deaktiviert sind, weil API-Schlüssel, API-Secret oder Kontonummer fehlen (bzw. bei XML Services Site ID oder Passwort), wenn Herkunftsland oder -stadt fehlt, wenn XML Services ausgewählt sind (DHL stellt sie ein), wenn eine Angebotswährung ohne Wechselkurs gesetzt ist und wenn die Gewichts- oder Maßeinheit des Shops unter International > Localization (Local units) dem Modul unbekannt ist (dann wird kg bzw. cm angenommen). Ist ein Wert beim Speichern ungültig (ein leerer Name oder einer mit mehr als 64 Zeichen, eine ungültige oder negative Zahl, ein Wechselkurs von 0, ein Mindestgewicht über dem Höchstgewicht, die Angebotswährung, das Herkunftsland oder die Steuerregel), nennt ein Fehler das Feld, der bisherige Wert dieses Feldes bleibt erhalten, und die übrigen Einstellungen werden gespeichert.
Allgemein
Enable DHL Express Africa: schaltet den Versanddienst ein oder aus. Dies ist derselbe Schalter wie der Status des Versanddienstes unter Shipping > Carriers.
Name: der Name des Versanddienstes, den der Kunde an der Kasse sieht. Standard: DHL Express. Pflichtfeld, bis zu 64 Zeichen.
Tax: die Steuerregel des Versanddienstes oder No tax. Mit einer Steuerregel (und aktivierter Steuerberechnung im Shop) wird der DHL-Tarif ohne die von DHL angegebene Steuer übernommen, und PrestaShop fügt seine eigene Steuer hinzu. Bei No tax wird der DHL-Tarif wie angeboten berechnet, einschließlich Steuer.
DHL-Express-Konto (nur für Live-Tarife erforderlich)
DHL API: die verwendete DHL-Schnittstelle. Es werden nur die Felder der gewählten API angezeigt.
API key: Ihr MyDHL-API-Benutzername (API-Schlüssel).
API secret: Ihr MyDHL-API-Passwort (API-Secret). Nach dem Speichern bleiben die Felder API key und API secret leer und zeigen Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Remove the saved API key and API secret: wird nur angezeigt, wenn ein Schlüssel oder ein Secret gespeichert ist. Aktivieren Sie es und klicken Sie auf Save, um beide zu löschen.
XML Site ID: Ihre DHL-XML-Services-Site-ID (nur für die Legacy-API). Wenn Sie sie leeren, wird auch das gespeicherte XML-Passwort entfernt.
XML password: Ihr DHL-XML-Services-Passwort (nur für die Legacy-API). Wie das API-Secret wird es nach dem Speichern nicht mehr angezeigt.
DHL account number: Ihre DHL-Express-Kontonummer (9 Stellen). Die MyDHL API benötigt sie. Mit XML Services liefert sie Ihre Kontotarife statt der veröffentlichten Tarife.
Test mode: nutzt die DHL-Testumgebung. Standardmäßig eingeschaltet. Testzugangsdaten funktionieren nur in der Testumgebung, Produktivzugangsdaten nur in der Produktivumgebung. Schalten Sie es aus, wenn Sie live gehen.
Ship from
Die Adresse, an der DHL die Pakete abholt. Der Tarif hängt davon ab.
Origin country: das Land, aus dem Sie versenden.
Origin city: die Stadt, aus der Sie versenden, zum Beispiel Johannesburg. Die MyDHL API benötigt sie.
Origin postcode: leer lassen für Länder ohne Postleitzahlen (zum Beispiel Kenia, Nigeria, Ghana).
Rates
Alle Preise sind in der Standardwährung Ihres Shops angegeben, ohne Steuern. Der Live-Tarif ist das günstigste DHL-Express-Produkt für das Paket. Ist DHL nicht konfiguriert, schlägt die Anfrage fehl oder gibt es keinen Service für die Route, wird der Länderpreis verwendet, danach der Ersatzbetrag. Ohne beides wird der Versanddienst ausgeblendet.
DHL quote currency: DHL bietet in der Währung des Landes Ihres DHL-Kontos an (zum Beispiel ZAR, NGN oder KES). Gibt DHL keinen Betrag in der Standardwährung Ihres Shops zurück, wird der Live-Tarif aus dieser Währung mit dem unten stehenden Wechselkurs umgerechnet. Andernfalls wird er nicht verwendet. Standard: — None —.
Exchange rate: wie viel 1 Einheit der DHL-Angebotswährung in der Standardwährung Ihres Shops entspricht, zum Beispiel 1 ZAR = 0.05. Er muss größer als 0 sein. Leer lassen, wenn nicht umgerechnet werden soll. Der Wechselkurs ist eine manuelle Einstellung.
Fallback cost: ein Pauschalbetrag, wenn es weder einen Live-Tarif noch einen Länderpreis gibt. Leer lassen, um den Versanddienst in diesem Fall auszublenden.
Country prices: ein Ersatzpreis pro Zielland, eine Zeile pro Land: CC:Price, zum Beispiel ZA:25.00. Wird verwendet, wenn kein Live-Tarif vorliegt. Zeilen in einem anderen Format werden ignoriert; eine Warnung beim Speichern listet sie auf.
Fallback price basis: Per order berechnet den Preis einmal. Per item (multiplied by the cart quantity) multipliziert ihn mit der Anzahl der Artikel. Gilt nur für den Länderpreis und den Ersatzbetrag. Der Live-DHL-Tarif gilt immer für das gesamte Paket.
Free shipping from: die Warenkorb-Zwischensumme (versandpflichtige Produkte, nach Rabatten, vor Steuern), ab der dieser Versanddienst kostenlos ist. DHL wird nicht abgefragt. Leer lassen, wenn er nie kostenlos sein soll.
Bedingungen
Minimum weight: blendet den Versanddienst unterhalb dieses Warenkorbgewichts aus, in kg. 0 bedeutet kein Limit. Er darf nicht größer sein als Maximum weight.
Maximum weight: blendet den Versanddienst oberhalb dieses Warenkorbgewichts aus, in kg. Standard: 70 (wird auch verwendet, wenn das Feld leer ist). 0 bedeutet kein Limit.
Minimum subtotal: zeigt den Versanddienst nur, wenn die Warenkorb-Zwischensumme (nach Rabatten, vor Steuern) mindestens diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.
Verfügbarkeit ohne Versandzonen
Ignore shipping zones: bietet den Versanddienst an, ohne ihm selbst Zonen zuzuweisen. Der Versanddienst erhält jede Zone, auch später angelegte, und die unten stehenden Länder entscheiden. Ausschalten gibt dem Versanddienst wieder seine eigenen Zonen.
Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zuzulassen, in die Sie versenden. Wird nur mit Ignore shipping zones verwendet.
Erweitert
Debug log: schreibt die Tarifberechnungen in logs/vfd_dhla_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. DHL-Fehler werden immer protokolliert, auch wenn dies ausgeschaltet ist. Zugangsdaten und Kundenadressen werden nie protokolliert.
Log: zeigt die Größe und die neuesten Einträge des Debug-Logs. Klicken Sie auf Clear log, um es zu leeren.
Remove data on uninstall: ist es eingeschaltet, löscht die Deinstallation des Moduls die Einstellungen, den Versanddienst, die gespeicherten DHL-Produkte der Bestellungen und das Log. Ist es ausgeschaltet, bleibt alles für eine erneute Installation erhalten.
So funktioniert es an der Kasse
Im Versandschritt fragt PrestaShop das Modul nach dem DHL-Express-Preis. Nur physische Produkte zählen: Virtuelle Produkte erhöhen weder das Gewicht noch sind sie in der Zwischensumme enthalten. Das Modul prüft zuerst die Bedingungen: die Länder von Ignore shipping zones, das Warenkorbgewicht und die Mindestzwischensumme. Gilt kostenloser Versand, beträgt der Preis 0, und es wird keine Anfrage an DHL gesendet.
Andernfalls sendet das Modul an DHL Herkunft und Ziel (Land, Stadt, Postleitzahl), das in kg umgerechnete Warenkorbgewicht (mindestens 0,5 kg) und eine Box, die aus den Produktabmessungen in cm gebildet wird: die längste Länge, die breiteste Breite und die gestapelten Höhen. Produkte ohne Abmessungen fügen nichts hinzu. Hat kein Produkt Abmessungen, wird eine Box von 10 x 10 x 10 cm verwendet. Sendungen in ein anderes Land werden zollrechtlich angemeldet, mit der Warenkorb-Zwischensumme als Warenwert. Inlandssendungen werden nicht angemeldet. Das Abholdatum ist heute, an Wochenenden der Montag. Ein Live-Tarif wird erst angefragt, nachdem der Kunde eine Stadt eingegeben hat (bei XML Services eine Stadt oder eine Postleitzahl). Davor gelten die Ersatzpreise.
Das günstigste DHL-Express-Produkt wird als ein Preis mit Ihrem Versanddienstnamen angezeigt. Der Kunde sieht das DHL-Produkt nicht. Der Preis wird in Ihrer Standardwährung berechnet, gerundet und danach in der Warenkorbwährung des Kunden angezeigt.
Jedes Angebot wird 1 Stunde pro Paket und Route zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf DHL warten muss. Das API-Timeout beträgt 12 Sekunden. Gibt DHL einen Fehler zurück, hat keinen Service oder antwortet in einer unbrauchbaren Währung, sieht der Kunde keinen Fehler: Es wird der Ersatzpreis verwendet, oder der Versanddienst wird ausgeblendet. Der Grund wird im Debug-Log protokolliert.
Wenn Sie den Versanddienst unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstes. Das Modul folgt der neuen Version automatisch.
Das Modul berechnet nur Tarife. Es erstellt keine DHL-Sendungen, druckt keine Etiketten oder Handelsrechnungen, bucht keine Abholungen, verfolgt keine Pakete, bietet keine DHL-Servicepunkte an, lässt den Kunden nicht zwischen DHL-Produkten wählen, packt keine mehreren Boxen, fügt keine Versicherung hinzu und berechnet keine Zölle und Steuern. Das Angebot gilt nur für den Versand. Zölle und Importsteuern trägt der Empfänger.
Bestellungen
Beim Abschluss der Bestellung speichert das Modul den für den Warenkorb berechneten Tarif. Die Bestellseite im Back Office zeigt dann einen Block DHL Express Africa, damit Sie wissen, was Sie bei DHL buchen müssen:
DHL product: das DHL-Express-Produkt des Live-Tarifs, zum Beispiel "EXPRESS WORLDWIDE (P)". Wird nur bei Live-Tarifen angezeigt.
Price source: Live DHL rate, Fallback price (no live rate) oder Free shipping threshold.
Calculated price (excl. tax): der Preis in der Standardwährung Ihres Shops.
Spätere Neuberechnungen des Warenkorbs, zum Beispiel wenn die Bestellung im Back Office bearbeitet wird, ändern diese Werte nicht. Tarife von Warenkörben, die nie zu einer Bestellung wurden, werden nach 30 Tagen entfernt.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox DHL Africa ist der erste Block auf Modules > Module Manager > VibeFox DHL Africa > Configure, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-shipping-dhl-africa und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).
Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul mit dem zuletzt bekannten Status weiter.
Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch bei einem Multistore-Setup. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.
Ohne einen aktiven Schlüssel wird der Versanddienst DHL Express an der Kasse nicht angezeigt und es wird kein Tarif berechnet. Das Frontend des Shops weiß nicht, dass Sie im Back Office angemeldet sind, daher wird der Versanddienst auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind davon nicht betroffen.
Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back Office arbeiten: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
DHL Express erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable DHL Express Africa eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienst die Zone des Landes und die Kundengruppe des Kunden abdeckt (oder schalten Sie Ignore shipping zones ein und prüfen Sie Countries). Prüfen Sie die Gewichtsgrenzen und Minimum subtotal. Ohne Live-Tarif erscheint der Versanddienst nur, wenn ein Länderpreis oder ein Ersatzbetrag gesetzt ist. Produkte können auf der Produktseite auch auf bestimmte Versanddienste beschränkt sein.
Live-Tarife erscheinen nicht: Prüfen Sie die Warnungen oben auf der Modulseite (fehlende Zugangsdaten oder Herkunft). Schalten Sie das Debug log ein, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Modulseite an. DHL-Fehler wie ein HTTP-Fehler der MyDHL API, keine Produkte für die Route oder ein Währungsproblem werden immer protokolliert. Prüfen Sie, ob Test mode zu Ihren Zugangsdaten passt und ob die Kundenadresse eine Stadt enthält.
DHL liefert den Tarif in ZAR, NGN oder KES, aber mein Shop verwendet eine andere Währung: Das Log meldet DHL quote not usable. Setzen Sie DHL quote currency auf diese Währung und geben Sie den Exchange rate ein. Ohne ihn wird der Live-Tarif nicht verwendet, und es gelten die Ersatzpreise.
Ich habe alte DHL-XML-Services-Zugangsdaten: Wählen Sie unter DHL API XML Services (legacy). Wechseln Sie zur MyDHL API, sobald Sie MyDHL-Zugangsdaten erhalten.
Steuer wird auf den Versand doppelt berechnet: Legen Sie unter Tax eine Steuerregel fest, damit der DHL-Tarif ohne die DHL-Mehrwertsteuer übernommen wird, oder wählen Sie No tax, um den DHL-Betrag wie angeboten zu berechnen.
Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten DHL-Angebote geleert.
Die Seite meldet, dass der Versanddienst DHL Express nicht gefunden wurde: Der Versanddienst wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn neu anzulegen.
Für Entwickler stellt das Modul die Hooks actionVfdDhlaApiUrl, actionVfdDhlaIsDutiable, actionVfdDhlaPackageBox, actionVfdDhlaRestRequest und actionVfdDhlaXmlRequest bereit, um die API-Adresse, die Zollanmeldung, die Box und die DHL-Anfragen zu ändern.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox DHL Africa und wählen Sie Uninstall. Der Lizenzschlüssel, der Lizenzstatus und die zwischengespeicherten DHL-Angebote werden immer entfernt. Ist Remove data on uninstall eingeschaltet, wird der Versanddienst gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, die gespeicherten DHL-Produkte der Bestellungen und das Log werden entfernt. Ist es ausgeschaltet, wird der Versanddienst nur deaktiviert, und die Einstellungen sowie die DHL-Produkte aufgegebener Bestellungen bleiben erhalten. Eine erneute Installation stellt den vorherigen Status des Versanddienstes wieder her.
DHL ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit DHL verbunden noch wird es von DHL unterstützt.