VibeFox CTT 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.
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 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 Ansprechpartner für CTT-E-Commerce danach. 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 listet die Versanddienstleister Ihres Kontos auf, sobald die Schlüssel gespeichert sind. Wenn Sie nur die Preistabelle und die Zustellung an die Adresse nutzen, benötigen Sie keine API-Schlüssel.
VibeFox-Lizenzschlüssel: Erwerb auf vibefox.net. Ein Schlüssel gilt 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.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später in der Modulliste nach VibeFox CTT und klicken Sie 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üllen Sie die Preistabelle aus (mindestens eine Zeile Portugal oder * Default) und klicken Sie auf Save. Optional können Sie die CTT-API-Schlüssel und die Carrier ID eintragen sowie Live rates und Enable CTT point carrier aktivieren (siehe Konfiguration).
Bei der Installation legt das Modul zwei Versanddienstleister an. CTT (Zustellung an die Adresse des Kunden, Lieferzeit-Text CTT delivery to your address) ist aktiviert. CTT point / parcel locker (Lieferzeit-Text Pickup at a CTT point or parcel locker) ist deaktiviert, bis Sie ihn einschalten. Beide sind mit der Zone Portugal und allen Kundengruppen verknüpft. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbegrenzungen können Sie unter Shipping > Carriers ändern. Legen Sie dort keine Preise fest: Der Preis stammt immer aus dem Modul.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox CTT > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Die Preise und Bedingungen gelten für beide CTT-Versanddienstleister. Bei jedem Speichern werden die zwischengespeicherten CTT-Antworten gelöscht, einschließlich des API-Tokens und der CTT-Punktlisten.
Warnungen oberhalb der Einstellungen weisen auf eine leere Preistabelle, einen fehlenden Preis für Portugal, unvollständige API-Schlüssel, eine fehlende Carrier ID, eine Shopwährung außer EUR ohne Wechselkurs, einen fehlgeschlagenen Verbindungsaufbau zur CTT-API und einen gelöschten CTT-Versanddienstleister hin. Ungültige Werte werden beim Speichern gemeldet: Eine ungültige Zahl wird nicht gespeichert, ein unbekanntes Ziel oder eine doppelte Zeile in der Preistabelle wird entfernt. Wenn die Gewichts- oder Maßeinheit Ihres Shops dem Modul unbekannt ist, bittet Sie eine Warnung, die Einheiten unter International > Localization (Local units) festzulegen.
Allgemein
Enable/Disable: schaltet die CTT-Zustellung an die Adresse des Kunden ein oder aus. Es ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.
Name: der Name des Versanddienstleisters, der dem Kunden an der Kasse angezeigt wird, zum Beispiel "CTT Expresso". Standard: CTT. Pflichtfeld, bis zu 64 Zeichen.
Tax status: None bedeutet, dass die Preise endgültig sind. Taxable mit einer Steuerregel bedeutet, dass PrestaShop die Versandsteuer (zum Beispiel IVA) auf die Preise aufschlägt. Die Auswahl wird für beide CTT-Versanddienstleister gespeichert.
Zustellung an einen CTT-Punkt oder Paketautomaten
Der zweite CTT-Versanddienstleister. Der Kunde sucht CTT-Punkte nach Postleitzahl oder Ort und muss vor dem Fortfahren einen auswählen. Dafür werden die CTT-API-Schlüssel und die Carrier ID benötigt. Ohne sie handelt es sich um einen Versanddienstleister ohne Punktauswahl.
Enable CTT point carrier: schaltet den CTT-Punkt-Versanddienstleister ein oder aus. Es ist derselbe Schalter wie sein Status unter Shipping > Carriers. Standard: aus.
CTT point carrier name: der Name dieser Option an der Kasse. Standard: CTT point / parcel locker. Pflichtfeld, bis zu 64 Zeichen.
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 weder an CTT gesendet noch im Protokoll geschrieben.
Beide Schlüssel werden nach dem Speichern nie wieder angezeigt. Die Feldbeschreibung lautet dann Saved - leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie sie ändern möchten. Aktivieren Sie Remove the saved public and private key und speichern Sie, um beide zu löschen.
App ID (X-APPID): der von CTT ausgestellte Anwendungsschlüssel, der im Header X-APPID gesendet wird.
Carrier ID: die ID des CTT-Versanddienstleisters in Ihrem Konto, verwendet für Live-Tarife und die CTT-Punktsuche. Nach dem Speichern der Schlüssel und der App ID werden die Versanddienstleister Ihres Kontos unter dem Feld aufgelistet, wobei diejenigen, die CTT-Punkte unterstützen, mit (CTT points) markiert sind. Nur Zahlen.
Live rates: Das Modul 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 derjenige mit dieser ServiceId verwendet. Lassen Sie das Feld leer, um den günstigsten zu verwenden.
Exchange rate: CTT-Preise sind in Euro. Wenn die Standardwährung Ihres Shops eine andere ist, 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. Die Abmessungen werden in cm und die Gewichte in Gramm umgerechnet, ausgehend von den Einheiten Ihres Shops.
Preise (der Abschnittstitel zeigt die Standardwährung Ihres Shops)
Geben Sie die Preise Ihres CTT-Vertrags oder der öffentlichen CTT-Preisliste auf ctt.pt ein, in der Standardwährung des Shops, ohne Steuern. Bei deaktivierten Live-Tarifen legt diese Tabelle den Preis fest. Bei aktivierten Live-Tarifen dient sie als Ausweichpreis.
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 den Versanddienstleister aus. Die Zeile Azores gilt für portugiesische Postleitzahlen 9500-9999, die Zeile Madeira (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 Papierkorb-Symbol, um eine zu entfernen. Preise akzeptieren einen Dezimalpunkt oder ein Komma. Die Tabelle ist nach der Installation leer.
Calculation: so wird der Preis aus der Tabelle ermittelt.
Ein Live-Tarif von CTT gilt immer für die gesamte Sendung.
Bedingungen
Min weight (kg): das minimale Warenkorbgewicht, damit die Versanddienstleister angezeigt werden. 0 bedeutet keine Begrenzung.
Max weight (kg): die Versanddienstleister werden oberhalb dieses Warenkorbgewichts ausgeblendet. Standard: 30 (CTT-Pakete bis 30 kg). 0 bedeutet keine Begrenzung. Min weight (kg) darf nicht größer sein als Max weight (kg): Die Einstellungen werden dann nicht gespeichert.
Minimum order amount: Die Versanddienstleister werden nur angezeigt, wenn die Zwischensumme des Warenkorbs (Produkte mit Versand, nach Rabatten, vor Steuern) diesen Betrag erreicht. Lassen Sie das Feld leer, um sie immer anzuzeigen.
Kostenloser Versand
Free shipping: schaltet die kostenlose CTT-Zustellung ab dem unten angegebenen Betrag ein.
Free shipping from: die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern), ab der die Versanddienstleister 0 kosten. Sie gilt nur für Ziele, die einen Preis haben. Wird nur verwendet, wenn Free shipping aktiviert ist.
Verfügbarkeit ohne Versandzonen
Normalerweise werden die Versanddienstleister in den Versandzonen angeboten, mit denen sie unter Shipping > Carriers verknüpft sind.
Ignore shipping zones: bietet die Versanddienstleister in den unten angegebenen Ländern an, ohne sie ihrer Zone zuzuordnen. Wenn Sie es einschalten, werden beide Versanddienstleister mit jeder aktiven Zone verknüpft (auch mit Zonen, die Sie später anlegen). Wenn Sie es ausschalten, erhalten sie wieder die Zonen, die sie vorher hatten.
Countries: die Zielländer für diesen Modus. Standard: Portugal. Lassen Sie das Feld leer, um alle Länder zuzulassen. Wird nur verwendet, wenn Ignore shipping zones aktiviert ist. Kunden in den Zonen, die die Versanddienstleister vorher hatten, werden immer bedient.
Erweitert
Debug log: protokolliert die Preisberechnung und die CTT-API-Aufrufe in logs/vfd_ctt_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. CTT-API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Schlüssel, Token und Kundenadressen werden nie protokolliert.
Log: zeigt die Größe und die neuesten Einträge des Protokolls an. Klicken Sie auf Clear log, um es zu leeren.
Remove data on uninstall: Wenn aktiviert, löscht die Deinstallation des Moduls seine Einstellungen und seine Versanddienstleister. Wenn deaktiviert, werden bei der Deinstallation nur die Versanddienstleister ausgeschaltet. Bestellungen, einschließlich des gewählten CTT-Punkts, werden nie verändert.
So funktioniert es an der Kasse
Im Versandschritt fragt PrestaShop das Modul nach dem Preis jedes CTT-Versanddienstleisters. Nur physische Produkte zählen: Virtuelle Produkte erhöhen weder das Gewicht, noch werden sie im Bestellwert berücksichtigt. Das Modul prüft zuerst Ignore shipping zones und dessen Länder, das Warenkorbgewicht und den Mindestbestellwert. Mit aktivierten Live rates und einer vollständigen Adresse sendet es die Lieferadresse an CTT sowie für jede Warenkorbzeile die Menge, das Gewicht in Gramm und die Abmessungen in cm und verwendet den zurückgegebenen Preis. 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 kostenloser Versand, beträgt der Preis 0. Der Preis wird in der Standardwährung Ihres Shops berechnet und anschließend in der Warenkorbwährung des Kunden angezeigt.
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 wartet. Das Zeitlimit der API beträgt 12 Sekunden. API-Fehler erreichen den Kunden nie: Es wird der Preis aus der Tabelle verwendet, oder der Versanddienstleister wird ausgeblendet, wenn das Ziel keinen Preis hat.
Wenn Sie einen Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.
Mit ausgefüllten API-Schlüsseln sendet das Modul die Lieferadresse, die Produktgewichte und -abmessungen sowie die URL Ihres Shops an CTT, um einen Preis oder die nächstgelegenen CTT-Punkte zu erhalten.
Das Modul 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 beide Versanddienstleister.
Abholpunkte
Wenn der Kunde den CTT-Punkt-Versanddienstleister wählt, erscheinen darunter ein Suchfeld und eine Liste. Die Postleitzahl der Lieferadresse wird eingetragen und automatisch gesucht. Der Kunde kann andere CTT-Punkte nach Postleitzahl oder Ort suchen (Schaltfläche Search oder Eingabetaste) und einen aus der Liste wählen. Die Auswahl wird sofort im Warenkorb gespeichert. Es wird nur ein Punkt aus der CTT-Liste für diese Suche akzeptiert.
Ein Punkt muss gewählt werden, bevor der Kunde fortfahren kann. Wenn der Kunde im Versandschritt auf Continue klickt, prüft das Modul den Punkt erneut auf dem Server. Ohne Punkt sieht der Kunde Please select a CTT point., bei einem Punkt, der nicht in der CTT-Liste steht, The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. Die CTT-Punktlisten werden 6 Stunden lang zwischengespeichert. Wenn CTT nicht erreicht werden kann, sieht der Kunde CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
Die Punktauswahl funktioniert mit den Themes Classic und Hummingbird. Sie ist nur aktiv, wenn der öffentliche Schlüssel, der private Schlüssel, die App ID und die Carrier ID ausgefüllt sind.
Der gewählte Punkt wird in der Bestellung gespeichert. Er wird in der Bestellansicht im Back Office im Block CTT point (Name und ID) angezeigt, auf der Bestellbestätigungsseite und in den Bestelldetails im Kundenkonto sowie in der Bestellbestätigungs-E-Mail als CTT point: neben dem Namen des Versanddienstleisters. Die neue Bestell-E-Mail des Moduls Mail alerts zeigt ebenfalls die ID des Punkts an.
Geben Sie in der Bestellansicht im Back Office unter Change CTT point eine Postleitzahl oder einen Ort ein, klicken Sie auf Search, wählen Sie einen Punkt und klicken Sie auf Save. Die Seite zeigt CTT point updated., und eine private Bestellnachricht CTT point changed to: mit dem neuen Punkt wird hinzugefügt. Das Ändern des Punkts erfordert die Berechtigung, Bestellungen zu bearbeiten.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox CTT ist der erste Block auf Modules > Module Manager > VibeFox CTT > Configure, oberhalb der 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-ctt 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 Adresse des Shops geändert hat 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 keiner der beiden CTT-Versanddienstleister (Zustellung an die Adresse oder an einen CTT-Punkt) Kunden an der Kasse angezeigt, und es wird kein Tarif berechnet. Der PrestaShop-Shop weiß nicht, dass Sie im Back Office angemeldet sind, daher werden die Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht an der Kasse testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen.
Läuft eine Lizenz ab, 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 Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Die Deinstallation oder das Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
CTT erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable/Disable (oder Enable CTT point carrier) eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe abdeckt oder ob Ignore shipping zones eingeschaltet und das Land erlaubt ist. Prüfen Sie, ob das Ziel eine Zeile in der Preistabelle (oder eine Zeile * Default) hat, ob das Warenkorbgewicht innerhalb von Min weight und Max weight liegt und ob der Minimum order amount erreicht ist. Auf der Produktseite lassen sich Produkte außerdem auf bestimmte Versanddienstleister beschränken.
Der Kunde kann keinen CTT-Punkt wählen: Die Auswahl erscheint nur unter dem CTT-Punkt-Versanddienstleister und nur, wenn der öffentliche Schlüssel, der private Schlüssel, die App ID und die Carrier ID ausgefüllt sind. Prüfen Sie die Warnungen oberhalb der Einstellungen, schalten Sie Debug log ein und sehen Sie im Feld Log auf der Modulseite nach.
Live-Tarife erscheinen nicht: Die Preistabelle wird verwendet, bis der Kunde Straße, Postleitzahl und Ort eingegeben hat. Prüfen Sie die Warnungen 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, füllen Sie Exchange rate aus.
Die Verbindung zur CTT-API ist fehlgeschlagen: Die Warnung oberhalb der Einstellungen zeigt den Fehler an. Prüfen Sie die Schlüssel und die App ID. Das Modul versucht es nach einigen Minuten automatisch erneut.
Preise mit oder ohne MwSt.: Mit Tax status auf einer Regel Taxable schlägt PrestaShop die Versandsteuer auf den Preis auf. Bei None ist der Preis endgültig.
Preise wirken nach einer Änderung veraltet: Klicken Sie auf der Modulseite auf Save. Dadurch werden die zwischengespeicherten CTT-Antworten gelöscht.
Die Seite meldet, dass ein CTT-Versanddienstleister nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn erneut anzulegen. Ein Zurücksetzen behält die Einstellungen und den Ein-/Aus-Status beider Versanddienstleister bei.
Für Entwickler: Die Adresse der CTT-API kann mit dem Konfigurationsschlüssel vfd_ctt_API_URL geändert werden.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox CTT und wählen Sie Uninstall. Der Lizenzschlüssel, der Lizenzstatus, die zwischengespeicherten CTT-Antworten und das API-Token werden immer entfernt. Wenn Remove data on uninstall aktiviert ist, werden beide Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, das Protokoll sowie die CTT-Punkte von Warenkörben, die nie zu Bestellungen wurden, werden entfernt. Ist die Option deaktiviert, werden die Versanddienstleister nur ausgeschaltet und alle Einstellungen bleiben erhalten. Wird das Modul erneut installiert, erhält jeder Versanddienstleister den Ein-/Aus-Status zurück, den er zuvor hatte. In Bestellungen gespeicherte CTT-Punkte bleiben immer erhalten.
CTT ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit CTT verbunden und wird nicht von CTT unterstützt.