VibeFox PostNL for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

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. Methoden für die Lieferung nach Hause benötigen keinen Schlüssel.

VibeFox-Lizenzschlüssel: Erwerb über vibefox.net. Ein Schlüssel funktioniert auf einer Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Sie können den Ordner vfd_postnl auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox PostNL, oder klicken Sie auf der Plugins-Seite unter dem Plugin-Namen auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Tragen Sie die Preise ein. Für Abholpunkte geben Sie außerdem den PostNL-API key und den Ship from (postcode) ein (siehe Konfiguration).

6. Fügen Sie VibeFox PostNL in WooCommerce > Settings > Shipping > Shipping zones einer Versandzone hinzu, zum Beispiel Niederlande und Belgien. Legen Sie in der Zone den Title und das Delivery to fest. Fügen Sie die Methode ein zweites Mal für den anderen Liefertyp hinzu.

Konfiguration

Alle Einstellungen außer Titel und Liefertyp befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox PostNL. Sie gelten für jede Versandzone. Wenn Sie die Methode einer Zone hinzufügen, hat das Zonenfenster zwei Felder:

Title (zone): der Name, den Kunden für diese Zonenmethode sehen. Leer lassen, um den globalen Name zu verwenden.

Delivery to (zone): As in the global settings (Standard), PostNL pickup point (customer chooses a point) oder Home address. Fügen Sie die Methode einer Zone zweimal hinzu, um beide anzubieten.

Über den Einstellungen zeigt die Seite Warnungen an: einen fehlenden API-Schlüssel oder eine fehlende Absender-Postleitzahl für Abholpunkte, eine eingeschaltete Sandbox, einen nicht gesetzten Preis und die letzte fehlgeschlagene PostNL-Anfrage mit Datum und Fehler.

Allgemein

Enable/Disable: schaltet die PostNL-Zustellung in allen Zonen gleichzeitig ein oder aus.

Name: der Name der Versandmethode an der Kasse. Ein in der Zone gesetzter Title überschreibt ihn. Standard: PostNL.

Delivery to: der Standard-Liefertyp für Zonenmethoden mit As in the global settings und für den Modus Ignore zones.

Tax status: Taxable fügt den WooCommerce-Steuern auf die Versandkosten hinzu, None tut das nicht.

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, in der WordPress-Datenbank gespeichert und nie Kunden angezeigt oder ins Protokoll geschrieben.

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

Ship from (country): das Land, in dem Sie Ihre Pakete an PostNL übergeben, Niederlande oder Belgien. Standardmäßig ist es das Land Ihres Shops. 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 WooCommerce > Settings > General zu verwenden, wenn der Shop im selben Land liegt. Eine ungültige Postleitzahl wird mit einer Meldung abgelehnt. Wenn Sie den API-Schlüssel, die Sandbox-Einstellung oder die Absenderadresse ändern, werden die zwischengespeicherten Abholpunktlisten gelöscht.

Preise (in der Shop-Währung)

PostNL bietet keine öffentliche Tarif-API. Daher fragt das Plugin keine Live-Tarife ab und rechnet Preise nie um.

Price per country: eine Zeile je Zielland. Klicken Sie auf + Add country, um eine Zeile hinzuzufügen, und auf das Kreuz, um eine 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 überschreibt Price; leer lassen, um Price zu verwenden. Ein Price von 0 bedeutet kostenlosen Versand. „6.95“ und „6,95“ werden beide akzeptiert. Leere Zeilen und ungültige Ländercodes werden beim Speichern entfernt. Wenn ein Land zweimal vorkommt, bleibt die erste Zeile erhalten. Ungültige Preise werden mit einer Meldung ignoriert.

Calculation: Per order berechnet den Preis einmal. Per item (price x quantity) multipliziert ihn mit der Anzahl der versandfähigen Artikel im Warenkorb.

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

Bedingungen

Free shipping from: die Warenkorb-Zwischensumme, ab der die Lieferung kostenlos ist. Gilt nur dort, wo ein Preis gefunden wird. Leer lassen, um nie kostenlosen Versand anzubieten.

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

Minimum weight (kg): Die Methode wird ausgeblendet, wenn der Warenkorb weniger wiegt. Produktgewichte werden aus Ihrer Shop-Einheit umgerechnet. Leer lassen für kein Limit.

Maximum weight (kg): Die Methode wird bei schwereren Warenkörben ausgeblendet. Standard: 30 (PostNL-Pakete gehen im Benelux bis 30 kg). Leer lassen für kein Limit.

Hide for shipping classes: Die Methode wird ausgeblendet, wenn der Warenkorb ein Produkt aus einer dieser WooCommerce-Versandklassen enthält.

Alle Beträge und Gewichte akzeptieren ein Dezimalkomma, auch mit Tausendertrennzeichen (1.234,50 oder 1,234.50). Eine ungültige Zahl wird mit einer Meldung ignoriert.

Verfügbarkeit ohne Versandzonen

Ignore zones: bietet PostNL auch in den unten genannten Ländern an, wenn keine Zone es hinzufügt. Zonen, die die Methode enthalten, funktionieren wie gewohnt weiter. Dieser Modus verwendet den globalen Name und das globale Delivery to.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zu verwenden, in die der Shop liefert. Dieses Feld wird nur verwendet, wenn Ignore zones eingeschaltet ist.

Erweitert

Debug log: schreibt Debug-Meldungen nach WooCommerce > Status > Logs (Quelle „vfd-postnl“). API-Fehler werden immer protokolliert. Es werden weder API-Schlüssel noch Kundendaten geschrieben. Schalten Sie das Protokoll aus, wenn Sie fertig sind.

Remove data on uninstall: Wenn eingeschaltet, entfernt das Löschen des Plugins die PostNL-Einstellungen und Zonenmethoden. Das Deaktivieren des Plugins löscht nie Einstellungen. Abholpunkte in Bestellungen bleiben immer erhalten.

So funktioniert es an der Kasse

Wenn der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Tarif. Das Plugin prüft die Bedingungen: Warenkorbgewicht, Mindest-Zwischensumme und Versandklassen. Dann nimmt es den Preis aus der Tabelle für Land und Gewichtsklasse oder den Preis für andere Länder. Gibt es keinen Preis, wird die Methode ausgeblendet. Erreicht die Warenkorb-Zwischensumme Free shipping from, beträgt der Preis 0.

Eine Methode mit Abholpunkt wird nur für Adressen in den Niederlanden und Belgien und nur mit API-Schlüssel angeboten. Sobald der Kunde eine gültige Postleitzahl eingegeben hat, fragt das Plugin die PostNL-Checkout-API nach den nächsten Abholpunkten. Gesendet werden Postleitzahl, Straße, Hausnummer, Ort und Land des Kunden sowie Ihre Absenderadresse. Für Methoden mit Lieferung nach Hause wird nichts gesendet. Wenn PostNL nicht erreichbar ist oder keine Punkte für die Adresse liefert, wird die Methode mit Abholpunkt ausgeblendet, und Ihre übrigen Methoden bleiben verfügbar. Das API-Timeout beträgt 12 Sekunden.

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

Die Methode funktioniert an der klassischen Kasse und in den Warenkorb- und Kassen-Blöcken. Sie ist mit High-Performance Order Storage (HPOS) von WooCommerce kompatibel.

Das Plugin 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 sowie Abend- oder Morgenlieferung. Erstellen Sie die Sendung in Mijn PostNL oder einem anderen PostNL-Tool mit dem gespeicherten Abholpunkt.

Abholpunkte

Wenn der Kunde eine Methode mit Abholpunkt auswählt, erscheint darunter eine Liste PostNL pickup point mit den drei nächsten Punkten: Firmenname, Adresse und Entfernung. Bevor eine Postleitzahl eingegeben ist, sieht der Kunde die Meldung „Geben Sie Ihre Postleitzahl ein (zum Beispiel 1234 AB), um PostNL-Abholpunkte zu sehen.“ (4 Ziffern für Belgien). Die Auswahl bleibt erhalten, wenn die Kasse aktualisiert wird.

Der Punkt ist erforderlich. Ohne Punkt stoppt die Kasse mit der Meldung „Bitte wählen Sie einen PostNL-Abholpunkt.“ Der Server prüft den Punkt gegen die PostNL-Liste für die Lieferadresse. Steht er nicht auf der Liste, stoppt die Kasse mit der Meldung „Der gewählte PostNL-Abholpunkt ist für diese Adresse nicht verfügbar. Bitte wählen Sie ihn erneut.“ Name und Adresse, die mit der Bestellung gespeichert werden, stammen von PostNL, nicht vom Browser.

Bestellbildschirm im Admin-Bereich: PostNL pickup point mit Name und Adresse sowie dem Location code, unter der Lieferadresse.

Bestellbestätigung und Bestellansicht im Mein-Konto-Bereich: PostNL pickup point mit Name und Adresse.

Bestell-E-Mails: Name und Adresse des Punkts in HTML- und Text-E-Mails.

In der Datenbank wird der Punkt in den Bestell-Metadaten _vfd_ptnl_servicepoint_id (PostNL-Standortcode), _vfd_ptnl_servicepoint_name (Name und Adresse) und _vfd_ptnl_servicepoint (Partner-ID, Firma, Straße, Hausnummer, Postleitzahl, Ort, Land) gespeichert.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox PostNL. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel funktioniert auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird PostNL Kunden an der Kasse nicht angezeigt. Angemeldete Shop-Manager sehen es weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, funktioniert das Plugin weiter, für Updates und Support ist aber eine Verlängerung nötig. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

PostNL erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Methode der Zone des Landes des Kunden hinzugefügt wurde (oder Ignore zones eingeschaltet ist und das Land erlaubt ist). Prüfen Sie, ob für das Land ein Preis gesetzt ist, die Gewichtsgrenzen, Minimum subtotal und Hide for shipping classes.

Die Methode mit Abholpunkt erscheint nicht: Sie wird nur für niederländische und belgische Adressen angezeigt, nur mit API-Schlüssel, Absender-Postleitzahl und Preis, und nur wenn PostNL für die Postleitzahl des Kunden Punkte zurückgibt. Prüfen Sie die Warnungen oben auf der Einstellungsseite und WooCommerce > Status > Logs, Quelle „vfd-postnl“. Fehler werden immer protokolliert; schalten Sie Debug log ein, um Details zu sehen.

„PostNL-Abholpunkte können derzeit nicht geladen werden“: PostNL war nicht erreichbar, hat den API-Schlüssel abgelehnt, oder die Absender-Postleitzahl fehlt. Die Einstellungsseite 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.

Filter für Entwickler: vfd_ptnl_number_of_locations (Standard 3), vfd_ptnl_checkout_request (Anfragekörper) und vfd_ptnl_api_url.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel etwa schon auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem letzten bekannten Status weiter.

Deinstallation

Das Deaktivieren des Plugins behält alle Einstellungen und löscht nur die zwischengespeicherten Abholpunktlisten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt, zusammen mit den zwischengespeicherten Abholpunktlisten und dem letzten API-Fehler. Einstellungen und Zonenmethoden werden nur entfernt, wenn Remove data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Versandpositionen und den gespeicherten Abholpunkt.

PostNL ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit PostNL verbunden noch wird es von PostNL unterstützt oder empfohlen.