VibeFox Melhor Envio for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

Melhor-Envio-Konto (nur für Live-Tarife): Live-Tarife benötigen ein Zugriffstoken. Öffnen Sie in Ihrem Melhor-Envio-Konto die Seite mit den Zugriffsberechtigungen für Token (Integrações > Permissões de acesso, melhorenvio.com.br/painel/gerenciar/tokens) und erzeugen Sie ein Token mit der Berechtigung „shipping-calculate“. Zum Testen erzeugen Sie ein Token in der Sandbox von Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Produktions- und Sandbox-Token sind verschieden. Token laufen ab. Es gibt keinen Button zum Verbinden: Sie fügen das Token in die Einstellungen ein. Ohne Token verwendet die Methode die Ersatzpreise.

VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins aus und klicken Sie auf Install Now. Sie können den Ordner vfd_melhor_envio auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox Melhor Envio oder klicken Sie auf der Seite „Plugins“ unter dem Namen des Plugins auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Fügen Sie das Zugriffstoken, Ihre Kontakt-E-Mail-Adresse und die Ursprungs-CEP ein. Wenn die Währung Ihres Shops nicht BRL ist, legen Sie den BRL exchange rate fest. Optional können Sie die Tabelle mit Ersatzpreisen (zum Beispiel für Brasilien) oder eine Ersatzgebühr ausfüllen.

6. Legen Sie unter WooCommerce > Settings > Shipping > Shipping zones eine Zone für Brasilien an und fügen Sie VibeFox Melhor Envio hinzu, oder aktivieren Sie Ignore shipping zones und wählen Sie Länder aus.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Sie gelten für alle Versandzonen. Wenn Sie die Methode einer Zone hinzufügen, hat das Zonenfenster nur ein Feld:

Title (zone): der Name dieser Option an der Kasse. Lassen Sie das Feld leer, um den globalen Name zu verwenden.

Warnungen oben auf der Seite zeigen eine unvollständige Einrichtung an: eine Ursprungs-CEP, die nicht 8 Ziffern hat, eine fehlende Kontakt-E-Mail-Adresse, ein fehlender BRL-Wechselkurs, der letzte Fehler der Melhor-Envio-API mit Datum oder kein Token und kein Ersatzpreis. Bei jedem Speichern der Einstellungen wird der Cache der Tarife geleert.

Allgemein

Enable/Disable: schaltet den Versand über Melhor Envio in allen Zonen gleichzeitig ein oder aus.

Name: der Name der Versandmethode, den Kunden an der Kasse sehen. Standard: Melhor Envio.

Tax status: Taxable fügt die WooCommerce-Steuer zu den Versandkosten hinzu, None nicht.

Melhor Envio API

Access token: das Token der unten gewählten Umgebung. Es 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 an Melhor Envio übermittelt wird. Melhor Envio verlangt sie von jeder Integration.

Origin CEP: die CEP (8 Ziffern), von der die Pakete versendet werden, zum Beispiel 01310-100. Ohne gültige Ursprungs-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: legt fest, wie die Tarife angezeigt werden.

Delivery time: zeigt die Lieferzeit von Melhor Envio neben dem Namen an, zum Beispiel „(3-5 business days)“. Standard: ein.

Declared value: gibt den Produktwert (Versicherung) in den Tarifabfragen an. Ist es aus, werden Tarife ohne angegebenen Wert abgefragt: günstiger, aber die Pakete sind nicht versichert. Standard: ein.

BRL exchange rate: Melhor Envio rechnet in brasilianischen Real. Nur nötig, wenn die Währung Ihres Shops nicht BRL ist: Geben Sie den Preis von 1 BRL in der Währung Ihres Shops ein, zum Beispiel 0.17. Ohne ihn werden keine Live-Tarife verwendet. Der angegebene Wert wird mit demselben Kurs in BRL umgerechnet.

Default product weight (kg): wird für Produkte ohne Gewicht verwendet, sowohl bei den Tarifen als auch bei den Gewichtsgrenzen. Standard: 0.3.

Default product size (cm): Länge x Breite x Höhe, die für Produkte ohne Abmessungen verwendet wird. Standard: 16x11x5.

Fallback prices (in der Währung Ihres Shops)

Ersatzpreise werden verwendet, wenn kein Token vorliegt, die Ziel-CEP fehlt oder die API keinen 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 Kreuz, um sie zu entfernen. Wählen Sie * Any country 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 belegte 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 hat. Lassen Sie das Feld leer, um die Methode 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 (bei fehlendem Gewicht das Standardgewicht) den Ersatzpreis und multipliziert ihn mit der Menge. Dies gilt nur für Ersatzpreise. Die Tarife von Melhor Envio enthalten bereits alle Artikel.

Availability

Min weight (kg): blendet die Methode aus, wenn der Warenkorb weniger wiegt. 0 bedeutet keine Grenze.

Max weight (kg): blendet die Methode aus, wenn der Warenkorb mehr wiegt. Standard: 30. 0 bedeutet keine Grenze.

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

Free shipping from: die Warenkorb-Zwischensumme, 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 dies zu deaktivieren.

Excluded shipping classes: blendet die Methode aus, wenn der Warenkorb Artikel aus einer dieser WooCommerce-Versandklassen enthält.

Ignore shipping zones: bietet die Methode für die unten genannten Länder an, auch wenn sie keiner Versandzone hinzugefügt wurde.

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.

Advanced

Debug log: protokolliert API-Anfragen und die Tarifberechnung unter WooCommerce > Status > Logs (Quelle vfd-melhor-envio). Fehler werden immer protokolliert, auch wenn diese Option aus ist. Token und Kundenadressen werden nie protokolliert.

Remove data on uninstall: ist die Option aktiv, entfernt das Löschen des Plugins alle Plugin-Einstellungen und Zonenmethoden. Das Deaktivieren des Plugins löscht nie Einstellungen.

So funktioniert es an der Kasse

Sobald der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Tarif. Das Plugin prüft zuerst die Bedingungen: Warenkorbgewicht, Mindestzwischensumme und ausgeschlossene Versandklassen.

Bei einer Lieferadresse in Brasilien mit einer 8-stelligen CEP sendet das Plugin an Melhor Envio die Ursprungs- und die Ziel-CEP sowie jeden versandfähigen Artikel mit Gewicht, Größe, Menge und angegebenem Wert, zusätzlich die Serviceliste, falls Sie eine festgelegt haben. Die Tarife werden in die Währung Ihres Shops umgerechnet und nach Preis sortiert. Der Kunde sieht den günstigsten Service oder eine Option pro Service, mit der Lieferzeit, falls diese aktiviert ist. Gilt der kostenlose Versand, kostet der günstigste Service 0.

Jeder Tarif wird pro Paket, CEP und Umgebung 1 Stunde lang zwischengespeichert, damit 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. Die Zeitüberschreitung der API 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 meldet, werden die Ersatzpreise verwendet: die Zeile des Landes (oder die Zeile *), sonst die Ersatzgebühr. Gilt der kostenlose Versand, wird die Methode auch ohne Preis kostenlos angezeigt. Gibt es gar keinen Preis, wird die Methode ausgeblendet. Der Kunde sieht nie einen API-Fehler.

Die Methode funktioniert an der klassischen Kasse sowie im Warenkorb- und im Kassen-Block. Sie ist mit der WooCommerce-High-Performance-Bestellspeicherung (HPOS) kompatibel.

Das Plugin 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 Agenturen (Abgabestellen) bei Jadlog, Azul oder LATAM und keine Zusatzleistungen „Eigenhändig“ und „Empfangsbestätigung“. Verwalten Sie Sendungen in Ihrem Melhor-Envio-Panel. Melhor Envio liefert nur innerhalb Brasiliens. Andere Länder erhalten nur die Ersatzpreise.

Bestellungen

Wenn die Bestellung mit einem Live-Tarif aufgegeben wird, werden der Service und die Lieferzeit in der Versandposition der Bestellung gespeichert. Sie werden im Bestellbildschirm und in den Bestell-E-Mails als Melhor Envio service und Delivery estimate angezeigt, damit Sie wissen, welchen Service Sie in Melhor Envio buchen müssen. Bestehende Bestellungen behalten ihre Versandpositionen.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel funktioniert auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Melhor Envio Kunden an der Kasse nicht angezeigt. Angemeldete Shop-Manager sehen die Methode weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Auf der Seite „Plugins“ und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind davon nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

Melhor Envio erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Methode der Zone des Kundenlandes hinzugefügt wurde (oder Ignore shipping zones aktiv und das Land erlaubt ist). Beachten Sie die Warnungen oben auf der Einstellungsseite, die Gewichtsgrenzen, Minimum subtotal und Excluded shipping classes. Ohne Token oder Tarif braucht die Methode einen Ersatzpreis: eine Zeile in der Fallback price table oder eine Fallback cost.

Es werden nur Ersatzpreise angezeigt: Aktivieren Sie das Debug log, laden Sie die Kasse neu und öffnen Sie WooCommerce > Status > Logs, Quelle vfd-melhor-envio. Typische Ursachen: kein Token, eine Ursprungs-CEP mit nicht 8 Ziffern, kein BRL exchange rate bei einer anderen Shop-Währung als 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.

Welchen Preis Kunden sehen: bei einer Option den günstigsten von Melhor Envio gelieferten Service. Bei einer Option pro Service jeden Service, der die Strecke bedient. Per item gilt nur für Ersatzpreise.

Tarife wirken nach einer Änderung veraltet: Speichern Sie die Einstellungsseite. Dadurch wird der Tarif-Cache geleert.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel beispielsweise bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem letzten bekannten Status weiter.

Deinstallation

Das Deaktivieren des Plugins behält alle Einstellungen. Nur der Tarif-Cache wird geleert. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins sowie die zwischengespeicherten Tarife werden immer entfernt. Einstellungen und Zonenmethoden werden nur entfernt, wenn Remove data on uninstall aktiv war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Versandpositionen.

Melhor Envio ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit Melhor Envio verbunden und wird von Melhor Envio weder unterstützt noch empfohlen.