VibeFox J&T Express for OpenCart — Hilfe

Anforderungen

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

PHP: 8.0 oder neuer.

Zugang zur API von J&T Express Malaysia (nur für Echtzeit-Tarife): Echtzeit-Tarife 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 Erweiterungsseite enthält einen Link). J&T stellt Ihnen den VIP-Kundencode und den VIP-API-Schlüssel bereit. Das API-Konto und der private Schlüssel zum Signieren der Anfragen werden von J&T für die API-Integration ausgestellt. Fragen Sie Ihren J&T-Kundenbetreuer danach. J&T Philippinen, Indonesien und andere Länder haben keine öffentliche Tarif-API, verwenden Sie dort daher die Preistabelle. Wenn Sie nur die Preistabelle und die Ersatzkosten nutzen, brauchen Sie keinen Zugang zur J&T-API.

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

Installation

Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das Paket für OpenCart 3 vfd_jt_express-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_jt_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-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_jt_express-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Änderungen hinzu, daher müssen Sie Extensions > Modifications nicht aktualisieren. Statt des Installers können Sie den Inhalt des Ordners upload aus diesem Paket auch in das Stammverzeichnis Ihres Shops kopieren.

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

3. Klicken Sie auf Edit (die Stift-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. Für Echtzeit-Tarife in Malaysia geben Sie außerdem die J&T-API-Zugangsdaten, die Absender-PLZ und, falls die Standardwährung Ihres Shops nicht MYR ist, den Währungsumrechnungskurs ein (siehe Konfiguration). Aktivieren Sie Enable J&T Express 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_jt_express.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Code der Erweiterung 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 J&T Express, klicken Sie auf Install (die grüne +-Schaltfläche) und dann auf Edit (die Stift-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 J&T Express einschalten und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die gespeicherten Einstellungen von J&T Express wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox J&T Express > Edit. Die Abschnitte stehen links. Eine Schaltfläche Save unten speichert die gesamte Seite ohne Neuladen. Jedes Speichern leert außerdem die zwischengespeicherten J&T-Tarife. Ist ein Wert falsch, wird nichts gespeichert, und die Seite zeigt den Grund an: einen ungültigen Versandtitel, einen Betrag, der keine Zahl von 0 oder mehr ist, eine Currency conversion rate von 0, ein Min weight (kg), das größer als Max weight (kg) ist, oder eine Sortierreihenfolge, die keine ganze Zahl ist. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Warnungen über den Einstellungen (nach jedem Speichern erneut angezeigt) zeigen an, wenn Echtzeit-Tarife nur teilweise konfiguriert sind: Sie listen die fehlenden API-Einstellungen auf oder weisen darauf hin, dass die Währung Ihres Shops nicht MYR ist und der Umrechnungskurs fehlt. Eine weitere Warnung erscheint, wenn Ihr Shop unter System > Localisation > Weight Classes keine Gewichtsklasse mit der Einheit kg hat. Produktgewichte werden dann anhand ihres Einheitennamens umgerechnet (kg, g, lb, oz), andere Einheiten werden als kg gelesen.

Allgemein

Die Versandart wird für die gewählte Geozone oder für die Länder unter Ignore shipping zones angeboten. Die Einstellungen auf dieser Seite gelten für alle Zonen.

Enable J&T Express: blendet die Versandart an der Kasse ein oder aus (der Status dieser Erweiterung). Standard: aus.

Method title: der Name der Versandart, den der Kunde im Warenkorb und an der Kasse sieht. Standard: J&T Express. Erforderlich, bis zu 64 Zeichen, ohne die Zeichen < > ; = # { }.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Eine Steuerklasse fügt Ihre Versandsteuer auf die Kosten hinzu. Wählen Sie No tax, wenn der J&T-Preis bereits alles enthält, was Sie berechnen möchten.

Sort order: die Position der Versandart unter den Versandarten an der Kasse. Eine ganze Zahl.

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

Der Tarif wird für jede malaysische PLZ bei J&T Express Malaysia angefragt und eine Stunde lang zwischengespeichert. Ohne die Zugangsdaten und für andere Länder werden die Preistabelle und die Ersatzkosten verwendet.

VIP customer code: Ihr VIP-Code von J&T Express. Ihn zu leeren, löscht auch den gespeicherten VIP-API-Schlüssel.

VIP API key: der API-Schlüssel (Passwort), den J&T Express zusammen mit dem VIP-Code bereitgestellt 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. Zum Entfernen leeren Sie VIP customer code und speichern.

API account: der Name Ihres API-Kontos bei J&T Express. Ihn zu leeren, löscht auch den gespeicherten privaten Schlüssel.

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

Sender postcode: die malaysische PLZ, von der die Pakete versendet werden, zum Beispiel 50000. Für Echtzeit-Tarife erforderlich: Die Shop-Adresse in OpenCart ist Freitext, daher wird die PLZ nie daraus entnommen.

Currency conversion rate: J&T-Express-Malaysia-Tarife sind in MYR. Ist die Standardwährung Ihres Shops nicht MYR, geben Sie ein, wie viele Einheiten Ihrer Währung einem MYR entsprechen (1 MYR = X), zum Beispiel 0.20. Ohne diesen Wert werden Echtzeit-Tarife nicht verwendet, stattdessen die Preistabelle oder die Ersatzkosten. Ist Ihre Standardwährung MYR, weist das Feld darauf hin und wird nicht benötigt: Die Tarife werden unverändert übernommen. Der Kurs muss größer als 0 sein.

Preistabelle und Ersatz (für Länder außer Malaysia, wenn Echtzeit-Tarife nicht konfiguriert sind oder J&T keinen Tarif liefert; Preise in der Standardwährung Ihres Shops, ohne Steuern)

Country prices: eine Tabelle mit einer Zeile pro Land. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Entfernen-Schaltfläche, um eine zu löschen. 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 Basispreis für Warenkörbe in dieser Stufe. Eine Stufe mit 0 verwendet den Basispreis. Ein Basispreis von 0 bedeutet kostenlosen Versand, und ein leerer Basispreis wird als 0 gespeichert. Länder ohne Zeile (wenn keine *-Zeile vorhanden ist) erhalten keinen Tabellenpreis.

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

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

Bedingungen

Free shipping from: die Zwischensumme des Warenkorbs (versandpflichtige Produkte, nach dem Gutschein, vor Steuern), ab der der Versand kostenlos ist. Lassen Sie das Feld leer, wenn es keinen kostenlosen Versand gibt.

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

Min weight (kg): die Versandart ausblenden, wenn der Warenkorb weniger wiegt. Produktgewichte werden mit ihrer Gewichtsklasse umgerechnet. 0 bedeutet keine Grenze (Standard). Der Wert darf nicht größer als Max weight (kg) sein.

Max weight (kg): die Versandart ausblenden, wenn der Warenkorb mehr wiegt. Standard: 50. 0 bedeutet keine Grenze.

Geo zone: die Versandart nur für Adressen in dieser Geozone anbieten. All zones (Standard) bedeutet keine Begrenzung. Geozonen werden unter System > Localisation > Geo Zones verwaltet. Sie wird nicht verwendet, wenn Ignore shipping zones aktiviert ist.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: die Versandart für die unten genannten Länder anbieten, unabhängig von der Geozone. Standard: aus.

Countries: die Zielländer für diesen Modus, ausgewählt aus den in Ihrem Shop aktivierten Ländern. Lassen Sie das Feld leer, um alle Länder zuzulassen. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Erweitert

Debug log: schreibt Preisberechnungen in storage/logs/vfd_jtex_debug.log.php (bei OpenCart 4 system/storage/logs/vfd_jtex_debug.log.php). Die Datei ist aus dem Web nicht lesbar. J&T-API-Fehler werden immer protokolliert, auch wenn diese Option aus ist. Schlüssel, Passwörter, der Kundencode und PLZ von Kunden werden nie geschrieben. Schalten Sie das Protokoll nach Abschluss wieder aus. Erreicht die Datei 5 MB, wird sie nach vfd_jtex_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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

Remove data on uninstall: ist die Option aktiv, löscht die Deinstallation der Erweiterung die Einstellungen von J&T Express und das Protokoll. Ist sie aus (Standard), bleiben sie für eine erneute Installation erhalten. Zwischengespeicherte Tarife werden immer entfernt.

Import / Export

Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Der VIP-API-Schlüssel und der private Schlüssel werden nicht exportiert.

Import: 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. Die gespeicherten Schlüssel bleiben erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem J&T-Express-Preis. Ist eine Geo zone gesetzt (und Ignore shipping zones ist aus) und liegt die Adresse außerhalb, wird die Versandart nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: Andere Produkte bringen kein Gewicht und sind nicht in der Zwischensumme enthalten. Die Erweiterung prüft dann die Bedingungen: erlaubte Länder (mit Ignore shipping zones), Warenkorbgewicht und Mindest-Zwischensumme. Die Zwischensumme ist der Preis der versandpflichtigen Produkte nach dem Gutscheinrabatt und vor Steuern. Geschenkgutscheine, Bonuspunkte und Store-Guthaben werden nicht berücksichtigt. Erreicht die Zwischensumme Free shipping from, beträgt der Preis 0 und es wird keine Anfrage an J&T gesendet.

Andernfalls werden die Kosten aus der ersten Quelle übernommen, die einen Preis liefert:

1. Live-J&T-Tarif: nur wenn alle vier API-Zugangsdaten und eine Absender-PLZ gesetzt sind, das Zielland Malaysia ist, der Kunde eine 5-stellige PLZ eingegeben hat und bei Shops mit einer anderen Standardwährung als MYR ein Umrechnungskurs gesetzt ist. Die Erweiterung sendet an J&T die Absender- und Ziel-PLZ sowie das Warenkorbgewicht (mindestens 0,1 kg) für den Standardservice EZ, ein Paket, und rechnet den zurückgegebenen MYR-Preis in Ihre Standardwährung um.

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

3. Ersatzkosten.

Wenn keine dieser Quellen einen Preis liefert, wird die Versandart für diesen Warenkorb ausgeblendet. Per item gilt nur für die Tabellen- und Ersatzpreise. Der Preis wird in Ihrer Standardwährung berechnet, auf deren Dezimalstellen gerundet und dem Kunden in seiner Währung mit der Steuer der gewählten Tax class angezeigt.

Jede Antwort von J&T wird eine Stunde lang zwischengespeichert, damit 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 keinen Fehler. Es wird der Tabellen- oder Ersatzpreis verwendet, und der Grund wird im Protokoll festgehalten.

Bei OpenCart 4 klickt der Kunde im Bereich Versandart der Kassenseite auf Choose und wählt im Fenster Shipping method options J&T Express. Die Versandart funktioniert genauso wie bei OpenCart 3.

Die Erweiterung berechnet nur die Versandkosten. Sie erstellt keine Frachtbriefe, Waybills oder Etiketten, bucht keine Abholungen, storniert oder verfolgt keine Sendungen und lässt Kunden keinen Abholpunkt wählen. Sie fügt Bestellungen nichts hinzu: Die Bestellung zeigt den Titel der Versandart und die Versandkosten wie bei jeder anderen OpenCart-Versandart. Erstellen und verfolgen Sie Sendungen wie gewohnt in Ihrem J&T-Konto. Die Erweiterung wurde auf Basis des Anfrageformats der offiziellen J&T-Express-Malaysia-Integration entwickelt. Bestätigen Sie die Preise vor dem Live-Betrieb mit Ihrem J&T-Konto.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox J&T Express ist der erste Block auf Extensions > Extensions > Shipping > VibeFox J&T 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 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 zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: opencart-shipping-jt-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, 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 funktioniert 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 die Versandart J&T Express an der Kasse nicht angezeigt und kein Tarif berechnet. Ein Admin-Benutzer, der im Admin-Bereich im selben Browser angemeldet ist, sieht die Versandart weiterhin im Shop, markiert mit (unlicensed — visible to admins only), sodass Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Bei OpenCart 4 steht diese Vorschau nicht zur Verfügung: Der Shop sieht die Anmeldung im Admin-Bereich nicht, daher wird die Versandart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint im Admin-Bereich auf dem Dashboard ein Hinweis. Schließen Sie ihn mit ×, um ihn 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

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 im Admin-Bereich 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 der Lizenzschlüssel und der Lizenzstatus immer entfernt.

Fehlerbehebung

J&T Express erscheint nicht an der Kasse: prüfen Sie, dass die Lizenz aktiv ist und Enable J&T Express eingeschaltet ist. Prüfen Sie Geo zone (oder dass Ignore shipping zones eingeschaltet ist und das Land in Countries steht), die Gewichtsgrenzen und Minimum subtotal. Prüfen Sie, dass Country prices eine Zeile für das Land oder eine *-Zeile hat oder dass Fallback cost gesetzt ist. Prüfen Sie, dass die Produkte Requires Shipping auf Yes haben. Schalten Sie Debug log ein und sehen Sie sich das Feld Log auf der Erweiterungsseite an.

Der Preis stammt aus der Tabelle, nicht von J&T: Echtzeit-Tarife benötigen alle vier API-Zugangsdaten, eine Absender-PLZ, eine malaysische Lieferadresse mit 5-stelliger PLZ und bei Shops, die nicht in MYR arbeiten, die Currency conversion rate. Prüfen Sie die Warnungen oben auf der Erweiterungsseite. 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 wiederholt.

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

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

Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Erweiterungsseite auf Save. Dadurch werden die zwischengespeicherten J&T-Tarife geleert.

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

Für Entwickler: andere Erweiterungen können den Körper der Tarifanfrage (zum Beispiel den Servicetyp) über das OpenCart-Ereignis vfd_jt_express/quote_request ändern und den Tarif-Endpunkt über vfd_jt_express/api_url.

Deinstallation

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

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

J&T Express ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit J&T Express verbunden und wird von J&T Express nicht unterstützt.