VibeFox Mercado Envios 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.

Mercado-Pago-Konto (nur für Live-Tarife): Live-Tarife stammen aus dem Rechner von Mercado Envios in Ihrem Mercado-Pago-Konto in Argentinien, Brasilien oder Mexiko. Mercado Envios muss für das Konto aktiviert sein. Pakete werden ab der in diesem Konto hinterlegten Versandadresse angeboten. Sie benötigen den Access Token für den Produktivbetrieb (er beginnt mit APP_USR-): Öffnen Sie in Mercado Pago Developers Ihre Anwendung und deren Zugangsdaten für den Produktivbetrieb. Es gibt keine Anmeldeschaltfläche: Sie fügen den Token in die Einstellungen der Erweiterung ein. Wenn Sie nur Preise je Land verwenden, brauchen Sie kein Mercado-Pago-Konto.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel gilt für eine 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_mercado_envios-oc3-(version).ocmod.zip und das Paket für OpenCart 4 vfd_mercado_envios.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_mercado_envios-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 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 Mercado Envios 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. 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 für Live-Tarife den Access Token ein, wählen Sie das Land von Mercado Envios und, falls die Standardwährung Ihres Shops nicht ARS, BRL oder MXN ist, den Wechselkurs. Optional füllen Sie Country prices und Fallback cost aus (werden ohne Live-Tarife verwendet). Aktivieren Sie Enable Mercado Envios shipping 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_mercado_envios.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 Mercado Envios, 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 Mercado Envios shipping aktivieren und speichern. Wenn Sie die Erweiterung nach einer Deinstallation erneut installieren, werden die aufbewahrten Einstellungen wieder verwendet.

Konfiguration

Alle Einstellungen befinden sich auf der Erweiterungsseite: Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit. Die Abschnitte stehen links. Eine Schaltfläche Save speichert die gesamte Seite ohne Neuladen. Jedes Speichern löscht außerdem die zwischengespeicherten Live-Tarife von Mercado Envios und den letzten API-Fehler. Nur Administratoren mit der Bearbeitungsberechtigung für diese Erweiterung können die Einstellungen speichern.

Warnungen im Abschnitt General (und nach jedem Speichern) zeigen Konfigurationsprobleme an: ein fehlender Wechselkurs, kein Access Token und kein Preis (dann wird die Versandart nie angezeigt), der letzte API-Fehler von Mercado Envios mit Datum sowie eine Gewichts- oder Längeneinheit des Shops, die die Erweiterung nicht kennt (sie wird dann als kg bzw. cm gelesen). Ist Name leer oder länger als 64 Zeichen, ist Exchange rate keine positive Zahl, ist ein anderes Zahlenfeld keine Zahl von 0 oder mehr oder ist Min weight größer als Max weight, zeigt die Seite einen Fehler an und es wird nichts gespeichert.

Allgemein

Der Kunde sieht eine einzige Tarifangabe von Mercado Envios. Sie können die Versandart auf eine Geo-Zone oder auf Länder unter Availability beschränken. Diese Einstellungen gelten für alle Zonen.

Enable Mercado Envios shipping: blendet Mercado Envios an der Kasse ein oder aus. Standard: aus.

Name: der Name der Versandart, der Kunden im Warenkorb und an der Kasse angezeigt wird. Standard: Mercado Envios. Pflichtfeld, höchstens 64 Zeichen.

Tax class: die Steuerklasse der Versandkosten oder No tax (Standard). Mercado Envios nennt Endpreise. No tax zeigt sie wie angeboten an; eine Steuerklasse fügt Ihre Versandsteuer obendrauf hinzu.

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

API von Mercado Envios (Live-Tarife) (ohne Token werden nur die unten genannten Preise verwendet)

Access token: Ihr Access Token von Mercado Pago für den Produktivbetrieb (APP_USR-...). Er wird nur an api.mercadopago.com gesendet und nie protokolliert. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Remove the saved access token: aktivieren und speichern, um den gespeicherten Token zu löschen. Dann werden nur die unten genannten Preise verwendet. Ein oben eingegebener Token ersetzt dagegen den gespeicherten.

Mercado Envios country: das Land Ihres Mercado-Pago-Kontos: Argentina (ARS) (Standard), Brazil (BRL) oder Mexico (MXN). Live-Tarife werden nur für Ziele in diesem Land abgefragt und in dessen Währung angegeben.

Exchange rate: nur nötig, wenn die Standardwährung Ihres Shops von der Währung von Mercado Envios abweicht: der Preis von 1 ARS, BRL oder MXN in Ihrer Standardwährung, zum Beispiel 0.001. Ohne ihn werden Live-Tarife nicht verwendet. Er muss eine positive Zahl sein. Als Dezimaltrennzeichen sind sowohl Punkt als auch Komma zulässig.

Preise ohne Live-Tarife

Diese Preise werden verwendet, wenn kein Access Token vorliegt, für Ziele außerhalb des Landes von Mercado Envios und wenn die API keinen Tarif liefert (eine fehlgeschlagene Anfrage wird nach 5 Minuten wiederholt). Sie gelten in der Standardwährung Ihres Shops ohne Steuer.

Country prices: eine Tabelle mit Zielländern und Preisen. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Entfernen-Schaltfläche, um eine zu löschen. Wählen Sie * All other countries für alle Länder ohne eigene Zeile. Price ist der Preis für das Land. Die Spalten XS (bis 1 kg), S (1-2 kg), M (2-3 kg), L (3-5 kg) und XL (über 5 kg) ersetzen ihn für dieses Warenkorbgewicht. Eine leere oder 0-Spalte verwendet Price. Ein Price von 0 bedeutet kostenloser Versand in dieses Land. Sowohl 9.99 als auch 9,99 werden akzeptiert. Werte, die keine Zahlen sind, werden nach dem Speichern gemeldet und gelöscht. Zeilen ohne jeden Preis werden beim Speichern entfernt.

Fallback cost: wird verwendet, wenn weder die API noch Country prices einen Preis liefern. Lassen Sie das Feld leer, um die Versandart in diesem Fall auszublenden.

Calculation type: Per order (Standard) berechnet den Preis einmal. Per item (each item priced by its own weight x quantity) sucht in Country prices (oder Fallback cost) den Preis für das Gewicht jedes Produkts und multipliziert ihn mit der Menge. Erhält ein Produkt keinen Preis, wird die Versandart ausgeblendet. Live-Tarife von Mercado Envios gelten immer für das gesamte Paket.

Verfügbarkeit

Min weight (kg): das minimale Warenkorbgewicht, damit diese Versandart erscheint. 0 bedeutet keine Grenze (Standard).

Max weight (kg): blendet die Versandart aus, wenn der Warenkorb schwerer ist. Standard: 25. Leer bedeutet 25 kg, 0 bedeutet keine Grenze.

Minimum subtotal: zeigt die Versandart nur an, wenn die Zwischensumme der Produkte, die versendet werden müssen (nach dem Gutschein, vor Steuern), mindestens diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.

Geo zone: bietet Mercado Envios nur für Adressen in dieser Geo-Zone an. All zones (Standard) bedeutet keine Begrenzung. Die Geo-Zone wird nicht geprüft, wenn Ignore shipping zones aktiviert ist. Geo-Zonen werden unter System > Localisation > Geo Zones verwaltet.

Ignore shipping zones: bietet die Versandart für die unten genannten Länder an, unabhängig von der gewählten Geo-Zone.

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

Kostenloser Versand

Free shipping from: die Zwischensumme der Produkte, die versendet werden müssen (nach dem Gutschein, vor Steuern), ab der diese Versandart kostenlos ist. In diesem Fall wird keine API-Anfrage gestellt. Lassen Sie das Feld leer, um es zu deaktivieren.

Erweitert

Debug log: schreibt API-Anfragen und die Tarifberechnung in storage/logs/vfd_mrcv_debug.log.php (in OpenCart 4 system/storage/logs/vfd_mrcv_debug.log.php). Die Datei kann nicht über das Web gelesen werden. Fehler werden immer protokolliert, auch wenn diese Option aus ist. Access Token und Kundenadressen werden nie protokolliert. Erreicht die Datei 5 MB, wird sie nach vfd_mrcv_debug.old.log.php verschoben und ein neues Protokoll begonnen.

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

Remove data on uninstall: wenn aktiviert, löscht die Deinstallation der Erweiterung die Einstellungen und das Protokoll. Wenn deaktiviert (Standard), bleiben sie für eine erneute Installation erhalten. Zwischengespeicherte Tarife werden immer gelöscht. Die Mercado-Envios-Daten aufgegebener Bestellungen bleiben immer als Bestellverlauf erhalten.

Import / Export

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

So funktioniert es an der Kasse

Wenn OpenCart die Versandarten anzeigt, fragt es die Erweiterung nach dem Preis von Mercado Envios. Ist eine Geo zone gesetzt und liegt die Adresse außerhalb, wird Mercado Envios nicht angeboten (außer Ignore shipping zones ist aktiviert; dann entscheidet Countries). Nur Produkte mit Requires Shipping auf Yes zählen: andere Produkte erhöhen das Gewicht nicht und sind nicht in der Zwischensumme enthalten. Die Erweiterung prüft dann das Warenkorbgewicht und die Mindest-Zwischensumme. Die Zwischensumme ist der Preis der Produkte, die versendet werden müssen, nach dem Gutscheinrabatt und vor Steuern. Geschenkgutscheine, Treuepunkte und Shop-Guthaben werden nicht berücksichtigt. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an Mercado Envios gesendet.

Für ein Ziel im Land von Mercado Envios mit gültiger Postleitzahl (4 Ziffern in Argentinien, auch aus einem CPA wie C1425ABC; 8 Ziffern in Brasilien; 5 Ziffern in Mexiko) beschreibt die Erweiterung den Warenkorb als ein Paket: die größte Breite und Länge der Produkte, die addierten Höhen aller Produkte und das Gesamtgewicht in Gramm. Gewichte und Abmessungen der Produkte werden aus ihren Gewichts- und Längenklassen in OpenCart umgerechnet. Jede Seite und das Gewicht werden auf die Mindestwerte von Mercado Envios des Landes angehoben, sodass auch Produkte ohne Abmessungen oder Gewicht einen Tarif erhalten. Der Warenkorbwert wird als Artikelpreis in der Währung von Mercado Envios übermittelt. Die günstigste Option von Mercado Envios wird in Ihre Standardwährung umgerechnet, auf deren Dezimalstellen gerundet und in der Kundenwährung mit der Steuer der gewählten Tax class angezeigt.

Jedes Angebot wird bis zu 1 Stunde zwischengespeichert (nicht länger als die Cache-Dauer von OpenCart), damit derselbe Warenkorb keine neue Anfrage auslöst. Ein fehlgeschlagenes Angebot wird 5 Minuten lang nicht wiederholt. Ist Mercado Pago nicht erreichbar, lehnt es den Token ab, begrenzt die Anfragen oder antwortet in einer anderen Währung, werden alle Live-Angebote 5 Minuten lang pausiert, damit die Kasse bei jeder Aktualisierung nicht auf die API warten muss. Das API-Timeout beträgt 10 Sekunden.

Stattdessen werden die Preise ohne Live-Tarife verwendet, wenn kein Token vorliegt, das Ziel außerhalb des Landes von Mercado Envios liegt, die Postleitzahl fehlt oder ungültig ist, der Wechselkurs fehlt, das Paket schwerer als das Gewichtslimit von Mercado Envios für das Land ist (25 kg in Argentinien, 15 kg in Brasilien, 30 kg in Mexiko) oder Mercado Envios für die Adresse einen Fehler oder keine Option zurückgibt. Verwendet wird die Zeile des Landes (oder die *-Zeile), sonst die Ersatzkosten. Gibt es keinen Preis, wird die Versandart ausgeblendet. Der Kunde sieht nie einen API-Fehler.

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

Die Erweiterung berechnet nur Tarife. Sie erstellt keine Sendungen, druckt keine Etiketten und verfolgt keine Pakete. Erstellen Sie die Sendung in Ihrem Mercado-Libre- oder Mercado-Pago-Konto. Sie zeigt einen einzigen Preis, die günstigste Option von Mercado Envios, keine Auswahl aus allen Optionen, und hat keine Auswahl für Abholstellen (Agenturen).

Bestellungen

Wird eine Bestellung mit einem Live-Tarif von Mercado Envios aufgegeben, speichert die Erweiterung den Servicenamen, die voraussichtliche Lieferzeit in Tagen und den Live-Tarif. Unter Sales > Orders zeigt die Bestellseite einen Block Mercado Envios mit Mercado Envios service, Estimated delivery und Live rate (excl. tax). Der Block wird auch angezeigt, wenn die Versandart später deaktiviert wird. Ein registrierter Kunde sieht Mercado Envios service und Estimated delivery unter der Versandart auf der Bestellseite seines Kontos, und dieselben Zeilen werden der E-Mail zur neuen Bestellung hinzugefügt. Bestellungen mit einem Tabellenpreis oder den Ersatzkosten haben keinen Service. Bestehende Bestellungen werden durch spätere Tarifänderungen nicht beeinflusst.

In OpenCart 4 wird der Block Mercado Envios oberhalb von History angezeigt. OpenCart 4 führt für den Checkout eine einzige Bestellung und aktualisiert sie jedes Mal, wenn der Kunde erneut bestätigt: Der gespeicherte Dienst wird dann mit aktualisiert, und er wird entfernt, wenn der Kunde zu einer anderen Versandart wechselt oder die Bestellung einen Tabellenpreis oder die Ersatzkosten erhält.

Lizenzschlüssel

Die Erweiterung funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Mercado Envios ist der erste Block auf Extensions > Extensions > Shipping > VibeFox Mercado Envios > 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) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: opencart-shipping-mercado-envios und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Administratoren mit der Bearbeitungsberechtigung für diese 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 Mercado Envios 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

Mercado Envios erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable Mercado Envios shipping aktiviert ist. Prüfen Sie Geo zone oder aktivieren Sie Ignore shipping zones und prüfen Sie Countries. Prüfen Sie die Warnungen auf der Erweiterungsseite, die Gewichtsgrenzen und Minimum subtotal. Die Versandart benötigt einen Preis: einen funktionierenden Access Token für Adressen im Land von Mercado Envios oder Country prices bzw. Fallback cost. Prüfen Sie, ob die Produkte Requires Shipping auf Yes haben.

Live-Tarife erscheinen nicht: aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Erweiterungsseite an. Typische Gründe: kein Token, ein Ziel außerhalb des Landes von Mercado Envios, eine fehlende oder ungültige Postleitzahl, ein fehlender Exchange rate, ein Paket über dem Gewichtslimit oder keine Option von Mercado Envios für die Adresse.

HTTP 401 oder 403 in den Warnungen: der Access Token ist ungültig oder abgelaufen. Kopieren Sie den Access Token für den Produktivbetrieb erneut aus Mercado Pago Developers.

Mercado Envios hat in einer anderen Währung geantwortet: das Land des Kontos stimmt nicht mit Mercado Envios country überein. Wählen Sie das Land Ihres Mercado-Pago-Kontos.

Währung der Preise: Country prices, Fallback cost und die Grenzwerte sind in der Standardwährung Ihres Shops angegeben. Live-Tarife kommen in der Währung Ihres Mercado-Pago-Kontos und werden mit Exchange rate umgerechnet, wenn der Shop eine andere Standardwährung nutzt.

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

Die Seite zeigt "Warning: You do not have permission to modify VibeFox Mercado Envios!": Ihre Administratorgruppe darf die Einstellungen möglicherweise nur ansehen. Geben Sie der Gruppe die Bearbeitungsberechtigung für extension/shipping/vfd_mercado_envios (OpenCart 3) oder extension/vfd_mercado_envios/shipping/vfd_mercado_envios (OpenCart 4) unter System > Users > User Groups.

Für Entwickler: die Adresse der Mercado-Envios-API kann mit der Einstellung vfd_mrcv_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 Mercado Envios auf Uninstall (die rote −-Schaltfläche). Der Lizenzschlüssel und der Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart setzt immer Enable Mercado Envios shipping, Sort order, Tax class und Geo zone zurück. Die zwischengespeicherten Tarife und der letzte API-Fehler werden immer gelöscht. Ist Remove data on uninstall aktiviert, werden auch die übrigen Einstellungen und das Debug-Protokoll gelöscht. Ist es deaktiviert, bleiben sie erhalten und werden bei einer erneuten Installation wieder verwendet. Die Mercado-Envios-Daten aufgegebener Bestellungen bleiben immer erhalten, und 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 Mercado Envios auf Uninstall (die orangefarbene −-Schaltfläche) und anschließend auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

Mercado Envios und Mercado Pago sind Marken ihrer jeweiligen Inhaber. Diese Erweiterung ist nicht mit Mercado Envios oder Mercado Pago verbunden und wird von ihnen nicht unterstützt.