VibeFox Cargoson 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.

Cargoson-Konto (nur für Echtzeitpreise): Echtzeitpreise nutzen die Frachtpreis-API von Cargoson. Frachtpreisabfragen erfordern ein Cargoson-Abonnement mit API-Zugang (zum Zeitpunkt der Erstellung Plan Advanced oder höher). Der API-Schlüssel wird in Ihrem Cargoson-Konto ausgestellt; wenden Sie sich an den Cargoson-Support, falls Ihr Tarif keine API-Einstellungen anzeigt. Die Preise stammen von den Spediteuren und Preislisten, die mit diesem Konto verbunden sind. Wenn Sie nur Festpreise verwenden, benötigen Sie kein Cargoson-Konto.

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

Installation

Das Download-Paket 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 OpenCart-3-Paket vfd_cargoson-oc3-(Version).ocmod.zip und das OpenCart-4-Paket vfd_cargoson.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen derselbe.

OpenCart 3

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_cargoson-oc3-(Version).ocmod.zip. Die Erweiterung nimmt keine OCMOD-Änderungen vor, 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 Cargoson und klicken Sie auf Install (die grüne +-Schaltfläche).

3. Klicken Sie auf Edit (die Schaltfläche mit dem Stift), um die Einstellungsseite zu öffnen.

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

5. Wählen Sie, wie die Versandkosten berechnet werden, und füllen Sie die passenden Abschnitte aus: die Festpreise und bei Echtzeitpreisen den API-Schlüssel und die Abholpostleitzahl (siehe Konfiguration). Aktivieren Sie Enable Cargoson 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_cargoson.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 Cargoson, klicken Sie auf Install (die grüne +-Schaltfläche) und danach auf Edit (die Schaltfläche mit dem Stift).

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 ausgeschaltet, bis Sie Enable Cargoson aktivieren und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die gespeicherten Cargoson-Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Cargoson > Edit. Die Abschnitte sind links aufgelistet. Ein Button Save unten speichert die gesamte Seite ohne Neuladen. Nach dem Speichern sehen Sie Settings saved. Cached Cargoson prices were cleared. Dezimalzahlen können mit Punkt oder Komma eingegeben werden. Nichts wird gespeichert, und die Seite listet die Fehler auf, wenn Method title leer oder länger als 64 Zeichen ist, ein Zahlenfeld Text oder eine negative Zahl enthält, Currency conversion rate 0 ist, Minimum weight (kg) größer als Maximum weight (kg) ist, Price currency kein 3-stelliger Code ist, eine Zeile der Preistabelle ein ungültiges Land oder einen ungültigen Preis hat oder Sort order keine ganze Zahl ist. Wenn die Gewichtseinheit des Shops der Erweiterung unbekannt ist, weist eine Warnung nach dem Speichern darauf hin, dass Produktgewichte als Kilogramm behandelt werden; legen Sie unter System > Localisation > Weight Classes eine Gewichtsklasse mit der Einheit kg an. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Allgemein

Der Kunde sieht einen einzigen Cargoson-Tarif. Sie können die Versandart unter Availability auf eine Geozone oder auf Länder beschränken.

Enable Cargoson: blendet Cargoson an der Kasse ein oder aus. Standard: aus.

Method title: der Name der Versandart, den der Kunde im Warenkorb und an der Kasse sieht, höchstens 64 Zeichen. Standard: Cargoson. Pflichtfeld.

Shipping cost: wie der Preis berechnet wird.

Der Grund für einen fehlenden Echtzeitpreis wird im Debug-Protokoll festgehalten. Er wird dem Kunden nie angezeigt.

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

Cargoson-API (nur für Echtzeitpreise erforderlich)

API key: der API-Schlüssel aus Ihrem Cargoson-Konto. Er wird nur an Cargoson gesendet und nie Kunden angezeigt oder im Protokoll festgehalten. 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.

Remove the saved API key: aktivieren und speichern, um den gespeicherten Schlüssel zu löschen.

Carrier: welche Preise verwendet werden. Der Kunde sieht einen einzigen Tarif.

Package type code: der Cargoson-Pakettyp, der mit der Preisabfrage gesendet wird. Standard: CLL. Die Beispiele der Cargoson-API verwenden EUR (EUR-Palette) und FIN (FIN-Palette). Für Pakete verwenden Sie den Paketcode Ihres Cargoson-Kontos. Die Bestellung wird als ein Paket mit dem Gesamtgewicht des Warenkorbs gesendet.

Price currency: die Währung der Preise in Ihrem Cargoson-Konto als 3-stelliger Code. Standard: EUR. Die API liefert Beträge ohne Währungscode.

Currency conversion rate: nur nötig, wenn die Preiswährung von der Standardwährung Ihres Shops abweicht: 1 Einheit der Cargoson-Währung = X Einheiten Ihrer Standardwährung. Leer lassen, um solche Preise abzulehnen, damit ein Kunde nie in der falschen Währung belastet wird.

Versandadresse (Abholadresse) (für Echtzeitpreise)

Collection country: das Land, aus dem Sie versenden. Die erste Option, Store country, verwendet das Land Ihres Shops.

Collection postcode: die Postleitzahl, von der Sie versenden. Cargoson verlangt sie für Echtzeitpreise. Die Shopadresse in OpenCart ist Freitext, daher wird die Postleitzahl nie daraus übernommen: Geben Sie sie hier ein.

Das Abholdatum, das an Cargoson gesendet wird, ist heute in der Zeitzone des Shops oder am Wochenende der nächste Montag.

Festpreise (werden verwendet, wenn Shipping cost auf Fixed prices steht, und als Ersatz für Echtzeitpreise)

Price per country and size: eine Liste von Zeilen mit einem Country, einem Price und Preisen nach Warenkorbgewicht in der Standardwährung des Shops, ohne Steuern: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg, XL über 5 kg. Ein leerer oder 0-Größenpreis verwendet die Spalte Price; ein leerer Price bedeutet, dass es für diese Größe keinen Festpreis gibt. Klicken Sie auf Add country, um eine Zeile hinzuzufügen. Wählen Sie * All other countries für Preise, die für jedes Land ohne eigene Zeile gelten. Länder ohne Zeile (wenn keine *-Zeile vorhanden ist) haben keinen Festpreis, daher wird die Versandart für sie ausgeblendet. Preise müssen Zahlen größer oder gleich 0 sein. Eine leere Zeile wird ignoriert.

Fixed price applies: Per order (Standard) berechnet den Preis einmal. Per item (price × quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Echtzeitpreise von Cargoson gelten immer pro Sendung.

Bedingungen

Minimum weight (kg): blendet die Versandart unterhalb dieses Warenkorbgewichts aus. 0 bedeutet keine Grenze (Standard).

Maximum weight (kg): blendet die Versandart oberhalb dieses Warenkorbgewichts aus. Standard: 25. 0 bedeutet keine Grenze.

Minimum order amount: zeigt die Versandart nur, wenn die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern) diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.

Free shipping: aktiviert kostenlose Cargoson-Lieferung ab dem unten genannten Betrag.

Free shipping from: die Zwischensumme der versandpflichtigen Produkte (nach dem Gutschein, vor Steuern), ab der die Lieferung kostenlos ist. Wird nur verwendet, wenn Free shipping aktiviert ist.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Cargoson-Spediteurpreise sind in der Regel netto (ohne MwSt.). Wählen Sie No tax, wenn Ihre Preise bereits Steuern enthalten.

Verfügbarkeit

Geo zone: bietet Cargoson nur für Adressen in dieser Geozone an. All zones (Standard) bedeutet keine Grenze. Geozonen verwalten Sie unter System > Localisation > Geo Zones.

Ignore shipping zones: die Geozone wird nicht geprüft; die unten stehende Länderliste entscheidet.

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

Erweitert

Debug log: protokolliert jede Tarifberechnung in storage/logs/vfd_cgs_debug.log.php. Die Datei kann nicht über das Web gelesen werden. API-Fehler und abgelehnte Preise werden immer protokolliert, auch wenn diese Option aus ist. API-Schlüssel und Postleitzahl des Kunden werden nie protokolliert. Erreicht die Datei 5 MB, wird sie nach vfd_cgs_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 aktiviert, löscht die Deinstallation der Erweiterung die Cargoson-Einstellungen, die zwischengespeicherten Preise und das Protokoll. Ist sie aus (Standard), bleiben sie für eine erneute Installation erhalten. Die Cargoson-Angebote abgeschlossener Bestellungen werden immer aufbewahrt.

Import / Export

Export: klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Der API-Schlüssel wird 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. Der gespeicherte API-Schlüssel bleibt erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Cargoson-Preis. Ist eine Geo zone gesetzt, Ignore shipping zones aus und liegt die Adresse außerhalb der Zone, wird Cargoson nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: Andere Produkte erhöhen das Gewicht nicht und fließen nicht in den Bestellwert ein. Produktgewichte werden aus ihrer Gewichtsklasse in Kilogramm umgerechnet. Danach prüft die Erweiterung die Bedingungen: erlaubte Länder, Warenkorbgewicht und Mindestbestellwert. Der Bestellwert ist der Preis der versandpflichtigen Produkte nach dem Gutscheinrabatt und vor Steuern. Geschenkgutscheine, Bonuspunkte und Store Credit werden nicht berücksichtigt. Gilt kostenloser Versand, ist der Preis 0 und es wird keine Anfrage an Cargoson gesendet.

Im Festpreismodus wird der Preis aus der Tabelle entnommen. In den Echtzeitmodi sendet die Erweiterung an Cargoson das Abholdatum, das Abholland und die Abholpostleitzahl, das Zielland und die Ziel-Postleitzahl sowie ein Paket mit dem Pakettypcode und dem Gesamtgewicht des Warenkorbs (mindestens 0,1 kg). Ein Echtzeitpreis wird nur angefragt, wenn die Lieferadresse eine Postleitzahl hat. Cargoson liefert die Preise Ihrer Spediteure; die Erweiterung wählt den günstigsten (des gewählten Spediteurs, falls gesetzt) und rechnet ihn bei Bedarf in Ihre Standardwährung um. Der Preis wird in Ihrer Standardwährung berechnet, auf deren Nachkommastellen gerundet und dem Kunden in seiner Währung mit der Steuer der gewählten Tax class angezeigt.

Jede Antwort wird 1 Stunde zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 10 Minuten zwischengespeichert, damit die Kasse bei jeder Aktualisierung nicht auf Cargoson warten muss. Das API-Timeout beträgt 10 Sekunden. Gibt Cargoson einen Fehler, keinen Preis für die Strecke oder einen Preis in einer anderen Währung ohne Umrechnungskurs zurück, sieht der Kunde keinen Fehler. Die Versandart wird ausgeblendet oder im Ersatzmodus wird der Festpreis verwendet.

Die Erweiterung berechnet nur Tarife. Sie erstellt keine Sendungen oder Buchungen in Cargoson, druckt keine Etiketten und verfolgt keine Pakete; Kunden können keine Paketstation und keinen Abholpunkt wählen. Der Warenkorb wird als ein Paket mit dem Gesamtgewicht berechnet; Paketabmessungen werden nicht gesendet. Es wird nur der einzelne günstigste Preis angezeigt, keine Liste von Spediteuren.

Unter OpenCart 4 klickt der Kunde im Versandart-Block der Kasse auf Choose und wählt im Fenster Shipping method options Cargoson aus. Die Versandart funktioniert genauso wie unter OpenCart 3.

Bestellungen

Wenn ein Kunde mit Cargoson bestellt, wird der an der Kasse berechnete Tarif mit der Bestellung gespeichert. Unter Sales > Orders zeigt die Bestellseite ein Panel Cargoson shipping:

Carrier, Service und Cargoson service ID: der angebotene Cargoson-Spediteur und Service, angezeigt, wenn ein Echtzeitpreis verwendet wurde.

Price source: Cargoson live price, Fixed price oder Free shipping threshold.

Calculated price (excl. tax): der Preis in der Standardwährung Ihres Shops.

Das Panel wird auch angezeigt, während die Versandart ausgeschaltet ist. Unter OpenCart 4 wird die Bestellung im Bestätigungsschritt einmal angelegt und jedes Mal aktualisiert, wenn der Kunde dorthin zurückkehrt; das gespeicherte Angebot ist daher das zuletzt an der Kasse berechnete. Wechselt der Kunde zu einer anderen Versandart, wird das Cargoson-Angebot der Bestellung entfernt. Das Ändern der Bestellung im Admin ändert das Angebot nicht, und es ändert sich auch später nicht. Buchen Sie die Sendung in Cargoson oder über eigene Integrationen.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Cargoson ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Cargoson > Edit, über den Einstellungen. Geben 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 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-cargoson 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 auf einer Domain: der 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 Cargoson Kunden an der Kasse nicht angezeigt und es wird kein Tarif berechnet. Ein Admin-Benutzer, der im Admin im selben Browser angemeldet ist, sieht die Versandart weiterhin im Shop, markiert als (unlicensed — visible to admins only), damit Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. Unter OpenCart 4 gibt es diese Vorschau nicht: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Versandart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard des Admins. 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, Updates und Support erfordern jedoch 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 wöchentlich. Ein Cron-Job ist nicht nötig. Die Deinstallation der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Cargoson erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Cargoson eingeschaltet ist. Prüfen Sie die Geo zone (oder Ignore shipping zones und Countries), die Gewichtsgrenzen und den Minimum order amount. Prüfen Sie im Festpreismodus, ob das Land oder * All other countries einen Preis für die Warenkorbgröße hat. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Echtzeitpreise erscheinen nicht: Sehen Sie im Feld Log auf der Erweiterungsseite nach. API-Fehler werden immer protokolliert; aktivieren Sie Debug log, um jede Berechnung zu sehen. Typische Gründe: noch keine Ziel-Postleitzahl eingegeben, keine Collection postcode, der API-Schlüssel wird abgelehnt (falscher oder abgelaufener Schlüssel oder kein API-Zugang in Ihrem Cargoson-Tarif), kein Spediteur für Strecke oder Gewicht oder ein Preis in einer anderen Währung. Mit Cargoson live prices, fixed prices if the API fails erhalten Kunden weiterhin den Festpreis, während Sie das Problem beheben.

Cargoson lehnt den Pakettyp ab: verwenden Sie den Paketcode, den Ihr Cargoson-Konto unter Package type code nutzt. Der Grund steht im Protokoll.

Preis in anderer Währung wird abgelehnt: setzen Sie Price currency auf die Währung Ihrer Cargoson-Preise und geben Sie die Currency conversion rate ein.

Steuer wird auf den Versand doppelt berechnet: Ihre Cargoson-Preise enthalten bereits MwSt. Setzen Sie Tax class auf No tax.

Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Erweiterungsseite auf Save. Das leert die zwischengespeicherten Cargoson-Preise.

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

Für Entwickler: Die Adresse der Cargoson-API kann mit der Einstellung vfd_cgs_api_url (für Tests) ersetzt werden; dafür gibt es kein Feld auf der Einstellungsseite.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Cargoson auf Uninstall (den roten −-Button). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable Cargoson, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Preise werden immer entfernt. Ist Remove data on uninstall aktiv, werden außerdem die Cargoson-Einstellungen und das Debug-Protokoll gelöscht. Ist die Option aus, bleiben die übrigen Einstellungen erhalten und werden bei einer erneuten Installation wieder verwendet. Die Cargoson-Angebote abgeschlossener Bestellungen werden nie gelöscht, und bestehende Bestellungen behalten ihre Versandart und ihre Kosten.

Um unter 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 Cargoson auf Uninstall (den orangefarbenen −-Button) und danach auf Delete (den roten Papierkorb-Button), um das hochgeladene Paket zu entfernen.

Cargoson ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit Cargoson verbunden und wird von Cargoson nicht unterstützt.