VibeFox CTT 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.
CTT-E-Commerce-Konto (nur für Live-Tarife und CTT-Punkte): Live-Tarife und die Zustellung an einen CTT-Punkt nutzen die CTT-E-Commerce-API. Sie benötigen ein CTT-E-Commerce-Konto bei enviosecommerce.ctt.pt (für Kunden mit einem CTT-Expresso-Vertrag, oder fragen Sie bei CTT nach einem Angebot). Erstellen Sie auf der Schlüsselverwaltungsseite dieses Kontos ein Paar aus öffentlichem und privatem Schlüssel. Die App-ID (X-APPID) stellt CTT für Ihre Integration aus: Fragen Sie Ihren CTT-E-Commerce-Ansprechpartner. CTT entscheidet außerdem, welche API-Funktionen (Kostenschätzung, CTT-Punkte) Ihre App-ID nutzen darf. Schließlich benötigen Sie die Carrier-ID von CTT in Ihrem Konto. Die Einstellungsseite zeigt die Transportdienstleister Ihres Kontos an, sobald die Schlüssel gespeichert sind. Wenn Sie nur die Preistabelle und die Zustellung nach Hause nutzen, benötigen Sie keine API-Schlüssel.
VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel gilt für eine 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_ctt per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox CTT oder klicken Sie auf der Plugins-Seite 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üllen Sie die Preistabelle aus (mindestens eine Zeile Portugal oder * Default). Optional tragen Sie die CTT-API-Schlüssel und die Carrier-ID ein und aktivieren Live rates (siehe Konfiguration).
6. Öffnen oder erstellen Sie unter WooCommerce > Settings > Shipping > Shipping zones eine Zone für Portugal und fügen Sie VibeFox CTT hinzu. Wählen Sie in den Einstellungen der Methode den Titel und den Zustelltyp. Alternativ aktivieren Sie Ignore shipping zones und wählen die Länder aus.
Konfiguration
Preise, API-Schlüssel und Bedingungen befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox CTT. Sie gelten für jede Versandzone. Wenn Sie die Methode einer Zone hinzufügen, enthält das Zonenfenster zwei Felder:
Title (zone): der Name dieser Option an der Kasse in dieser Zone. Lassen Sie das Feld leer, um den globalen Name zu verwenden.
Delivery: To the customer's address (Standard) oder To a CTT point or parcel locker chosen at checkout. Ein CTT-Punkt benötigt die CTT-API-Schlüssel und die Carrier-ID in den globalen Einstellungen. Fügen Sie die Methode einer Zone zweimal hinzu, um Heimlieferung und Zustellung an einen CTT-Punkt nebeneinander anzubieten.
Hinweise oberhalb der Einstellungen informieren Sie über einen fehlenden Preis für Portugal, unvollständige API-Schlüssel, eine fehlende Carrier-ID, eine Shopwährung ohne Wechselkurs und einen fehlgeschlagenen Verbindungsaufbau zur CTT-API. Bei jedem Speichern der Einstellungen werden die zwischengespeicherten CTT-Antworten gelöscht.
Allgemein
Enable/Disable: schaltet die Methode in allen Zonen gleichzeitig ein oder aus.
Name: der Name der Versandmethode an der Kasse, zum Beispiel „CTT Expresso“. Standard: CTT. Ein Zonen-Title überschreibt ihn.
Tax status: Taxable fügt die WooCommerce-Versandsteuer (zum Beispiel IVA) auf den Preis auf, None bedeutet, dass der Preis endgültig ist.
CTT-E-Commerce-API (Live-Tarife, CTT-Punkte) (optional; ohne Schlüssel wird die Preistabelle verwendet)
Public key: der öffentliche Schlüssel von der Schlüsselverwaltungsseite Ihres CTT-E-Commerce-Kontos.
Private key: der geheime Schlüssel, mit dem jede Anfrage signiert wird (HMAC-SHA256). Er wird nie an CTT gesendet und nicht im Protokoll gespeichert.
App ID (X-APPID): der Anwendungsschlüssel, den CTT für Ihre Integration ausstellt.
Carrier ID: die ID des CTT-Transportdienstleisters in Ihrem Konto, die für Live-Tarife und die Suche nach CTT-Punkten verwendet wird. Nach dem Speichern der Schlüssel werden die Transportdienstleister Ihres Kontos unter dem Feld aufgelistet; diejenigen, die CTT-Punkte unterstützen, sind markiert.
Live rates: fragt bei CTT den Preis (Kostenschätzung) an, sobald der Kunde Straße, Postleitzahl und Ort eingegeben hat. Solange die Adresse unvollständig ist oder CTT keinen Preis liefert, wird die Preistabelle verwendet. CTT bezeichnet diesen Preis als Schätzung. Standard: aus.
Service ID: optional. Liefert CTT mehrere Dienste, wird der Dienst mit dieser ServiceId verwendet. Lassen Sie das Feld leer, um den günstigsten zu verwenden.
Exchange rate: CTT-Preise sind in Euro angegeben. Wenn Ihre Shopwährung abweicht, geben Sie an, wie viele Einheiten Ihrer Shopwährung 1 Einheit der CTT-Währung entsprechen. Ohne diesen Wert werden Live-Tarife in einer anderen Währung nicht verwendet und die Preistabelle gilt.
Default product size (cm): Länge x Breite x Höhe, die für Produkte ohne Abmessungen an CTT gesendet werden. Standard: 30x20x15. Produkte mit Abmessungen verwenden ihre eigenen. Abmessungen werden in cm und Gewichte in Gramm umgerechnet, ausgehend von den Einheiten Ihres Shops.
Preise (der Abschnittstitel zeigt Ihre Shopwährung an)
Geben Sie die Preise Ihres CTT-Vertrags oder der öffentlichen CTT-Preisliste in Ihrer Shopwährung ein. Bei ausgeschalteten Live-Tarifen legt diese Tabelle den Preis fest. Bei eingeschalteten Live-Tarifen dient sie als Ersatz.
Price table: eine Zeile pro Ziel. Wählen Sie ein Land, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) oder * Default (other destinations). Jede Zeile hat einen Grundpreis (Price) und optionale Preise für die Größen XS (bis 1 kg), S (bis 2 kg), M (bis 3 kg), L (bis 5 kg) und XL (über 5 kg). Ein leerer (oder 0) Größenpreis verwendet den Grundpreis. Eine Zeile, in der beide Felder leer sind, blendet die Methode aus. Die Azoren-Zeile gilt für portugiesische Postleitzahlen 9500–9999, die Madeira-Zeile (einschließlich Porto Santo) für 9000–9499. Ohne sie gilt die Zeile Portugal. Klicken Sie auf + Add destination, um eine Zeile hinzuzufügen, und auf das Kreuz, um eine zu entfernen. Preise akzeptieren einen Dezimalpunkt oder ein Dezimalkomma. Ungültige Zeilen werden beim Speichern gemeldet.
Calculation: so wird der Tabellenpreis ermittelt.
Ein Live-Preis von CTT gilt immer für die gesamte Sendung.
Bedingungen
Min weight (kg): das minimale Warenkorbgewicht, damit die Methode erscheint. 0 bedeutet keine Begrenzung.
Max weight (kg): die Methode wird oberhalb dieses Warenkorbgewichts ausgeblendet. Standard: 30 (CTT-Pakete sind bis 30 kg möglich). 0 bedeutet keine Begrenzung.
Minimum order amount: zeigt die Methode nur an, wenn die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern) diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.
Excluded shipping classes: blendet die Methode aus, wenn ein Artikel im Warenkorb zu einer dieser WooCommerce-Versandklassen gehört.
Kostenloser Versand
Free shipping: aktiviert die kostenlose CTT-Zustellung ab dem unten angegebenen Betrag.
Free shipping from: die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern), ab der diese Methode 0 kostet. Gilt nur, wenn die Methode einen Preis hat. Wird nur verwendet, wenn Free shipping aktiviert ist.
Verfügbarkeit ohne Versandzonen
Ignore shipping zones: bietet die Methode in den unten genannten Ländern an, wenn die Zone des Kunden sie nicht enthält.
Countries: die Zielländer für diesen Modus. Standard: Portugal. Lassen Sie das Feld leer, um alle Länder zu verwenden, in die Sie liefern. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.
Erweitert
Debug log: protokolliert die Preisberechnung und die CTT-API-Aufrufe unter WooCommerce > Status > Logs, Quelle vfd-ctt. CTT-API-Fehler werden immer protokolliert, auch wenn dies ausgeschaltet ist. Schlüssel, Token und Kundenadressen werden nie protokolliert.
Remove data on uninstall: ist die Option aktiviert, entfernt das Löschen des Plugins seine Einstellungen und Zonenmethoden. Das Deaktivieren des Plugins löscht nie Daten. Bestellungen werden nie verändert.
So funktioniert es an der Kasse
Wenn der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Preis. Das Plugin prüft zuerst das Warenkorbgewicht, den Mindestbestellwert und die ausgeschlossenen Versandklassen. Sind Live rates aktiviert und die Adresse vollständig, sendet es die Lieferadresse sowie für jede Warenkorbposition Menge, Gewicht in Gramm und Abmessungen in cm an CTT und zeigt den zurückgegebenen Preis an. Andernfalls, oder wenn CTT keinen Preis liefert (API-Fehler, Zeitüberschreitung, keine Abdeckung, eine für Ihre App-ID nicht aktivierte Funktion), stammt der Preis aus der Tabelle. Gilt der kostenlose Versand, beträgt der Preis 0.
Ein CTT-Preis wird 1 Stunde lang zwischengespeichert, damit derselbe Warenkorb keine neue Anfrage auslöst. Eine fehlgeschlagene Anfrage wird 5 Minuten lang gemerkt, damit die Kasse bei jeder Aktualisierung nicht auf CTT warten muss. Das Zeitlimit der API beträgt 12 Sekunden.
Die Methode funktioniert an der klassischen Kasse sowie im Warenkorb- und Kassen-Block. Sie ist mit dem WooCommerce High-Performance Order Storage (HPOS) kompatibel.
Sind die API-Schlüssel ausgefüllt, sendet das Plugin Lieferadresse, Produktgewichte und -abmessungen sowie die URL Ihres Shops an CTT, um einen Preis oder die nächstgelegenen CTT-Punkte zu erhalten.
Das Plugin erstellt keine Sendungen, druckt keine Etiketten, beauftragt keine Abholungen, stellt keine Sendungsnummern bereit und zeigt keine Karte mit CTT-Punkten an. Es gibt eine Preistabelle und einen Satz API-Einstellungen für den gesamten Shop. Zonen unterscheiden sich durch Titel und Zustelltyp.
Abholpunkte
Bei einer Zonenmethode mit Delivery auf einem CTT-Punkt erscheinen an der Kasse unter der Methode ein Suchfeld und eine Liste. Die Lieferadresse wird automatisch durchsucht. Der Kunde kann nach Postleitzahl oder Ort nach anderen CTT-Punkten suchen und muss vor der Bestellung einen auswählen. Dies wird auch serverseitig geprüft. Die Listen der CTT-Punkte werden 6 Stunden lang zwischengespeichert. Ist CTT nicht erreichbar, sieht der Kunde eine Meldung und kann es später erneut versuchen oder eine andere Versandart wählen.
Der gewählte Punkt wird in der Bestellung gespeichert. Er wird in der Bestellverwaltung unter der Lieferadresse, auf der Bestelleingangsseite, unter My account > Orders und in den Bestell-E-Mails (HTML und Nur-Text) als CTT point angezeigt.
Klicken Sie in der Bestellverwaltung neben dem CTT-Punkt auf Change, suchen Sie nach Postleitzahl oder Ort und wählen Sie einen anderen Punkt. Die Änderung wird sofort gespeichert und fügt der Bestellung eine Notiz hinzu.
Lizenzschlüssel
Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox CTT. 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 gilt für eine 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 CTT Kunden an der Kasse nicht angezeigt. Angemeldete Shop-Manager sehen es weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen.
Läuft eine Lizenz ab, funktioniert das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.
Fehlerbehebung
CTT 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 aktiviert ist und das Land erlaubt ist). Prüfen Sie, ob das Ziel eine Zeile in der Preistabelle hat (oder eine Zeile * Default), ob das Warenkorbgewicht innerhalb von Min weight und Max weight liegt, ob der Minimum order amount erreicht ist und ob kein Produkt zu einer ausgeschlossenen Versandklasse gehört.
Der Kunde kann keinen CTT-Punkt wählen: Die Auswahl erscheint nur für eine Zonenmethode mit Delivery auf einem CTT-Punkt und nur, wenn öffentlicher Schlüssel, privater Schlüssel, App-ID und Carrier-ID ausgefüllt sind. Aktivieren Sie das Debug log und prüfen Sie WooCommerce > Status > Logs.
Live-Tarife erscheinen nicht: Die Preistabelle wird verwendet, bis der Kunde Straße, Postleitzahl und Ort eingegeben hat. Prüfen Sie die Hinweise oberhalb der Einstellungen und das Protokoll. Die Antwort „405“ bedeutet, dass die Funktion für Ihre App-ID nicht aktiviert ist: Fragen Sie CTT. In einem Shop, der nicht in Euro arbeitet, tragen Sie den Exchange rate ein.
Die Verbindung zur CTT-API ist fehlgeschlagen: Der Hinweis oberhalb der Einstellungen zeigt den Fehler. Prüfen Sie die Schlüssel und die App-ID. Das Plugin versucht es nach einigen Minuten automatisch erneut.
Preise mit oder ohne MwSt.: Mit Tax status auf Taxable fügt WooCommerce die Versandsteuer auf den Preis auf. Bei None ist der Preis endgültig.
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, ebenso die zwischengespeicherten CTT-Antworten und das API-Token. Einstellungen und Zonenmethoden werden nur entfernt, wenn Remove data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestellungen einschließlich des gewählten CTT-Punkts werden nie verändert, und bestehende Bestellungen behalten ihre Versandpositionen.
CTT ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit CTT verbunden und wird nicht von CTT unterstützt.