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

Coordinadora-API-Schlüssel (nur für Live-Angebote): Live-Angebote stammen aus dem Cotizador von Coordinadora über den WooCommerce-Dienst von Coordinadora, den auch das offizielle Coordinadora-Plugin nutzt. Coordinadora stellt den API-Schlüssel Kunden mit einer aktiven Handelsvereinbarung aus. Fragen Sie Ihren Kundenbetreuer bei Coordinadora oder schauen Sie auf wc.coordinadora.com. Sie benötigen außerdem den 8-stelligen DANE-Code der Stadt, aus der Sie versenden. Ohne Schlüssel funktioniert die Versandart nur mit Festpreisen.

Produkte: für ein Live-Angebot benötigt jedes Produkt im Warenkorb ein Gewicht und drei Abmessungen (Länge, Breite, Höhe).

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel gilt 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_coordinadora-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_coordinadora.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_coordinadora-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 Coordinadora 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 im Feld License key des Lizenzblocks oben auf der Seite Edit ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

5. Geben Sie den API-Schlüssel, den DANE-Code der Ausgangsstadt und, falls Ihre Standardwährung nicht COP ist, den COP-Wechselkurs ein. Legen Sie mindestens einen Festpreis für Kolumbien als Ersatz fest (siehe Konfiguration). Aktivieren Sie Enable Coordinadora und klicken Sie auf Save.

6. Stellen Sie sicher, dass Ihre Produkte Gewicht und Abmessungen haben.

OpenCart 4

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei vfd_coordinadora.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 Coordinadora, klicken Sie auf Install (die grüne +-Schaltfläche) und danach auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel und die Einstellungen wie in den Schritten 4 bis 6 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 Coordinadora aktivieren und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die Coordinadora-Einstellungen, die Sie behalten haben, wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit. Die Einstellungen gelten für jede Geo-Zone; Sie können die Versandart unter Conditions auf eine Geo-Zone und auf Länder beschränken. Die Abschnitte sind links aufgelistet. Eine Schaltfläche Save unten speichert die gesamte Seite ohne Neuladen. Nach dem Speichern sehen Sie Settings saved. Cached Coordinadora rates were cleared. Zahlen können mit Punkt oder Komma eingegeben werden (9,99 = 9.99). Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser Erweiterung können die Einstellungen speichern.

Nichts wird gespeichert, und die Seite listet die Fehler auf, wenn Name leer ist oder mehr als 64 Zeichen hat, eine Zahl oder ein Tabellenpreis ungültig oder negativ ist, COP per 1 unit of store currency 0 ist, Min weight (kg) größer als Max weight (kg) ist oder Sort order keine ganze Zahl ist.

Die Seite zeigt oberhalb der Einstellungen Warnungen an, wenn Live-Angebote nicht funktionieren können oder die Versandart ausgeblendet würde: Origin city (DANE code) ist leer oder ungültig; COP per 1 unit of store currency fehlt, obwohl Ihre Standardwährung nicht COP ist; es gibt keinen Festpreis für Kolumbien (oder *); es gibt weder API-Schlüssel noch Festpreis für Kolumbien, daher wird die Versandart nie für kolumbianische Adressen angezeigt. Eine Warnung erscheint auch, wenn der Shop keine Gewichtsklasse in kg oder keine Längenklasse in cm hat und seine Standardeinheit der Erweiterung unbekannt ist; Produktgewichte werden dann als kg und Abmessungen als cm gelesen (verwenden Sie kg, g, lb oder oz sowie cm, mm, m oder in unter System > Localisation). Die Warnungen werden nach jedem Speichern aktualisiert.

Allgemein

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

Name: der Name der Versandart, den der Kunde an der Kasse sieht. Standard: Coordinadora. Pflichtfeld, bis zu 64 Zeichen.

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

Live-Angebote von Coordinadora

Live-Angebote werden für Ziele in Kolumbien abgefragt. Lassen Sie den Schlüssel leer, um nur Festpreise zu verwenden.

API key: Ihr WooCommerce-API-Schlüssel von Coordinadora. 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. Der Schlüssel wird nie in das Protokoll geschrieben.

Remove the saved API key: wird nur angezeigt, wenn ein Schlüssel gespeichert ist. Aktivieren Sie die Option und klicken Sie auf Save, um den Schlüssel zu löschen; die Versandart verwendet dann nur noch Festpreise.

Origin city (DANE code): der 8-stellige DANE-Code der Stadt, aus der Sie versenden, zum Beispiel 11001000 Bogotá, 05001000 Medellín, 76001000 Cali oder 08001000 Barranquilla. Ein 5-stelliger Gemeindecode wird ebenfalls akzeptiert und auf 8 Stellen ergänzt.

COP per 1 unit of store currency: Coordinadora rechnet in kolumbianischen Pesos ab. Wenn Ihre Standardwährung nicht COP ist, geben Sie an, wie viele COP 1 Einheit Ihrer Währung entsprechen, zum Beispiel 4300. Der Kurs wird auch verwendet, um den deklarierten Wert in COP zu übermitteln. Lassen Sie das Feld leer, werden keine Live-Angebote verwendet. Der Kurs muss größer als 0 sein. Ist Ihre Standardwährung COP, lassen Sie das Feld leer.

Festpreise (werden verwendet, wenn kein API-Schlüssel vorhanden ist, für Ziele außerhalb Kolumbiens und als Ersatz, wenn kein Live-Angebot verfügbar ist)

Prices by country: eine Liste von Ländern mit einer Spalte Price und optionalen Preisen nach Paketgröße, in Ihrer Standardwährung, ohne Steuer. Die Größe ergibt sich aus dem Warenkorbgewicht: XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL über 5 kg. Price wird verwendet, wenn die Größenspalte 0 oder leer ist. Klicken Sie auf Add country, um eine Zeile hinzuzufügen; eine neue Zeile beginnt mit Kolumbien. Das Land * All other countries gilt für Länder ohne eigene Zeile. Ein Land ohne Zeile (und ohne *) erhält keinen Festpreis. Eine Zeile mit Price 0 und ohne Größenpreis ergibt kostenlosen Versand.

Fixed price per: Order (Standard) berechnet den Preis einmal. Item (price × quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Dies gilt nur für Festpreise; ein Live-Angebot von Coordinadora deckt immer die gesamte Bestellung ab.

Bedingungen

Min weight (kg): blendet die Versandart unterhalb dieses Warenkorbgewichts aus. 0 bedeutet kein Limit (Standard).

Max weight (kg): blendet die Versandart oberhalb dieses Warenkorbgewichts aus. Standard: 25 (wird auch verwendet, wenn das Feld leer ist). 0 bedeutet kein Limit.

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

Free shipping: schaltet kostenlosen Versand ab der unten genannten Zwischensumme ein.

Free shipping from: die Zwischensumme (nach dem Gutschein, vor Steuern), ab der der Versand kostenlos ist. Wird nur verwendet, wenn Free shipping aktiv ist. In diesem Fall wird keine API-Anfrage gestellt.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Mit einer Steuerklasse fügt OpenCart die Versandsteuer auf den Tarif auf. Wählen Sie No tax, wenn Ihre Preise oder das Angebot von Coordinadora bereits Steuern enthalten.

Geo zone: bietet Coordinadora nur für Adressen in dieser Geo-Zone an. All zones (Standard) bedeutet kein Limit. Geo-Zonen werden unter System > Localisation > Geo Zones verwaltet.

Countries: bietet Coordinadora nur für diese Zielländer an. Leer lassen, um alle Länder zuzulassen. Diese Beschränkung gilt zusammen mit Geo zone.

Erweitert

Debug log: schreibt Tarifberechnungen in storage/logs/vfd_crd_debug.log.php (unter OpenCart 4 in system/storage/logs/vfd_crd_debug.log.php). Die Datei kann nicht über das Web gelesen werden. API-Fehler und unvollständige Einstellungen werden immer protokolliert, auch wenn diese Option aus ist. API-Schlüssel und Kundenadressen werden nie protokolliert. Erreicht die Datei 5 MB, wird sie nach vfd_crd_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 Coordinadora-Einstellungen, zwischengespeicherten Angebote und Protokolle. Ist sie aus (Standard), bleibt alles für eine erneute Installation erhalten.

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 Coordinadora-Preis. Ist eine Geo zone gesetzt und liegt die Adresse außerhalb, wird Coordinadora nicht angeboten. Nur Produkte mit Requires Shipping auf Yes zählen: Andere Produkte erhöhen das Gewicht nicht und sind nicht im Angebot enthalten. Die Zwischensumme ist der Preis der versandpflichtigen Produkte nach Abzug des Gutscheinrabatts und vor Steuern. Geschenkgutscheine, Bonuspunkte und Shop-Guthaben werden nicht berücksichtigt. Die Erweiterung prüft zuerst die Bedingungen: erlaubte Länder, Warenkorbgewicht und minimale Bestellzwischensumme. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an Coordinadora gesendet.

Für eine Adresse in Kolumbien mit API-Schlüssel ermittelt die Erweiterung den DANE-Code der Zielstadt in dieser Reihenfolge: einen DANE-Code im Stadtfeld (die kolumbianischen Checkout-Module für Departamentos und Städte schreiben ihn hinein, zum Beispiel MEDELLIN (ANT) (05001000)), eine 8-stellige Postleitzahl oder die integrierte Liste der Departamento-Hauptstädte und rund 40 größerer Städte. Hat die Adresse eine Region (Departamento), wird eine Stadt aus der Liste dagegen geprüft. Akzente und Groß-/Kleinschreibung werden ignoriert.

Anschließend sendet die Erweiterung an Coordinadora den DANE-Code des Ziels und jedes Produkt mit der Ausgangsstadt, seinem Gewicht (kg), seinen Abmessungen (cm), seiner Menge und seinem deklarierten Wert (COP). Der deklarierte Wert ist die Positionssumme des Produkts vor Steuern, nach Abzug des Gutscheinrabatts. Gewichts- und Längenklassen der Produkte werden automatisch umgerechnet. Coordinadora liefert den Preis in COP; die Erweiterung rechnet ihn in Ihre Standardwährung um, rundet ihn auf die Dezimalstellen dieser Währung und zeigt ihn in der Währung des Kunden mit der Steuer der gewählten Tax class an. Jedes Angebot wird 1 Stunde zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten gemerkt, damit ein Ausfall bei Coordinadora nicht jede Aktualisierung der Kasse verlangsamt. Das API-Timeout beträgt 10 Sekunden.

Ist kein Live-Angebot verfügbar (API-Fehler, unbekannte Stadt, ein Produkt ohne Gewicht oder Abmessungen, unvollständige Einstellungen), wird der Festpreis verwendet. Gibt es keinen, wird die Versandart für diesen Warenkorb ausgeblendet. Fehlerdetails gehen in das Debug-Protokoll, nie an den Kunden.

Die Erweiterung berechnet nur Tarife. Sie erstellt keine Sendungen oder Guías, druckt keine Etiketten, bucht keine Abholungen (recogidas), verfolgt keine Pakete, zieht keine Nachnahmebeträge (recaudo) ein und bietet keine Droop-Abholpunkte an; nutzen Sie dafür das Coordinadora-Portal. Sie fügt den Bestellungen nichts hinzu: Die Bestellung zeigt den Namen der Versandart und die Versandkosten wie bei jeder anderen OpenCart-Versandart. Internationale Ziele verwenden die Festpreise.

Unter OpenCart 4 klickt der Kunde auf der Checkout-Seite im Block der Versandarten auf Choose und wählt Coordinadora im Fenster Shipping method options. Die Versandart funktioniert genauso wie unter OpenCart 3.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Coordinadora ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Coordinadora > Edit, oberhalb der Einstellungen. Fügen 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zur erneuten Prüfung 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-coordinadora und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung zum Ändern dieser 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 gilt 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 Coordinadora 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 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. Unter OpenCart 4 gibt es diese Vorschau nicht: Der Shop sieht die Admin-Anmeldung nicht, daher ist die Versandart ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint auf dem Dashboard des Admins 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, Updates und Support benötigen 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 pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren der Erweiterung entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Coordinadora erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable Coordinadora eingeschaltet ist. Prüfen Sie die Warnungen oben auf der Erweiterungsseite, Geo zone, Countries, die Gewichtsgrenzen und Minimum order subtotal. Ohne Live-Angebot muss ein Festpreis für das Land oder für * vorhanden sein. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Der Live-Tarif wird nicht angezeigt, nur der Festpreis: aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Erweiterungsseite an. Typische Gründe: die Zielstadt wird nicht erkannt, ein Produkt hat kein Gewicht oder keine Abmessungen, der DANE-Code der Ausgangsstadt oder der COP-Wechselkurs fehlt, oder Coordinadora hat einen Fehler zurückgegeben.

Die Zielstadt wird nicht erkannt: installieren Sie ein kolumbianisches Checkout-Modul für Departamentos und Städte, das den DANE-Code in das Stadtfeld schreibt. Entwickler können mit den OpenCart-Events vfd_coordinadora/dane_cities, vfd_coordinadora/destination_dane und vfd_coordinadora/api_url weitere Städte zuordnen oder die API-Adresse ändern; die API-Adresse lässt sich außerdem mit der Einstellung vfd_crd_api_url (für Tests) ersetzen, die auf der Einstellungsseite kein Feld hat.

Enthält der Tarif Steuern? Der Tarif ist das, was Coordinadora angibt. Mit einer Tax class fügt OpenCart die Versandsteuer auf den Tarif auf; wählen Sie No tax, wenn das Angebot sie bereits enthält.

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

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

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Shipping und klicken Sie neben VibeFox Coordinadora auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable Coordinadora, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Angebote werden immer entfernt. Ist Remove data on uninstall aktiv, werden auch die Coordinadora-Einstellungen und das Protokoll gelöscht. Ist sie 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 und klicken Sie in der Liste der installierten Erweiterungen neben VibeFox Coordinadora auf Uninstall (die orangefarbene −-Schaltfläche). Klicken Sie danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

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