VibeFox SF Express 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.

SF-Express-Konto (nur für Live-Preise): Live-Preise nutzen die FengQiao-Open-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 ihr 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 verwenden, benötigen Sie kein SF-Express-Konto.

Chinesische Provinzen (nur für Live-Preise): der Live-Preis benötigt die Provinz der Lieferadresse. PrestaShop enthält standardmäßig keine chinesischen Provinzen. Das Modul kann sie für Sie hinzufügen (siehe unten Chinese provinces).

VibeFox-Lizenzschlüssel: erhältlich 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox SF Express in der Modulliste und klicken Sie auf Configure.

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

4. Füllen Sie die Preistabelle und/oder den Ersatzpreis aus und klicken Sie auf Save.

5. Für Live-Preise auf dem chinesischen Festland geben Sie den Kundencode und das Checkword, die Absenderprovinz und -stadt (oder legen Sie eine chinesische Shop-Adresse fest) und, falls die Währung Ihres Shops nicht CNY ist, den Währungsumrechnungskurs ein. Klicken Sie auf Add Chinese provinces, wenn die Seite dazu auffordert. Testen Sie zuerst mit Sandbox und Sandbox-Zugangsdaten.

Bei der Installation legt das Modul den Versanddienstleister SF Express mit dem Liefertext Courier delivery an. Der Versanddienstleister 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 kommt immer vom Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox SF Express > Configure. Sie gelten für alle Zonen des Versanddienstleisters. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten SF-Express-Preise.

Beim Speichern prüft das Modul die Zahlen. Ein Wert, der keine Zahl ist, ein negativer Betrag oder ein negatives Gewicht, ein Währungsumrechnungskurs von 0, ein Min weight über Max weight oder ein falscher Preis in der Preistabelle wird mit einer Meldung abgelehnt, und nichts wird gespeichert, bis Sie ihn korrigieren. Warnungen über den Einstellungen zeigen an, wenn die Live-Preise nur teilweise eingerichtet sind (die fehlenden Einstellungen werden aufgelistet), wenn der Währungsumrechnungskurs fehlt, wenn chinesische Adressen kein Provinzfeld haben oder wenn die Gewichts- oder Maßeinheit Ihres Shops dem Modul nicht bekannt ist. Die Einheiten werden unter International > Localization (Local units) eingestellt.

Allgemein

Enable SF Express: schaltet den Versanddienstleister ein oder aus. Das ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Method title: der Name des Versanddienstleisters, der im Warenkorb und an der Kasse angezeigt wird. Standard: SF Express. Pflichtfeld, maximal 64 Zeichen.

Tax: die Steuerregel des Versanddienstleisters oder No tax. Mit einer Steuerregel 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.

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 leeren, wird auch das gespeicherte Checkword gelöscht, sodass Sie die Zugangsdaten entfernen können.

Checkword: das Checkword (校验码) derselben Umgebung. Es wird nur zum Signieren von Anfragen verwendet und nie gesendet oder protokolliert. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. Geben Sie einen neuen Wert nur 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. In einem Live-Shop ausschalten. Standard: aus.

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

Sender province: die Provinz, aus der die Pakete versendet werden. Leer lassen, um die Provinz der Shop-Adresse unter Shop Parameters > Contact > Stores zu verwenden, wenn der Shop in China liegt.

Sender city: der standardisierte chinesische Stadtname, zum Beispiel 深圳市. Leer lassen, um die Stadt des Shops zu verwenden, wenn der Shop in China liegt.

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). Ohne diesen Wert werden keine Live-Preise verwendet. Wenn die Währung Ihres Shops CNY ist, werden die Preise unverändert übernommen. Sowohl Punkt als auch Komma werden als Dezimaltrennzeichen akzeptiert.

Chinese provinces: zeigt an, ob chinesische Adressen eine Provinz haben können. Wenn nicht, klicken Sie auf Add Chinese provinces. Die Schaltfläche fügt die 32 Provinzen, autonomen Regionen und Gemeinden als Bundesländer von China hinzu (ISO-Codes wie GD und BJ, Namen wie „Guangdong / 广东“), aktiviert „Contains states“ für China und fügt das Bundeslandfeld dem chinesischen Adressformular hinzu. Bereits vorhandene Provinzen werden nicht erneut hinzugefügt. Ohne diesen Klick wird nichts verändert.

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

Country prices: eine Tabelle mit einem Grundpreis pro Land. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorb-Symbol, um eine zu entfernen. 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 ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg und XL >5 kg. Ein Grundpreis von 0 bedeutet kostenlosen Versand. Ein leerer Grundpreis bedeutet, dass es für dieses Land keinen Preis gibt und der Ersatzpreis verwendet wird. „9.99“ und „9,99“ werden beide akzeptiert. Eine Zeile ohne Preis wird nicht gespeichert.

Fallback cost: wird verwendet, wenn weder SF Express noch die Tabelle einen Preis liefern. Leer lassen, um den Versanddienstleister in diesem Fall auszublenden.

Table / fallback price is: wie die Preise aus der Tabelle und der Ersatzpreis berechnet werden.

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

Bedingungen

Free shipping from: die Warenkorb-Zwischensumme (nach Rabatten, vor Steuern), ab der der Versand kostenlos ist. Leer lassen, um nie kostenlosen Versand anzubieten. Der kostenlose Versand wird geprüft, bevor ein Preis ermittelt wird. Ab diesem Betrag wird der Versanddienstleister daher für jedes Ziel kostenlos angeboten, für das er verfügbar ist, auch für ein Land ohne Tabellenzeile oder ohne Fallback cost.

Minimum subtotal: zeigt den Versanddienstleister nur, wenn die Warenkorb-Zwischensumme (nach Rabatten, vor Steuern) diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.

Min weight: das minimale Warenkorbgewicht in kg. Produktgewichte werden aus Ihrer Gewichtseinheit umgerechnet. 0 bedeutet keine Grenze.

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

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet SF Express für die unten angegebenen Länder an, unabhängig davon, welche Zone passt. Beim Speichern wird der Versanddienstleister allen Zonen hinzugefügt, und später erstellte Zonen werden ebenfalls hinzugefügt. Wenn Sie die Option ausschalten, werden die hinzugefügten Zonen wieder entfernt. Ist sie ausgeschaltet, erscheint der Versanddienstleister nur in seinen eigenen Zonen.

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

Erweitert

Debug log: schreibt die Preisberechnungen in logs/vfd_sfex_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Es werden weder das Checkword noch Kundenadressen geschrieben.

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 eingeschaltet, löscht die Deinstallation des Moduls die Einstellungen, den Versanddienstleister, die zwischengespeicherten Preise und die Protokolle. Wenn ausgeschaltet, bleibt alles für eine erneute Installation erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem SF-Express-Preis. Nur physische Produkte zählen: Virtuelle Produkte erhöhen das Gewicht nicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft zuerst 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 das Modul an SF Express Ihre Absenderprovinz und -stadt, die Provinz und Stadt des Kunden, das Warenkorbgewicht und das Warenkorbvolumen (aus Produkten mit allen drei Maßen). Die Anfrage wird mit Ihrem Checkword signiert. SF Express liefert Preise in CNY, und das Modul rechnet den gewählten in die Standardwährung Ihres Shops um. Der Preis wird dann in der Warenkorbwährung des Kunden angezeigt.

SF Express erkennt Adressen anhand standardisierter chinesischer Namen. Die Provinz des Kunden stammt aus dem Bundeslandfeld der Adresse. Die Stadt muss auf Chinesisch geschrieben sein, zum Beispiel 广州市. Für Beijing, Shanghai, Tianjin und Chongqing wird die Stadt automatisch ausgefüllt. Eine Stadt in lateinischen Buchstaben, etwa „Guangzhou“, erhält den Tabellenpreis.

Jeder Preis wird eine Stunde lang zwischengespeichert, sodass derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird zehn Minuten lang zwischengespeichert, damit die Kasse 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 Fallback cost. Wenn keines zutrifft, wird der Versanddienstleister ausgeblendet. Der Kunde sieht nie einen Fehler. Der Fehler wird im Protokoll festgehalten.

Wenn Sie den Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul übernimmt die neue Version automatisch.

Das Modul berechnet nur Preise. Es 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 und keinen Paketautomaten wählen. SF Express wird als Haus-zu-Haus-Kurier genutzt. Live-Preise gibt es nur für Lieferadressen auf dem chinesischen Festland. Das Modul wurde anhand der FengQiao-Dokumentation und simulierter Antworten entwickelt. Bestätigen Sie die Preise daher mit Ihrem SF-Express-Konto (zuerst Sandbox), bevor Sie live gehen.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox SF Express ist der erste Block auf Modules > Module Manager > VibeFox SF Express > Configure, 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, 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-sf-express 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 Blocks folgen der Sprache des Back Office (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 das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-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 der Versanddienstleister SF Express Kunden an der Kasse nicht angezeigt und es wird kein Preis berechnet. Das PrestaShop-Frontend weiß nicht, dass Sie im Back Office angemeldet sind, daher wird der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse testen. Ein Hinweis erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während Ihrer 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 wird nicht benötigt. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

SF Express erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable SF Express eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe des Kunden abdeckt (oder schalten Sie Ignore shipping zones ein und prüfen Sie Countries). Prüfen Sie die Gewichtsgrenzen und die Minimum subtotal. Prüfen Sie, ob die Tabelle oder der Fallback cost einen Preis für das Land hat. Produkte können auf der Produktseite auch auf bestimmte Versanddienstleister beschränkt sein.

Der Preis stammt aus der Tabelle, nicht von SF Express: Live-Preise benötigen Kundencode und Checkword, eine Absenderprovinz und -stadt, eine Lieferadresse auf dem chinesischen Festland mit Provinz und einem chinesischen Stadtnamen sowie (bei nicht-CNY-Shops) den Währungsumrechnungskurs. Lesen Sie die Warnungen oben auf der Modulseite, schalten Sie dann Debug log ein, laden Sie die Kasse neu und sehen Sie im Feld Log nach dem Grund. Eine fehlgeschlagene Anfrage wird nach 10 Minuten wiederholt.

Das Adressformular für China hat keine Provinz: Klicken Sie im API-Bereich der Modulseite auf Add Chinese provinces.

Fehler A1006 im Protokoll: ungültige Signatur. Das Checkword ist falsch oder gehört zur anderen Umgebung. Prüfen Sie die Einstellung Sandbox.

Fehler A1004 im Protokoll: die Preisabfrage-API ist Ihrer FengQiao-Anwendung nicht hinzugefügt.

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

Preise wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten SF-Express-Preise gelöscht.

Die Seite meldet, dass der Versanddienstleister SF Express nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn neu anzulegen.

Für Entwickler: der Hook actionVfdSfExpressQuoteRequest ändert die Preisanfrage, zum Beispiel auf einen anderen Produktcode. actionVfdSfExpressApiUrl ändert die Gateway-URL.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox SF Express und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Preise werden immer entfernt. Wenn Remove data on uninstall eingeschaltet ist, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen und das Protokoll werden entfernt. Ist die Option ausgeschaltet, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Eine erneute Installation des Moduls oder ein Reset gibt dem Versanddienstleister den Status zurück, den er vorher hatte. Bestehende Bestellungen behalten ihre Versandzeilen.

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