VibeFox Melhor Envio 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.
Melhor-Envio-Konto (nur für Live-Tarife): Live-Tarife benötigen ein Zugriffstoken. Öffnen Sie in Ihrem Melhor-Envio-Konto die Token-Seite (melhorenvio.com.br/painel/gerenciar/tokens) und erzeugen Sie ein Token mit der Berechtigung „shipping-calculate“. Zum Testen erzeugen Sie ein Token in der Melhor-Envio-Sandbox (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Produktions- und Sandbox-Token sind verschieden. Es gibt keine Schaltfläche „verbinden“: Sie fügen das Token in die Moduleinstellungen ein. Ohne Token verwendet der Versanddienstleister die Ersatzpreise.
VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer 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. Später finden Sie VibeFox Melhor Envio in der Modulliste und klicken dort auf Configure.
3. Fügen 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ügen Sie das Zugriffstoken, Ihre Kontakt-E-Mail-Adresse und die Versand-CEP ein. Wenn die Standardwährung Ihres Shops nicht BRL ist, legen Sie BRL exchange rate fest. Optional füllen Sie die Tabelle mit Ersatzpreisen (zum Beispiel für Brasilien) oder eine Ersatzgebühr aus. Klicken Sie auf Save.
Bei der Installation legt das Modul den Versanddienstleister Melhor Envio mit dem Lieferzeittext Delivery by the carriers of your Melhor Envio account an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugeordnet. Zonen, Kundengruppen, Lieferzeit, Logo und Größenlimits können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis kommt immer vom Modul.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Melhor Envio > Configure. Sie gelten für alle Zonen des Versanddienstleisters. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern leert außerdem die zwischengespeicherten Tarife von Melhor Envio und den letzten API-Fehler.
Warnungen oben auf der Seite zeigen eine unvollständige Einrichtung an: ein leerer Versand-CEP oder einer mit nicht 8 Ziffern, eine fehlende Kontakt-E-Mail-Adresse, ein fehlender BRL-Wechselkurs, der letzte API-Fehler von Melhor Envio mit Datum, fehlendes Token, fehlender Ersatzpreis (dann wird der Versanddienstleister nie angezeigt) oder eine Gewichts- bzw. Maßeinheit des Shops, die das Modul nicht kennt (sie wird dann als kg bzw. cm gelesen). Wenn ein Zahlenfeld etwas enthält, das keine Zahl von 0 oder mehr ist, Min weight größer als Max weight ist oder Default product size nicht im Format Länge x Breite x Höhe angegeben ist, zeigt die Seite einen Fehler an und es wird nichts gespeichert.
General
Enable Melhor Envio shipping: schaltet den Versanddienstleister ein oder aus. Dies ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.
Name: der Name des Versanddienstleisters, den Kunden an der Kasse sehen. Standard: Melhor Envio. Pflichtfeld, höchstens 64 Zeichen.
Tax: die Steuerregel des Versanddienstleisters oder No tax. Die Preise von Melhor Envio sind endgültige Preise des Versanddienstleisters. Wählen Sie No tax, wenn PrestaShop keine Steuer darauf aufschlagen soll.
Melhor Envio API
Access token: das Token der unten ausgewählten Umgebung. Es wird als Bearer-Token an Melhor Envio gesendet. Nach dem Speichern bleibt das Feld leer und zeigt A token is saved — leave empty to keep it. an. Geben Sie nur dann ein neues Token ein, wenn Sie es ändern möchten. Um das gespeicherte Token zu löschen, aktivieren Sie Remove the saved token und speichern Sie. Das Token wird nie ins Protokoll geschrieben.
Sandbox: nutzt die Sandbox von Melhor Envio (sandbox.melhorenvio.com.br) zum Testen. Verwenden Sie dafür ein Sandbox-Token. Standard: aus.
Contact e-mail: eine technische Kontakt-E-Mail-Adresse, die bei jeder Anfrage im User-Agent-Header an Melhor Envio gesendet wird. Melhor Envio verlangt sie von jeder Integration. Eine ungültige Adresse wird nicht gespeichert, und ein Hinweis weist darauf hin.
Origin CEP: die CEP (8 Ziffern), von der die Pakete versendet werden, zum Beispiel 01310-100. Sie wird im Format 00000-000 gespeichert. Ohne gültige Versand-CEP werden keine Tarife angefragt.
Services: optionale, durch Kommas getrennte Service-IDs von Melhor Envio für die Tarifabfrage, zum Beispiel 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Leer lassen, um alle Services Ihres Kontos abzufragen.
Quotes at checkout: wie die Tarife angezeigt werden.
Delivery time: zeigt die Lieferzeitangabe von Melhor Envio an der Kasse an, zum Beispiel „3-5 business days“. Standard: ein.
Declared value: deklariert den Warenwert (Versicherung) in den Tarifabfragen. Ist die Option aus, werden Tarife ohne deklarierten Wert abgefragt: günstiger, aber die Pakete sind nicht versichert. Standard: ein.
BRL exchange rate: Melhor Envio rechnet in brasilianischen Real. Dies wird nur benötigt, wenn die Standardwährung Ihres Shops nicht BRL ist: Geben Sie den Preis von 1 BRL in Ihrer Standardwährung ein, zum Beispiel 0.17. Ohne ihn werden Live-Tarife nicht verwendet. Der Wert muss größer als 0 sein. Der deklarierte Wert wird mit demselben Kurs in BRL umgerechnet. Wenn Ihre Standardwährung BRL ist, zeigt das Feld Store currency is BRL an.
Default product weight: in kg, für Produkte ohne Gewicht, sowohl für die Tarife als auch für die Gewichtslimits. Muss größer als 0 sein. Standard: 0.3.
Default product size: Länge x Breite x Höhe in cm, für Produkte ohne Abmessungen. Standard: 16x11x5.
Ersatzpreise (in der Standardwährung Ihres Shops)
Ersatzpreise werden verwendet, wenn kein Token vorliegt, die Ziel-CEP fehlt oder die API kein Tarif liefert (Fehler, Zeitüberschreitung, keine Abdeckung).
Fallback price table: Preis nach Land und Warenkorbgewicht. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Papierkorb-Symbol, um eine zu entfernen. Wählen Sie * Default als Land für alle Länder ohne eigene Zeile. Jede Zeile hat einen Price und Gewichtsspalten: XS bis 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg und XL über 5 kg. Eine leere oder mit 0 gefüllte Spalte verwendet Price. Sowohl „9.99“ als auch „9,99“ werden akzeptiert. Werte, die keine Zahlen sind, werden nach dem Speichern gemeldet und ignoriert.
Fallback cost: wird verwendet, wenn die Tabelle ebenfalls keinen Preis enthält. Lassen Sie das Feld leer, um den Versanddienstleister in diesem Fall auszublenden.
Fallback calculation: Per order berechnet den Ersatzpreis einmal. Per item (each item priced by its own weight x quantity) sucht für das Gewicht jedes Artikels den Ersatzpreis (das Standardgewicht, wenn der Artikel keines hat) und multipliziert ihn mit der Menge. Wenn ein Artikel keinen Preis hat, wird der Versanddienstleister ausgeblendet. Dies gilt nur für Ersatzpreise. Die Tarife von Melhor Envio enthalten bereits alle Artikel.
Verfügbarkeit
Min weight: blendet den Versanddienstleister aus, wenn der Warenkorb weniger wiegt, in kg. 0 bedeutet kein Limit.
Max weight: blendet den Versanddienstleister aus, wenn der Warenkorb mehr wiegt, in kg. Standard: 30. 0 bedeutet kein Limit. Ein leeres Feld bedeutet 30 kg in den Zonen des Versanddienstleisters und kein Limit nur für die Länder unter Ignore shipping zones, die außerhalb davon liegen.
Minimum subtotal: zeigt den Versanddienstleister nur, wenn die Zwischensumme des Warenkorbs (versandpflichtige Produkte, nach Rabatten, vor Steuern) mindestens diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.
Free shipping from: die Zwischensumme des Warenkorbs, ab der der Versand kostenlos ist. Bei einer Option pro Service wird nur der günstigste Service kostenlos. Schnellere Services behalten ihren Preis. Leer lassen, um die Funktion zu deaktivieren.
Ignore shipping zones: bietet den Versanddienstleister in den unten genannten Ländern an, auch wenn er diesen Zonen nicht zugeordnet ist. Solange diese Option aktiv ist, wird der Versanddienstleister allen Zonen zugeordnet, einschließlich inaktiver Zonen und später erstellter Zonen. Wenn Sie sie ausschalten, erhält der Versanddienstleister wieder seine eigenen Zonen zurück.
Countries: die Zielländer für diesen Modus. Leer lassen für alle Länder. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiv ist.
Erweitert
Debug log: schreibt API-Anfragen und die Tarifberechnung in logs/vfd_menv_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert, auch wenn diese Option aus ist. Das Token wird nie protokolliert, und die CEP des Kunden wird auf ihre ersten 5 Ziffern gekürzt.
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 aktiv, löscht die Deinstallation des Moduls alle Moduleinstellungen, den Versanddienstleister und das Protokoll. Wenn inaktiv, bleibt alles für eine erneute Installation erhalten. Der Tarif-Cache wird immer entfernt. Die mit Bestellungen gespeicherten Services sind Teil der Bestellhistorie und bleiben erhalten.
So funktioniert es an der Kasse
Im Versandschritt fragt PrestaShop das Modul nach dem Preis von Melhor Envio. Nur versandpflichtige Produkte zählen: Virtuelle Produkte haben kein Gewicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft zuerst die Bedingungen: die Länder unter Ignore shipping zones, das Warenkorbgewicht und die Mindestzwischensumme.
Bei einer Lieferadresse in Brasilien mit einer 8-stelligen CEP sendet das Modul an Melhor Envio die Versand- und Ziel-CEP sowie jeden versandpflichtigen Artikel mit Gewicht, Größe, Menge und deklariertem Wert, außerdem die Serviceliste, falls Sie eine festgelegt haben. Die Tarife werden in Ihre Standardwährung umgerechnet, nach Preis sortiert und dann in der Warenkorbwährung des Kunden angezeigt. Wenn kostenloser Versand gilt, kostet der günstigste Service 0.
Bei One option - the cheapest service zeigt der Versanddienstleister den Preis des günstigsten Services und unter dem Versanddienstleister die Zeile Delivery estimate:, wenn Delivery time aktiv ist. Bei One option per service sieht der Kunde unter dem Versanddienstleister Choose a delivery service: mit einem Optionsfeld pro Service, dessen Preis und der Lieferzeitangabe. Die Auswahl wird sofort gespeichert, und der Preis des Versanddienstleisters sowie die Warenkorbübersicht werden aktualisiert. Wenn der Service für die Adresse nicht mehr angeboten wird, sieht der Kunde This service is not available for your address any more. Please choose another one. und die vorherige Auswahl kehrt zurück.
Jeder Tarif wird pro Paket, CEP, Token und Umgebung 1 Stunde lang zwischengespeichert, sodass derselbe Warenkorb keine neue Anfrage auslöst. Ein fehlgeschlagener Aufruf wird 5 Minuten lang gemerkt, damit ein API-Ausfall nicht jede Aktualisierung der Kasse verlangsamt. Das API-Zeitlimit beträgt 12 Sekunden.
Wenn kein Token vorliegt, die Adresse außerhalb Brasiliens liegt oder noch keine gültige CEP hat, der BRL-Wechselkurs fehlt oder Melhor Envio einen Fehler oder keinen Service für die Strecke zurückgibt, werden die Ersatzpreise verwendet: die Zeile des Landes (oder die Zeile *), sonst die Ersatzgebühr. Wenn kostenloser Versand gilt, wird der Versanddienstleister kostenlos angezeigt, auch ohne Preis. Gibt es überhaupt keinen Preis, wird der Versanddienstleister ausgeblendet. Der Kunde sieht nie einen API-Fehler.
Wenn Sie den Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.
Das Modul berechnet nur Preise. Es kauft oder erstellt keine Etiketten, legt keine Sendungen in den Warenkorb von Melhor Envio, verfolgt keine Pakete, plant keine Abholungen und übermittelt keine Rechnungsdaten (NF-e). Es bietet keine Auswahl von Jadlog-, Azul- oder LATAM-Agenturen (Abgabestellen) und keine Zusatzleistungen „eigenhändige Übergabe“ und „Rückschein“ an. Verwalten Sie Sendungen in Ihrem Melhor-Envio-Panel. Melhor Envio versendet nur innerhalb Brasiliens. Andere Länder erhalten nur die Ersatzpreise.
Bestellungen
Wenn eine Bestellung mit einem Live-Tarif aufgegeben wird, speichert das Modul den Service von Melhor Envio und seine Lieferzeitangabe mit der Bestellung. Die Bestellseite im Back Office zeigt einen Block Melhor Envio mit Melhor Envio service (mit der Service-ID) und Delivery estimate, damit Sie wissen, welchen Service Sie bei Melhor Envio buchen müssen. Der Kunde sieht dieselben Angaben auf der Bestellseite in seinem Konto. In der Bestellbestätigungs-E-Mail werden sie nach dem Namen des Versanddienstleisters ergänzt. Bestellungen mit Ersatzpreis haben keinen Service. Bestehende Bestellungen bleiben unverändert.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Melhor Envio ist der erste Block auf Modules > Module Manager > VibeFox Melhor Envio > Configure, ü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 gültig 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: presta-shipping-melhor-envio 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 folgen der Sprache des Back Office (Englisch und Russisch sind enthalten).
Ist der Schlüssel nicht gültig, 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 das Modul mit dem zuletzt bekannten Status weiter.
Ein Schlüssel gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Installation. 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 von Melhor Envio den Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Das 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 unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen bleiben unverändert.
Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support benötigen eine Verlängerung. Der Status wird während Ihrer Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal wöchentlich. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Melhor Envio erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Melhor Envio shipping eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes 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 Gewichtslimits und Minimum subtotal. Ohne Token oder Tarif braucht der Versanddienstleister einen Ersatzpreis: eine Zeile in Fallback price table oder eine Fallback cost. Produkte können auf der Produktseite außerdem auf bestimmte Versanddienstleister beschränkt sein.
Es werden nur Ersatzpreise angezeigt: Aktivieren Sie Debug log, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Modulseite an. Typische Ursachen: kein Token, eine Versand-CEP mit nicht 8 Ziffern, kein BRL exchange rate bei einer Standardwährung außer BRL, noch keine Ziel-CEP oder kein Service deckt die Strecke ab.
HTTP 401 oder 403 im Protokoll oder in den Warnungen: Melhor Envio hat das Zugriffstoken abgelehnt. Es ist falsch, abgelaufen oder widerrufen oder gehört zur anderen Umgebung. Erzeugen Sie ein neues Token und prüfen Sie, ob Sandbox dazu passt.
Der Kunde sieht „The service could not be saved. Please try again.“: Die Auswahl ist nicht im Shop angekommen, zum Beispiel wegen eines Netzwerkfehlers. Der Kunde kann den Service erneut wählen. Der Service, der beim Klick des Kunden auf Continue ausgewählt ist, wird ebenfalls gespeichert.
Auf den Preis von Melhor Envio wird Steuer aufgeschlagen: Stellen Sie Tax auf No tax ein.
Die Tarife wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Das leert die zwischengespeicherten Tarife.
Die Seite meldet, dass der Versanddienstleister von Melhor Envio nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn neu anzulegen.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Melhor Envio und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Der Tarif-Cache wird immer entfernt. Ist Remove data on uninstall aktiv, wird der Versanddienstleister gelöscht (Bestellungen behalten ihre Historie), seine eigenen Zonen werden wiederhergestellt, und die Einstellungen, die Serviceauswahl offener Warenkörbe und das Protokoll werden entfernt. Ist die Option aus, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren, erhält der Versanddienstleister den Status zurück, den er vorher hatte. Die mit Bestellungen gespeicherten Services bleiben immer erhalten.
Melhor Envio ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Melhor Envio verbunden und wird nicht von Melhor Envio unterstützt.