VibeFox Australia Post for OpenCart — Hilfe

Anforderungen

OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).

PHP: 8.0 oder neuer.

Australia-Post-PAC-API-Schlüssel (nur für Live-Tarife): Live-Tarife nutzen die Postage Assessment Calculator (PAC) API von Australia Post. Der Schlüssel ist kostenlos: Registrieren Sie sich im Australia Post Developer Centre (developers.auspost.com.au) für einen PAC-API-Schlüssel. Die Einstellungsseite verlinkt auf die Registrierungsseite. Sie benötigen außerdem die vierstellige australische Postleitzahl, von der Sie versenden. Wenn Sie nur feste Preise je Land nutzen, brauchen Sie keinen API-Schlüssel.

VibeFox-Lizenzschlüssel: Kauf auf vibefox.net. Ein Schlüssel gilt für eine Domain.

Installation

Der Download ist eine einzige ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das OpenCart-3-Paket vfd_australia_post-oc3-(version).ocmod.zip und das OpenCart-4-Paket vfd_australia_post.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen gleich.

OpenCart 3

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_australia_post-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Modifikationen hinzu, Sie müssen Extensions > Modifications also nicht aktualisieren. Statt des Installers können Sie auch den Inhalt des Ordners upload aus diesem Paket in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Australia Post und klicken Sie auf Install (die grüne +-Schaltfläche).

3. Klicken Sie auf Edit (die Bleistift-Schaltfläche), um die Einstellungsseite zu öffnen.

4. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Edit ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

5. Wählen Sie die Rate source (Tarifquelle). Für feste Preise fügen Sie Zeilen unter Country prices hinzu. Für Live-Tarife geben Sie den PAC-API-Schlüssel, Ihre Versand-Postleitzahl und, falls die Standardwährung Ihres Shops nicht AUD ist, den AUD-Umrechnungskurs ein (siehe Konfiguration). Aktivieren Sie Enable Australia Post und klicken Sie auf Save.

OpenCart 4

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_australia_post.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Erweiterungscode dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.

2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Australia Post, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Bleistift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel und die Einstellungen wie in den Schritten 4 und 5 für OpenCart 3 ein. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich.

Nach der Installation ist die Versandart deaktiviert, bis Sie Enable Australia Post einschalten und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die von Ihnen behaltenen Australia-Post-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Australia Post > Edit. Die Abschnitte stehen links. Ein Button Save speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht außerdem die zwischengespeicherten Australia-Post-Tarife. Nur Administratoren mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Einige Fehler verhindern das Speichern, dann wird nichts gespeichert: ein Method title mit mehr als 64 Zeichen, ein Sort order, der keine ganze Zahl ist, oder eine unbekannte Steuerklasse oder Geozone. Andere Probleme werden als Warnungen über dem Bereich angezeigt, und der Rest der Einstellungen wird gespeichert. Ein Zahlenfeld mit einem Wert, der keine Zahl oder negativ ist, behält seinen vorherigen Wert, und die Warnung nennt das Feld. Zahlenfelder akzeptieren Punkt oder Komma als Dezimaltrennzeichen.

Ist eine Live-Tarifquelle gewählt, aber der API-Schlüssel, eine vierstellige Versand-Postleitzahl oder der AUD-Umrechnungskurs fehlt, wird nach dem Speichern eine Warnung angezeigt. Sie sagt auch, was bis zur Korrektur geschieht: Die Methode wird an der Kasse ausgeblendet, oder im Ersatzmodus werden die festen Länderpreise verwendet. Die Seite warnt außerdem, wenn Ihr Shop keine Gewichtsklasse mit der Einheit kg oder keine Längenklasse mit der Einheit cm hat. Produktgewichte und -abmessungen werden dann nach der Einheit ihrer Klasse umgerechnet (kg, g, lb, oz; cm, mm, m, in), andere Einheiten werden als kg und cm gelesen.

Allgemein

Die Einstellungen gelten für alle Geozonen. Sie können die Methode unter Conditions auf eine Geozone beschränken oder unter Availability without shipping zones auf eine Liste von Ländern.

Enable Australia Post: blendet Australia Post an der Kasse ein oder aus. Standard: aus.

Method title: der Name der Versandart, den der Kunde im Warenkorb und an der Kasse sieht. Standard: Australia Post. Höchstens 64 Zeichen: Ein längerer Titel wird abgelehnt, und nichts wird gespeichert. Ist das Feld leer, wird eine Warnung angezeigt und Australia Post verwendet.

Rate source: wie der Preis berechnet wird.

Fehlerdetails gehen ins Protokoll, nie an den Kunden.

Sort order: die Position von Australia Post unter den Versandarten an der Kasse. Eine ganze Zahl.

Australia-Post-API (Live-Tarife) (für feste Preise nicht nötig)

PAC API key: Ihr kostenloser Australia-Post-PAC-API-Schlüssel. Er wird im Header AUTH-KEY an Australia Post gesendet. 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: einschalten und speichern, um den gespeicherten Schlüssel zu löschen. Live-Tarife werden dann nicht mehr abgefragt.

Ship-from postcode: die vierstellige australische Postleitzahl, von der die Pakete versendet werden, zum Beispiel 2000.

Domestic service: wird für Sendungen innerhalb Australiens verwendet (bis 22 kg, 105 cm pro Seite): Parcel Post (Standard) oder Express Post.

International service: wird für Sendungen außerhalb Australiens verwendet (bis 20 kg): International Standard (Standard), International Express oder International Courier.

Remove GST: teilt die inländischen API-Preise durch 1,1. Inlandspreise von Australia Post enthalten 10 % GST. Schalten Sie dies ein, wenn OpenCart selbst Steuern auf den Versand aufschlägt (eine Tax class ist gewählt), damit die GST nicht doppelt berechnet wird. Internationales Porto ist GST-frei und wird nie verändert.

AUD → (your currency) rate: das Feld zeigt die Standardwährung Ihres Shops. Die Preise von Australia Post sind in AUD. Ist Ihre Standardwährung nicht AUD, geben Sie ein, wie viele Einheiten Ihrer Währung einem AUD entsprechen, zum Beispiel 0,61. Der Kurs muss größer als 0 sein. Ohne ihn werden Live-Tarife nicht verwendet. Ist Ihre Standardwährung AUD, zeigt das Feld, dass keine Umrechnung nötig ist: Lassen Sie es leer.

Paket für Live-Tarife

Der Warenkorb wird als ein einziges Paket gesendet. Produktgewichte und -abmessungen werden von ihren OpenCart-Gewichts- und Längenklassen in kg bzw. cm umgerechnet. Die folgenden Werte gelten für Produkte ohne Gewicht oder Abmessungen.

Default product weight (kg): wird für jedes Produkt ohne Gewicht verwendet, in der Anfrage an Australia Post und bei der Prüfung von Min cart weight (kg) / Max cart weight (kg). Standard: 1.

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

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

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

Haben Produkte Abmessungen, übernimmt das Paket die größte Länge und Breite unter ihnen, und die Höhe wächst, bis das Paket das Volumen aller Artikel fasst.

Feste Preise (für feste Preise und als Ersatz bei Live-Tarifen)

Country prices: eine Liste von Ländern und Preisen in der Standardwährung Ihres Shops, ohne Steuern. Klicken Sie auf Add row, um eine Zeile hinzuzufügen, und auf die Schaltfläche ×, um eine zu entfernen. Wählen Sie * All other countries für einen Preis, der für jedes Land ohne eigene Zeile gilt. Ein Land ohne Preis (und ohne *-Zeile) erhält keinen festen Tarif, daher wird die Methode für dieses Land ausgeblendet. Zeilen ohne Preis werden beim Speichern entfernt. Die Tabelle ist leer, bis Sie Preise hinzufügen.

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

Bedingungen

Min cart weight (kg): blendet die Methode unterhalb dieses Warenkorbgewichts aus. 0 bedeutet keine Grenze (Standard).

Max cart weight (kg): blendet die Methode oberhalb dieses Warenkorbgewichts aus. Standard: 22. 0 bedeutet keine Grenze, ein leeres Feld bedeutet 22 kg. Pakete von Australia Post: 22 kg national, 20 kg international. Ist Min cart weight (kg) größer als das Maximum, würde die Methode nie angezeigt: Es erscheint eine Warnung, und beide Gewichte behalten ihre vorherigen Werte.

Minimum order amount: zeigt die Methode nur an, wenn die Summe der versandpflichtigen Produkte (nach dem Gutschein, ohne Steuern, in Ihrer Standardwährung) diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.

Free shipping: aktiviert kostenlosen Versand ab dem unten angegebenen Betrag.

Free shipping from: die Summe der versandpflichtigen Produkte (nach dem Gutschein, ohne Steuern), ab der der Versand kostenlos ist. In diesem Fall wird keine API-Anfrage gestellt. Wird nur verwendet, wenn Free shipping aktiviert ist.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Inlandspreise von Australia Post enthalten GST: Bei einer Steuerklasse aktivieren Sie Remove GST.

Geo zone: bietet Australia Post nur für Adressen in dieser Geozone an. All zones (Standard) bedeutet keine Begrenzung. Geozonen verwalten Sie unter System > Localisation > Geo Zones. Wird nicht mit Ignore shipping zones verwendet.

Verfügbarkeit ohne Versandzonen

Normalerweise wird die Methode in der Geozone angeboten, die unter Conditions gewählt ist (All zones bedeutet überall).

Ignore shipping zones: bietet die Methode für die unten genannten Länder an, unabhängig von der Geozone.

Countries: die Zielländer für diesen Modus. Tippen Sie, um zu suchen, und wählen Sie mehrere aus. Lassen Sie das Feld leer, um alle aktivierten Länder des Shops zu erlauben. Wird nur mit Ignore shipping zones verwendet.

Erweitert

Debug log: protokolliert Tarifberechnungen in storage/logs/vfd_ap.log.php. Die Datei ist aus dem Web nicht lesbar. API-Fehler werden immer protokolliert. Der API-Schlüssel und die Postleitzahlen der Kunden werden nicht protokolliert. Schalten Sie das Protokoll aus, wenn Sie fertig sind. Erreicht die Datei 5 MB, wird sie nach vfd_ap.old.log.php verschoben und ein neues Protokoll begonnen.

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

Remove data on uninstall: ist die Option eingeschaltet, löscht das Deinstallieren der Erweiterung die Einstellungen, die zwischengespeicherten Tarife und das Protokoll. Ist sie aus (Standard), bleiben sie für eine erneute Installation erhalten.

Importieren / Exportieren

Exportieren: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Der API-Schlüssel wird nicht exportiert.

Importieren: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen, zum Beispiel in einem anderen Shop. Die Werte werden wie bei einem normalen Speichern geprüft. Der gespeicherte API-Schlüssel bleibt erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Preis von Australia Post. Ist eine Geo zone gesetzt (und Ignore shipping zones ist aus) und liegt die Adresse außerhalb, wird Australia Post nicht angeboten. Mit Ignore shipping zones entscheidet die Liste Countries. Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte fügen kein Gewicht hinzu und sind nicht im Bestellwert enthalten. Danach prüft die Erweiterung das Warenkorbgewicht und den Minimum order amount. Der Bestellwert ist der Preis der versandpflichtigen Produkte nach Abzug des Gutscheinrabatts und vor Steuern. Geschenkgutscheine, Bonuspunkte und Store-Guthaben werden nicht berücksichtigt. Gilt kostenloser Versand, beträgt der Preis 0, und es wird keine Anfrage an Australia Post gesendet.

Im Modus mit festen Preisen wird der Preis aus der Tabelle entnommen. In den Live-Modi sendet die Erweiterung an Australia Post das Paketgewicht und bei Lieferungen innerhalb Australiens die Versand- und Lieferpostleitzahlen sowie die Paketgröße; bei internationalen Lieferungen das Zielland. Ein inländischer Live-Tarif wird nur angefragt, wenn die Lieferadresse eine vierstellige Postleitzahl hat. Ist das Paket über den Grenzen von Australia Post (22 kg oder 105 cm national, 20 kg international), wird keine Anfrage gesendet. Der AUD-Preis wird mit Ihrem Kurs umgerechnet, und die GST wird aus Inlandspreisen herausgerechnet, wenn Remove GST eingeschaltet ist. Der Preis wird in Ihrer Standardwährung berechnet, auf deren Dezimalstellen gerundet und dem Kunden in seiner Währung angezeigt, mit der Steuer der gewählten Tax class.

Jede erfolgreiche Antwort wird 1 Stunde zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf Australia Post warten muss. Das API-Zeitlimit beträgt 10 Sekunden. API-Fehler werden dem Kunden nie angezeigt: Die Methode wird ausgeblendet, oder im Ersatzmodus wird der feste Preis verwendet. Der Grund wird im Protokoll notiert.

Die Erweiterung berechnet nur Tarife. Sie erstellt keine Versandetiketten, eParcel- oder MyPost-Business-Sendungen oder Manifeste, verfolgt keine Pakete und lässt Kunden keine Paketautomaten oder Postfilialen wählen. Sie fügt Bestellungen nichts hinzu: Die Bestellung zeigt den Namen der Methode und die Versandkosten wie bei jeder anderen OpenCart-Versandart. Der Warenkorb wird immer als ein einziges Paket berechnet. Briefe, Versandtaschen und Vertragstarife (eParcel) sind nicht enthalten.

Auf OpenCart 4 klickt der Kunde an der Kasse im Versandart-Block der Kassenseite auf Choose und wählt im Fenster Shipping method options Australia Post aus. Die Methode funktioniert genauso wie unter OpenCart 3.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Australia Post ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Australia Post > Edit, oberhalb der Einstellungen. Fügen 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 zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-shipping-australia-post und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Administratoren mit der Berechtigung zum Ändern der Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (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. 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 die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel gilt für eine Domain: die Shop-Adresse aus der OpenCart-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 aktiven Schlüssel wird Australia Post Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Ein Administrator, der im Admin-Bereich im selben Browser angemeldet ist, sieht die Methode im Shop weiterhin, markiert als (unlicensed — visible to admins only), sodass Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. Unter OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard des Admin-Bereichs. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen bleiben unberührt.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, aber Updates und Support benötigen eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard des Admin-Bereichs oder die Seite Edit öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Beim Deinstallieren der Erweiterung werden Lizenzschlüssel und Lizenzstatus immer entfernt.

Fehlerbehebung

Australia Post erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable Australia Post eingeschaltet ist. Prüfen Sie Geo zone (oder Ignore shipping zones und Countries), die Gewichtsgrenzen des Warenkorbs und Minimum order amount. Prüfen Sie im Modus mit festen Preisen, ob das Land oder * All other countries einen Preis hat. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Live-Tarife erscheinen nicht: schalten Sie das Debug log ein, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Erweiterungsseite an. Es zeigt den Grund: fehlender API-Schlüssel oder Versand-Postleitzahl, noch keine vierstellige Lieferpostleitzahl, ein Paket über den Grenzen, kein AUD-Umrechnungskurs oder die Fehlermeldung von Australia Post. Mit Live rates, fixed price if the API gives no rate erhalten Kunden weiterhin den festen Preis, während Sie das Problem beheben.

Mein Shop ist nicht in AUD: geben Sie den Umrechnungskurs (wie viele Einheiten Ihrer Standardwährung einem AUD entsprechen) im Feld AUD → (your currency) rate ein. Feste Preise sind immer in Ihrer Standardwährung.

GST wird beim Versand doppelt berechnet: Inlandspreise von Australia Post enthalten 10 % GST. Ist eine Tax class gewählt, schalten Sie Remove GST ein oder setzen Sie Tax class auf No tax.

Der Preis ist zu hoch oder zu niedrig: prüfen Sie die Produktgewichte und -abmessungen, deren Gewichts- und Längenklassen sowie die Standardwerte unter Parcel for live rates. Bei Item (price × quantity) werden feste Preise mit der Anzahl der Artikel multipliziert.

Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Erweiterungsseite auf Save. Dadurch werden die zwischengespeicherten Australia-Post-Tarife gelöscht.

Die Seite meldet "Warning: You do not have permission to modify VibeFox Australia Post!": Ihre Admin-Benutzergruppe darf die Einstellungen möglicherweise nur ansehen. Geben Sie der Gruppe die Bearbeitungsberechtigung für extension/shipping/vfd_australia_post (OpenCart 3) oder extension/vfd_australia_post/shipping/vfd_australia_post (OpenCart 4) unter System > Users > User Groups.

Für Entwickler: die PAC-API-Adresse kann mit der Einstellung vfd_ap_api_url (für Tests) ersetzt werden; sie hat kein Feld auf der Einstellungsseite.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Australia Post auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt Enable Australia Post, Sort order, Tax class und Geo zone immer zurück. Die zwischengespeicherten Tarife werden immer entfernt. Ist Remove data on uninstall eingeschaltet, werden außerdem die Einstellungen von Australia Post und das Protokoll gelöscht. Ist es aus, bleiben die übrigen Einstellungen erhalten und werden bei einer erneuten Installation wieder verwendet. Bestehende Bestellungen behalten ihre Versandart und Kosten.

Auf OpenCart 4 entfernen Sie die Dateien der Erweiterung ebenfalls, indem Sie nach der Deinstallation zu Extensions > Installer gehen, in der Liste der installierten Erweiterungen neben VibeFox Australia Post auf Uninstall (die orange −-Schaltfläche) klicken und danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Australia Post ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist weder mit Australia Post verbunden noch von Australia Post unterstützt.