VibeFox UPS for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

App im UPS Developer Portal (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 Client ID und Client Secret. Das Plugin 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 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. Alternativ können Sie den Ordner vfd_ups per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox UPS oder klicken Sie auf der Plugin-Seite unter dem Plugin-Namen auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Geben Sie Client ID und Client Secret, Ihre UPS-Kontonummer (für verhandelte Tarife) und die Adresse Ship from ein: die Postleitzahl und bei den USA und Kanada den zweistelligen Bundesstaat.

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

7. Fügen Sie VibeFox UPS in WooCommerce > Settings > Shipping > Shipping zones einer Versandzone hinzu oder aktivieren Sie Ignore shipping zones und wählen Sie Länder aus.

8. Optional können Sie feste Preise als Ausweichlösung eingeben.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox UPS. Sie gelten für alle Versandzonen. Wenn Sie die Methode einer Zone hinzufügen, hat das Zonenfenster nur ein Feld:

Title (zone): der Name dieser Option im Checkout. Leer lassen, um den globalen Name zu verwenden.

Bei jedem Speichern der Einstellungen werden der zwischengespeicherte UPS-Token und die Tarife gelöscht. Sie können auch im Abschnitt UPS API auf Clear cached UPS token and rates klicken. Warnungen über den Einstellungen zeigen an, wenn nur eines von Client ID und Client Secret gesetzt ist, keine Zugangsdaten und keine festen Preise vorhanden sind, Postleitzahl oder Bundesstaat des Versandorts fehlen, verhandelte Tarife ohne Kontonummer gewählt sind oder der Wechselkurs fehlt.

General

Enable/Disable: schaltet die Methode in allen Zonen gleichzeitig ein oder aus.

Name: der Name der Versandart, der im Checkout angezeigt wird. Standard: UPS.

Tax status: Taxable lässt WooCommerce die Versandsteuer aufschlagen, None nicht. UPS-Tarife werden ohne Steuern angeboten, sodass die Steuer nicht doppelt berechnet wird.

UPS API (Live-Tarife)

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

Client ID: die Client ID Ihrer App im UPS Developer Portal.

Client Secret: das Client Secret derselben App.

UPS account number: Ihre 6-stellige UPS-Versendernummer, zum Beispiel A1B2C3. Erforderlich für Kontotarife (verhandelt), optional für Listentarife.

Rates: welche UPS-Preise verwendet werden.

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

Residential delivery: bewertet Kundenadressen als Privatadressen mit dem UPS-Zuschlag für Privatzustellung. 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 kalkulieren.

UPS account currency: UPS kalkuliert 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 Shop-Währung abweicht. Geben Sie den Preis von 1 Einheit der Kontowährung in Ihrer Shop-Wä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, bei der UPS die Pakete abholt oder bei der Sie sie 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: der zweistellige Code, für die 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 eingetragen sind, und als Ausweichlösung, wenn UPS keinen Tarif liefert; lassen Sie beide Felder leer, um die Methode in diesem Fall auszublenden)

Country prices: Preise in Ihrer Shop-Währung je Zielland. Klicken Sie auf + Add country, um eine Zeile hinzuzufügen, und auf das X, um eine zu entfernen. Die Zeile * Default gilt für jedes andere Land. Eine Gewichtsspalte (XS bis 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL über 5 kg) ersetzt Price für dieses Warenkorbgewicht. Leere Zellen verwenden Price. 0 bedeutet kostenloser Versand. Zeilen ohne Preis werden beim Speichern entfernt, und Werte, die keine Zahlen sind, werden mit einer Meldung abgelehnt.

Fallback cost: ein fester Preis in Ihrer Shop-Währung, wenn kein Länderpreis passt. Leer lassen, um die Methode in diesem Fall auszublenden.

Fixed price is: Per order berechnet den Preis einmal. Per item (each item priced by its own weight x quantity) bepreist jeden Artikel nach seinem eigenen Gewicht (bei fehlendem Gewicht das Standardgewicht) und multipliziert es mit der Menge. Live-Tarife von UPS werden immer für das gesamte Warenkorbgewicht berechnet.

Bedingungen

Free shipping from: der Warenkorb-Zwischensummenbetrag, ab dem diese Methode kostenlos ist. Der Kunde sieht den Methodennamen mit „(Free)“, und es wird keine Anfrage an UPS gesendet. Leer lassen, um nie kostenlosen Versand anzubieten.

Minimum subtotal: die Methode nur anzeigen, wenn die Warenkorb-Zwischensumme mindestens diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.

Min weight (kg): das minimale Warenkorbgewicht, damit diese Methode erscheint. 0 bedeutet keine Grenze.

Max weight (kg): die Methode wird oberhalb dieses Warenkorbgewichts ausgeblendet. Standard: 70, das UPS-Limit je Paket (70 kg / 150 lbs). 0 bedeutet keine Grenze.

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

Excluded shipping classes: die Methode ausblenden, wenn der Warenkorb ein Produkt aus einer dieser WooCommerce-Versandklassen enthält.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet die Methode für die unten genannten Länder an, auch wenn sie keiner Versandzone hinzugefügt wurde.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Versandländer des Shops zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones aktiviert ist.

Erweitert

Debug log: protokolliert API-Anfragen und die Tarifberechnung unter WooCommerce > Status > Logs, Quelle vfd-ups. API-Fehler werden immer protokolliert, auch wenn diese Option aus ist. Zugangsdaten, Token und Kundenadressen werden nie protokolliert.

Remove data on uninstall: wenn aktiviert, entfernt das Löschen des Plugins alle Plugin-Einstellungen und Zonenmethoden. Deaktivieren löscht nie Einstellungen.

So funktioniert es im Checkout

Wenn der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Tarif. Das Plugin prüft zuerst die Bedingungen: Warenkorbgewicht, Mindestzwischensumme und ausgeschlossene Versandklassen. Gilt kostenloser Versand, wird die Methode als kostenlos angezeigt und es wird keine Anfrage an UPS gesendet.

Das Plugin holt sich ein OAuth-Token von UPS und behält es, bis es abläuft. Ein von UPS abgelehntes Token wird automatisch erneuert. Danach fragt das Plugin die UPS Rating API nach allen Services von Ihrer Versandadresse zur Adresse des Kunden an, und zwar für den Warenkorb als ein Paket. Bei Ländern mit Postleitzahlen wartet die Anfrage, bis der Kunde eine eingegeben hat. Bei Versand 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, umgerechnet in Ihre Shop-Währung. UPS Access Point Economy wird nicht angeboten, da das Plugin keine Access-Point-Adresse erfasst.

Jeder Tarif wird 1 Stunde zwischengespeichert. Eine fehlgeschlagene Anfrage wird 10 Minuten lang gespeichert, eine fehlgeschlagene Token-Anfrage 5 Minuten, damit ein Ausfall nicht jede Aktualisierung des Checkouts verlangsamt. Das HTTP-Timeout beträgt 15 Sekunden. Das Deaktivieren des Plugins löscht den zwischengespeicherten Token und die Tarife.

Wenn UPS keinen Tarif liefert (API nicht erreichbar, falsche Zugangsdaten, kein Service), stammt der Preis aus Country prices und danach aus Fallback cost. Trifft keines davon zu, wird die Methode ausgeblendet. Der Kunde sieht nie UPS-Fehlermeldungen.

Die Methode funktioniert im klassischen Checkout sowie im Warenkorb- und im Kassen-Block. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin berechnet nur Tarife. Es bietet keine Auswahl eines UPS Access Points, erstellt keine Versandetiketten oder UPS-Sendungen, bucht keine Abholungen und verfolgt keine Pakete. Es zeigt eine Option, nicht mehrere UPS-Services. Es gibt keine Verpackungsoptimierung: Der Warenkorb wird als ein Paket kalkuliert. Wechselkurse sind nicht automatisch.

Bestellungen

Bei einem Live-Tarif speichert die Versandzeile der Bestellung den UPS service, zum Beispiel UPS Ground. Der Shop-Manager sieht ihn auf dem Bestellbildschirm im Admin-Bereich.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox UPS. 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-Kontingent nicht frei. Geben Sie das Kontingent in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird UPS Kunden im Checkout nicht angezeigt. Angemeldete Shop-Manager sehen es weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Auf der Plugin-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen bleiben unberührt.

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

UPS erscheint nicht im Checkout: 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 aktiv ist und das Land erlaubt ist). Prüfen Sie die Gewichtsgrenzen, die Minimum subtotal und die Excluded shipping classes. Ohne funktionierende UPS-Zugangsdaten braucht die Methode einen festen Preis (Country prices oder Fallback cost).

Live-Tarife erscheinen nicht: Prüfen Sie die Warnungen oben auf der Einstellungsseite. Aktivieren Sie den Debug log und öffnen Sie WooCommerce > Status > Logs, Quelle vfd-ups. Dort sehen Sie OAuth-Fehler (prüfen Sie Client ID, Client Secret und den Test mode), UPS-Fehlermeldungen und Währungsprobleme.

Der Tarif ist in USD, der Shop aber nicht: UPS liefert Tarife in der Währung des Versenderkontos. Legen Sie UPS account currency und Exchange rate fest. Ohne Wechselkurs werden solche Tarife ignoriert und der feste Preis 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.

Tarife wirken nach einer Änderung veraltet: Speichern Sie die Einstellungsseite oder klicken Sie auf Clear cached UPS token and rates.

Für Entwickler: die Filter vfd_upsx_allowed_services und vfd_upsx_excluded_services beschränken die UPS-Services, die angezeigt werden können. vfd_upsx_rate_request ändert die Tarifanfrage, vfd_upsx_api_base_url die API-Adresse und vfd_upsx_currency_codes ordnet von UPS zurückgegebene Währungscodes zu.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung im Block. Wenn der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet wird, geben Sie ein Kontingent in Ihrem vibefox.net-Konto frei und klicken Sie auf Check now. Wenn sich die Adresse der Website geändert hat, 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 zuletzt bekannten Status weiter.

Deinstallation

Das Deaktivieren des Plugins behält die Einstellungen und löscht nur den zwischengespeicherten Token und die Tarife. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins sowie der zwischengespeicherte Token und die Tarife werden immer entfernt. Einstellungen und Zonenmethoden werden nur entfernt, wenn Remove data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Versandzeilen.

UPS ist eine Marke des jeweiligen Inhabers. Dieses Plugin ist nicht mit UPS verbunden und wird nicht von UPS unterstützt.