VibeFox PostNL for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x, Theme Classic oder Hummingbird (oder ein darauf basierendes Theme).

PHP: 8.0 oder neuer. Das Modul verweigert die Installation auf älteren PHP-Versionen.

PostNL-API-Schlüssel (nur für Abholpunkte): Abholpunkte werden über die PostNL Checkout API geladen. PostNL-Geschäftskunden finden den API-Schlüssel in Mijn PostNL unter My account > API beheren. Die PostNL-Sandbox benötigt einen eigenen Sandbox-Schlüssel. Der Versanddienstleister für die Lieferung nach Hause benötigt keinen Schlüssel.

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.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox PostNL 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. Tragen Sie die Preise ein. Für Abholpunkte geben Sie außerdem den PostNL-API key und den Ship from (postcode) ein (siehe Konfiguration). Klicken Sie auf Save.

Bei der Installation legt das Modul zwei Versanddienstleister an: PostNL pickup point mit dem Liefertext Delivery to a PostNL pickup point und PostNL mit PostNL delivery to the home address. Beide sind mit den Zonen der Niederlande und Belgiens sowie mit allen Kundengruppen verknüpft. Sie können unter Shipping > Carriers Zonen hinzufügen und Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen ändern. Legen Sie dort keine Preise fest: Der Preis kommt immer aus dem Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox PostNL > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. In WooCommerce wird eine Methode zweimal einer Zone hinzugefügt, einmal je Liefertyp. In PrestaShop ist jeder Liefertyp ein eigener Versanddienstleister mit eigenem Namen, Status und eigenen Zonen.

Oberhalb der Einstellungen zeigt die Seite Warnungen an: fehlender API-Schlüssel oder fehlende Versand-Postleitzahl für Abholpunkte, eingeschaltete Sandbox, kein Preis festgelegt, die letzte fehlgeschlagene PostNL-Anfrage mit Datum und Fehler, eine Gewichtseinheit des Shops, die das Modul nicht kennt, und ein gelöschter Versanddienstleister.

Allgemein

PostNL pickup point: schaltet den Versanddienstleister mit Abholpunkt ein oder aus. Der Kunde muss an der Kasse einen PostNL-Punkt wählen. Er wird nur für Adressen in den Niederlanden und Belgien angeboten und nur mit API-Schlüssel. Dies ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Pickup point carrier name: der Name, den Kunden an der Kasse sehen. Standard: PostNL pickup point. Pflichtfeld.

PostNL home address: schaltet den Versanddienstleister für die Lieferung nach Hause ein oder aus. Es wird kein Punkt gewählt. Er funktioniert für jedes Land mit Preis. Gleicher Schalter wie der Status des Versanddienstleisters.

Home delivery carrier name: der Name, den Kunden an der Kasse sehen. Standard: PostNL. Pflichtfeld.

Tax status: die Steuerregel beider Versanddienstleister. Eine Regel Taxable rechnet die Versandsteuer dieser Regel auf die Preise auf. None bedeutet, dass die Preise endgültig sind.

PostNL-API (Abholpunkte) (für die Lieferung nach Hause nicht nötig)

API key: Ihr PostNL-API-Schlüssel aus Mijn PostNL (My account > API beheren). Er wird im Header "apikey" an PostNL gesendet und nie Kunden angezeigt oder im Protokoll gespeichert. Nach dem Speichern bleibt das Feld leer und zeigt 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: aktivieren Sie das Kästchen und klicken Sie auf Save, um den gespeicherten Schlüssel zu löschen. Der Versanddienstleister mit Abholpunkt wird danach nicht mehr angeboten.

Sandbox: verwendet die PostNL-Sandbox (api-sandbox.postnl.nl) mit einem Sandbox-API-Schlüssel. Kunden sehen dann Test-Abholpunkte. Im Live-Shop ausgeschaltet lassen.

Ship from (country): das Land, in dem Sie Ihre Pakete an PostNL übergeben, Netherlands oder Belgium. Standard: Netherlands. PostNL verwendet die Absenderadresse für das Abholdatum.

Ship from (postcode): die Absender-Postleitzahl, zum Beispiel 1234AB in den Niederlanden oder 1000 in Belgien. Leer lassen, um die Shop-Postleitzahl aus Shop Parameters > Contact > Stores zu verwenden, wenn der Shop im selben Land liegt. Eine ungültige Postleitzahl wird leer mit einer Warnung gespeichert. Wenn Sie den API-Schlüssel, die Sandbox-Einstellung oder die Versandadresse ändern, werden die zwischengespeicherten Abholpunktlisten und der letzte API-Fehler gelöscht.

Preise (in der Standardwährung des Shops, ohne Steuern)

Preise gelten für beide Versanddienstleister. PostNL bietet keine öffentliche Tarif-API, daher fragt das Modul keine Live-Tarife ab. Zahlt ein Kunde in einer anderen Währung, rechnet PrestaShop den Preis mit dem Wechselkurs Ihres Shops um.

Price per country: eine Zeile je Zielland. Klicken Sie auf + Add country, um eine Zeile hinzuzufügen, und auf das Papierkorbsymbol, um sie zu entfernen. Wählen Sie * All other countries für eine Zeile, die alle Länder ohne eigene Zeile abdeckt. Jede Zeile hat einen Price und optionale Gewichtsklassen nach Warenkorbgewicht: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg und XL über 5 kg. Ein Preis einer Gewichtsklasse ersetzt Price; lassen Sie ihn leer, um Price zu verwenden. Ein Price von 0 bedeutet kostenlosen Versand. "6.95", "6,95" sowie Beträge mit Tausendertrennzeichen wie "1.234,50" oder "1,234.50" werden akzeptiert. Leere Zeilen und ungültige Ländercodes werden beim Speichern entfernt. Erscheint ein Land zweimal, bleibt die erste Zeile erhalten. Ungültige Preise werden mit einer Warnung ignoriert.

Calculation: Per order berechnet den Preis einmal. Per item (price x quantity) multipliziert ihn mit der Anzahl der Artikel, die versendet werden müssen.

Price for other countries: wird verwendet, wenn die Tabelle weder das Land noch eine *-Zeile enthält. Leer lassen, um die Versanddienstleister dort auszublenden.

Bedingungen

Free shipping from: die Warenkorb-Zwischensumme (Produkte, die versendet werden müssen, ohne Steuern, nach Rabatten), ab der die Lieferung kostenlos ist. Gilt nur dort, wo ein Preis gefunden wird. Leer lassen, um nie kostenlosen Versand anzubieten.

Minimum subtotal: die Versanddienstleister werden nur angezeigt, wenn die Warenkorb-Zwischensumme mindestens diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.

Minimum weight (kg): blendet die Versanddienstleister aus, wenn der Warenkorb weniger wiegt. Produktgewichte werden aus Ihrer Gewichtseinheit im Shop umgerechnet. Leer lassen für keine Grenze.

Maximum weight (kg): blendet die Versanddienstleister bei schwereren Warenkörben aus. Standard: 30 (PostNL-Pakete gehen im Benelux bis 30 kg). 0 bedeutet keine Grenze. Lassen Sie das Feld leer, gelten in den Zonen der Versanddienstleister 30 kg, und keine Grenze gilt nur für die Länder, die über Ignore zones erreicht werden. Ein Mindestgewicht über dem Höchstgewicht wird mit einem Fehler abgelehnt, da die Versanddienstleister sonst nie angezeigt würden.

Alle Beträge und Gewichte akzeptieren ein Dezimalkomma, auch mit Tausendertrennzeichen. Eine ungültige oder negative Zahl wird mit einer Warnung ignoriert, und das Feld wird leer gespeichert.

Verfügbarkeit ohne Versandzonen

Normalerweise werden die Versanddienstleister in den Versandzonen angeboten, mit denen sie unter Shipping > Carriers verknüpft sind.

Ignore zones: bietet PostNL außerdem in den unten genannten Ländern an, in denen seine Zonen sie nicht enthalten. Die Versanddienstleister werden dann mit jeder aktiven Zone verknüpft, auch mit Zonen, die Sie später anlegen. Wenn Sie die Option wieder ausschalten, erhalten die Versanddienstleister die Zonen zurück, die sie vorher hatten.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zuzulassen. Dieses Feld wird nur verwendet, wenn Ignore zones eingeschaltet ist. In diesen Ländern können beide Versanddienstleister angeboten werden; der Versanddienstleister mit Abholpunkt jedoch nur in den Niederlanden und Belgien.

Erweitert

Debug log: schreibt Debug-Meldungen in logs/vfd_ptnl_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. API-Fehler werden immer protokolliert. Es werden keine API-Schlüssel oder Kundendaten geschrieben. Schalten Sie das Protokoll nach Abschluss wieder aus.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Remove data on uninstall: ist die Option eingeschaltet, löscht die Deinstallation des Moduls die PostNL-Einstellungen und Versanddienstleister. Ist sie ausgeschaltet, werden bei der Deinstallation nur die Versanddienstleister deaktiviert. Abholpunkte, die in Bestellungen gespeichert wurden, bleiben immer erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem Preis jedes PostNL-Versanddienstleisters. Nur physische Produkte zählen: Virtuelle Produkte haben kein Gewicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft die Bedingungen: Warenkorbgewicht und Mindest-Zwischensumme. Dann nimmt es den Preis aus der Tabelle für das Land und die Gewichtsklasse oder den Preis für andere Länder. Gibt es keinen Preis, wird der Versanddienstleister ausgeblendet. Erreicht die Warenkorb-Zwischensumme Free shipping from, beträgt der Preis 0.

Der Versanddienstleister mit Abholpunkt wird nur für Adressen in den Niederlanden und Belgien angeboten und nur mit API-Schlüssel. Hat die Lieferadresse eine gültige Postleitzahl, fragt das Modul die PostNL Checkout API nach den drei nächsten Abholpunkten. Es sendet die Postleitzahl, Straße, Hausnummer, Stadt und das Land des Kunden sowie Ihre Versandadresse. Für den Versanddienstleister für die Lieferung nach Hause wird nichts gesendet. Ist PostNL nicht erreichbar oder hat keine Punkte für die Adresse, wird der Versanddienstleister mit Abholpunkt ausgeblendet, und die Lieferung nach Hause bleibt verfügbar. Das Zeitlimit der API beträgt 12 Sekunden.

Punktlisten werden 6 Stunden je Postleitzahl zwischengespeichert, Antworten „keine Punkte“ 1 Stunde. Fehlgeschlagene Anfragen werden 10 Minuten zwischengespeichert, damit ein Ausfall nicht jede Aktualisierung der Kasse verlangsamt. Der letzte Fehler wird auf der Modulseite angezeigt.

Wenn Sie einen Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.

Das Modul fragt keine Live-Tarife von PostNL ab und erstellt keine Versandetiketten, Barcodes, track and trace, Retouren oder Voranmeldungen. Es bietet keine Optionen für Liefertage, Abend- oder Morgenlieferung. Erstellen Sie die Sendung in Mijn PostNL oder einem anderen PostNL-Tool mit dem gespeicherten Abholpunkt.

Abholpunkte

Wenn der Kunde den Versanddienstleister mit Abholpunkt wählt, erscheint darunter eine Liste PostNL pickup point mit den drei nächsten Punkten: Firmenname, Adresse und Entfernung. Die Seite wartet nie auf PostNL: Ist die Liste noch nicht zwischengespeichert, wird sie geladen, sobald der Versanddienstleister gewählt wird. Bevor eine vollständige Postleitzahl eingegeben wird, sieht der Kunde „Geben Sie Ihre Postleitzahl ein (zum Beispiel 1234 AB), um PostNL-Abholpunkte zu sehen.“ (4 Ziffern für Belgien). Der gewählte Punkt wird im Warenkorb gespeichert und bleibt erhalten, wenn die Kasse aktualisiert wird.

Der Punkt ist Pflicht. Ohne ihn kann der Kunde nicht fortfahren und sieht „Bitte wählen Sie einen PostNL-Abholpunkt.“ Klickt der Kunde auf Continue, prüft der Server den Punkt gegen die Liste von PostNL für die Lieferadresse. Steht er nicht auf der Liste, sieht der Kunde „Der gewählte PostNL-Abholpunkt ist für diese Adresse nicht verfügbar. Bitte wählen Sie ihn erneut.“ Kann PostNL nicht erreicht werden, sieht der Kunde „PostNL-Abholpunkte können derzeit nicht geladen werden. Bitte versuchen Sie es in einigen Minuten erneut oder wählen Sie eine andere Versandart.“ Ein Punkt, der für eine andere Adresse gewählt wurde, wird nie für die Bestellung verwendet. Name und Adresse, die mit der Bestellung gespeichert werden, stammen von PostNL, nicht vom Browser.

Bestellseite im Admin-Bereich: ein Block PostNL pickup point mit Name und Adresse, dem Location code und der Partner ID.

Bestellbestätigung und Bestelldetailseiten: PostNL pickup point mit Name und Adresse.

Bestell-E-Mails: Name und Adresse des Punkts werden in der Bestellbestätigungs-E-Mail dem Namen des Versanddienstleisters hinzugefügt. Die E-Mail für neue Bestellungen des Shops (Modul Mail alerts) zeigt außerdem den Standortcode.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox PostNL ist der erste Block unter Modules > Module Manager > VibeFox PostNL > 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-postnl 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. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Konfiguration. 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 werden die PostNL-Versanddienstleister Kunden an der Kasse nicht angezeigt, und es wird kein Versandpreis berechnet. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind. Daher werden die Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal wöchentlich. Es ist kein Cron-Job nötig. Das Deinstallieren des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus. Das Reset dieses Moduls löscht keine Daten, daher bleiben der Schlüssel und der Status erhalten.

Fehlerbehebung

PostNL erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv und der Schalter des Versanddienstleisters eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe des Kunden abdeckt (oder ob Ignore zones eingeschaltet und das Land erlaubt ist). Prüfen Sie, ob ein Preis für das Land, die Gewichtsgrenzen und Minimum subtotal festgelegt sind. Produkte können auch auf der Produktseite auf bestimmte Versanddienstleister beschränkt sein.

Der Versanddienstleister mit Abholpunkt erscheint nicht: Er wird nur für niederländische und belgische Adressen angezeigt, nur mit API-Schlüssel, Versand-Postleitzahl und Preis, und nur wenn PostNL Punkte für die Postleitzahl des Kunden zurückgibt. Prüfen Sie die Warnungen oben auf der Modulseite und das Feld Log. Fehler werden immer protokolliert; schalten Sie Debug log für Details ein.

"PostNL pickup points cannot be loaded right now": PostNL konnte nicht erreicht werden, hat den API-Schlüssel abgelehnt oder die Versand-Postleitzahl fehlt. Die Modulseite zeigt den letzten Fehler. Ein Sandbox-Schlüssel funktioniert nur mit eingeschalteter Sandbox, ein Live-Schlüssel nur mit ausgeschalteter.

Kunden sehen Test-Abholpunkte: Schalten Sie Sandbox aus.

Produktgewichte scheinen falsch: Warnt die Modulseite, dass die Gewichtseinheit des Shops nicht bekannt ist, legen Sie unter International > Localization bei Local units eine Standardeinheit fest (kg, g, lb oder oz). Bis dahin werden Produktgewichte als kg gelesen.

Die Seite meldet, dass ein PostNL-Versanddienstleister nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn erneut anzulegen. Das Zurücksetzen behält Ihre Einstellungen und den Status der Versanddienstleister.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox PostNL und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Abholpunktlisten und der letzte API-Fehler werden immer entfernt. Ist Remove data on uninstall eingeschaltet, werden die Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen und das Protokoll werden entfernt. Ist die Option ausgeschaltet, werden die Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren, erhalten die Versanddienstleister den Status zurück, den sie hatten. Bestehende Bestellungen behalten ihre Versandpositionen und den gespeicherten Abholpunkt.

PostNL ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit PostNL verbunden und wird von PostNL nicht unterstützt.