VibeFox NZ Post for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

NZ-Post-API-Zugang (nur für Live-Tarife): Live-Tarife verwenden 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, zuerst für die Testumgebung (UAT) und danach für die Produktion nach der Go-live-Checkliste. 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 verwenden, brauchen Sie keinen API-Zugang.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel gilt 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. Klicken Sie nach Abschluss des Uploads auf Configure, oder suchen Sie VibeFox NZ Post später in der Modulliste und klicken Sie auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzbereich oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Für Live-Tarife füllen Sie den Abschnitt NZ Post API (live rates) aus. Optional geben Sie feste Preise ein, die ohne Live-Tarife und als Ersatz verwendet werden (siehe Konfiguration). Klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienst NZ Post mit dem Lieferzeittext NZ Post parcel delivery an. Der Versanddienst wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis stammt immer vom Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox NZ Post > Configure. Sie gelten für jede Zone des Versanddienstes. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten Tarife von NZ Post und die Zugriffstoken.

Über den Einstellungen erscheinen Warnungen, wenn Live-Tarife mit den gespeicherten Werten nicht funktionieren können: nur eines von Client ID und Client Secret, kein NZD-Umrechnungskurs oder unvollständige Daten für Inlandstarife. Eine Warnung erscheint außerdem, wenn das Modul die Gewichts- oder Maßeinheit des Shops nicht kennt (dann werden Gewichte als kg und Abmessungen als cm behandelt). Stellen Sie die Einheiten unter International > Localization (Local units) ein. Zahlenfelder müssen 0 oder eine positive Zahl enthalten; andernfalls zeigt die Seite einen Fehler an und es wird nichts gespeichert.

General

Enable NZ Post: schaltet den Versanddienst ein oder aus. Dies ist derselbe Schalter wie der Status des Versanddienstes unter Shipping > Carriers.

Method title: der Name des Versanddienstes, der im Warenkorb und an der Kasse angezeigt wird. Standard: NZ Post. Pflichtfeld, höchstens 64 Zeichen.

Tax: die Steuerregel des Versanddienstes oder No tax (die Versandkosten werden nicht besteuert). Wenn der Shop GST auf den Versand aufschlägt, stellen Sie API prices weiter unten auf Excluding GST, damit GST nicht doppelt berechnet wird.

NZ Post API (live rates) (lassen Sie die Client ID leer, 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. Wenn Sie sie leeren, wird auch das gespeicherte Client Secret gelöscht.

Client Secret: das OAuth2-Client-Secret. Es wird gegen ein Zugriffstoken getauscht, das bis zu seinem Ablauf zwischengespeichert wird. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Account number: Ihre NZ-Post-Geschäftskundennummer (Abrechnungskonto). Für Tarife innerhalb Neuseelands erforderlich. Für internationale Tarife ist sie optional; mit ihr liefert NZ Post Ihre Vertragstarife zurück. Wenn Sie sie leeren, wird auch der gespeicherte auth code gelöscht.

Auth code: der Auth-Code des Kontos für Inlandstarife. Er wird nicht benötigt, wenn Sie einen site code eingeben. Wie das Client Secret wird er nach dem Speichern nicht erneut angezeigt.

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

Ship-from suburb: der Stadtteil (suburb) 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 Komma getrennt, zum Beispiel CPOLP, ICOU. Nur diese Dienste werden bepreist. Lassen Sie das Feld leer, 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 (zero-rated). Wählen Sie Excluding GST, wenn der Versanddienst eine Steuerregel hat (Tax oben), damit GST nicht doppelt berechnet wird.

NZD → (shop currency) rate: NZ-Post-Preise sind in NZD angegeben. Wenn die Standardwährung Ihres Shops nicht NZD ist, geben Sie ein, wie viele Einheiten Ihrer Währung einem NZD entsprechen, zum Beispiel 0.55. Ohne diesen Kurs werden keine Live-Tarife verwendet. Derselbe Kurs rechnet auch den Bestellwert um, der bei internationalen Anfragen übermittelt wird. Der Kurs muss größer als 0 sein. Wenn die Währung Ihres Shops NZD ist, lassen Sie das Feld leer.

Parcel for live rates

Der Warenkorb wird als ein Paket an NZ Post übermittelt. Produktgewichte und -abmessungen werden von Ihren Shop-Einheiten in kg und cm umgerechnet. Das Paket übernimmt die größte Länge und Breite der Produkte, 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.

Fixed prices (werden verwendet, wenn keine Live-Tarife eingerichtet sind oder NZ Post keinen Tarif liefert)

Die Preise gelten in der Standardwährung des Shops, ohne Steuern.

Country prices: 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 * Default für eine Zeile, die alle übrigen Länder abdeckt. Jede Zeile hat einen Preis Any weight und optionale Gewichtsspalten: ≤ 1 kg, 1–2 kg, 2–3 kg, 3–5 kg und > 5 kg (Warenkorbgewicht). Eine ausgefüllte Gewichtsspalte ersetzt Any weight; eine leere oder mit 0 belegte Spalte verwendet Any weight. Ein Preis Any weight von 0 bedeutet kostenloser Versand in dieses Land. Sowohl „9.99“ als auch „9,99“ werden akzeptiert. Zeilen ohne Preis 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änderliste einen Preis liefert. Lassen Sie das Feld leer, um den Versanddienst in diesem Fall auszublenden.

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

Conditions

Min cart weight (kg): blendet den Versanddienst aus, wenn der Warenkorb weniger wiegt. 0 bedeutet keine Begrenzung.

Max cart weight (kg): blendet den Versanddienst aus, wenn der Warenkorb mehr wiegt. Standard: 25 (Kurierpakete von NZ Post sind bis 25 kg zulässig); ein leeres Feld bedeutet ebenfalls 25. 0 bedeutet keine Begrenzung. Wenn Ignore shipping zones aktiviert ist, bedeutet ein leeres Feld keine Begrenzung außerhalb der eigenen Zonen des Versanddienstes. Ist Min cart weight größer als Max cart weight, zeigt die Seite einen Fehler an und es wird nichts gespeichert, da der Versanddienst nie angezeigt würde.

Minimum order amount: zeigt den Versanddienst nur an, wenn die Zwischensumme des Warenkorbs (Produkte, die versendet werden müssen, nach Rabatten, vor Steuern) diesen Betrag erreicht. Lassen Sie das Feld leer, um ihn immer anzuzeigen.

Free shipping from: die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern), ab der der Versand mit NZ Post kostenlos ist. Dann wird keine Anfrage an NZ Post gesendet. Lassen Sie das Feld leer, um nie kostenlosen Versand anzubieten.

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

Availability without shipping zones

Normalerweise wird der Versanddienst in den Zonen angezeigt, denen er unter Shipping > Carriers zugewiesen ist.

Ignore shipping zones: bietet NZ Post für die unten angegebenen Länder an, unabhängig davon, welche Zone passt. Beim Speichern wird der Versanddienst allen Zonen hinzugefügt (auch später erstellten Zonen). Wird die Option deaktiviert, werden die hinzugefügten Zonen wieder entfernt.

Countries: die Zielländer für diesen Modus. Lassen Sie das Feld leer, um alle aktiven Länder des Shops zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Advanced

Debug log: schreibt die Tarifberechnungen in logs/vfd_nzpt_debug.log.php im Modulordner. Die Datei kann nicht über den Webbrowser geöffnet werden. API-Fehler werden immer protokolliert, auch wenn das Debug-Protokoll ausgeschaltet ist. Zugangsdaten, Token und Kundenadressen werden nicht protokolliert. Schalten Sie das Protokoll nach Abschluss der Arbeiten 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 aktiviert, werden beim Deinstallieren des Moduls die Einstellungen, der Versanddienst, die zwischengespeicherten Tarife, die gespeicherten Bestelldetails und die Protokolle gelöscht. Ist sie deaktiviert, bleibt alles für eine erneute Installation erhalten.

So funktioniert das Modul an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem Preis von NZ Post. Es zählen nur physische Produkte: Virtuelle Produkte erhöhen das Gewicht nicht und sind nicht im Bestellwert enthalten. Das Modul prüft zuerst die Bedingungen: erlaubte Länder (mit Ignore shipping zones), Warenkorbgewicht und Mindestbestellwert. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an NZ Post gesendet. Andernfalls sucht es einen Preis: zuerst den Live-Tarif von NZ Post, dann die Länderliste und schließlich die Ersatzkosten. Gibt es keinen Preis, wird der Versanddienst ausgeblendet.

Sind Live-Tarife eingerichtet, holt das Modul 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. PrestaShop hat kein Feld für den Stadtteil: Das Modul verwendet Address line 2, wenn dort ein Stadtteilname steht (ohne Ziffern), andernfalls den Ort. Ein Inlandstarif wird erst angefragt, nachdem der Kunde einen Ort und eine vierstellige Postleitzahl eingegeben hat. Für andere Länder übermittelt es das Zielland, Gewicht und Größe des Pakets sowie den Bestellwert in NZD.

Verwendet wird der günstigste zulässige Dienst mit Preis, einschließlich Zuschlägen und verpflichtender Zusatzleistungen. Der Preis wird von NZD in die Standardwährung Ihres Shops umgerechnet und dann in der Warenkorbwährung des Kunden 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änderliste verwendet, danach die Ersatzkosten. Gibt es keinen festen Preis, wird der Versanddienst ausgeblendet. Der Grund wird im Protokoll festgehalten.

Wenn Sie den Versanddienst unter Shipping > Carriers bearbeiten, nachdem er bereits Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstes. Das Modul folgt automatisch der neuen Version.

Das Modul 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 bepreist, und der Kunde sieht einen NZ-Post-Tarif, nicht eine Liste der Dienste.

Bestellungen

Wenn eine Bestellung mit dem Versanddienst NZ Post aufgegeben wird, speichert das Modul, worauf der Versandpreis beruhte. Die Bestellseite im Back Office zeigt einen Block NZ Post mit NZ Post service (der bepreiste NZ-Post-Dienst eines Live-Tarifs) und Price source: Live rate (NZ Post ShippingOptions API), Fixed price oder Free shipping. Der Block zeigt die Werte zum Zeitpunkt der Bestellung, auch wenn sich Tarife oder Einstellungen später ändern.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich License — VibeFox NZ Post ist der erste Bereich unter Modules > Module Manager > VibeFox NZ Post > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Bereich den Schlüssel verdeckt, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: presta-shipping-nz-post 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 Bereichs folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, nennt der Bereich den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nach einer Änderung der Shop-Adresse 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 gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Einrichtung. Wenn Sie den Schlüssel aus dem Shop entfernen, wird sein Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird der Versanddienst NZ Post Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher ist 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. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern 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 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

NZ Post erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable NZ Post eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienst die Zone des Landes und die Kundengruppe des Kunden abdeckt (oder ob Ignore shipping zones aktiviert ist und das Land erlaubt ist). Kontrollieren Sie die Gewichtsgrenzen und den Minimum order amount. Liefert NZ Post keinen Tarif, wird der Versanddienst nur mit einem Länderpreis oder einer Fallback cost angezeigt. Produkte können auf der Produktseite auch auf bestimmte Versanddienste beschränkt sein.

Live-Tarife erscheinen nicht: Lesen Sie die Warnungen oben auf der Modulseite. Aktivieren Sie dann das Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log an. API-Fehler stehen dort immer. Das Protokoll nennt den Grund: fehlende Client ID oder Client Secret, ein abgelehnter Token, fehlende Konto- oder Versanddaten, noch keine Ortsangabe oder Postleitzahl des Kunden, kein NZD-Kurs oder kein Dienst mit Preis. Solange Sie das Problem beheben, werden feste Preise verwendet.

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

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

Mein Shop verwendet nicht NZD: Geben Sie den NZD → (shop currency) rate ein. Feste Preise gelten immer in der Standardwährung des Shops.

GST wird auf den Versand doppelt berechnet: Inlandspreise von NZ Post enthalten 15% GST. Hat der Versanddienst eine Steuerregel unter Tax, stellen Sie API prices auf Excluding GST.

Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten Tarife von NZ Post und die Token gelöscht.

Die Seite meldet, dass der Versanddienst NZ Post 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.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox NZ Post und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Tarife und Token werden immer entfernt. Ist Remove data on uninstall aktiviert, wird der Versanddienst gelöscht (Bestellungen behalten ihren Verlauf) und die Einstellungen, die gespeicherten Bestelldetails und das Protokoll werden entfernt. Ist die Option deaktiviert, wird der Versanddienst nur deaktiviert und alle Einstellungen bleiben erhalten. Bei einer erneuten Installation des Moduls oder bei einem Reset erhält der gespeicherte Versanddienst den Status zurück, den er vorher hatte (ein oder aus).

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