VibeFox FedEx for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer mit der cURL-Erweiterung. Ohne sie lässt sich das Modul nicht installieren.

FedEx-Konto und API-Schlüssel (nur für Live-Tarife): Erstellen Sie im FedEx Developer Portal (developer.fedex.com) ein Projekt mit der Rate API, verknüpfen Sie Ihr FedEx-Versandkonto und kopieren Sie den API Key und den Secret Key. Außerdem benötigen Sie Ihre 9-stellige FedEx-Kontonummer. Testschlüssel funktionieren nur mit eingeschaltetem Sandbox, Produktionsschlüssel nur mit ausgeschaltetem. Das Modul verwendet die FedEx REST API mit OAuth 2.0; es benötigt weder Meter Number noch Passwort für Webservices. Wenn Sie nur Festpreise nutzen, brauchen Sie keine FedEx-Schlüssel.

VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer 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. Klicken Sie nach Abschluss des Uploads auf Configure oder suchen Sie VibeFox FedEx später in der Modulliste und klicken Sie auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel in das Feld License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Geben Sie den API Key, den Secret Key, die 9-stellige FedEx-Kontonummer und die Ship from-Adresse ein (PLZ und bei den USA und Kanada den 2-stelligen Bundesstaat). Schalten Sie Sandbox aus, wenn Sie Produktionsschlüssel verwenden. Optional geben Sie Festpreise als Ausweichlösung ein. Klicken Sie auf Save.

Bei der Installation legt das Modul den Versanddienstleister FedEx mit dem Lieferzeittext FedEx delivery an. Der Versanddienstleister wird allen Zonen und allen Kundengruppen zugewiesen. Zonen, Kundengruppen, Lieferzeit, Logo und Größenbeschränkungen 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 FedEx > Configure. Sie gelten für alle Zonen des Versanddienstleisters. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Jedes Speichern leert außerdem das zwischengespeicherte FedEx-Token und die Tarife.

Oben auf der Seite zeigt das Modul Warnungen an: Nur einige der drei API-Zugangsdaten sind ausgefüllt, keine API-Schlüssel und keine Festpreise (dann wird der Versanddienstleister nie angezeigt), keine PLZ für den Versandort, kein Bundesstaat für den Versandort in den USA oder Kanada, eine Shop-Währung, die ohne Wechselkurs von der Währung des FedEx-Kontos abweicht, eine Gewichtseinheit des Shops (oder bei einer Paketgröße die Maßeinheit), die das Modul nicht kennt, oder ein gelöschter Versanddienstleister. Zahlenfelder akzeptieren einen Dezimalpunkt oder ein Komma. Eine ungültige Zahl oder Paketgröße, ein Wechselkurs von 0, eine Kontowährung, die kein 3-stelliger Code ist, und ein Name mit mehr als 64 Zeichen werden nicht gespeichert und gemeldet; das Feld behält seinen vorherigen Wert, die übrigen Felder werden gespeichert. Auch ein Mindestgewicht, das größer als das Höchstgewicht ist, wird gemeldet; beide Gewichte behalten ihre vorherigen Werte.

Allgemein

Enable/Disable: schaltet den Versand mit FedEx ein oder aus. Es ist derselbe Schalter wie der Status des Versanddienstleisters unter Shipping > Carriers.

Name: der Name der Versandart, den der Kunde an der Kasse sieht (der Name des Versanddienstleisters). Standard: FedEx. Pflichtfeld.

Tax status: die Steuerregel des Versanddienstleisters oder No tax. Mit einer Steuerregel (und aktivierten Steuern im Shop) rechnet PrestaShop die Steuer auf die Versandkosten auf, daher wird der FedEx-Betrag ohne Steuern verwendet. Bei No tax wird der FedEx-Nettobetrag unverändert übernommen.

FedEx-API (Live-Tarife)

Ohne Schlüssel werden die unten stehenden Festpreise verwendet. Der Abschnitt enthält die Schaltfläche Clear cached FedEx token and rates.

Sandbox: verwendet die FedEx-Sandbox (apis-sandbox.fedex.com) mit Testschlüsseln. Schalten Sie sie für echte Tarife (apis.fedex.com) mit Produktionsschlüsseln aus. Standard: ein.

API Key: der API Key (client_id) Ihres Projekts im FedEx Developer Portal.

Secret Key: der Secret Key (client_secret) desselben Projekts. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Wenn Sie den API Key löschen, wird auch der gespeicherte Secret Key entfernt.

FedEx account number: die 9-stellige FedEx-Versandkontonummer, die mit dem Projekt verknüpft ist. Für dieses Konto werden Kontotarife (verhandelt) berechnet.

Rates: Account rates (your negotiated FedEx prices) (Standard) oder List rates (FedEx published prices).

Residential delivery: berechnet Kundenadressen als Privatadressen (FedEx Home Delivery, Zuschlag für Privatzustellung). Schalten Sie dies aus, wenn Sie überwiegend an Unternehmen liefern. Standard: ein.

Box size: optionale Paketmaße in der Maßeinheit Ihres Shops, zum Beispiel 30x20x15. FedEx wendet dann das Dimensionsgewicht an. Lassen Sie das Feld leer, um nur nach Gewicht zu berechnen.

FedEx account currency: die Währung Ihres FedEx-Kontos, zum Beispiel USD für US-Konten oder CAD für Kanada. Standard: USD. FedEx wird immer auch gebeten, in der Standardwährung des Shops zu kalkulieren.

Exchange rate: nur nötig, wenn FedEx Tarife ausschließlich in der Kontowährung zurückgibt und die Standardwährung Ihres Shops eine andere ist: der Preis von 1 Einheit der Kontowährung in Ihrer Standardwährung, zum Beispiel 0.92. Ohne ihn werden solche Tarife nicht verwendet.

Versandort

Die Adresse, bei der FedEx die Pakete abholt oder bei der Sie sie abgeben. Wird für Live-Tarife verwendet.

Country: das Land, aus dem Sie versenden. Standard: United States.

State / province code: der 2-stellige Code, Pflicht für die USA und Kanada, zum Beispiel TN, CA oder ON.

City: die Stadt des Versandorts.

ZIP / postal code: die Postleitzahl des Versandorts. FedEx benötigt sie für die Berechnung der Tarife.

Festpreise

Sie werden verwendet, wenn keine API-Schlüssel eingegeben sind, und als Ausweichlösung, wenn FedEx keinen Tarif zurückgibt (API nicht erreichbar, falsche Schlüssel, kein Service). Lassen Sie beide Felder leer, um den Versanddienstleister in diesem Fall auszublenden.

Country prices: eine Tabelle mit 2-stelligen Ländercodes der Zielländer und Preisen in der Standardwährung Ihres Shops, ohne Steuern. Klicken Sie auf Add row, um ein Land hinzuzufügen, und auf das Papierkorb-Symbol, um eines zu entfernen. Verwenden Sie * als Ländercode für alle übrigen Länder. Zeilen, die kein Ländercode (oder *) mit einem Preis sind, werden beim Speichern ignoriert und gemeldet.

Fallback cost: ein fester Preis, wenn kein Länderpreis passt. Lassen Sie das Feld leer, um den Versanddienstleister auszublenden.

Fixed price is: Per order berechnet den Preis einmal. Per item (price x number of items) multipliziert ihn mit der Anzahl der Artikel im Warenkorb. Dies gilt nur für Festpreise. FedEx-Live-Tarife werden immer für das Gesamtgewicht des Warenkorbs berechnet.

Bedingungen

Free shipping from: die Zwischensumme des Warenkorbs (nach Rabatten, vor Steuern), ab der dieser Versanddienstleister kostenlos ist. Lassen Sie das Feld leer, um nie kostenlosen Versand anzubieten.

Minimum subtotal: zeigt den Versanddienstleister nur an, wenn die Zwischensumme des Warenkorbs mindestens diesen Betrag erreicht. Lassen Sie das Feld leer, um ihn immer anzuzeigen.

Min weight: das Mindestgewicht des Warenkorbs in kg, damit der Versanddienstleister erscheint. 0 bedeutet keine Grenze.

Max weight: das Höchstgewicht des Warenkorbs in kg. Der Versanddienstleister wird ausgeblendet, wenn es überschritten wird. 0 bedeutet keine Grenze.

Default product weight: das Gewicht in kg für Produkte ohne Gewicht, für die FedEx-Tarife und für die oben genannten Gewichtsgrenzen. Standard: 0.5. Produktgewichte werden aus der Gewichtseinheit Ihres Shops (kg, g, lb oder oz) umgerechnet, die unter International > Localization (Local units) festgelegt wird.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet den Versanddienstleister für die unten genannten Länder an, auch wenn deren Zone ihm nicht zugewiesen ist. Beim Speichern wird der Versanddienstleister mit allen Zonen verknüpft, auch mit später angelegten. Wenn Sie dies ausschalten, erhält der Versanddienstleister seine vorherigen Zonen zurück.

Countries: die Zielländer für diesen Modus. Lassen Sie das Feld leer, um alle Länder des Shops einzuschließen. Wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.

Erweitert

Debug log: protokolliert API-Anfragen und die Tarifberechnung in logs/vfd_fdx_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. API-Fehler werden immer protokolliert. 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 eingeschaltet, löscht die Deinstallation des Moduls alle Moduleinstellungen, den Versanddienstleister und die gespeicherten FedEx-Services der Bestellungen. Wenn ausgeschaltet, bleibt alles für eine erneute Installation erhalten.

So funktioniert es an der Kasse

Im Versandschritt fragt PrestaShop das Modul nach dem FedEx-Preis. Nur physische Produkte zählen: Virtuelle Produkte haben kein Gewicht und sind nicht in der Zwischensumme enthalten. Das Modul prüft zuerst die zulässigen Länder (mit Ignore shipping zones), das Gewicht des Warenkorbs und die Mindestzwischensumme. Gilt kostenloser Versand, beträgt der Preis 0, und es wird keine Anfrage an FedEx gesendet.

Andernfalls holt das Modul ein OAuth-Token und sendet an die FedEx Rate API die Versandadresse, die Lieferadresse, das Gewicht des Warenkorbs (in kg oder, für Shops mit lb oder oz, in lb), die Paketgröße, falls festgelegt, und Ihre Standardwährung als bevorzugte Währung. Für Länder, die eine Postleitzahl benötigen, wird die Anfrage erst gesendet, nachdem der Kunde eine eingegeben hat. Bei internationalen Sendungen wird der Zollwert des Warenkorbs übermittelt. Bundesstaatencodes werden nur für die USA und Kanada gesendet.

FedEx liefert die verfügbaren Services zurück. Für jeden Service übernimmt das Modul den von Ihnen gewählten Konto- oder Listentarif, bevorzugt einen Tarif in Ihrer Standardwährung, rechnet einen Tarif in der FedEx-Kontowährung mit Ihrem Wechselkurs um und verwirft Tarife, die es nicht umrechnen kann. Der günstigste Service bestimmt den Preis, und der Preis wird in der Warenkorbwährung des Kunden angezeigt.

Das Token wird je Umgebung und Schlüssel zwischengespeichert und automatisch neu angefordert, wenn FedEx es ablehnt. Berechnungen werden 1 Stunde zwischengespeichert. Eine fehlgeschlagene Tarifanfrage wird 10 Minuten lang gemerkt und eine fehlgeschlagene Token-Anfrage 5 Minuten lang, damit ein Ausfall nicht jede Aktualisierung der Kasse verlangsamt. Das Zeitlimit der API beträgt 15 Sekunden. Antwortet FedEx nicht, sieht der Kunde keine Fehlermeldung: Es wird der Festpreis verwendet oder der Versanddienstleister wird ausgeblendet. Der Grund wird im Debug-Protokoll festgehalten.

Wenn Sie den Versanddienstleister unter Shipping > Carriers bearbeiten, nachdem er Bestellungen hat, speichert PrestaShop ihn als neue Version des Versanddienstleisters. Das Modul folgt der neuen Version automatisch.

Das Modul berechnet nur Tarife. Es erstellt keine FedEx-Sendungen, druckt keine Etiketten, bucht keine Abholungen, verfolgt keine Pakete und lässt Kunden keinen FedEx-Standort wählen. Es zeigt eine Option (den günstigsten Service) statt mehrerer an, und es gibt keine Paketpackung: Der Warenkorb wird als ein Paket kalkuliert.

Bestellungen

Auf der Bestellseite im Back Office haben Bestellungen mit dem Versanddienstleister FedEx einen Block FedEx shipping. Er zeigt den FedEx service des Tarifs (bei Live-Tarifen), die Price source (FedEx live rate, Fixed price (no live rate) oder Free shipping threshold) und den Calculated price (excl. tax) in Ihrer Standardwährung. Die Werte werden beim Abschluss der Bestellung festgeschrieben: Spätere Änderungen der Einstellungen ändern sie nicht.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox FedEx ist der erste Block auf Modules > Module Manager > VibeFox FedEx > 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 gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zur erneuten Prüfung des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-shipping-fedex 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).

Wenn der Schlüssel nicht akzeptiert wird, 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 nachdem Sie in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul weiter mit dem zuletzt bekannten Status.

Ein Schlüssel funktioniert für eine Domain: die Domain des Haupt-Shops, auch in einer Multistore-Konfiguration. 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 FedEx-Versanddienstleister Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher wird der Versanddienstleister auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen bleiben unberührt.

Wenn eine Lizenz abläuft, arbeitet das Modul weiter, Updates und Support erfordern jedoch 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. Beim Deinstallieren oder Zurücksetzen des Moduls werden immer der Lizenzschlüssel und der Lizenzstatus entfernt.

Fehlerbehebung

FedEx erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist und Enable/Disable eingeschaltet ist. Prüfen Sie unter Shipping > Carriers, ob der Versanddienstleister die Zone des Landes und die Kundengruppe des Kunden abdeckt (oder schalten Sie Ignore shipping zones ein und prüfen Sie Countries). Beachten Sie die Warnungen oben auf der Modulseite, die Gewichtsgrenzen und die Minimum subtotal. Ohne Live-Tarif benötigt der Versanddienstleister einen Länderpreis, eine *-Zeile oder eine Fallback cost. Außerdem können Produkte auf der Produktseite auf bestimmte Versanddienstleister beschränkt sein.

Live-Tarife erscheinen nicht: Schalten Sie den Debug log ein, laden Sie die Kasse neu und sehen Sie sich das Feld Log auf der Modulseite an. Dort werden falsche Schlüssel, die falsche Umgebung (Testschlüssel mit ausgeschaltetem Sandbox oder Produktionsschlüssel mit eingeschaltetem), eine fehlende Lieferpostleitzahl und FedEx-Fehlercodes protokolliert.

Mein Shop nutzt nicht USD: FedEx wird um den Tarif in Ihrer Standardwährung gebeten. Gibt Ihr Konto nur seine eigene Währung zurück, stellen Sie FedEx account currency und Exchange rate ein. Ohne Wechselkurs werden solche Tarife ignoriert und der Festpreis verwendet, sodass ein USD-Betrag nie als Euro angezeigt wird.

Multipliziert „Per item“ den FedEx-Tarif? Nein. Per item gilt nur für Festpreise.

Tarife wirken nach einer Änderung veraltet: Beim Speichern der Modulseite wird der Cache geleert. Sie können auch auf Clear cached FedEx token and rates klicken.

Die Seite meldet, dass der FedEx-Versanddienstleister nicht gefunden wurde: Der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, um ihn neu anzulegen.

Nur einige Services sollen angeboten werden: Entwickler können Services mit dem Hook actionVfdFdxAllowedServices einschränken. Die Hooks actionVfdFdxRateRequest und actionVfdFdxApiBaseUrl ändern die Tarifanfrage und die API-Adresse.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox FedEx und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Zwischengespeicherte Token und Tarife werden immer entfernt. Ist Remove data on uninstall eingeschaltet, wird der Versanddienstleister gelöscht (Bestellungen behalten ihren Verlauf), und die Einstellungen, das Protokoll und die gespeicherten FedEx-Services der Bestellungen werden entfernt. Ist es ausgeschaltet, wird der Versanddienstleister nur deaktiviert und alle Einstellungen bleiben erhalten. Wenn Sie das Modul erneut installieren (oder Reset verwenden), erhält der gespeicherte Versanddienstleister seinen Status von vor der Deinstallation zurück.

FedEx ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit FedEx verbunden und wird von FedEx nicht unterstützt.