UPS Live Shipping (REST)¶
Mit dem Plugin UPS Live Shipping (REST) berechnen Sie Versandkosten live über die offizielle UPS REST API (OAuth 2.0) – direkt im Shopware 5 Checkout. Die Kosten basieren auf echten UPS-Tarifen für Zieladresse, Gewicht und gewählten Service, inklusive optionaler ausgehandelter Preise.
Das Plugin ordnet jede Shopware-Versandart einem UPS-Service zu, teilt schwere Bestellungen automatisch in mehrere Pakete auf und liefert über Fallback-Einstellungen auch dann ein Ergebnis, wenn Kundenadresse oder API einmal nicht verfügbar sind.
Highlights
- 🚚 Live-Versandkosten über die offizielle UPS REST API (OAuth 2.0)
- 🔀 Sandbox- und Production-Modus
- 🧭 Zuordnung jeder Versandart zu einem UPS-Service
- ⚖️ Automatisches Paket-Splitting bei über 70 kg
- 💶 Standard- oder ausgehandelte UPS-Preise
- 🛟 Fallback-Land, -PLZ und Ersatz-Versandkosten
- 🐞 Detailliertes Debug-Logging (
[UPS])
❓ FAQ¶
Woher kommen die Versandkosten?
Direkt von UPS: Das Plugin fragt zur Laufzeit die offizielle UPS REST API (OAuth 2.0) ab und berechnet die Kosten anhand von Zieladresse, Gewicht und gewähltem UPS-Service.
Benötige ich einen UPS-Account?
Ja. Sie hinterlegen Client ID und Client Secret aus dem UPS Developer Portal. Für ausgehandelte Preise wird zusätzlich Ihre Shipper Number (UPS-Kundennummer) empfohlen.
Wie werden Shopware-Versandarten mit UPS-Services verknüpft?
Über das Attribut welo_ups_service_id: Jede Versandart wird einer UPS-Service-ID zugeordnet (z. B. 65 → UPS Worldwide Saver). Ohne Service-ID kann keine Berechnung erfolgen.
Was passiert bei Bestellungen über 70 kg?
UPS erlaubt maximal 70 kg pro Paket. Das Plugin erkennt höhere Gesamtgewichte automatisch und teilt sie in mehrere Pakete auf (z. B. 210 kg → 3 × 70 kg).
Was passiert, wenn die UPS API nicht erreichbar ist?
Über die Fallback-Einstellungen greifen ein Standard-Zielland, eine Standard-PLZ und definierte Ersatz-Versandkosten, sodass der Checkout weiterhin funktioniert.
Kann ich die Berechnung nachvollziehen?
Ja. Mit aktiviertem Debug protokolliert das Plugin u. a. Gewicht, Service-Code, Cache-Key, Payload, Raw-Response und Fehlercodes. Alle Einträge sind mit [UPS] gekennzeichnet.
🔧 Installation¶
- Installation über den Shopware Plugin Manager
- Plugin installieren und aktivieren
- Konfiguration im Backend vornehmen (siehe Konfiguration unten)
Klicken Sie anschließend auf das Symbol, um das Plugin zu aktivieren:
⚙️ Allgemeine Einstellungen¶
| # | Einstellung | Beschreibung |
|---|---|---|
| 1 | Shop wählen | Wählen Sie den entsprechenden Shop. |
| 2 | Plugin aktivieren | Aktiviert die UPS Live-Versandberechnung. |
| 3 | Modus | Auswahl zwischen Sandbox (Testumgebung) und Production (Livebetrieb). |
| 4 | Client ID | Client ID aus dem UPS Developer Portal. |
| 5 | Client Secret | Client Secret aus dem UPS Developer Portal. |
| 6 | Shipper Number | UPS-Kundennummer (empfohlen bei ausgehandelten Preisen). |
| 7 | API Timeout | Timeout in Sekunden für die UPS API-Anfrage. |
| 8 | Absenderland | ISO-Code des Versandlandes (z. B. DE). |
| 9 | Absender-PLZ | Postleitzahl des Versandlagers. |
| 10 | Preis-Auswahl | Standardpreise erzwingen, Ausgehandelte Preise erzwingen oder Ausgehandelte Preise falls verfügbar. |
| 11 | Einstellungen speichern | Konfiguration speichern. |
🧭 Versandarten zuordnen¶
Jede Shopware-Versandart muss einem UPS-Service zugeordnet werden. Dafür wird das Attribut welo_ups_service_id verwendet.
| Service-ID | UPS-Service |
|---|---|
65 | UPS Worldwide Saver |
11 | UPS Standard |
07 | UPS Express |
Ohne Service-ID keine Berechnung
Ist einer Versandart keine welo_ups_service_id zugeordnet, kann für diese Versandart keine Live-Berechnung erfolgen.
⚖️ Gewicht & Splitting¶
UPS erlaubt maximal 70 kg pro Paket. Das Plugin erkennt höhere Gesamtgewichte automatisch und teilt diese in mehrere Pakete auf.
| Gesamtgewicht | Automatische Aufteilung |
|---|---|
| 100 kg | 2 × 50 kg |
| 210 kg | 3 × 70 kg |
| 350 kg | 5 × 70 kg |
| # | Einstellung | Beschreibung |
|---|---|---|
| 1 | Standardgewicht | Wird genutzt, wenn ein Artikel kein Gewicht besitzt. |
| 2 | Mindestgewicht | Untergrenze für die Berechnung. |
| 3 | Max-Gewicht pro Paket | Standard: 70 kg. |
| 4 | Einstellungen speichern | Konfiguration speichern. |
🛟 Fallback-Einstellungen¶
Wenn der Kunde nicht eingeloggt ist oder keine vollständige Adresse vorliegt, greifen folgende Einstellungen:
| # | Einstellung | Beschreibung |
|---|---|---|
| 1 | Fallback Zielland | Standardland für Gäste. |
| 2 | Fallback Ziel-PLZ | Standard-PLZ für Gäste. |
| 3 | Ersatz-Versandkosten | Wird genutzt, falls die UPS API nicht erreichbar ist. |
| 4 | Einstellungen speichern | Konfiguration speichern. |
Dynamische Zieladresse
Wählt der Kunde im Warenkorb ein anderes Land oder eine andere PLZ, wird diese dynamisch für die Berechnung verwendet.
🐞 Debug & Logging¶
| # | Einstellung | Beschreibung |
|---|---|---|
| 1 | Debug aktivieren | Aktiviert detaillierte Log-Ausgaben. |
| 2 | Einstellungen speichern | Konfiguration speichern. |
Die Logs beinhalten unter anderem:
- Gewicht
- Service-Code
- Cache-Key
- Payload an UPS
- Raw API Response
- Fehlercodes
- API Exceptions
Alle Logs sind mit [UPS] gekennzeichnet.
💡 Typische Anwendungsfälle¶
Exakte internationale Versandkosten¶
Zeigen Sie Kunden im Checkout echte UPS-Tarife für ihre Zieladresse – statt pauschaler Versandkosten.
Schwere und sperrige Bestellungen¶
Große Bestellungen werden automatisch in UPS-konforme Pakete (max. 70 kg) aufgeteilt und korrekt kalkuliert.
Ausgehandelte UPS-Konditionen nutzen¶
Mit hinterlegter Shipper Number berechnet das Plugin Ihre individuell ausgehandelten UPS-Preise.
⭐ Vorteile für Shopbetreiber¶
- Präzise, tarifgenaue Versandkosten direkt von UPS
- Weniger Über- oder Unterberechnung der Versandkosten
- Automatisches Paket-Splitting ohne manuellen Aufwand
- Zuverlässiger Checkout dank Fallback-Einstellungen
- Volle Transparenz durch detailliertes Debug-Logging
🧩 Funktionsumfang¶
- Live-Versandkostenberechnung über die UPS REST API (OAuth 2.0)
- Sandbox- und Production-Modus
- Zuordnung jeder Versandart zu einem UPS-Service
- Standard- oder ausgehandelte Preise
- Automatisches Paket-Splitting ab 70 kg
- Fallback-Land, -PLZ und Ersatz-Versandkosten
- Detailliertes Debug-Logging mit
[UPS]-Kennzeichnung
📬 Support¶
Bei Fragen, Verbesserungsvorschlägen oder individuellen Anpassungen erreichen Sie uns per E-Mail unter support@cnk-plugins.de.