VibeFox Mercado Envios for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Mercado-Pago-Konto (nur für Live-Tarife): Live-Tarife stammen aus dem Mercado-Envios-Rechner Ihres Mercado-Pago-Kontos in Argentinien, Brasilien oder Mexiko. Mercado Envios muss für das Konto aktiviert sein. Pakete werden ab der Versandadresse berechnet, die in diesem Konto hinterlegt ist. Sie benötigen das Access Token für die Produktionsumgebung (es beginnt mit APP_USR-): Öffnen Sie im Entwicklerbereich von Mercado Pago Ihre Anwendung und deren Zugangsdaten für die Produktion. Es gibt keinen Anmeldebutton: Sie fügen das Token in die Moduleinstellungen ein. Wenn Sie nur Preise je Land verwenden, benötigen Sie kein Mercado-Pago-Konto.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. Ein Schlüssel funktioniert für eine Domain.

Installation

1. Gehen Sie im Back-Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls aus.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Mercado Envios in der Modulliste und klicken Sie dort auf Configure.

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

4. Für Live-Tarife fügen Sie das Access Token ein, wählen 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 (sie werden ohne Live-Tarife verwendet). Klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienstleister Mercado Envios mit dem Lieferzeittext Mercado Envios delivery an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugewiesen, ohne Steuerregel. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis kommt immer aus dem Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Mercado Envios > Configure. Jeder Abschnitt hat seinen eigenen Button Save, der die ganze Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten Tarife von Mercado Envios und den letzten API-Fehler.

Warnungen oben auf der Seite zeigen Konfigurationsprobleme an: einen fehlenden Wechselkurs, kein Access Token und keinen Preis, den letzten API-Fehler von Mercado Envios mit Datum sowie eine Gewichts- oder Maßeinheit des Shops, die das Modul nicht kennt (sie wird dann als kg bzw. cm gelesen). Wurde der Versanddienstleister gelöscht, heißt es im Abschnitt General: The Mercado Envios carrier was not found — reset the module to create it again.

Allgemein

Fügen Sie die Zonen Ihrer Kunden unter Shipping > Carriers dem Versanddienstleister Mercado Envios hinzu, oder verwenden Sie unten Ignore shipping zones. Diese Einstellungen gelten für jede Zone.

Enable Mercado Envios shipping: schaltet den Versanddienstleister ein oder aus. Das ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Name: der Name des Versanddienstleisters, der Kunden an der Kasse angezeigt wird. Standard: Mercado Envios. Pflichtfeld, höchstens 64 Zeichen.

Tax: die Steuerregel des Versanddienstleisters oder No tax (Standard). Mercado Envios nennt Endpreise. No tax zeigt sie so an, wie sie angeboten werden; eine Steuerregel fügt Ihre Versandsteuer obendrauf hinzu.

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

Access token: Ihr Access Token für die Produktionsumgebung von Mercado Pago (APP_USR-...). Es wird nur an api.mercadopago.com gesendet und niemals protokolliert. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. Geben Sie einen neuen Wert nur ein, um ihn zu ändern. Um Live-Tarife nicht mehr zu verwenden, aktivieren Sie Remove the saved access token (only the prices below are used then) und speichern Sie.

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 sich die Standardwährung Ihres Shops von der Währung von Mercado Envios unterscheidet: der Preis von 1 ARS, BRL oder MXN in Ihrer Standardwährung, zum Beispiel 0.001. Ohne Wechselkurs werden keine Live-Tarife verwendet. Er muss eine positive Zahl sein. Sowohl Punkt als auch Komma werden als Dezimaltrennzeichen akzeptiert.

Preise ohne Live-Tarife

Diese Preise werden verwendet, wenn kein Access Token vorhanden ist, für Ziele außerhalb des Landes von Mercado Envios und wenn die API keinen Tarif liefert. Sie gelten in der Standardwährung Ihres Shops ohne Steuern.

Country prices: eine Tabelle mit Zielländern und Preisen. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorb-Symbol, um eine zu entfernen. 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 jeglichen 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 den Versanddienstleister in diesem Fall auszublenden.

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

Verfügbarkeit

Min weight: das minimale Warenkorbgewicht in kg, damit dieser Versanddienstleister erscheint. 0 bedeutet kein Limit.

Max weight: blendet den Versanddienstleister aus, wenn der Warenkorb mehr wiegt, in kg. Leer bedeutet 25 kg, 0 bedeutet kein Limit. Ein Min weight, das größer als Max weight ist, wird beim Speichern abgelehnt.

Minimum subtotal: zeigt den Versanddienstleister nur, wenn die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern) mindestens diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.

Ignore shipping zones: bietet den Versanddienstleister für die unten genannten Länder an, ohne dessen Zonen einzurichten. Beim Speichern wird der Versanddienstleister allen Zonen hinzugefügt, ebenso später angelegten Zonen. Wird die Option ausgeschaltet, entfernt das die Zonen, die sie hinzugefügt hat; der Versanddienstleister behält seine eigenen Zonen.

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

Kostenloser Versand

Free shipping from: die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern), ab der dieser Versanddienstleister kostenlos ist. In diesem Fall wird keine API-Anfrage gestellt. Leer lassen, um dies zu deaktivieren.

Erweitert

Debug log: schreibt API-Anfragen und die Tarifberechnung in logs/vfd_mrcv_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Das Access Token und Kundenadressen werden nie protokolliert.

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 die Option aktiviert, löscht die Deinstallation des Moduls die Einstellungen, den Versanddienstleister, die zwischengespeicherten Tarife und die Protokolle. Ist sie deaktiviert, bleibt alles für eine erneute Installation erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem Preis von Mercado Envios. Nur physische Produkte zählen: Virtuelle Produkte erhöhen das Gewicht nicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft zuerst die Bedingungen: erlaubte Länder (bei Ignore shipping zones), Warenkorbgewicht und Mindestzwischensumme. 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 beschreibt das Modul 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. Jede Seite und das Gewicht werden auf die Mindestwerte von Mercado Envios für das Land angehoben, sodass auch Produkte ohne Maße oder Gewicht einen Tarif erhalten. Der Warenkorbwert wird als Artikelpreis in der Währung von Mercado Envios übermittelt. Der günstigste Tarif von Mercado Envios wird in die Standardwährung Ihres Shops umgerechnet und dann in der Warenkorbwährung des Kunden angezeigt.

Jedes Angebot wird 1 Stunde lang zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Ein fehlgeschlagenes Angebot wird 5 Minuten lang nicht wiederholt. Kann Mercado Pago nicht erreicht werden, lehnt es das Token ab oder begrenzt es die Anfragen, werden alle Live-Tarife 5 Minuten lang pausiert, damit die Kasse bei jeder Aktualisierung nicht auf die API warten muss. Das API-Zeitlimit beträgt 10 Sekunden.

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

Bearbeiten Sie den Versanddienstleister unter Shipping > Carriers, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.

Das Modul berechnet nur Tarife. Es erstellt keine Sendungen, druckt keine Etiketten und verfolgt keine Pakete. Legen Sie die Sendung in Ihrem Mercado-Libre- oder Mercado-Pago-Konto an. Es zeigt einen Preis, die günstigste Option von Mercado Envios, nicht eine 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 das Modul den Namen des Dienstes, die voraussichtliche Lieferzeit in Tagen und den Live-Tarif. Im Back-Office zeigt die Bestellseite einen Block Mercado Envios mit Mercado Envios service, Estimated delivery und Live rate (excl. tax). Der Kunde sieht Mercado Envios service und Estimated delivery auf der Bestelldetailseite seines Kontos. Bestehende Bestellungen werden von späteren Tarifänderungen nicht berührt.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Mercado Envios ist der erste Block auf Modules > Module Manager > VibeFox Mercado Envios > Configure, 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 gültig ist, und Ihre Domain) sowie die Buttons 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: presta-shipping-mercado-envios und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks richten sich nach der Sprache des Back-Office (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. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-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 der Versanddienstleister Mercado Envios Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Der PrestaShop-Storefront weiß nicht, dass Sie im Back-Office angemeldet sind, daher wird der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber nicht an der Kasse testen. Eine Erinnerung erscheint in Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind davon nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber für Updates und Support ist eine Verlängerung nötig. Der Status wird automatisch erneut geprüft, während Sie im Back-Office arbeiten: an den ersten 14 Tagen nach der Eingabe des Schlüssels einmal täglich, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls 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 eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes des Kunden und die Kundengruppe abdeckt (oder aktivieren Sie Ignore shipping zones und prüfen Sie Countries). Prüfen Sie die Warnungen oben auf der Modulseite, die Gewichtsgrenzen und Minimum subtotal. Der Versanddienstleister braucht einen Preis: ein funktionierendes Access Token für Adressen im Land von Mercado Envios oder Country prices bzw. Fallback cost. Außerdem können Produkte auf der Produktseite auf bestimmte Versanddienstleister beschränkt sein.

Live-Tarife erscheinen nicht: Aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie im Feld Log auf der Modulseite nach. 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: Das Access Token ist ungültig oder abgelaufen. Kopieren Sie das Access Token für die Produktionsumgebung erneut aus dem Entwicklerbereich von Mercado Pago.

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.

In welcher Währung sind die Preise? Country prices, Fallback cost und die Schwellenwerte 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 Modulseite auf Save. Dadurch werden die zwischengespeicherten Tarife gelöscht.

Die Seite meldet, dass der Versanddienstleister Mercado Envios nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn erneut anzulegen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Mercado Envios und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Die zwischengespeicherten Tarife werden immer entfernt. Ist Remove data on uninstall aktiviert, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), außerdem werden die Einstellungen, das Protokoll und die gespeicherten Dienstdaten der Bestellungen entfernt. Ist die Option deaktiviert, wird der Versanddienstleister nur deaktiviert, und alle Einstellungen sowie Dienstdaten der Bestellungen bleiben erhalten. Bei einer erneuten Installation des Moduls erhält der Versanddienstleister seinen Status von vor der Deinstallation zurück.

Mercado Envios und Mercado Pago sind Marken ihrer jeweiligen Inhaber. Dieses Modul ist weder mit Mercado Envios noch mit Mercado Pago verbunden und wird von diesen auch nicht unterstützt.