VibeFox J&T 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.

Zugang zur J&T Express Malaysia API (nur für Live-Preise): Live-Preise gibt es nur für J&T Express Malaysia, für Lieferadressen in Malaysia. Sie benötigen vier Werte. Beantragen Sie ein J&T-VIP-Konto auf der Website von J&T Express Malaysia (die Modulseite enthält einen Link): J&T stellt Ihnen den VIP-Kundencode und den VIP-API-Schlüssel bereit. Das API-Konto und den privaten Schlüssel zum Signieren der Anfragen stellt J&T für die API-Integration aus. Fragen Sie Ihren J&T-Kundenbetreuer danach. J&T Philippinen, Indonesien und andere Länder haben keine öffentliche Preis-API, verwenden Sie dort daher die Preistabelle. Wenn Sie nur die Preistabelle und die Ersatzkosten nutzen, benötigen Sie keinen Zugang zur J&T-API.

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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox J&T Express in der Modulliste und klicken Sie auf Configure.

3. Fügen 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 die Ersatzkosten aus. Für Live-Preise in Malaysia geben Sie außerdem die J&T-API-Zugangsdaten, die Absender-Postleitzahl und, falls die Standardwährung Ihres Shops nicht MYR ist, den Umrechnungskurs ein (siehe Konfiguration). Klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienstleister J&T Express mit dem Liefertext Courier delivery an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugeordnet. 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 J&T Express > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten J&T-Preise. Sind die Live-Preise nur teilweise konfiguriert, zeigt eine Warnung oben auf der Seite die fehlenden Einstellungen an oder weist darauf hin, dass der Umrechnungskurs fehlt. Beträge, die keine Zahl größer oder gleich 0 sind, werden mit einem Fehler abgelehnt, ebenso ein Currency conversion rate von 0 und ein Min weight, der größer als Max weight ist. Wird die Gewichtseinheit Ihres Shops nicht erkannt, fordert eine Warnung Sie auf, unter International > Localization eine Standardeinheit festzulegen.

Allgemein

Die Einstellungen auf dieser Seite gelten für alle Zonen. Zonen, Kundengruppen und Größenbeschränkungen des Versanddienstleisters werden unter Shipping > Carriers festgelegt (oder verwenden Sie unten Ignore shipping zones).

Enable J&T Express: schaltet den Versanddienstleister ein oder aus. Dies 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: J&T Express. Pflichtfeld.

Tax: die Steuerregel des Versanddienstleisters oder No tax. Eine Steuerregel fügt die Versandsteuer Ihres Shops auf die Kosten hinzu. Wählen Sie No tax, wenn der J&T-Preis bereits alles enthält, was Sie berechnen möchten.

J&T Express Malaysia API (Live-Preise) (optional, für Lieferadressen in Malaysia; alle vier Zugangsdaten sind erforderlich)

VIP customer code: Ihr J&T-Express-VIP-Code. Wenn Sie ihn leeren, wird auch der gespeicherte VIP-API-Schlüssel gelöscht.

VIP API key: der API-Schlüssel (Passwort), den J&T Express Ihnen zusammen mit dem VIP-Code gegeben hat. Er wird nie protokolliert. 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.

API account: der Name Ihres J&T-Express-API-Kontos. Wenn Sie ihn leeren, wird auch der gespeicherte private Schlüssel gelöscht.

API private key: der private Schlüssel des API-Kontos. Er wird nur zum Signieren der Anfragen (SHA-256) verwendet. Er wird nie an J&T gesendet und nie protokolliert. Wie der VIP-API-Schlüssel wird er nach dem Speichern nicht mehr angezeigt.

Sender postcode: die malaysische Postleitzahl, von der die Pakete versendet werden. Lassen Sie das Feld leer, um die Shop-Postleitzahl aus Shop Parameters > Contact > Stores zu verwenden, sofern der Shop in Malaysia liegt. Leerzeichen werden beim Speichern entfernt.

Currency conversion rate: J&T-Express-Malaysia-Preise sind in MYR angegeben. Ist die Standardwährung Ihres Shops nicht MYR, geben Sie ein, wie viele Einheiten Ihrer Währung ein MYR wert ist (1 MYR = X). Ohne diesen Wert werden keine Live-Preise verwendet; stattdessen gelten die Preistabelle oder die Ersatzkosten. Ist Ihre Standardwährung MYR, zeigt das Feld dies an und der Kurs ist nicht nötig: Die Preise werden unverändert übernommen. Sowohl Punkt als auch Komma werden als Dezimaltrennzeichen akzeptiert. Der Kurs muss größer als 0 sein.

Preistabelle und Ersatz (verwendet für andere Länder als Malaysia, wenn Live-Preise nicht konfiguriert sind oder J&T keinen Preis liefert; Preise in der Standardwährung Ihres Shops, ohne Steuer)

Country prices: eine Tabelle mit einer Zeile pro Land. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorbsymbol, um eine zu entfernen. Wählen Sie * Any other country für alle Länder ohne eigene Zeile. Jede Zeile hat einen Base price und fünf Gewichtsstufen: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg und XL über 5 kg. Ein Stufenpreis über 0 ersetzt den Grundpreis für Warenkörbe in dieser Stufe. Eine Stufe mit 0 verwendet den Grundpreis. Ein Grundpreis von 0 bedeutet kostenlosen Versand, ein leerer Grundpreis wird als 0 gespeichert. Erscheint ein Land in zwei Zeilen, bleibt die letzte erhalten. Länder ohne Zeile (wenn es keine *-Zeile gibt) erhalten keinen Tabellenpreis.

Fallback cost: der Preis, der verwendet wird, wenn weder J&T noch die Tabelle einen Preis liefert. Lassen Sie das Feld leer, um den Versanddienstleister in diesem Fall auszublenden. 0 bedeutet kostenlosen Versand.

Table / fallback price is: Per order berechnet den Preis einmal. Per item (multiplied by the number of items) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Live-J&T-Preise gelten immer für die gesamte Bestellung.

Bedingungen

Free shipping from: die Warenkorb-Zwischensumme (versandpflichtige Produkte, nach Rabatten, vor Steuern), ab der der Versand kostenlos ist. Lassen Sie das Feld leer, wenn es keinen kostenlosen Versand geben soll.

Minimum subtotal: zeigt den Versanddienstleister nur an, wenn die Warenkorb-Zwischensumme diesen Betrag erreicht. Lassen Sie das Feld leer, um ihn immer anzuzeigen.

Min weight: blendet den Versanddienstleister aus, wenn der Warenkorb weniger wiegt, in kg. Produktgewichte werden aus der Gewichtseinheit Ihres Shops umgerechnet. 0 bedeutet keine Grenze. Er darf nicht größer sein als Max weight.

Max weight: blendet den Versanddienstleister aus, wenn der Warenkorb mehr wiegt, in kg. Standard: 50. 0 bedeutet keine Grenze.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet den Versanddienstleister für die unten angegebenen Länder an, auch wenn er nicht mit deren Zone verknüpft ist. Wenn Sie dies einschalten, wird der Versanddienstleister mit allen aktiven Zonen verknüpft, und auch Zonen, die Sie später anlegen, werden verknüpft. Ist es ausgeschaltet, wird der Versanddienstleister nur in seinen eigenen Zonen unter Shipping > Carriers angeboten. Beim Ausschalten erhält der Versanddienstleister seine vorherigen Zonen zurück.

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

Erweitert

Debug log: schreibt Preisberechnungen in logs/vfd_jtex_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. J&T-API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Es werden keine Schlüssel, Passwörter oder Postleitzahlen von Kunden geschrieben. Schalten Sie das Protokoll aus, wenn Sie fertig sind.

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 Modul-Einstellungen, den Versanddienstleister, die zwischengespeicherten Preise und das Protokoll. Ist es ausgeschaltet, bleibt alles für eine Neuinstallation erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem J&T-Express-Preis. Nur physische Produkte zählen: Virtuelle Produkte haben kein Gewicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft zuerst die Bedingungen: Lieferland (mit Ignore shipping zones), Warenkorbgewicht und Mindest-Zwischensumme. Erreicht die Warenkorb-Zwischensumme Free shipping from, beträgt der Preis 0 und es wird keine Anfrage an J&T gesendet.

Andernfalls stammen die Kosten aus der ersten Quelle, die einen Preis liefert:

1. Live-J&T-Preis: nur wenn alle vier API-Zugangsdaten und eine Absender-Postleitzahl gesetzt sind, das Lieferland Malaysia ist, der Kunde eine 5-stellige Postleitzahl eingegeben hat und bei Shops mit einer Standardwährung ungleich MYR ein Umrechnungskurs gesetzt ist. Das Modul sendet an J&T die Absender- und Lieferpostleitzahlen sowie das Warenkorbgewicht (mindestens 0,1 kg) für den Standarddienst EZ, ein Paket, und rechnet den zurückgegebenen Preis in MYR in Ihre Standardwährung um.

2. Länderpreise: die Zeile des Lieferlandes oder die *-Zeile mit dem Preis für die Gewichtsstufe des Warenkorbs.

3. Ersatzkosten.

Gibt keine dieser Quellen einen Preis, wird der Versanddienstleister für diesen Warenkorb ausgeblendet. Per item gilt nur für die Tabellen- und Ersatzpreise. Der Preis wird in Ihrer Standardwährung berechnet und dann in der Warenkorbwährung des Kunden angezeigt.

Jede Antwort von J&T wird 1 Stunde lang zwischengespeichert, sodass derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 10 Minuten lang zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf J&T warten muss. Das Zeitlimit für Anfragen beträgt 10 Sekunden. Gibt J&T einen Fehler, einen Preis von null oder keine Antwort zurück, sieht der Kunde keine Fehlermeldung. Es wird der Tabellen- oder Ersatzpreis verwendet, und der Grund wird im Protokoll festgehalten.

Bearbeiten Sie den Versanddienstleister unter Shipping > Carriers, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.

Das Modul berechnet nur die Versandkosten. Es erstellt keine Frachtbriefe, Versandbelege oder Etiketten, bucht keine Abholungen, storniert oder verfolgt keine Sendungen und ermöglicht Kunden nicht, einen Abholpunkt zu wählen. Erstellen und verfolgen Sie Sendungen wie gewohnt in Ihrem J&T-Konto. Das Modul wurde auf Basis des Anfrageformats des offiziellen Plugins von J&T Express Malaysia entwickelt. Bestätigen Sie die Preise mit Ihrem J&T-Konto, bevor Sie live gehen.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox J&T Express ist der erste Block auf Modules > Module Manager > VibeFox J&T 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 Schlüssel maskiert, 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-jt-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. Nachdem sich die Shop-Adresse geändert hat oder nachdem Sie in Ihrem Konto einen Domainplatz 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 Domainplatz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird der Versanddienstleister J&T Express Kunden an der Kasse nicht angezeigt, und es wird kein Preis berechnet. Der Kundenbereich von PrestaShop weiß nicht, dass Sie im Back Office angemeldet sind, daher wird der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, es aber an der Kasse nicht testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen bleiben unberührt.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen jedoch 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 Cronjob ist nicht nötig. Beim Deinstallieren oder Zurücksetzen des Moduls werden der Lizenzschlüssel und der Lizenzstatus immer entfernt.

Fehlerbehebung

J&T Express erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable J&T Express eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes des Kunden und die Kundengruppe abdeckt (oder ob Ignore shipping zones eingeschaltet ist und das Land erlaubt ist). Prüfen Sie die Gewichtsgrenzen und Minimum subtotal. Prüfen Sie, ob Country prices eine Zeile für das Land oder eine *-Zeile hat bzw. ob Fallback cost gesetzt ist. Produkte können auf der Produktseite auch auf bestimmte Versanddienstleister beschränkt sein. Schalten Sie Debug log ein und sehen Sie sich das Feld Log auf der Modulseite an.

Der Preis stammt aus der Tabelle, nicht von J&T: Live-Preise benötigen alle vier API-Zugangsdaten, eine Absender-Postleitzahl, eine Lieferadresse in Malaysia mit 5-stelliger Postleitzahl und bei Shops, die nicht MYR verwenden, den Currency conversion rate. Prüfen Sie die Warnungen oben auf der Modulseite. Lehnt J&T die Anfrage ab oder antwortet nicht, wird der Fehler protokolliert und der Tabellen- oder Ersatzpreis verwendet. Die fehlgeschlagene Anfrage wird nach 10 Minuten erneut versucht.

Keine Live-Preise für die Philippinen oder Indonesien: J&T bietet für diese Länder keine öffentliche Preis-API an. Verwenden Sie dort die Preistabelle und die Ersatzkosten.

Ein Land erhält irrtümlich kostenlosen Versand: Seine Zeile hat einen Grundpreis von 0 (ein leerer Grundpreis wird als 0 gespeichert). Geben Sie einen Grundpreis ein oder entfernen Sie die Zeile. Prüfen Sie außerdem Free shipping from.

Preise wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dies löscht die zwischengespeicherten J&T-Preise.

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

Entwickler-Hooks: Der Hook actionVfdJtexQuoteRequest ändert den Inhalt der Preisanfrage (zum Beispiel den Servicetyp), und actionVfdJtexApiUrl ändert den Endpunkt für Preisanfragen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox J&T Express und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Preise werden immer entfernt. Ist Remove data on uninstall eingeschaltet, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen und das Protokoll werden entfernt. Ist es ausgeschaltet, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren, erhält der gespeicherte Versanddienstleister seinen früheren Status zurück.

J&T Express ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit J&T Express verbunden noch wird es von J&T Express unterstützt.