VibeFox Frenet for OpenCart — Hilfe

Voraussetzungen

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.

Frenet-Konto (nur für Live-Angebote): erstellen Sie im Frenet-Panel (painel.frenet.com.br) ein kostenloses Konto, aktivieren Sie die von Ihnen genutzten Versanddienstleister und kopieren Sie Ihr API-Token. Wenn Sie nur Festpreise nutzen, benötigen Sie kein Frenet-Konto.

Produkte: Tragen Sie Gewicht und Abmessungen für genaue Preise ein. Produkte ohne diese Angaben werden mit 0,3 kg und 16 × 11 × 2 cm berechnet (die kleinste Correios-Schachtel).

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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_frenet-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_frenet.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 zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_frenet-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 Frenet und klicken Sie auf Install (der grüne +-Button).

3. Klicken Sie auf Edit (der Stift-Button), um die Einstellungsseite zu öffnen.

4. Fügen 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ügen Sie das API-Token ein und geben Sie die Ursprungs-CEP ein. Wenn Ihre Standardwährung nicht BRL ist, geben Sie den BRL-Wechselkurs ein. Optional können Sie Festpreise und einen Ersatzpreis hinzufügen. Aktivieren Sie Enable Frenet 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_frenet.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 in der Liste der installierten Erweiterungen auf derselben Seite. Klicken Sie daneben auf Install (der grüne +-Button).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Erweiterungstyp Shipping. Suchen Sie VibeFox Frenet, klicken Sie auf Install (der grüne +-Button) und dann auf Edit (der Stift-Button).

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

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. Die Abschnitte sind links aufgeführt. Ein Button Save unten speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht außerdem die zwischengespeicherten Frenet-Angebote. Preisfelder akzeptieren sowohl Punkt als auch Komma als Dezimaltrennzeichen. Ist ein Wert falsch, wird nichts gespeichert und die Seite zeigt den Grund an, zum Beispiel Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. oder "…" must not be negative. Ein BRL exchange rate von 0 oder weniger und ein Minimum weight (kg), das über dem Maximum weight (kg) liegt, werden ebenfalls abgelehnt. Nur Admin-Benutzer mit der Änderungsberechtigung für diese Erweiterung können die Einstellungen speichern.

Oben auf der Seite und nach jedem Speichern zeigt die Erweiterung Warnungen an: kein API-Token (dann werden nur Festpreise verwendet, oder die Versandart wird nicht angezeigt, wenn es auch keine Festpreise gibt), keine Ursprungs-CEP, eine Ursprungs-CEP mit nicht 8 Ziffern oder eine Standardwährung ungleich BRL ohne Wechselkurs. Außerdem warnt sie, wenn Ihr Shop keine Gewichtsklasse mit der Einheit kg oder keine Längenklasse mit der Einheit cm hat. Produktgewichte und -abmessungen werden dann anhand des Einheitennamens ihrer Klasse umgerechnet, unbekannte Einheiten werden als kg bzw. cm gelesen. Prüfen Sie System > Localisation > Weight Classes und Length Classes.

Allgemein

Die Einstellungen gelten für jede Geozone. Sie können die Versandart unter Conditions auf eine Geozone beschränken oder Ignore shipping zones verwenden. Der Preis stammt immer von dieser Erweiterung.

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

Method title: der Name der Versandart, der dem Kunden im Warenkorb und an der Kasse angezeigt wird. Standard: Frenet. Pflichtfeld, höchstens 64 Zeichen, ohne die Zeichen < > ; = # { }.

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

Frenet-Live-Angebote

Frenet vergleicht die in Ihrem Frenet-Konto aktivierten Versanddienstleister (Correios, Jadlog, Loggi und andere) und liefert deren Preise für den Warenkorb. Live-Angebote werden nur für Adressen in Brasilien mit einer vollständigen 8-stelligen CEP angefragt. Der Abschnitt enthält einen Link zum Frenet-Panel.

API token: Ihr Frenet-API-Token aus dem Frenet-Panel. Lassen Sie das Feld leer, um nur Festpreise zu verwenden. Nach dem Speichern bleibt das Feld leer und zeigt A token is saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Um das gespeicherte Token zu löschen, aktivieren Sie Remove the saved token und speichern Sie.

Origin CEP: die Postleitzahl (CEP), von der die Pakete versendet werden, zum Beispiel 01001-000. OpenCart hat keine Postleitzahl für den Shop, daher benötigen Live-Angebote dieses Feld. Eine CEP ohne 8 Ziffern wird so gespeichert, wie Sie sie eingegeben haben, und die Seite zeigt Frenet: the origin CEP must have 8 digits. an.

Service to offer: Cheapest service (Standard) oder Fastest service. Frenet liefert mehrere Dienste, die Versandart zeigt einen Preis. Der gewählte Versanddienstleister, Dienst und die Lieferzeit werden mit der Bestellung gespeichert.

BRL exchange rate: Frenet rechnet in brasilianischen Real. Wenn Ihre Standardwährung nicht BRL ist, geben Sie an, wie viel 1 BRL in Ihrer Standardwährung entspricht, zum Beispiel 0.16. Das Angebot und der angegebene Bestellwert werden damit umgerechnet. Ohne diesen Kurs werden keine Live-Angebote verwendet. Wenn Ihre Standardwährung BRL ist, zeigt das Feld an, dass die Frenet-Preise unverändert übernommen werden.

Festpreise

Werden verwendet, wenn kein API-Token vorhanden ist, für Länder, die Frenet nicht bedient, und immer dann, wenn Frenet keinen Preis liefert (API nicht erreichbar, CEP nicht bedient).

Price per country: eine Tabelle mit den Spalten Country, Price, XS, S, M, L und XL, Preise in Ihrer Standardwährung, ohne Steuer. Klicken Sie auf Add country, um eine Zeile hinzuzufügen. Die Größenspalten hängen vom Warenkorbgewicht ab: XS bis 1 kg, S bis 2 kg, M bis 3 kg, L bis 5 kg, XL über 5 kg. Price wird verwendet, wenn die Größenspalte leer ist. Ein Price von 0 bedeutet kostenlosen Versand für dieses Land. Verwenden Sie * Default (all other countries) für alle Länder ohne eigene Zeile. Zeilen ohne Preis werden beim Speichern entfernt.

Fallback cost: wird verwendet, wenn weder Frenet noch die Tabelle einen Preis liefern. Lassen Sie das Feld leer, um die Versandart auszublenden.

Fixed price applies: Per order (Standard) berechnet den Preis einmal. Per item (price × quantity) multipliziert ihn mit der Anzahl der Artikel. Dies gilt nur für Festpreise und den Ersatzpreis. Frenet-Angebote decken bereits den gesamten Warenkorb ab.

Bedingungen

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

Maximum weight (kg): blendet die Versandart oberhalb dieses Warenkorbgewichts aus. Standard: 30 (wird auch verwendet, wenn das Feld leer ist). 0 bedeutet keine Begrenzung. Er darf nicht niedriger sein als Minimum weight (kg).

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

Free shipping from: die Zwischensumme (nach Coupon, vor Steuern), ab der der Versand kostenlos ist. Lassen Sie das Feld leer, um nie kostenlosen Versand zu gewähren.

Tax class: die Steuerklasse, die auf die Versandkosten aufgeschlagen wird, oder No tax. Frenet-Preise sind endgültige Preise des Versanddienstleisters. Wählen Sie No tax, wenn OpenCart darauf keine Steuer aufschlagen soll.

Geo zone: bietet Frenet nur für Adressen in dieser Geozone an. All zones bedeutet keine Begrenzung. Wird nicht zusammen mit Ignore shipping zones verwendet. Geozonen werden unter System > Localisation > Geo Zones verwaltet.

Verfügbarkeit ohne Versandzonen

Normalerweise wird die Versandart in der unter Conditions gewählten Geozone angeboten (in allen Zonen, wenn keine gewählt ist).

Ignore shipping zones: bietet Frenet für die unten aufgeführten Länder an, unabhängig davon, welche Geozone zutrifft. Die Geo zone unter Conditions wird dann nicht geprüft.

Countries: die Zielländer für diesen Modus, ausgewählt aus den aktivierten Ländern Ihres Shops. Lassen Sie das Feld leer, um alle Länder zu verwenden, in die Sie liefern. Wird nur verwendet, wenn Ignore shipping zones aktiv ist.

Erweitert

Debug log: protokolliert jede Angebotsanfrage und -antwort in storage/logs/vfd_frn_debug.log.php (auf OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). Die Datei ist aus dem Web nicht lesbar. API-Fehler werden immer protokolliert. Das Token wird nie protokolliert, und die CEP des Kunden wird gekürzt. Schalten Sie es nach Abschluss wieder aus. Erreicht die Datei 5 MB, wird sie nach vfd_frn_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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: ist diese Option aktiv, löscht die Deinstallation der Erweiterung alle Frenet-Einstellungen und das Protokoll. Ist sie inaktiv, bleibt alles für eine erneute Installation erhalten. Zwischengespeicherte Angebote werden immer entfernt. Die mit Bestellungen gespeicherten Frenet-Dienste sind Teil der Bestellhistorie und bleiben erhalten.

Import / Export

Export: Klicken Sie auf Download JSON, um die Einstellungen als JSON-Datei zu speichern. Das API-Token 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. Das gespeicherte API-Token bleibt erhalten.

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Frenet-Preis. Ist eine Geo zone festgelegt (und Ignore shipping zones ist aus) und liegt die Adresse außerhalb, wird Frenet nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: Andere Produkte fügen kein Gewicht hinzu und sind nicht im Bestellwert enthalten. Die Erweiterung prüft dann die Länderliste (wenn Ignore shipping zones aktiv ist), das Warenkorbgewicht und den Mindestbestellwert. Der Bestellwert ist der Preis der versandpflichtigen Produkte nach Coupon-Rabatt und vor Steuern. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an Frenet gesendet.

Bei einer Adresse in Brasilien mit einer vollständigen 8-stelligen CEP und wenn API-Token und Ursprungs-CEP gesetzt sind, sendet die Erweiterung an Frenet die Ursprungs- und Ziel-CEP, jeden Warenkorbartikel (Gewicht in kg, Abmessungen in cm, Menge, das Produkt-Model und seine Kategorien), den Bestellwert in BRL und den Couponcode des Warenkorbs. Solange die CEP unvollständig ist, wird keine Anfrage gestellt. Frenet liefert die Dienste Ihrer aktivierten Versanddienstleister. Dienste mit Fehler oder ohne Preis werden übersprungen. Die Erweiterung wählt den günstigsten oder den schnellsten Dienst und rechnet den Preis in Ihre Standardwährung um. Der Preis wird auf die Nachkommastellen Ihrer Standardwährung gerundet und dem Kunden in seiner Währung mit der Steuer der gewählten Tax class angezeigt.

Jede Antwort wird 1 Stunde lang für denselben Warenkorb und dieselbe Adresse zwischengespeichert. Eine fehlgeschlagene Anfrage oder eine CEP, die kein aktivierter Versanddienstleister bedient, wird 10 Minuten lang gemerkt. Das API-Timeout beträgt 10 Sekunden. In diesen Fällen sieht der Kunde keinen Fehler: Es wird der Festpreis oder der Ersatzpreis verwendet, oder die Versandart wird ausgeblendet, wenn keiner vorhanden ist. Der Grund wird im Protokoll festgehalten. Für Adressen außerhalb Brasiliens werden nur Festpreise verwendet.

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

Die Erweiterung berechnet nur Tarife. Sie erstellt keine Sendungen, druckt keine Etiketten und verfolgt keine Pakete. Sie zeigt pro Warenkorb einen Frenet-Dienst an, nicht mehrere, und hat keine Abholstellen oder Paketboxen. Frenet liefert Angebote nur innerhalb Brasiliens; verwenden Sie für andere Länder die Festpreise.

Bestellungen

Wird eine Bestellung mit Frenet aufgegeben, speichert die Erweiterung, wie der Versandpreis berechnet wurde: genau die Option, die der Kunde im Versandschritt sah, ohne neue Anfrage an Frenet. Die Bestellseite unter Sales > Orders zeigt dann einen Block Frenet mit diesen Zeilen:

Carrier: der Frenet-Versanddienstleister und -Dienst, zum Beispiel ein Correios- oder Jadlog-Dienst. Wird bei Live-Angeboten angezeigt.

Delivery time: die von Frenet gelieferte Lieferzeit in Werktagen. Wird bei Live-Angeboten angezeigt.

Price source: Live Frenet quote, Fixed price (price per country), Fallback cost oder Free shipping.

Auf OpenCart 4 wird der Block oberhalb von History angezeigt. OpenCart 4 aktualisiert dieselbe Bestellung, wenn der Kunde sie erneut bestätigt: Die gespeicherten Frenet-Daten werden dabei ebenfalls aktualisiert, und wenn der Kunde eine andere Versandart gewählt hat, werden die Frenet-Daten der Bestellung entfernt.

Der Block wird auch angezeigt, wenn die Erweiterung deaktiviert ist. Diese Daten bleiben bei der Deinstallation der Erweiterung erhalten, auch bei aktivem Remove data on uninstall.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Frenet ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Frenet > Edit, über den 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) und die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: opencart-shipping-frenet und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Änderungsberechtigung für die Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (Englisch und Russisch sind enthalten).

Wenn der Schlüssel nicht akzeptiert wird, 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 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 Frenet 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 Methode weiterhin im Shop, markiert mit (unlicensed — visible to admins only), sodass Sie die Erweiterung vor dem Kauf eines Schlüssels einrichten und testen können. Auf OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Admin-Anmeldung nicht, daher wird die Methode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint auf dem Admin-Dashboard eine Erinnerung. Schließen Sie sie mit ×, um sie 7 Tage lang auszublenden. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Admin-Dashboard 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

Frenet erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable Frenet eingeschaltet ist. Prüfen Sie Geo zone bzw. Ignore shipping zones und Countries, die Gewichtsgrenzen und Minimum order amount. Prüfen Sie die Warnungen oben auf der Erweiterungsseite. Typische Gründe: Der Kunde hat noch keine vollständige 8-stellige CEP eingegeben und es gibt keine Festpreise, oder Frenet hat für die Strecke keinen Dienst geliefert und es gibt keinen Festpreis. Prüfen Sie, dass die Produkte Requires Shipping auf Yes haben.

Live-Angebote erscheinen nicht: aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Erweiterungsseite an. Es zeigt den Grund: keine Ursprungs-CEP, kein BRL-Wechselkurs, eine unvollständige CEP des Kunden, eine Gewichts- oder Betragsgrenze oder die Meldungen der übersprungenen Dienste.

Das Protokoll meldet, dass das API-Token abgelehnt wurde (HTTP 401 oder 403): kopieren Sie das Token erneut aus dem Frenet-Panel und fügen Sie es in API token ein.

Das Protokoll meldet, dass Frenet keine Dienste geliefert hat: aktivieren Sie mindestens einen Versanddienstleister im Frenet-Panel.

Mein Shop verkauft in Euro oder US-Dollar: Frenet antwortet in BRL. Geben Sie den BRL exchange rate ein (wie viel 1 BRL in Ihrer Standardwährung entspricht).

Auf den Frenet-Preis wird zusätzlich Steuer berechnet: Frenet-Preise sind endgültige Preise des Versanddienstleisters. Setzen Sie Tax class auf No tax.

Die Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Erweiterungsseite auf Save. Dadurch werden die zwischengespeicherten Frenet-Angebote gelöscht.

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

Für Entwickler: die Frenet-Angebots-Adresse kann mit der Einstellung vfd_frn_api_url (für Tests) ersetzt werden; sie hat kein Feld auf der Einstellungsseite.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Frenet auf Uninstall (der rote −-Button). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable Frenet, Sort order, Tax class und Geo zone zurück. Zwischengespeicherte Angebote werden immer entfernt. Das OpenCart-Event der Erweiterung wird ebenfalls entfernt (bei OpenCart 4 außerdem die Events, die die Frenet-Daten neuer Bestellungen speichern), sodass der Frenet-Block nicht mehr auf der Bestellseite angezeigt wird. Die mit Bestellungen gespeicherten Frenet-Daten bleiben erhalten und werden nach einer erneuten Installation wieder angezeigt. Ist Remove data on uninstall aktiv, werden auch die Frenet-Einstellungen und das Debug-Protokoll gelöscht. Ist es inaktiv, bleiben die übrigen Einstellungen erhalten und werden bei einer erneuten Installation wieder verwendet. Bestehende Bestellungen behalten ihre Versandart und ihre Kosten.

Um bei OpenCart 4 auch die Dateien der Erweiterung zu entfernen, gehen Sie nach der Deinstallation zu Extensions > Installer, klicken Sie in der Liste der installierten Erweiterungen neben VibeFox Frenet auf Uninstall (der orangefarbene −-Button) und anschließend auf Delete (der rote Mülleimer-Button), um das hochgeladene Paket zu entfernen.

Frenet ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung steht in keiner Verbindung zu Frenet und wird von Frenet nicht unterstützt.