VibeFox Correios 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.
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 einer Posting-Karte. Sie brauchen drei Werte: Ihren Meu-Correios-Benutzer (in der Regel 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 die Homologation cwshom.correios.com.br). Außerdem benötigen Sie die CEP, von der Sie versenden. Ohne Zugangsdaten arbeitet das Modul nur mit Festpreisen.
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 Correios in der Modulliste und klicken Sie 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. Geben Sie den Correios-API-Benutzer, den Zugangscode, die Nummer der Posting-Karte, die Ursprungs-CEP und den Service ein. Wenn die Standardwährung Ihres Shops nicht BRL ist, geben Sie den BRL-Kurs ein. Füllen Sie die Festpreise für andere Länder und als Ausweichpreis aus (siehe Konfiguration) und klicken Sie auf Save.
Bei der Installation legt das Modul den Transporteur Correios mit dem Lieferzeittext Correios (Brazilian Post) an. Der Transporteur wird allen Zonen und allen Kundengruppen zugewiesen. 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 Correios > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern löscht außerdem die zwischengespeicherten Correios-Preise und API-Token. Zahlen können mit Punkt oder Komma eingegeben werden.
Die Seite zeigt Warnungen, wenn Live-Preise oder der Transporteur nicht funktionieren können: Nur einige der drei Zugangsdaten sind ausgefüllt, die Ursprungs-CEP fehlt, der BRL-Kurs fehlt bei einem Shop mit anderer Währung, oder es sind weder Zugangsdaten noch Festpreise vorhanden. Jede Warnung sagt, ob in der Zwischenzeit die Festpreise verwendet werden oder der Transporteur ausgeblendet wird. Eine Warnung erscheint auch, wenn die Gewichts- oder Maßeinheit des Shops dem Modul unbekannt ist (sie wird dann als kg bzw. cm gelesen). Stellen Sie kg, g, lb oder oz sowie cm, mm, m oder in unter International > Localization (Local units) ein.
Das Speichern wird mit einer Meldung abgelehnt, wenn der Methodentitel leer oder ungültig ist (maximal 64 Zeichen), ein Zahlenfeld oder ein Preis unter Country prices keine Zahl von 0 oder mehr ist, der BRL-Kurs 0 ist, Min cart weight größer als Max cart weight ist, die Ursprungs-CEP nicht 8 Ziffern hat oder der andere Service-Code mehr als 5 Ziffern hat. Nichts wird gespeichert, bis Sie den Wert korrigieren.
Allgemein
Enable Correios: schaltet den Transporteur in allen Zonen gleichzeitig ein oder aus. Dies ist derselbe Schalter wie der Status des Transporteurs unter Shipping > Carriers.
Method title: der Name des Transporteurs, der im Warenkorb und an der Kasse angezeigt wird. Standard: Correios. Pflichtfeld.
Tax: die Steuerregel, die auf die Versandkosten aufgeschlagen wird, oder No tax (der Standard).
Correios-API (Live-Preise in Brasilien)
Für Adressen in Brasilien stammt der Preis aus der Preis-API von Correios. Wenn die API keinen Preis liefert (API nicht erreichbar, CEP nicht bedient, Paket zu groß), wird der Festpreis aus Country prices verwendet, oder der Transporteur wird ausgeblendet, wenn kein Festpreis vorhanden ist. Fehlerdetails gehen in das Protokoll, nie an den Kunden.
API user: Ihr Anmeldename im Meu-Correios-Portal, in der Regel 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. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it (empty the API user as well to remove it). Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Um den gespeicherten Code zu entfernen, leeren Sie sowohl API user als auch Access code und speichern Sie.
Posting card: die Nummer der Posting-Karte (cartão de postagem) Ihres Vertrags: 10 Ziffern, in der Regel beginnend mit zwei Nullen, zum Beispiel 0012345678. Kürzere Nummern werden mit führenden Nullen ergänzt. Sie können die Nummer auf der Seite Correios Fácil der Correios-Website prüfen.
Homologation: nutzt die Testumgebung (Homologation) von Correios: Anfragen gehen an apihom.correios.com.br mit einem Homologationszugangscode. Schalten Sie sie in einem Live-Shop aus.
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 enthält.
Other service code: optional, ein 5-stelliger Service-Code Ihres Vertrags, der nicht in der Liste steht, zum Beispiel 03085. Ein kürzerer Code wird mit führenden Nullen ergänzt. Wenn er ausgefüllt ist, wird er anstelle von Service verwendet.
Package format: die Objektart, die an Correios gesendet wird.
Default product weight: in kg, wird für jedes Produkt ohne Gewicht an Correios gesendet. Standard: 0.3. Produktgewichte und -maße werden aus den Einheiten Ihres Shops umgerechnet (die Feldbeschreibung zeigt sie an), und der Warenkorb wird als ein Paket bepreist.
BRL → store currency rate: der Feldname zeigt die Standardwährung Ihres Shops, zum Beispiel BRL → EUR rate. Correios-Preise sind in BRL. Wenn Ihre Standardwährung nicht BRL ist, geben Sie ein, wie viele Einheiten Ihrer Währung einem BRL entsprechen, zum Beispiel 0.17. Ohne diesen Wert werden keine Live-Preise verwendet. Der Kurs muss größer als 0 sein. Wenn Ihre Standardwährung BRL ist, lassen Sie das Feld leer.
Festpreise (werden für Länder außerhalb Brasiliens, ohne API-Zugangsdaten und als Ausweichpreis verwendet, wenn die API keinen Preis liefert)
Country prices: eine Tabelle von Ländern mit einem Base-Preis und Preisen nach Warenkorbgewicht in der Standardwährung Ihres Shops, ohne Steuern: XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL über 5 kg. Ein leerer oder Nullpreis für eine Größe verwendet den Base-Preis. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf das Kreuz, um eine zu entfernen. Die Zeile * Default (all other countries) legt die Preise für alle Länder ohne eigene Zeile fest. Ein Land ohne Zeile (und ohne *) erhält keinen Festpreis. Eine Zeile ohne jeden Preis wird nicht gespeichert. Ein Preis, der keine Zahl oder negativ ist, bricht das Speichern mit einem Fehler ab. Ein Basispreis 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: in kg, blendet den Transporteur unterhalb dieses Warenkorbgewichts aus. 0 bedeutet kein Limit. Er darf nicht größer als Max cart weight sein.
Max cart weight: in kg, blendet den Transporteur oberhalb dieses Warenkorbgewichts aus. Standard: 30. 0 bedeutet kein Limit, ein leeres Feld bedeutet 30 kg. Correios-PAC- und SEDEX-Pakete können bis zu 30 kg wiegen.
Minimum order amount: zeigt den Transporteur nur an, wenn die Zwischensumme des Warenkorbs (Produkte, die versendet werden müssen, nach Rabatten, vor Steuern) diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.
Free shipping: aktiviert kostenlosen Versand ab dem unten angegebenen Betrag.
Free shipping from: die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern), ab der der Versand kostenlos ist. In diesem Fall wird keine API-Anfrage gestellt.
Verfügbarkeit ohne Versandzonen
Normalerweise wird der Transporteur in den Zonen angezeigt, denen er unter Shipping > Carriers zugewiesen ist.
Ignore shipping zones: bietet den Transporteur für die unten angegebenen Länder an, unabhängig von der passenden Zone. Beim Speichern wird der Transporteur allen Zonen hinzugefügt. Wenn Sie die Option deaktivieren, werden die von ihr hinzugefügten Zonen entfernt. Eine später angelegte Zone wird automatisch hinzugefügt, solange die Option aktiv ist.
Countries: die Zielländer für diesen Modus. Leer lassen, um alle aktiven Länder des Shops zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.
Erweitert
Debug log: schreibt die Preisberechnungen in logs/vfd_crr_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. API-Benutzer, Zugangscode, Posting-Karte, Token und CEPs der Kunden werden nicht protokolliert.
Log: zeigt die Größe und die neuesten Einträge des Debug-Protokolls. Klicken Sie auf Clear log, um es zu leeren.
Remove data on uninstall: wenn aktiviert, löscht die Deinstallation des Moduls die Einstellungen, den Transporteur, die Bestellservices, die zwischengespeicherten Preise und das Protokoll. Wenn deaktiviert, bleibt alles für eine erneute Installation erhalten.
So funktioniert es an der Kasse
Im Versandschritt fragt PrestaShop das Modul nach dem Correios-Preis. Nur physische Produkte zählen: Virtuelle Produkte haben kein Gewicht und sind nicht im Bestellwert enthalten. Das Modul prüft zuerst die Bedingungen: erlaubte Länder (mit Ignore shipping zones), Warenkorbgewicht und Mindestbestellwert. Gilt kostenloser Versand, beträgt der Preis 0 und es wird keine Anfrage an Correios gesendet.
Bei einer Adresse in Brasilien mit hinterlegten Zugangsdaten holt das Modul zuerst einen API-Token für Ihre Posting-Karte. Der Token liefert zudem die Nummern des Vertrags und der Regionalstelle, sodass der Preis der Preis Ihres Vertrags ist. Danach fragt es den Preis des gewählten Services anhand der Ursprungs- 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. Wenn alle Produkte Maße haben, 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 Preis wird in Ihrer Standardwährung berechnet und danach in der Warenkorbwährung des Kunden angezeigt.
Jeder Preis wird pro Paket 1 Stunde lang zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten lang zwischengespeichert, damit ein API-Ausfall nicht jede Aktualisierung an der Kasse verlangsamt. Der Token wird bis kurz vor seinem Ablauf zwischengespeichert und automatisch erneuert; weist Correios ihn ab, wird ein neuer Token angefordert und die Preisanfrage einmal wiederholt. Das API-Zeitlimit beträgt 12 Sekunden.
Wenn die API keinen Preis liefert, wird der Festpreis verwendet, oder der Transporteur wird ausgeblendet, wenn kein Festpreis vorhanden ist. Der Kunde sieht nie Details zu API-Fehlern; diese gehen in das Debug-Protokoll.
Wenn Sie den Transporteur unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Transporteur-Version. Das Modul folgt der neuen Version automatisch.
Das Modul 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 Paketstation wählen. Zusatzleistungen (deklarierter Wert, eigenhändige Übergabe, Empfangsbestätigung) werden nicht hinzugefügt. Pro Shop wird ein Correios-Service angezeigt, und Währungskurse werden nicht automatisch aktualisiert.
Bestellungen
Wenn eine Bestellung mit dem Correios-Transporteur aufgegeben wird, speichert das Modul, wie sein Versandpreis berechnet wurde. Die Bestellseite im Back Office zeigt dann einen Block Correios mit Correios service (bei einem Live-Preis, zum Beispiel PAC — contract (03298)) und Price source: Live price (Correios API), Fixed price oder Free shipping.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Correios ist der erste Block auf Modules > Module Manager > VibeFox Correios > Configure, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain) sowie die Schaltflächen 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-correios 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).
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. Nachdem sich die Shop-Adresse geändert hat oder Sie einen Domain-Platz in Ihrem Konto 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-Einrichtung. 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 einen aktiven Schlüssel wird der Correios-Transporteur an der Kasse nicht angezeigt und es wird kein Tarif berechnet. Das PrestaShop-Frontend weiß nicht, dass Sie im Back Office angemeldet sind, daher ist der Transporteur 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 der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen.
Wenn eine Lizenz abläuft, arbeitet das Modul weiter, aber Updates und Support erfordern 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 der Eingabe des Schlüssels, 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
Correios erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable Correios eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Transporteur die Zone des Landes des Kunden und die Kundengruppe abdeckt (oder ob Ignore shipping zones eingeschaltet ist und das Land erlaubt ist). Kontrollieren Sie die Gewichtslimits und Minimum order amount. Ohne Live-Preis muss ein Festpreis für das Land oder für * vorhanden sein. Produkte können auf der Produktseite außerdem auf bestimmte Transporteure beschränkt sein.
Der Transporteur zeigt einen Festpreis statt des Correios-Preises: Sehen Sie sich das Feld Log auf der Modulseite an. Dort werden 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 Ursprungs-CEP gesetzt ist, die CEP des Kunden 8 Ziffern hat und, falls die Standardwä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 den API-Benutzer, den Zugangscode, die Posting-Karte und die Umgebung. Ein Homologationszugangscode funktioniert nur, wenn Homologation eingeschaltet ist, und ein Produktionscode nur, wenn sie ausgeschaltet ist.
Preise wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten Preise und der API-Token gelöscht.
Die Seite meldet, dass der Correios-Transporteur nicht gefunden wurde: Der Transporteur wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn erneut anzulegen.
Beim Speichern erscheint die Meldung, dass Sie keine Berechtigung haben: Ihr Mitarbeiterprofil kann das Modul sehen, aber nicht konfigurieren. Zum Speichern der Einstellungen und zum Leeren des Protokolls ist die Berechtigung zum Konfigurieren des Moduls erforderlich.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Correios und wählen Sie Uninstall. Der Lizenzschlüssel, der Lizenzstatus sowie die zwischengespeicherten Preise und Token werden immer entfernt. Wenn Remove data on uninstall eingeschaltet ist, wird der Transporteur gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, die gespeicherten Bestellservices und das Protokoll werden entfernt. Ist die Option ausgeschaltet, wird der Transporteur nur deaktiviert und alle Einstellungen bleiben erhalten. Wird das Modul erneut installiert, wird der Transporteur mit dem Status wiederhergestellt, den er zuvor hatte.
Correios ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Correios verbunden und wird nicht von Correios unterstützt.