VibeFox NZ Post for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 5.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

Zugang zur NZ-Post-API (nur für Live-Tarife): Live-Tarife nutzen die ShippingOptions API von NZ Post. Beantragen Sie den API-Zugang im Developer Resource Centre auf der Website von NZ Post. NZ Post stellt eine Client ID und ein Client Secret aus, zunächst für die Testumgebung (UAT) und danach nach der Go-live-Checkliste für die Produktion. Für Tarife innerhalb Neuseelands benötigen Sie außerdem ein NZ-Post-Geschäftskonto: die Kontonummer und den auth code (oder site code). Wenn Sie nur feste Preise nutzen, brauchen Sie keinen API-Zugang.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel gilt für eine 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 auch den Ordner vfd_nz_post per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox NZ Post, oder klicken Sie auf der Seite Plugins 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. Für Live-Tarife füllen Sie den Bereich NZ Post API (live rates) aus. Optional können Sie feste Preise eintragen; sie werden ohne Live-Tarife und als Ersatz verwendet (siehe Konfiguration).

6. Fügen Sie VibeFox NZ Post unter WooCommerce > Settings > Shipping > Shipping zones einer Versandzone hinzu oder aktivieren Sie Ignore shipping zones und wählen Sie Länder aus.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox NZ Post. Sie gelten für alle Versandzonen. Wenn Sie die Versandart einer Zone hinzufügen, hat das Zonenfenster nur ein Feld:

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

Bei jedem Speichern der Einstellungen werden die zwischengespeicherten NZ-Post-Tarife und Zugriffstoken gelöscht. Wenn Live-Tarife mit den gespeicherten Werten nicht funktionieren können (nur eines von Client ID und Client Secret, kein NZD-Umrechnungskurs, unvollständige Daten für Inlandstarife), erscheint oberhalb der Einstellungen eine Warnung.

Allgemein

Enable/Disable: schaltet die Versandart in allen Zonen gleichzeitig ein oder aus.

Method title: der Name der Versandart, der im Warenkorb und an der Kasse angezeigt wird. Eine Zone kann ihn überschreiben. Standard: NZ Post.

Tax status: Taxable fügt die WooCommerce-Steuer zu den Versandkosten hinzu, None nicht. Siehe auch unten API prices.

NZ Post API (Live-Tarife) (Client ID leer lassen, um nur feste Preise zu verwenden)

Environment: Production (api.nzpost.co.nz) (Standard) oder Testing / UAT (api.uat.nzpost.co.nz). Verwenden Sie die Umgebung, für die Ihre Client ID ausgestellt wurde.

Client ID: die OAuth2-Client-ID Ihrer NZ-Post-API-Anwendung.

Client Secret: das OAuth2-Client-Secret. Es wird gegen ein Zugriffstoken getauscht, das bis zu seinem Ablauf zwischengespeichert wird.

Account number: Ihre NZ-Post-Geschäftskundennummer (Abrechnungskonto). Für Tarife innerhalb Neuseelands erforderlich. Für internationale Tarife optional; mit ihr liefert NZ Post Ihre Vertragstarife zurück.

Auth code: der auth code des Kontos für Inlandstarife. Nicht nötig, wenn Sie einen site code eingeben.

Site code: die Alternative zum auth code: Ihr NZ-Post-Abholstandortcode.

Ship-from suburb: der Stadtteil der Adresse, von der die Pakete versendet werden, zum Beispiel Petone. Für Inlandstarife erforderlich.

Ship-from city: der Ort oder die Stadt, von der die Pakete versendet werden, zum Beispiel Lower Hutt. Für Inlandstarife erforderlich.

Ship-from postcode: die vierstellige neuseeländische Postleitzahl, von der die Pakete versendet werden, zum Beispiel 5012. Für Inlandstarife erforderlich.

Services: optionale NZ-Post-Dienstcodes, durch Kommas getrennt, zum Beispiel CPOLP, ICOU. Nur diese Dienste werden berechnet. Leer lassen, um den günstigsten Dienst zu verwenden, den NZ Post für das Paket zurückgibt.

API prices: Including GST (Standard) oder Excluding GST. Inlandspreise von NZ Post enthalten 15% GST; internationales Porto ist steuerfrei. Wählen Sie Excluding GST, wenn Tax status auf Taxable steht, damit GST nicht doppelt berechnet wird.

NZD → (store currency) rate: Preise von NZ Post sind in NZD. Wenn die Währung Ihres Shops nicht NZD ist, geben Sie ein, wie viele Einheiten Ihrer Währung einem NZD entsprechen, zum Beispiel 0.55. Ohne diesen Wert werden Live-Tarife nicht verwendet. Derselbe Kurs rechnet den Bestellwert um, der bei internationalen Anfragen übermittelt wird. Wenn die Währung Ihres Shops NZD ist, lassen Sie das Feld leer.

Paket für Live-Tarife

Der Warenkorb wird als ein einziges Paket an NZ Post übermittelt. Gewichte und Abmessungen der Produkte werden von Ihren Shop-Einheiten in kg und cm umgerechnet. Das Paket nimmt die größte Länge und Breite der Produkte an, und seine Höhe wächst, bis das Volumen aller Artikel hineinpasst. Die folgenden Werte gelten für Produkte ohne Gewicht oder Abmessungen.

Default product weight (kg): wird für jedes Produkt ohne Gewicht verwendet. Standard: 0.5.

Default parcel length (cm): wird verwendet, wenn kein Produkt im Warenkorb Abmessungen hat. Standard: 30.

Default parcel width (cm): wird verwendet, wenn kein Produkt im Warenkorb Abmessungen hat. Standard: 20.

Default parcel height (cm): wird verwendet, wenn kein Produkt im Warenkorb Abmessungen hat. Standard: 10.

Feste Preise (werden verwendet, wenn Live-Tarife nicht eingerichtet sind oder NZ Post keinen Tarif liefert)

Die Preise sind in der Währung des Shops angegeben.

Country prices: eine Zeile je Zielland. Klicken Sie auf + Add country, um eine Zeile hinzuzufügen, und auf das Kreuz, um sie zu entfernen. Wählen Sie * Default für eine Zeile, die alle übrigen Länder abdeckt. Jede Zeile hat einen Any weight-Preis und optionale Gewichtsspalten: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg und > 5 kg (Warenkorbgewicht). Eine ausgefüllte Gewichtsspalte überschreibt Any weight; eine leere oder 0-Spalte verwendet Any weight. Ein Any weight-Preis von 0 bedeutet kostenlosen Versand in dieses Land. Sowohl "9.99" als auch "9,99" werden akzeptiert. Zeilen ohne Preis, ungültige Ländercodes und negative Preise werden beim Speichern entfernt. Je Land bleibt nur eine Zeile erhalten.

Fallback cost: wird verwendet, wenn weder die API noch die Länder-Tabelle einen Preis liefern. Leer lassen, um die Versandart in diesem Fall auszublenden.

Fixed price per: Order berechnet den Preis einmal. Item (price × quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Das gilt nur für feste Preise und die Ersatzkosten. Live-Tarife werden immer für das gesamte Paket berechnet.

Bedingungen

Min cart weight (kg): blendet die Versandart aus, wenn der Warenkorb weniger wiegt. 0 bedeutet keine Grenze.

Max cart weight (kg): blendet die Versandart aus, wenn der Warenkorb mehr wiegt. Standard: 25 (NZ-Post-Kurierpakete wiegen bis zu 25 kg). 0 bedeutet keine Grenze.

Minimum order amount: zeigt die Versandart nur an, wenn die Zwischensumme des Warenkorbs diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.

Excluded shipping classes: blendet die Versandart aus, wenn der Warenkorb ein Produkt aus einer dieser WooCommerce-Versandklassen enthält.

Free shipping from: die Warenkorb-Zwischensumme, ab der der Versand mit NZ Post kostenlos ist. Gilt nur, wenn die Versandart einen Preis hat: ein Länderpreis oder die Ersatzkosten (dann wird keine Anfrage an NZ Post gesendet) oder ein Live-Tarif. Leer lassen, um nie kostenlosen Versand anzubieten.

Für diese Bedingungen zählen Produkte ohne Gewicht im Warenkorbgewicht als 0.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet NZ Post für die unten genannten Länder an, auch wenn die Versandart keiner Versandzone hinzugefügt wurde.

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

Erweitert

Debug log: schreibt Tarifberechnungen in WooCommerce > Status > Logs (Quelle „vfd-nz-post“). API-Fehler werden immer protokolliert, auch bei ausgeschaltetem Debug-Log. Zugangsdaten, Token und Kundenadressen werden nicht protokolliert. Schalten Sie das Log aus, wenn Sie fertig sind.

Remove data on uninstall: wenn eingeschaltet, werden beim Löschen des Plugins seine Einstellungen, Zonen-Versandarten und zwischengespeicherten Tarife entfernt. Das Deaktivieren des Plugins löscht nie etwas.

So funktioniert es an der Kasse

Sobald der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Tarif. Das Plugin prüft zuerst die Bedingungen: Lieferland, Warenkorbgewicht, Mindestbestellwert und ausgeschlossene Versandklassen. Dann sucht es einen Preis: den Live-Tarif von NZ Post, danach die Länder-Tabelle und zuletzt die Ersatzkosten. Gibt es keinen Preis, wird die Versandart ausgeblendet. Gilt kostenloser Versand, sieht der Kunde die Versandart ohne Kosten.

Sind Live-Tarife eingerichtet, holt sich das Plugin mit Ihrer Client ID und Ihrem Client Secret ein Zugriffstoken und fragt NZ Post nach einem Preis. Für eine Adresse in Neuseeland übermittelt es Ihre Kontodaten, die Versandadresse, Stadtteil, Ort und Postleitzahl des Kunden sowie Gewicht und Größe des Pakets. WooCommerce hat kein Stadtteil-Feld: Das Plugin verwendet Address line 2, wenn dort ein Stadtteilname steht, sonst den Ort oder die Stadt. Ein Inlandstarif wird erst angefragt, wenn der Kunde eine Stadt und eine vierstellige Postleitzahl eingegeben hat. Für andere Länder übermittelt es das Zielland, Gewicht und Größe des Pakets und den Bestellwert in NZD.

Verwendet wird der günstigste erlaubte Dienst mit Preis, einschließlich Zuschlägen und verpflichtender Zusatzleistungen. Der Preis wird von NZD in die Währung Ihres Shops umgerechnet. Der berechnete Dienst wird mit der Bestellung als NZ Post service gespeichert und auf dem Bestellbildschirm angezeigt. Jede Antwort wird 1 Stunde zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf NZ Post warten muss. Das Zeitlimit der API beträgt 10 Sekunden. Ein abgelaufenes Zugriffstoken wird automatisch erneuert.

Liefert NZ Post keinen Tarif (API nicht eingerichtet, Fehler, unvollständige Adresse, Dienst nicht verfügbar, kein NZD-Kurs), sieht der Kunde keine Fehlermeldung. Es wird der Preis aus der Länder-Tabelle verwendet, danach die Ersatzkosten. Gibt es keinen festen Preis, wird die Versandart ausgeblendet. Der Grund wird im Log festgehalten.

Die Versandart funktioniert in der klassischen Kasse sowie im Warenkorb- und Kassen-Block. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin berechnet nur Tarife. Es erstellt keine Versandetiketten, bucht keine Abholungen, erstellt keine Manifeste, verfolgt keine Pakete, prüft keine Adressen und lässt Kunden keinen Abholpunkt, kein Postfach (PO Box) und keinen Paketautomaten (parcel locker) wählen. Der Warenkorb wird als ein Paket berechnet, und der Kunde sieht einen Tarif von NZ Post, keine Liste von Diensten.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox NZ Post. 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, sowie 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 gilt für eine 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 NZ Post Kunden an der Kasse nicht angezeigt. Angemeldete Shop-Manager sehen die Versandart weiterhin, mit dem Hinweis (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen.

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

Fehlerbehebung

NZ Post erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Versandart der Zone des Kundenlandes hinzugefügt ist (oder Ignore shipping zones eingeschaltet ist und das Land erlaubt ist). Prüfen Sie die Gewichtsgrenzen, Minimum order amount und Excluded shipping classes. Liefert NZ Post keinen Tarif, wird die Versandart nur mit einem Länderpreis oder einer Fallback cost angezeigt.

Live-Tarife erscheinen nicht: Öffnen Sie WooCommerce > Status > Logs, Quelle „vfd-nz-post“. API-Fehler stehen dort immer. Schalten Sie Debug log für Details ein. Das Log nennt den Grund: fehlende Client ID oder fehlendes Client Secret, ein abgelehntes Token, fehlende Konto- oder Versanddaten, noch keine Stadt oder Postleitzahl des Kunden, kein NZD-Kurs oder kein Dienst mit Preis. Bis Sie das Problem behoben haben, werden feste Preise verwendet.

Token-Anfrage schlägt fehl: Prüfen Sie Client ID, Client Secret und Environment. Zugangsdaten für UAT funktionieren nicht mit der Produktion und umgekehrt.

Inlandstarife fehlen, internationale Tarife funktionieren: Tarife innerhalb Neuseelands benötigen Account number, Auth code oder Site code sowie die vollständige Versandadresse mit vierstelliger Postleitzahl. Der Kunde muss eine Stadt und eine vierstellige Postleitzahl eingeben. Entwickler können den für die Lieferadresse übermittelten Stadtteil mit dem Filter vfd_nzpt_delivery_suburb ändern.

Mein Shop ist nicht in NZD: Geben Sie den NZD → (store currency) rate ein. Feste Preise sind immer in der Währung des Shops.

GST wird beim Versand doppelt berechnet: Inlandspreise von NZ Post enthalten 15% GST. Steht Tax status auf Taxable, stellen Sie API prices auf Excluding GST.

Tarife wirken nach einer Änderung veraltet: Speichern Sie die Einstellungsseite. Dadurch werden die zwischengespeicherten NZ-Post-Tarife und Token gelöscht.

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 Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Einstellungen, Zonen-Versandarten, zwischengespeicherte Tarife und Zugriffstoken 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.

NZ Post ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit NZ Post verbunden und wird nicht von NZ Post unterstützt.