VibeFox SF Express for OpenCart — Hilfe

Voraussetzungen

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.

SF-Express-Konto (nur für Live-Preise): Live-Preise nutzen die offene FengQiao-Plattform von SF Express (open.sf-express.com). Sie benötigen ein monatliches SF-Express-Konto und ein Entwicklerkonto bei FengQiao. Registrieren Sie sich dort, legen Sie eine Anwendung an, fügen Sie die API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) hinzu und kopieren Sie den Kundencode und das Checkword. Die Checkwords für Sandbox und Produktion unterscheiden sich. Wenn Sie nur die Preistabelle nutzen, brauchen Sie kein SF-Express-Konto.

Chinesische Provinzen (nur für Live-Preise): der Live-Preis benötigt die Provinz der Lieferadresse, also die OpenCart-Zone (Region / State) der Adresse. OpenCart enthält die Zonen Chinas, aber Tibet fehlt. Die Erweiterung kann sie für Sie hinzufügen (siehe unten Chinese provinces).

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.

Installation

Die Download-Datei ist ein einziges ZIP-Archiv mit den Paketen für beide OpenCart-Versionen. Entpacken Sie es auf Ihrem Computer. Es enthält README.txt, das Paket für OpenCart 3 vfd_sf_express-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_sf_express.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 zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_sf_express-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Modifikationen hinzu, Sie müssen also Extensions > Modifications nicht aktualisieren. Statt des Installers können Sie den Inhalt des Ordners upload aus dem Paket in das Hauptverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox SF Express 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. Geben 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. Füllen Sie die Preistabelle und/oder die Ersatzkosten aus.

6. Für Live-Preise auf dem chinesischen Festland geben Sie den Kundencode und das Checkword, die Versandprovinz und -stadt sowie, falls die Standardwährung Ihres Shops nicht CNY ist, den Währungsumrechnungskurs ein. Klicken Sie auf Add Chinese provinces, falls die Seite dies verlangt. Testen Sie zuerst mit Sandbox und Sandbox-Zugangsdaten.

7. Aktivieren Sie Enable SF Express und klicken Sie auf Save.

OpenCart 4

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_sf_express.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 SF Express, 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 bis 7 für OpenCart 3 ein. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich.

Nach der Installation ist die Methode deaktiviert, bis Sie Enable SF Express aktivieren und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die von Ihnen beibehaltenen SF-Express-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. Die Abschnitte stehen links. Sie gelten für alle Geo-Zonen. Eine Schaltfläche Save unten speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht auch die zwischengespeicherten SF-Express-Preise. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Beim Speichern prüft die Erweiterung die Werte. Ein leerer Methodentitel, ein Titel mit mehr als 64 Zeichen oder mit den Zeichen < > ; = # { }, ein Wert, der keine Zahl ist, ein negativer Betrag oder ein negatives Gewicht, ein Umrechnungskurs von 0, ein Min weight (kg), der über Max weight (kg) liegt, ein falscher Preis in der Preistabelle oder eine Sortierreihenfolge, die keine ganze Zahl ist, wird mit einer Meldung abgelehnt, und nichts wird gespeichert, bis Sie es korrigieren. Warnungen über den Einstellungen zeigen an, wenn Live-Preise nur teilweise eingerichtet sind (die fehlenden Einstellungen werden aufgelistet), wenn der Umrechnungskurs fehlt, wenn der Shop keine Zonen Chinas hat oder wenn Ihr Shop keine Gewichtsklasse in kg oder Längenklasse in cm hat und seine Standardeinheit der Erweiterung nicht bekannt ist.

Allgemein

Enable SF Express: blendet SF Express an der Kasse ein oder aus. Standard: aus.

Method title: der Name der Methode, der im Warenkorb und an der Kasse angezeigt wird. Standard: SF Express. Pflichtfeld, höchstens 64 Zeichen.

Tax class: die Steuerklasse der Versandkosten oder No tax. Mit einer Steuerklasse wird die Versandsteuer Ihres Shops auf die Kosten aufgeschlagen. Wählen Sie No tax, wenn der SF-Express-Preis bereits alles enthält, was Sie berechnen möchten.

Sort order: die Position von SF Express unter den Versandmethoden an der Kasse. Eine ganze Zahl.

SF Express FengQiao API (Live-Preise) (optional, für Lieferadressen auf dem chinesischen Festland)

Customer code (partnerID): der Kundencode (顾客编码) Ihrer FengQiao-Anwendung. Wenn Sie ihn löschen, wird auch das gespeicherte Checkword gelöscht, sodass Sie die Zugangsdaten entfernen können.

Checkword: das Checkword (校验码) derselben Umgebung. Es dient nur zum Signieren von Anfragen und wird nie gesendet oder protokolliert. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. Geben Sie nur einen neuen Wert ein, wenn Sie ihn ändern möchten.

Sandbox: nutzt die FengQiao-Sandbox (sfapi-sbox.sf-express.com) zum Testen mit Sandbox-Zugangsdaten. Sandbox-Preise sind nicht echt. Schalten Sie sie in einem Live-Shop aus. Standard: aus.

SF Express product: welches SF-Express-Produkt zum Preis angezeigt wird.

Sender province: die Provinz, aus der die Pakete versendet werden, zum Beispiel Guangdong / 广东. Die erste Option nutzt die Region Ihres Shops (System > Settings > Store > Local), wenn der Shop in China ist. Dann steht dort Same as the store region mit dem Provinznamen, sonst — Select —.

Sender city: der standardisierte chinesische Stadtname, zum Beispiel 深圳市. Für Live-Preise erforderlich: Die Shopadresse in OpenCart ist Freitext, daher wird die Stadt nie daraus übernommen.

Currency conversion rate: SF-Express-Preise sind in CNY (Yuan). Wenn die Standardwährung Ihres Shops nicht CNY ist, geben Sie ein, wie viele Einheiten Ihrer Währung ein CNY wert ist (1 CNY = ? Einheiten), zum Beispiel 0.13. Ohne diesen Wert werden keine Live-Preise verwendet. Wenn die Shopwährung CNY ist, zeigt das Feld an, dass er nicht nötig ist, und die Preise werden unverändert verwendet. Sowohl Punkt als auch Komma werden als Dezimaltrennzeichen akzeptiert.

Chinese provinces: zeigt, wie viele der 32 Provinzen, autonomen Regionen und regierungsunmittelbaren Städte von SF Express in OpenCart als Zonen Chinas vorhanden sind und welche fehlen. Adressen in einer fehlenden Provinz erhalten den Tabellenpreis. Klicken Sie auf Add Chinese provinces, um nur die fehlenden als Zonen Chinas hinzuzufügen (ISO-Code, ein Name wie "Tibet / 西藏"). Bestehende Zonen werden nicht geändert. Ohne diesen Klick wird nichts geändert. So hinzugefügte Zonen bleiben nach einer Deinstallation im Shop erhalten.

Preistabelle und Ersatzpreis (verwendet für Hongkong, Macau, Taiwan und andere Länder, wenn Live-Preise nicht eingerichtet sind oder SF Express keinen Preis liefert; Preise in der Standardwährung Ihres Shops, ohne Steuer)

Country prices: eine Tabelle mit einem Grundpreis pro Land. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Entfernen-Schaltfläche, um eine zu löschen. Die Zeile * All other countries gilt für alle Länder ohne eigene Zeile. Ein Gewichtsstufenpreis über 0 ersetzt den Grundpreis für Pakete in dieser Stufe: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg und XL über 5 kg. Ein Base-Preis von 0 bedeutet kostenlosen Versand. Ein leerer Grundpreis bedeutet, dass es für dieses Land keinen Preis gibt und die Ersatzkosten verwendet werden. Sowohl "9.99" als auch "9,99" werden akzeptiert. Eine Zeile ohne Preis wird nicht gespeichert.

Fallback cost: wird verwendet, wenn weder SF Express noch die Tabelle einen Preis liefern. Lassen Sie das Feld leer, um die Methode in diesem Fall auszublenden.

Table / fallback price is: wie Tabellen- und Ersatzpreise berechnet werden.

Live-Preise von SF Express gelten immer für die gesamte Bestellung.

Bedingungen

Free shipping from: die Zwischensumme des Warenkorbs (Produkte, die versendet werden müssen, nach dem Gutschein, vor Steuern), ab der der Versand kostenlos ist. Lassen Sie das Feld leer, um nie kostenlosen Versand anzubieten. Der kostenlose Versand wird vor jeder Preisabfrage geprüft, sodass die Methode ab diesem Betrag für jedes verfügbare Ziel kostenlos angeboten wird, auch für ein Land ohne Tabellenzeile oder ohne Fallback cost.

Minimum subtotal: die Methode nur anzeigen, wenn die Zwischensumme des Warenkorbs diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.

Min weight (kg): das minimale Warenkorbgewicht in kg. Produktgewichte werden aus ihrer Gewichtsklasse umgerechnet. 0 bedeutet keine Grenze.

Max weight (kg): das maximale Warenkorbgewicht in kg. Standard: 50. 0 oder leer bedeutet keine Grenze.

Geo zone: SF Express nur für Adressen in dieser Geo-Zone anbieten. All zones (Standard) bedeutet keine Einschränkung. Geo-Zonen werden unter System > Localisation > Geo Zones verwaltet. Sie wird nicht geprüft, wenn Ignore shipping zones aktiviert ist.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: SF Express für die unten genannten Länder anbieten, unabhängig von der Geo-Zone. Ist die Option aus, entscheidet die Geo-Zone, und die Länderliste wird nicht verwendet.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle aktivierten Länder zu erlauben. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Erweitert

Debug log: schreibt Preisberechnungen in storage/logs/vfd_sfex_debug.log.php. Die Datei kann nicht über das Web gelesen werden. API-Fehler werden immer protokolliert, auch wenn diese Option aus ist. Checkword oder Kundenadressen werden nicht geschrieben. Erreicht die Datei 5 MB, wird sie nach vfd_sfex_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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: wenn aktiviert, löscht die Deinstallation der Erweiterung die Einstellungen und das Protokoll. Ist die Option aus (Standard), bleiben die Einstellungen für eine erneute Installation erhalten. Zwischengespeicherte Preise werden immer gelöscht.

Import / Export

Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern, ohne das Checkword.

Import: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Die Werte werden wie beim normalen Speichern geprüft. Das gespeicherte Checkword bleibt erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandmethoden anzeigt, fragt es die Erweiterung nach dem SF-Express-Preis. Ist eine Geo zone gesetzt und die Adresse liegt außerhalb, wird SF Express nicht angeboten (außer Ignore shipping zones ist aktiviert). Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte haben kein Gewicht und sind nicht in der Zwischensumme enthalten. Die Zwischensumme ist der Preis dieser Produkte nach dem Gutscheinrabatt und vor Steuern. Geschenkgutscheine, Bonuspunkte und Shopguthaben werden nicht berücksichtigt. Die Erweiterung prüft dann die Bedingungen: erlaubte Länder (mit Ignore shipping zones), Warenkorbgewicht und Mindestzwischensumme. Erreicht die Zwischensumme Free shipping from, beträgt der Preis 0 und es wird keine Anfrage an SF Express gesendet.

Für eine Lieferadresse auf dem chinesischen Festland mit gesetztem Kundencode und Checkword sendet die Erweiterung an SF Express Ihre Versandprovinz und -stadt, die Provinz und Stadt des Kunden, das Warenkorbgewicht (mindestens 0,1 kg) und das Warenkorbvolumen (aus Produkten mit allen drei Maßen). Die Anfrage wird mit Ihrem Checkword signiert. SF Express liefert Preise in CNY; die Erweiterung rechnet den gewählten Preis in die Standardwährung Ihres Shops um und rundet ihn auf die Dezimalstellen. Der Preis wird dann in der Währung des Kunden mit der Steuer der gewählten Tax class angezeigt.

SF Express erkennt Adressen anhand der standardisierten chinesischen Namen. Die Provinz des Kunden stammt aus der Zone Region / State der Adresse und wird über ihren Namen zugeordnet. Die Zone "Hong Kong" ist keine Provinz des Festlands und erhält den Tabellenpreis. Die Stadt muss auf Chinesisch geschrieben sein, zum Beispiel 广州市. Für Peking, Shanghai, Tianjin und Chongqing wird die Stadt automatisch eingetragen. Eine Stadt in lateinischen Buchstaben, etwa "Guangzhou", erhält den Tabellenpreis.

Jeder Preis wird eine Stunde lang zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 10 Minuten lang zwischengespeichert, damit der Checkout bei jeder Aktualisierung nicht auf SF Express wartet. Das HTTP-Timeout beträgt 10 Sekunden.

Wenn kein Live-Preis vorliegt, stammt der Preis aus der Preistabelle und danach aus den Fallback cost. Trifft keines davon zu, wird die Methode ausgeblendet. Der Kunde sieht nie einen Fehler. Der Fehler wird im Protokoll festgehalten.

Die Erweiterung berechnet nur Preise. Sie erstellt keine Frachtbriefe oder Etiketten, legt keine Bestellungen bei SF Express an, bucht keine Abholungen und storniert oder verfolgt keine Sendungen. Erstellen und verfolgen Sie Sendungen wie gewohnt in Ihrem SF-Express-Konto. Kunden können keine SF-Servicestelle oder kein Schließfach wählen. SF Express wird als Haustürkurier genutzt. Live-Preise gibt es nur für Lieferadressen auf dem chinesischen Festland. Die Erweiterung wurde anhand der FengQiao-Dokumentation und simulierter Antworten entwickelt. Bestätigen Sie daher die Preise mit Ihrem SF-Express-Konto (zuerst in der Sandbox), bevor Sie live gehen.

In OpenCart 4 klickt der Kunde in der Versandart-Auswahl der Kasse auf Choose und wählt im Fenster Shipping method options SF Express aus. Dort wird der Name der Methode mit dem Preis angezeigt. Die Methode funktioniert genauso wie in OpenCart 3.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox SF Express ist der erste Block auf Extensions > Extensions > Shipping > VibeFox SF Express > 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 zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-shipping-sf-express und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung Modify für die 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, zeigt der Block den Grund an, 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 funktioniert für eine Domain: die Shop-Adresse aus der OpenCart-Konfiguration. Wenn Sie den Schlüssel aus dem Shop entfernen, wird sein Domain-Platz dadurch nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird die SF-Express-Versandmethode Kunden an der Kasse nicht angezeigt, und es wird kein Preis berechnet. Ein Admin-Benutzer, der im Admin im selben Browser angemeldet ist, sieht die Methode weiterhin im Shop, markiert mit (unlicensed — visible to admins only). So können Sie die Erweiterung einrichten und testen, bevor Sie einen Schlüssel kaufen. In OpenCart 4 gibt es diese Vorschau nicht: Der Shop sieht die Admin-Anmeldung nicht, daher ist die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint eine Erinnerung auf dem Admin-Dashboard. Schließen Sie sie mit ×, um sie für 7 Tage auszublenden. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, aber Updates und Support brauchen eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Admin-Dashboard oder die Seite Edit öffnen: 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. Die Deinstallation der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

SF Express erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv und Enable SF Express eingeschaltet ist. Prüfen Sie Geo zone oder aktivieren Sie Ignore shipping zones und prüfen Sie Countries. Prüfen Sie die Gewichtsgrenzen und Minimum subtotal. Prüfen Sie, ob die Tabelle oder die Fallback cost für das Land einen Preis hat. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Der Preis stammt aus der Tabelle, nicht von SF Express: Live-Preise benötigen Kundencode und Checkword, eine Versandprovinz und -stadt, eine Lieferadresse auf dem chinesischen Festland mit Provinz und chinesischem Stadtnamen sowie (bei Shops mit anderer Währung als CNY) den Währungsumrechnungskurs. Lesen Sie die Warnungen oben auf der Erweiterungsseite, aktivieren Sie dann das Debug log, laden Sie die Kasse neu und prüfen Sie das Feld Log, um den Grund zu sehen. Eine fehlgeschlagene Anfrage wird nach 10 Minuten erneut versucht.

Das Protokoll zeigt einen Signaturfehler: das Checkword ist falsch oder gehört zur anderen Umgebung. Prüfen Sie die Einstellung Sandbox. Wenn SF Express meldet, dass die API nicht erlaubt ist, fügen Sie der FengQiao-Anwendung die Preisabfrage-API hinzu.

Adressen in Tibet erhalten den Tabellenpreis: klicken Sie auf Add Chinese provinces im API-Bereich der Erweiterungsseite.

Hongkong: funktioniert mit der Preistabelle und den Ersatzkosten. Die FengQiao-Preisabfrage gilt für Adressen auf dem chinesischen Festland.

Preise wirken nach einer Änderung veraltet: klicken Sie auf der Erweiterungsseite auf Save. Das löscht die zwischengespeicherten SF-Express-Preise.

Die Seite zeigt "Warning: You do not have permission to modify VibeFox SF Express!": Ihre Admin-Benutzergruppe darf die Einstellungen nur ansehen. Geben Sie der Gruppe die Berechtigung zum Ändern für extension/shipping/vfd_sf_express (OpenCart 3) bzw. extension/vfd_sf_express/shipping/vfd_sf_express (OpenCart 4) unter System > Users > User Groups.

Für Entwickler: die OpenCart-Ereignisse vfd_sf_express/quote_request und vfd_sf_express/api_url erlauben einer anderen Erweiterung, die Preisanfrage (zum Beispiel an einen anderen Produktcode) und die Gateway-URL zu ändern.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox SF Express auf Uninstall (die rote −-Schaltfläche). Lizenzschlüssel und Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable SF Express, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Preise werden immer entfernt. Ist Remove data on uninstall aktiviert, werden auch die übrigen Einstellungen und das Protokoll gelöscht. Ist die Option aus, bleiben sie erhalten und werden bei einer erneuten Installation wieder verwendet. Mit Add Chinese provinces hinzugefügte chinesische Zonen bleiben bestehen. Bestehende Bestellungen behalten ihre Versandmethode und ihre Kosten.

Um in OpenCart 4 auch die Dateien der Erweiterung zu entfernen, gehen Sie nach der Deinstallation zu Extensions > Installer und klicken Sie in der Liste der installierten Erweiterungen neben VibeFox SF Express auf Uninstall (die orange −-Schaltfläche) und dann auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

SF Express ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist weder mit SF Express verbunden noch wird sie von SF Express unterstützt.