VibeFox Correios for WooCommerce — Hilfe
Anforderungen
WordPress: 5.8 oder neuer.
WooCommerce: 5.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.
PHP: 8.0 oder neuer.
Correios-Vertrag (nur für Live-Preise): Live-Preise nutzen die Preis-API der Correios Web Services (CWS) und benötigen die Zugangsdaten eines Correios-Vertrags mit Posting-Karte. Sie brauchen drei Angaben: Ihren Meu-Correios-Benutzer (meist die CNPJ oder CPF des Vertrags), den API-Zugangscode und die Nummer der Posting-Karte. Den Zugangscode erzeugen Sie im Portal der Correios Web Services (cws.correios.com.br; für Homologation cwshom.correios.com.br). Außerdem benötigen Sie die CEP, von der aus Sie versenden. Ohne Zugangsdaten arbeitet das Plugin nur mit Festpreisen.
VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 und klicken Sie auf Install Now. Sie können auch den Ordner vfd_correios per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox Correios, oder klicken Sie auf der Seite Plugins unter dem Plugin-Namen auf Settings.
4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.
5. Geben Sie den Correios-API-Benutzer, den Zugangscode, die Nummer der Posting-Karte, die Absende-CEP und den Service ein. Wenn Ihre Shop-Währung nicht BRL ist, tragen Sie den BRL-Kurs ein. Füllen Sie die Festpreise für andere Länder und als Ausweichpreis aus (siehe Konfiguration).
6. Fügen Sie VibeFox Correios unter WooCommerce > Settings > Shipping > Shipping zones einer Versandzone hinzu oder aktivieren Sie Ignore shipping zones und wählen Sie Länder.
Konfiguration
Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox Correios. Sie gelten für alle Versandzonen. Wenn Sie die Methode einer Zone hinzufügen, hat das Zonenfenster nur ein Feld:
Title (zone): der Name, der Kunden für diese Zone angezeigt wird. Leer lassen, um den globalen Method title zu verwenden.
Die Einstellungsseite zeigt Warnungen, wenn Live-Preise oder die Methode nicht funktionieren können: Nur einige der drei Zugangsdaten sind ausgefüllt, die Absende-CEP fehlt, der BRL-Kurs fehlt für einen Shop mit anderer Währung, oder es sind weder Zugangsdaten noch Festpreise hinterlegt. Bei jedem Speichern der Einstellungen werden die zwischengespeicherten Preise und der API-Token gelöscht. Zahlen können mit Punkt oder Komma eingegeben werden.
Allgemein
Enable/Disable: schaltet die Methode in allen Zonen gleichzeitig ein oder aus.
Method title: der Name der Versandmethode, der im Warenkorb und an der Kasse angezeigt wird. Standard: Correios. Eine Zone kann ihn mit einem eigenen Titel überschreiben.
Tax status: Taxable fügt die WooCommerce-Steuer auf die Versandkosten hinzu, None nicht.
Correios-API (Live-Preise in Brasilien)
Für Adressen in Brasilien stammt der Preis aus der Preis-API von Correios. Liefert die API keinen Preis (API nicht erreichbar, CEP nicht bedient, Paket zu groß), wird der Festpreis aus Country prices verwendet, oder die Methode wird ausgeblendet, wenn es keinen gibt.
API user: Ihr Login im Meu-Correios-Portal, meist die CNPJ oder CPF des Vertrags.
Access code: der API-Zugangscode (código de acesso), der im Portal der Correios Web Services erzeugt wird. Es ist nicht das Portalpasswort.
Posting card: die Nummer der Posting-Karte (cartão de postagem) Ihres Vertrags: 10 Ziffern, meist mit zwei führenden Nullen, zum Beispiel 0012345678. Kürzere Nummern werden mit führenden Nullen aufgefüllt. Sie können die Nummer auf der Seite Correios Fácil der Correios-Website prüfen.
Homologation: nutzt die Homologations- (Test-)Umgebung von Correios mit einem Homologations-Zugangscode. In einem Live-Shop ausschalten.
Origin CEP: die CEP (8 Ziffern), von der die Pakete versendet werden, zum Beispiel 01001-000.
Service: der Correios-Service, der an der Kasse bepreist wird. Einzelhandelscodes: PAC (04510, Standard), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Vertragscodes: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Vertragscodes benötigen eine Posting-Karte eines Vertrags, der den Service umfasst.
Other service code: optional, ein 5-stelliger Service-Code Ihres Vertrags, der nicht in der Liste steht, zum Beispiel 03085. Wenn er ausgefüllt ist, wird er anstelle von Service verwendet.
Package format: der Objekttyp, der an Correios gesendet wird.
Default product weight (kg): wird für jedes Produkt ohne Gewicht an Correios gesendet. Default: 0.3. Gewichte und Maße der Produkte werden aus den Einheiten Ihres Shops umgerechnet, und der Warenkorb wird als ein Paket bepreist.
BRL → store currency rate: der Feldname zeigt Ihre Shop-Währung an. Correios-Preise sind in BRL. Ist Ihre Shop-Währung nicht BRL, geben Sie ein, wie viele Einheiten Ihrer Währung einem BRL entsprechen, zum Beispiel 0.17. Ohne diesen Wert werden keine Live-Preise verwendet. Ist Ihre Shop-Währung BRL, lassen Sie das Feld leer.
Festpreise (für Länder außerhalb Brasiliens, ohne API-Zugangsdaten und als Ausweichpreis, wenn die API keinen Preis liefert)
Country prices: eine Tabelle mit Ländern, einem Base-Preis und Preisen nach Warenkorbgewicht in Ihrer Shop-Währung: XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL über 5 kg. Ein leerer oder Null-Preis für eine Größe verwendet den Base-Preis. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Kreuz, um sie zu entfernen. Die Zeile * Default (all other countries) legt Preise für alle Länder ohne eigene Zeile fest. Ein Land ohne Zeile (und ohne *) erhält keinen Festpreis. Ein Grundpreis von 0 bedeutet kostenlosen Versand für dieses Land.
Fixed price per: Order berechnet den Preis einmal. Item (price × quantity) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Dies gilt nur für Festpreise. Live-Preise werden immer für das gesamte Paket berechnet.
Bedingungen
Min cart weight (kg): blendet die Methode unterhalb dieses Warenkorbgewichts aus. 0 bedeutet keine Grenze.
Max cart weight (kg): blendet die Methode oberhalb dieses Warenkorbgewichts aus. Standard: 30. 0 bedeutet keine Grenze. Correios-Pakete PAC und SEDEX können bis zu 30 kg wiegen.
Minimum order amount: zeigt die Methode nur an, wenn die Zwischensumme des Warenkorbs diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.
Excluded shipping classes: blendet die Methode aus, wenn ein Artikel im Warenkorb eine dieser WooCommerce-Versandklassen hat.
Free shipping: aktiviert kostenlose Lieferung ab dem unten angegebenen Betrag.
Free shipping from: die Zwischensumme des Warenkorbs, ab der der Versand kostenlos ist. In diesem Fall wird keine API-Anfrage gestellt.
Verfügbarkeit ohne Versandzonen
Ignore shipping zones: bietet die Methode für die unten angegebenen Länder an, unabhängig von der passenden Zone.
Countries: die Zielländer für diesen Modus. Leer lassen, um alle Länder zu verwenden, in die der Shop liefert. Dieses Feld wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.
Erweitert
Debug log: protokolliert Preisberechnungen unter WooCommerce > Status > Logs, Quelle vfd-correios. API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Der API-Benutzer, der Zugangscode, die Posting-Karte, der Token und die CEPs der Kunden werden nicht protokolliert.
Remove data on uninstall: wenn eingeschaltet, entfernt das Löschen des Plugins seine Einstellungen, Zonenmethoden und zwischengespeicherten Preise. Das Deaktivieren des Plugins löscht nie etwas.
So funktioniert es an der Kasse
Wenn der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Preis. Das Plugin prüft zuerst die Bedingungen: Warenkorbgewicht, Mindestbestellwert und ausgeschlossene Versandklassen. Gilt kostenloser Versand, erhält der Kunde einen kostenlosen Tarif, und es wird keine Anfrage an Correios gesendet.
Für eine Adresse in Brasilien mit hinterlegten Zugangsdaten holt das Plugin zuerst einen API-Token für Ihre Posting-Karte. Der Token liefert außerdem die Nummern des Vertrags und des Regionalbüros, sodass der Preis dem Preis Ihres Vertrags entspricht. Danach fragt es den Preis des gewählten Service anhand der Absende- und Ziel-CEP, des Paketgewichts in Gramm und der Paketgröße in cm ab. Ein Preis wird nur angefragt, wenn die Ziel-CEP 8 Ziffern hat. Haben alle Produkte Maße, wird die Paketgröße daraus geschätzt; andernfalls wird die Mindestgröße von Correios gesendet. Pakete über 30 kg werden nicht an die API gesendet. Der BRL-Preis wird mit Ihrem Kurs umgerechnet. Der Service wird mit der Versandposition der Bestellung als Correios service gespeichert und ist im Bestellbereich des Admins sichtbar.
Jeder Preis wird 1 Stunde lang pro Paket zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten lang zwischengespeichert, damit ein API-Ausfall nicht jede Aktualisierung der Kasse verlangsamt. Der Token wird bis kurz vor seinem Ablauf zwischengespeichert und automatisch erneuert; weist Correios ihn zurück, wird ein neuer angefordert und die Preisanfrage einmal wiederholt. Das API-Timeout beträgt 12 Sekunden.
Liefert die API keinen Preis, wird der Festpreis verwendet, oder die Methode wird ausgeblendet, wenn kein Festpreis vorhanden ist. Der Kunde sieht nie API-Fehlerdetails; diese landen im WooCommerce-Protokoll.
Die Methode funktioniert an der klassischen Kasse sowie an den Warenkorb- und Checkout-Blöcken. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.
Das Plugin berechnet nur Tarife. Es ruft keine internationalen Correios-Preise ab (Exporta Fácil, Packet), keine Lieferzeitschätzungen, keine Labels, Vorabanmeldungen, Zollerklärungen oder Sendungsverfolgung. Kunden können keine Correios-Filiale oder kein Paketfach wählen. Zusatzleistungen (Wertangabe, Eigenhändig, Rückschein) werden nicht hinzugefügt. Es wird pro Shop ein Correios-Service angezeigt, und Währungskurse werden nicht automatisch aktualisiert.
Lizenzschlüssel
Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox Correios. 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 Correios Kunden an der Kasse nicht angezeigt. Angemeldete Shop-Manager sehen es weiterhin, markiert als (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Eine Erinnerung erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen.
Läuft eine Lizenz ab, arbeitet das Plugin weiter, für Updates und Support ist aber eine Verlängerung nötig. Der Status wird automatisch im Hintergrund erneut geprüft.
Fehlerbehebung
Correios erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Methode der Zone des Landes des Kunden hinzugefügt wurde (oder Ignore shipping zones eingeschaltet und das Land erlaubt ist). Prüfen Sie die Gewichtsgrenzen, Minimum order amount und Excluded shipping classes. Ohne Live-Preis muss ein Festpreis für das Land oder für * vorhanden sein.
Die Methode zeigt einen Festpreis statt des Correios-Preises: Öffnen Sie WooCommerce > Status > Logs, Quelle vfd-correios. Dort wird der Correios-Fehler protokolliert: falscher Zugangscode, Service nicht in Ihrem Vertrag, CEP nicht bedient, Paket über 30 kg oder über den Größenlimits. Prüfen Sie außerdem, ob die Absende-CEP gesetzt ist und, falls die Shop-Währung nicht BRL ist, der BRL-Kurs. Schalten Sie Debug log ein, um jede Berechnung zu sehen.
Token-Anfrage schlägt fehl: Prüfen Sie API-Benutzer, Zugangscode, Posting-Karte und Umgebung. Ein Homologations-Zugangscode funktioniert nur mit eingeschalteter Homologation, ein Produktions-Zugangscode nur mit ausgeschalteter.
Preise wirken nach einer Änderung veraltet: Speichern Sie die Einstellungsseite. Dadurch werden die zwischengespeicherten Preise und der API-Token gelöscht.
Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel 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 Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Einstellungen, Zonenmethoden und zwischengespeicherte Preise werden nur entfernt, wenn Remove data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestellungen werden nie angerührt.
Correios ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit Correios verbunden und wird nicht von Correios unterstützt.