VibeFox UPS for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer, mit der cURL-Erweiterung. Das Modul lässt sich auf älteren PHP-Versionen oder ohne cURL nicht installieren.

UPS-Developer-Portal-App (nur für Live-Tarife): melden Sie sich im UPS Developer Portal (developer.ups.com) an, erstellen Sie eine App mit dem Produkt „Rating“, verknüpfen Sie Ihr UPS-Konto und kopieren Sie die Client ID und das Client Secret. Das Modul verwendet OAuth 2.0. Es werden kein Access Key, kein Benutzername und kein Passwort benötigt. Für verhandelte Tarife brauchen Sie außerdem Ihre 6-stellige UPS-Kontonummer. Ohne Zugangsdaten werden nur die festen Preise verwendet.

VibeFox-Lizenzschlüssel: 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox UPS 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 die Client ID und das Client Secret, Ihre UPS-Kontonummer (für verhandelte Tarife) und die Adresse Ship from ein: die Postleitzahl und bei USA und Kanada das 2-stellige Kürzel des Bundesstaats.

5. Wenn die Währung Ihres UPS-Kontos von der Standardwährung Ihres Shops abweicht, geben Sie UPS account currency und Exchange rate ein.

6. Optional können Sie feste Preise als Ausweichlösung eingeben und auf Save klicken.

Bei der Installation erstellt das Modul den Versanddienstleister UPS mit dem Lieferzeittext UPS delivery. 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 kommt immer vom Modul.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox UPS > 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 den zwischengespeicherten UPS-Token und die Tarife. Außerdem können Sie im Abschnitt UPS API auf Clear cached UPS token and rates klicken.

Hinweise oberhalb der Einstellungen zeigen an, wenn nur eines von Client ID und Client Secret gesetzt ist, keine Zugangsdaten und keine festen Preise vorhanden sind (der Versanddienstleister wird dann nie angezeigt), die Postleitzahl oder der Bundesstaat der Versandadresse fehlt, Kontotarife ohne Kontonummer gewählt sind, der Wechselkurs fehlt oder die Gewichts- bzw. Maßeinheit des Shops dem Modul unbekannt ist. Ungültige Zahlen, eine falsche Kartongröße und ein Min weight, das über Max weight liegt, werden beim Speichern gemeldet, und der alte Wert bleibt erhalten.

Allgemein

Enable UPS shipping: schaltet den Versanddienstleister 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. Standard: UPS. Pflichtfeld, höchstens 64 Zeichen.

Tax status: die Steuerregel des Versanddienstleisters oder None. UPS-Tarife werden ohne Steuern angegeben. Mit einer Steuerregel fügt der Shop seine Versandsteuer obendrauf hinzu.

UPS-API (Live-Tarife)

Test mode: nutzt die UPS-Testumgebung. Testtarife sind keine echten Preise. Für Live-Tarife ausschalten. Standard: aus.

Client ID: die Client ID Ihrer App im UPS Developer Portal. Wenn Sie sie leeren, wird auch das gespeicherte Client Secret entfernt.

Client Secret: das Client Secret derselben App. Nach dem Speichern bleibt das Feld leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

UPS account number: Ihre 6-stellige UPS-Versendernummer, zum Beispiel A1B2C3. Für Kontotarife (verhandelt) erforderlich, für öffentliche Tarife optional.

Rates: welche UPS-Preise verwendet werden.

Measurement units: die Einheiten, die an UPS gesendet werden. Shop-Gewichte und -Maße werden umgerechnet.

Residential delivery: Kundenadressen als Wohnadressen mit dem UPS-Zuschlag für Wohnadressen berechnen. Ausschalten, wenn Sie überwiegend an Unternehmen liefern. Standard: an.

Box size: optionale Kartonmaße in der Maßeinheit Ihres Shops, zum Beispiel 30x20x15. UPS wendet dann das Volumengewicht an. Leer lassen, um nur nach Gewicht zu berechnen.

UPS account currency: UPS rechnet in der Währung des Landes des Versenderkontos, zum Beispiel USD für die USA, CAD für Kanada oder EUR für den Euroraum. Standard: USD.

Exchange rate: nur nötig, wenn die Währung des UPS-Kontos von der Standardwährung Ihres Shops abweicht. Geben Sie den Preis für 1 Einheit der Kontowährung in Ihrer Standardwährung ein, zum Beispiel 0.92. Ohne ihn werden solche Tarife nicht verwendet und die festen Preise gelten. Wechselkurse werden nicht automatisch aktualisiert.

Versandadresse (die Adresse, an der UPS abholt bzw. an der Sie die Pakete abgeben; wird für Live-Tarife verwendet)

Country: das Land, aus dem Sie versenden. Standardmäßig ist es das Land Ihres Shops.

State / province code: das 2-stellige Kürzel, für USA und Kanada erforderlich, zum Beispiel NY, CA oder ON.

City: die Stadt, aus der Sie versenden.

ZIP / postal code: die Postleitzahl, aus der Sie versenden. UPS benötigt sie für die Tarifberechnung.

Feste Preise (werden verwendet, wenn keine API-Zugangsdaten eingegeben sind, und als Ausweichlösung, wenn UPS keinen Tarif liefert; lassen Sie beide leer, um den Versanddienstleister in diesem Fall auszublenden)

Country prices: Preise in der Standardwährung Ihres Shops, ohne Steuern, je Zielland. Klicken Sie auf Add country, um eine Zeile hinzuzufügen, und auf die Entfernen-Schaltfläche, um eine zu löschen. Das Land * gilt für alle anderen Länder. Eine Gewichtsspalte (XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL über 5 kg) überschreibt Price für dieses Gewicht. Leere Zellen greifen auf Price zurück. 0 bedeutet kostenloser Versand. Zeilen ohne jeglichen Preis werden beim Speichern entfernt, und Werte, die keine Zahlen sind, werden mit einer Meldung abgelehnt.

Fallback cost: ein Pauschalpreis in der Standardwährung Ihres Shops, wenn kein Länderpreis passt. Lassen Sie das Feld leer, um den Versanddienstleister in diesem Fall auszublenden.

Fixed price is: Per order berechnet den Preis einmal, für das Gewicht des gesamten Warenkorbs. Per item (each item priced by its own weight x quantity) berechnet jedes Produkt nach seinem eigenen Gewicht (Standardgewicht, falls keins vorhanden ist) und multipliziert es mit der Menge. Hat ein Produkt keinen festen Preis, wird der Versanddienstleister ausgeblendet. UPS-Live-Tarife werden immer für das Gesamtgewicht des Warenkorbs berechnet.

Bedingungen

Free shipping from: der Zwischensummenbetrag des Warenkorbs (Produkte, die versendet werden müssen, nach Rabatten, vor Steuern), ab dem dieser Versanddienstleister kostenlos ist. Dann wird keine Anfrage an UPS gesendet. Leer lassen, um nie kostenlosen Versand anzubieten.

Minimum subtotal: Der Versanddienstleister wird nur angezeigt, wenn die Zwischensumme des Warenkorbs mindestens diesen Betrag erreicht. Leer lassen, um ihn immer anzuzeigen.

Min weight: das minimale Warenkorbgewicht in kg, damit dieser Versanddienstleister erscheint. 0 bedeutet keine Grenze.

Max weight: der Versanddienstleister wird oberhalb dieses Warenkorbgewichts in kg ausgeblendet. Standard: 70, das UPS-Limit pro Paket (70 kg / 150 lbs). 0 bedeutet keine Grenze, leer bedeutet 70. Min weight darf nicht über Max weight liegen.

Default product weight: das Gewicht in kg für Produkte ohne Gewicht, in den UPS-Tarifen, den Gewichtsspalten und den Gewichtsgrenzen. Standard: 0.5.

Verfügbarkeit ohne Versandzonen

Normalerweise wird der Versanddienstleister in den Zonen angeboten, denen er unter Shipping > Carriers zugewiesen ist.

Ignore shipping zones: bietet den Versanddienstleister für die unten angegebenen Länder an, unabhängig davon, welche Zone passt. Beim Speichern wird der Versanddienstleister allen Zonen hinzugefügt, auch später erstellten Zonen. Wenn Sie es ausschalten, werden diese Zonen wieder entfernt.

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 eingeschaltet ist.

Erweitert

Debug log: protokolliert API-Anfragen und die Tarifberechnung in logs/vfd_upsx_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. Zugangsdaten, Token und Kundenadressen werden nie protokolliert.

Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.

Remove data on uninstall: wenn eingeschaltet, löscht die Deinstallation des Moduls die Einstellungen, den Versanddienstleister, zwischengespeicherte Token und Tarife, das Protokoll und die mit Bestellungen gespeicherten UPS-Services. Die Bestellungen selbst bleiben erhalten. Wenn ausgeschaltet, bleibt alles für eine erneute Installation erhalten.

So funktioniert es an der Kasse

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

Das Modul holt sich von UPS einen OAuth-Token und behält ihn, bis er abläuft. Ein Token, den UPS ablehnt, wird automatisch erneuert. Danach fragt es die UPS Rating API nach allen Services von Ihrer Versandadresse bis zur Adresse des Kunden ab, und zwar für den Warenkorb als ein Paket. Bei Ländern mit Postleitzahlen wartet die Anfrage, bis der Kunde eine Postleitzahl eingegeben hat. Bei Sendungen aus den USA nach Kanada oder Puerto Rico wird der Warenwert übermittelt, wie es UPS verlangt.

Der Kunde sieht eine Option mit dem günstigsten UPS-Service. Der Preis wird in der Standardwährung Ihres Shops berechnet und danach in der Warenkorbwährung des Kunden angezeigt. UPS Access Point Economy wird nicht angeboten, weil das Modul keine Access-Point-Adresse erfasst.

Jede Angebotsanfrage wird 1 Stunde zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten gemerkt, eine fehlgeschlagene Token-Anfrage 5 Minuten, damit ein Ausfall nicht jede Aktualisierung an der Kasse verlangsamt. Das HTTP-Timeout beträgt 15 Sekunden.

Wenn UPS keinen Tarif liefert (API nicht erreichbar, falsche Zugangsdaten, kein Service, andere Währung ohne Wechselkurs), kommt der Preis aus Country prices, danach aus Fallback cost. Trifft keines von beidem zu, wird der Versanddienstleister ausgeblendet. Kunden sehen niemals UPS-Fehlermeldungen.

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 bietet keine Auswahl von UPS Access Points an, erstellt keine Versandetiketten oder UPS-Sendungen, bucht keine Abholungen und verfolgt keine Pakete. Es zeigt eine Option, nicht mehrere UPS-Services. Eine Kartonauswahl gibt es nicht: Der Warenkorb wird als ein Paket berechnet. Wechselkurse werden nicht automatisch aktualisiert.

Bestellungen

Wenn eine Bestellung mit einem UPS-Live-Tarif aufgegeben wird, wird der UPS-Service zusammen mit der Bestellung gespeichert. Die Bestellseite im Back Office zeigt einen Block UPS mit dem UPS service, zum Beispiel UPS Ground, und dem Live rate (excl. tax). Spätere Änderungen am Warenkorb im Back Office ändern ihn nicht. Bestellungen mit festem Preis oder kostenlosem Versand haben keinen solchen Block.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox UPS ist der erste Block auf Modules > Module Manager > VibeFox UPS > 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 Statusprüfung, 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-ups 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. Nach einer Änderung der Shop-Adresse 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 funktioniert auf einer Domain: der Domain des Hauptshops, auch in einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird der UPS-Versanddienstleister Kunden an der Kasse nicht angezeigt, und es wird kein Tarif berechnet. Das PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher ist 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 dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen.

Wenn eine Lizenz abläuft, arbeitet das Modul weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird während der 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

UPS erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist und Enable UPS shipping 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. Prüfen Sie die Gewichtsgrenzen und die Minimum subtotal. Ohne funktionierende UPS-Zugangsdaten braucht der Versanddienstleister einen festen Preis (Country prices oder Fallback cost). Außerdem lassen sich Produkte auf der Produktseite auf bestimmte Versanddienstleister beschränken.

Live-Tarife erscheinen nicht: prüfen Sie die Hinweise oben auf der Seite Configure. Schalten Sie Debug log ein, laden Sie die Kasse neu und schauen Sie im Feld Log auf der Modulseite nach. Es zeigt OAuth-Fehler (prüfen Sie Client ID, Client Secret und Test mode), UPS-Fehlermeldungen und Währungsprobleme.

Der Tarif ist in USD, der Shop aber nicht: UPS gibt Tarife in der Währung des Versenderkontos zurück. Stellen Sie UPS account currency und Exchange rate ein. Ohne Wechselkurs werden solche Tarife ignoriert und der feste Preis wird verwendet.

„This measurement system is not valid for the selected country“: lassen Sie Measurement units auf Automatic oder wählen Sie die Einheiten, die UPS für Ihr Versandland erwartet.

Die Seite warnt, dass die Gewichts- oder Maßeinheit des Shops unbekannt ist: Gewichte werden dann als kg und die Kartongröße als cm gelesen. Stellen Sie unter International > Localization, Abschnitt Local units, eine Standardeinheit ein (kg, g, lb oder oz; cm, mm, m oder in).

Tarife wirken nach einer Änderung veraltet: klicken Sie auf der Modulseite auf Save oder auf Clear cached UPS token and rates.

Die Seite meldet, dass der UPS-Versanddienstleister nicht gefunden wurde: der Versanddienstleister wurde unter Shipping > Carriers gelöscht. Setzen Sie das Modul unter Modules > Module Manager zurück, damit er neu erstellt wird.

Für Entwickler: die Hooks actionVfdUpsxAllowedServices und actionVfdUpsxExcludedServices beschränken die UPS-Services, die angezeigt werden können. actionVfdUpsxRateRequest ändert die Tarifanfrage, actionVfdUpsxApiBaseUrl die API-Adresse und actionVfdUpsxCurrencyCodes ordnet die von UPS zurückgegebenen Währungscodes zu.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox UPS und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus werden immer entfernt. Der zwischengespeicherte UPS-Token und die 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 mit Bestellungen gespeicherten UPS-Services werden entfernt. Ist die Option ausgeschaltet, wird der Versanddienstleister nur deaktiviert und die Einstellungen bleiben erhalten. Eine erneute Installation des Moduls oder ein Reset gibt dem Versanddienstleister den Status zurück, den er vorher hatte.

UPS ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit UPS verbunden noch von UPS unterstützt oder empfohlen.