VibeFox Ninja Van 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.

Ninja-Van-Tarifkarte: die Preise Ihres Ninja-Van-Versandkontos oder vom Ninja-Van-Vertrieb, eingetragen in der Preistabelle. Es werden keine API-Schlüssel benötigt. Die optionalen Live-Preise innerhalb Indonesiens nutzen die Ninja Van Tariff API, die öffentlich ist und keine Authentifizierung erfordert.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert auf einer 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 Paket für OpenCart 3 vfd_ninja_van-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_ninja_van.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_ninja_van-oc3-(version).ocmod.zip. Die Erweiterung fügt keine OCMOD-Modifikationen hinzu, daher müssen Sie Extensions > Modifications nicht aktualisieren. Statt des Installers können Sie auch den Inhalt des Ordners upload dieses Pakets in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Ninja Van 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. Tragen Sie Ihre Ninja-Van-Preise in der Preistabelle ein. Für Indonesien können Sie optional Live rates aktivieren (siehe Konfiguration). Aktivieren Sie Enable Ninja Van 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_ninja_van.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 Ninja Van, 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 Methode deaktiviert, bis Sie Enable Ninja Van aktivieren und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die von Ihnen gespeicherten Ninja-Van-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Ninja Van > Edit. Die Abschnitte sind links aufgeführt. Eine Schaltfläche Save unten speichert die gesamte Seite ohne Neuladen. Es wird nichts gespeichert, und ein Fehler wird angezeigt, wenn Method title leer ist, länger als 64 Zeichen ist oder < > ; = # { } enthält, wenn ein Zahlenfeld Text oder eine negative Zahl enthält, wenn der IDR conversion rate 0 ist, wenn Minimum weight (kg) größer als Maximum weight (kg) ist oder wenn Sort order keine ganze Zahl ist. Wenn Ihr Shop keine Gewichtsklasse mit der Einheit kg hat und die Einheit der Standard-Gewichtsklasse der Erweiterung nicht bekannt ist, weist eine Warnung darauf hin, dass Produktgewichte als Kilogramm angenommen werden: Fügen Sie unter System > Localisation > Weight Classes eine Gewichtsklasse kg hinzu. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Allgemein

Die Einstellungen gelten für jede Geo-Zone. Sie können die Methode unter Conditions auf eine Geo-Zone beschränken oder Ignore shipping zones verwenden.

Enable Ninja Van: blendet Ninja Van 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: Ninja Van. Pflichtfeld, höchstens 64 Zeichen.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Wählen Sie No tax, wenn die Preise in der Tabelle die Steuer (GST, SST, VAT) bereits enthalten.

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

Preise (in der Standardwährung Ihres Shops, ohne Steuer)

Tragen Sie die Preise Ihrer Ninja-Van-Tarifkarte in der Standardwährung Ihres Shops ein. Wenn Ihre Tarifkarte in SGD, MYR, IDR oder einer anderen Währung vorliegt, rechnen Sie sie zuerst um. Diese Tabelle wird für jedes Ziel außerhalb Indonesiens verwendet und immer dann, wenn kein Live-Preis verfügbar ist.

Price table: eine Zeile pro Zielland. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Schaltfläche ×, um sie zu entfernen. Wählen Sie * All other countries für alle Länder ohne eigene Zeile. Jede Zeile hat einen Preis Base und Gewichtsspalten: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg und XL über 5 kg. Eine leere (oder mit 0 belegte) Gewichtsspalte verwendet den Grundpreis. Ein Grundpreis von 0 bedeutet kostenlosen Versand in dieses Land. Sowohl „9.99“ als auch „9,99“ werden akzeptiert. Zeilen ohne Preise werden beim Speichern entfernt, und pro Land bleibt nur die erste Zeile erhalten.

Price for countries not in the table: wird verwendet, wenn die Tabelle keine Zeile für das Zielland hat (und auch keine *-Zeile), oder die Zeile für dieses Gewicht keinen Preis hat. Lassen Sie das Feld leer, um die Methode in diesem Fall auszublenden. 0 bedeutet kostenloser Versand.

Price applies: die Art, wie die Preise berechnet werden. Dies gilt auch für Live-Preise.

Live-Tarife (API) — Indonesien

Die Ninja Van Tariff API liefert die Standard-Liefergebühr ohne Zuschläge und Rabatte für Pakete innerhalb Indonesiens. Ninja Van bietet sie nur für Indonesien an. Wenn Live rates aktiviert ist, zeigen Statuszeilen unter dem Abschnittstitel die Versand-Ursprungszone, einen fehlenden Umrechnungskurs und die letzte Antwort der Tariff API (Umgebung, Zeit und Ergebnis). Sie werden nach jedem Speichern aktualisiert.

Live rates: Live-Preise von Ninja Van für Lieferungen innerhalb Indonesiens abrufen. Standard: aus. Ohne diese Option wird während des Checkouts nichts an Ninja Van gesendet.

Environment: Production (api.ninjavan.co) (Standard) oder Sandbox — testing only (api-sandbox.ninjavan.co).

Service level: die Servicestufe, für die der Preis angefragt wird: Standard (Standard), Express, Same day oder Next day. Wenn Ninja Van für Route und Service keinen Preis hat, wird die Preistabelle verwendet.

Ship-from zone code L1 und Ship-from zone code L2: die L1- und L2-Stufencodes des Distrikts, von dem Sie versenden, zum Beispiel ID_A00007_01 und ID_B00069_01, aus dem Ninja-Van-Zonencode-Mapping (CSV), dessen Adresse unter dem Feld angezeigt wird. Geben Sie beide ein: Die Shop-Adresse in OpenCart hat keine separate Stadt oder Straße, daher kann die Versand-Ursprungszone nicht daraus ermittelt werden. Codes werden in Großbuchstaben umgewandelt. Ein Code im falschen Format wird mit einer Warnung gelöscht. Wenn nur ein Code eingegeben ist, fordert eine Warnung auf, beide einzugeben, und eine Statuszeile zeigt, dass keine Live-Preise angefragt werden. Eine Statuszeile warnt außerdem, wenn die beiden Codes im Zonencode-Mapping kein Paar bilden.

IDR conversion rate: die Tariff API liefert die Gebühr in indonesischen Rupiah (IDR). Wenn die Standardwährung Ihres Shops IDR ist, lassen Sie das Feld leer. Andernfalls geben Sie ein, wie viel 1 IDR in der Währung Ihres Shops ist, zum Beispiel 0.000058. Der Wert muss größer als 0 sein. Ohne ihn werden keine Live-Preise verwendet, sondern die Preistabelle.

Bedingungen

Minimum weight (kg): blendet die Methode aus, wenn der Warenkorb weniger wiegt. Produktgewichte werden von ihrer OpenCart-Gewichtsklasse in Kilogramm umgerechnet. 0 bedeutet keine Grenze (Standard).

Maximum weight (kg): blendet die Methode aus, wenn der Warenkorb mehr wiegt. Standard: 30. 0 oder ein leeres Feld bedeuten keine Grenze. Er darf nicht niedriger sein als Minimum weight (kg).

Minimum order amount: zeigt die Methode nur an, wenn die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern) diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.

Free shipping from: die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern), ab der der Versand mit Ninja Van kostenlos ist. Lassen Sie das Feld leer, wenn es keinen kostenlosen Versand geben soll.

Geo zone: bietet Ninja Van nur für Adressen in dieser Geo-Zone an. All zones (Standard) bedeutet keine Beschränkung. Sie wird nicht geprüft, wenn Ignore shipping zones aktiviert ist. Geo-Zonen verwalten Sie unter System > Localisation > Geo Zones.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet Ninja Van für die unten genannten Länder an, unabhängig von der Geo zone. Ist die Option aus (Standard), entscheidet die Geo-Zone, und die Länderliste wird nicht verwendet.

Countries: die Zielländer für diesen Modus. 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 die Tarifberechnungen in storage/logs/vfd_njvn_debug.log.php (in OpenCart 4 system/storage/logs/vfd_njvn_debug.log.php). Die Datei ist nicht über das Web lesbar. Es werden keine Kundenadressen oder Zonencodes protokolliert. Fehlgeschlagene Tariff-API-Anfragen werden auch protokolliert, wenn diese Option aus ist. Schalten Sie sie nach Abschluss wieder aus. Erreicht die Datei 5 MB, wird sie nach vfd_njvn_debug.old.log.php verschoben und ein neues Protokoll gestartet.

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 aktiviert, werden bei der Deinstallation der Erweiterung die Ninja-Van-Einstellungen und das Protokoll gelöscht. Ist sie aus (Standard), bleiben sie 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. Die Erweiterung hat keine geheimen Schlüssel, daher wird alles 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 beim normalen Speichern geprüft.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Ninja-Van-Preis. Ist eine Geo zone festgelegt (und Ignore shipping zones ist aus) und liegt die Adresse außerhalb, wird Ninja Van nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: Andere Produkte fügen kein Gewicht hinzu und werden nicht in den Bestellwert einbezogen. Danach prüft die Erweiterung die Bedingungen: die Länderliste von Ignore shipping zones (falls aktiviert), das Warenkorbgewicht und den Mindestbestellwert. Der Bestellwert ist der Preis der versandpflichtigen Produkte nach dem Gutscheinrabatt und vor Steuern. Geschenkgutscheine, Bonuspunkte und Shop-Guthaben werden nicht berücksichtigt. Gilt der kostenlose Versand, ist der Preis 0, und es wird keine Anfrage an Ninja Van gesendet.

Der Preis stammt aus der Zeile des Landes (oder der *-Zeile): zuerst die Gewichtsspalte, sonst der Grundpreis, sonst Price for countries not in the table. Gibt es keinen Preis, wird die Methode für diesen Warenkorb ausgeblendet. Der Preis wird in der Standardwährung Ihres Shops berechnet, auf deren Dezimalstellen gerundet und dem Kunden in seiner Währung mit der Steuer der gewählten Tax class angezeigt.

Ist Live rates aktiviert, wird eine Lieferung innerhalb Indonesiens zuerst von Ninja Van bepreist. Die Erweiterung wandelt die Lieferadresse in Ninja-Van-Zonencodes um: die Region (Provinz) der Adresse, das Feld City (Stadt oder Regentschaft) und bei Städten mit mehreren Zonen den Distrikt (Kecamatan) in Address 1 oder Address 2. Sie sendet Ihre Versand-Ursprungscodes, die Zielcodes, das Gewicht und die Servicestufe und rechnet die Gebühr von IDR in die Währung Ihres Shops um. Bei Per item wird pro unterschiedlichem Artikelgewicht eine Anfrage gesendet, höchstens 5 pro Warenkorb. Bei mehr unterschiedlichen Gewichten wird die Preistabelle verwendet.

Die Tariff API erlaubt 20 Anfragen pro Minute, daher werden Antworten in einer Tabelle der Erweiterung zwischengespeichert: Preise für 6 Stunden, „kein Preis für diese Route“ für 1 Stunde und Fehler für 5 Minuten. Das Speichern der Einstellungen leert diesen Cache nicht. Die Erweiterung sendet nie mehr als 18 Anfragen pro Minute, und nach einer HTTP-429-Antwort pausiert sie eine Stunde. Das API-Zeitlimit beträgt 12 Sekunden. Antwortet Ninja Van nicht, meldet einen Fehler, hat keinen Preis für die Route oder kann die Adresse nicht zugeordnet werden, wird der Tabellenpreis verwendet. Fehler gehen ins Protokoll, nie zum Kunden.

In OpenCart 4 klickt der Kunde im Block der Versandart auf der Kassenseite auf Choose und wählt im Fenster Shipping method options Ninja Van aus. Die Methode funktioniert genauso wie in OpenCart 3.

Die Erweiterung berechnet nur Preise. Sie erstellt keine Ninja-Van-Bestellungen, druckt keine Luftfrachtbriefe (AWB), bucht keine Abholungen, verfolgt keine Pakete und verarbeitet keine Nachnahmesendungen (COD). Dafür nutzen Sie das Ninja-Van-Dashboard. Es gibt keine Auswahl von Abholstationen (Ninja Points): Die Methode ist Lieferung an die Haustür. Sie fügt den Bestellungen nichts hinzu: Die Bestellung zeigt den Methodennamen und die Versandkosten wie jede andere OpenCart-Versandart. Live-Preise sind außerhalb Indonesiens nicht verfügbar.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Ninja Van ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Ninja Van > 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 aktiv 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-ninja-van und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung zum Ändern 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 auf einer 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 Ninja Van Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Ein Administrator, der im Admin im selben Browser angemeldet ist, sieht die Methode im Shop weiterhin, markiert als (unlicensed — visible to admins only), damit Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. In OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Anmeldung im Admin nicht, daher wird die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint eine Erinnerung im Dashboard des Admins. Schließen Sie sie mit ×, um sie 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard des Admins 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. Die Deinstallation der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Ninja Van erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Ninja Van eingeschaltet ist. Prüfen Sie Geo zone (oder Ignore shipping zones und Countries), die Gewichtsgrenzen und Minimum order amount, und ob das Land, die *-Zeile oder Price for countries not in the table einen Preis hat. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Der Live-Preis wird für manche Adressen nicht verwendet: Das Ziel muss einer Ninja-Van-Zone zugeordnet werden: Indonesien, Region (Provinz), Stadt oder Regentschaft in City und bei Städten mit mehreren Zonen der Distrikt (Kecamatan) in einer Adresszeile. Andernfalls wird der Tabellenpreis verwendet. Aktivieren Sie das Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Erweiterungsseite an.

Live-Preise werden überhaupt nicht angefragt: Die Statuszeilen unter Live-Tarife (API) — Indonesien zeigen den Grund: Die Zonencodes des Versand-Ursprungs fehlen, es ist nur einer der beiden Codes eingegeben, die eingegebenen Codes bilden im Zonencode-Mapping kein Paar, oder der IDR conversion rate fehlt.

Ratenlimit erreicht (HTTP 429): Live-Anfragen werden für eine Stunde pausiert, und in der Zwischenzeit wird die Preistabelle verwendet. Das Speichern der Einstellungen beendet die Pause nicht.

In welcher Währung sind die Preise: Die Tabelle und die Bedingungen sind in der Standardwährung Ihres Shops. Live-Preise sind in Rupiah (IDR) und werden mit dem IDR conversion rate umgerechnet, außer die Währung Ihres Shops ist IDR.

Auf der Seite steht „Warning: You do not have permission to modify VibeFox Ninja Van!“: Ihre Admin-Benutzergruppe darf die Einstellungen nur ansehen. Geben Sie der Gruppe die Berechtigung zum Ändern für extension/shipping/vfd_ninja_van (OpenCart 3) oder extension/vfd_ninja_van/shipping/vfd_ninja_van (OpenCart 4) unter System > Users > User Groups.

Für Entwickler: Ein Shop mit einem eigenen Distrikt-Feld (Kecamatan) kann die Zonencodes über das OpenCart-Ereignis vfd_ninja_van/tariff_zone (Auslöser catalog/vfd_ninja_van/tariff_zone) liefern, auch für die Versand-Ursprungszone. Die Adresse der Tariff API lässt sich mit der Einstellung vfd_njvn_api_url ersetzen (für Tests); sie hat kein Feld auf der Einstellungsseite.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Ninja Van auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt Enable Ninja Van, Sort order, Tax class und Geo zone immer zurück. Die zwischengespeicherten Preise werden immer entfernt. Ist Remove data on uninstall aktiviert, werden außerdem die Ninja-Van-Einstellungen, der letzte Status der Tariff API 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 ihre Kosten.

In OpenCart 4 entfernen Sie außerdem die Dateien der Erweiterung: Gehen Sie nach der Deinstallation zu Extensions > Installer und klicken Sie in der Liste der installierten Erweiterungen neben VibeFox Ninja Van auf Uninstall (die orangefarbene −-Schaltfläche) und anschließend auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Ninja Van ist eine Marke des jeweiligen Inhabers. Diese Erweiterung ist nicht mit Ninja Van verbunden und wird von Ninja Van nicht unterstützt.