Fehlerbehebung & FAQ

Hier finden Sie Lösungen für häufige Probleme mit dem UPS Connector sowie allgemeine Fragen.

Verbindungsprobleme

"OAuth2 token request failed" / Authentifizierungsfehler

Mögliche Ursache	Lösung
Client ID oder Client Secret falsch	Prüfen Sie die Credentials im UPS Developer Portal
Sandbox-/Produktiv-URL vertauscht	Stellen Sie sicher, dass Sandbox Mode korrekt gesetzt ist
Token abgelaufen und nicht automatisch erneuert	Klicken Sie auf Test Connection im Setup
UPS-Konto deaktiviert oder gesperrt	Kontaktieren Sie den UPS-Support

OAuth 2.0 Token-Ablauf

Der UPS Connector holt sich automatisch ein neues Token, wenn das alte abgelaufen ist (~4 Stunden Gültigkeit). Wenn trotzdem Fehler auftreten, prüfen Sie die Client Credentials.

"Test Connection" schlägt fehl

Schritt-für-Schritt-Diagnose:

Client ID prüfen: Ist die Client ID korrekt aus dem UPS Developer Portal kopiert?
Client Secret prüfen: Wurde das Secret korrekt eingegeben? (Wird als *** angezeigt)
Account Number prüfen: 6-stellige UPS-Kundennummer korrekt?
Sandbox Mode prüfen: Sandbox nur für Tests, Produktiv für echte Sendungen
Internet-Verbindung: Kann der BC-Server die UPS-URLs erreichen?
- Sandbox: https://wwwcie.ups.com
- Produktiv: https://onlinetools.ups.com
Firewall/Proxy: Sind die UPS-URLs in der Firewall freigegeben?

Label-Erstellung

"Missing weight for package" / Gewichtsfehler

Ursache	Lösung
Gewicht nicht angegeben	Geben Sie das Gewicht im Paket ein (Pflichtfeld)
Gewicht = 0	Mindestens 0,1 kg (100 g) angeben

Gewichtsformat

UPS erwartet das Gewicht in Kilogramm mit der Einheit KGS. Der Connector übersetzt die Eingabe automatisch.

"Missing dimensions" / Maßfehler

Paketabmessungen (Länge, Breite, Höhe) sind optional bei UPS. Wenn Sie jedoch Maße angeben, müssen alle drei Werte (L×B×H) ausgefüllt sein.

"Invalid service for destination" / Falscher Service

Nicht alle UPS-Services sind für alle Zielländer verfügbar:

Service	Einsatzgebiet
11 - Standard	Nur Europa
65 - Express Saver	Nur Europa
07 - Express	Weltweit
54 - Express Plus	Weltweit (ausgewählte Ziele)
08 - Expedited	Weltweit
70 - Access Point	Nur mit Access Point-Netzwerk
96 - Express Freight	Weltweit

Lösung: Wählen Sie einen Service, der für das Zielland verfügbar ist. Für internationale Sendungen außerhalb Europas empfehlen sich Express (07) oder Expedited (08).

"Label creation failed" / Allgemeiner API-Fehler

Prüfen Sie die Empfängeradresse auf Vollständigkeit (Name, Straße, PLZ, Ort, Land)
Prüfen Sie, ob die Absenderadresse im Setup korrekt ist
Prüfen Sie die UPS Account Number
Kontrollieren Sie das Gewicht (min. 0,1 kg)
Schauen Sie in die BC-Fehlermeldung — die UPS-API liefert meist einen spezifischen Fehlertext

Internationale Sendungen

"Missing customs items for international shipment"

Ursache	Lösung
Keine Zollpositionen angelegt	Erstellen Sie mindestens eine Customs Item-Position
Zielland ist Nicht-EU	Zolldaten sind Pflicht für Nicht-EU-Länder

Siehe: Internationale Sendungen für eine vollständige Anleitung.

"Invalid HS Code" / Zolltarifnummer ungültig

HS-Codes müssen mindestens 6 Stellen haben (z. B. 844332)
Für die EU empfohlen: 8–10 Stellen (z. B. 84433291)
Prüfen Sie den Code auf zolltarifnummern.de

Zollerklärung fehlt bei Sendung nach Großbritannien

Seit dem Brexit ist GB ein Nicht-EU-Land. Der Connector prüft dies automatisch — stellen Sie sicher, dass alle Customs Items und Zolldaten (Invoice No., Date, Incoterm) ausgefüllt sind.

Stornierung & Void

"Void failed — shipment already in transit"

Sendungen können nur storniert werden, bevor UPS das Paket übernommen hat. Sobald das Paket gescannt wurde, ist eine Stornierung nicht mehr möglich.

Alternative: Kontaktieren Sie direkt den UPS-Kundenservice für eine Rückholung.

"Shipment not found for void"

Prüfen Sie, ob die Tracking-Nummer korrekt ist
Sendungen in der Sandbox können nicht mit dem Produktiv-Endpunkt storniert werden (und umgekehrt)
Sehr alte Sendungen (>90 Tage) können möglicherweise nicht mehr über die API storniert werden

Sandbox- vs. Produktivbetrieb

Wie wechsle ich von Sandbox zu Produktiv?

Öffnen Sie die UPS-Setup-Seite
Deaktivieren Sie den Schalter Sandbox Mode
Die URLs werden automatisch umgeschaltet:
- Sandbox: https://wwwcie.ups.com
- Produktiv: https://onlinetools.ups.com
Klicken Sie auf Test Connection, um die Verbindung zu prüfen

Credentials beachten

Die Client ID und das Client Secret sind in der Regel für Sandbox und Produktiv identisch. Die UPS Account Number muss jedoch Ihr echtes Kundenkonto sein.

Sandbox-Label funktionieren nicht zum Versand

Das ist normal — Sandbox-Label haben keine gültigen Tracking-Nummern und werden von UPS nicht verarbeitet. Sie dienen nur zum Testen der API-Integration.

Labelformat-Probleme

Label wird nicht korrekt angezeigt

Format	Beschreibung	Verwendung
GIF	Bilddatei	Standard für PC-Drucker
PNG	Bilddatei (höhere Qualität)	Empfohlen für PC-Drucker
ZPL	Zebra Programming Language	Nur für Zebra-Thermodrucker
EPL	Eltron Programming Language	Ältere Thermodrucker
SPL	Sato Printer Language	Sato-Thermodrucker

Lösung: Wählen Sie im Setup das Format, das zu Ihrem Drucker passt. Für normale PC-Drucker verwenden Sie PNG oder GIF.

Label ist zu klein / zu groß

Prüfen Sie die Label Size im Setup:

Größe	Verwendung
4×6 Zoll	Standard für Versandlabel-Drucker
4×8 Zoll	Größeres Format für mehr Informationen

Performance & Job Queue

Label-Erstellung dauert zu lange

Prüfen Sie die Internetverbindung des BC-Servers
UPS-API-Antwortzeiten können je nach Last variieren
Bei Bulk-Sendungen: Erstellen Sie Labels sequenziell (nacheinander), um Rate Limits zu vermeiden

Job Queue-Einträge fehlerhaft

Öffnen Sie Aufgabenwarteschlangenposten in Business Central
Filtern Sie nach UPS-relevanten Einträgen
Prüfen Sie die Fehlermeldung im Fehlerprotokoll
Setzen Sie den Status auf Bereit, um den Eintrag erneut auszuführen

Allgemeine FAQ

Welche UPS-Vertragsart brauche ich?

Sie benötigen einen UPS Geschäftskunden-Vertrag mit API-Zugang. Kontaktieren Sie Ihren UPS-Ansprechpartner oder registrieren Sie sich auf developer.ups.com.

Kann ich mehrere UPS-Konten verwenden?

Aktuell unterstützt der Connector ein UPS-Konto pro Business Central-Mandant. Die Account Number wird zentral im Setup gespeichert.

Werden Tracking-Nummern automatisch zurückgemeldet?

Ja, die Tracking-Nummer wird nach der Label-Erstellung automatisch im Shipment Label gespeichert und an den merchantCENTRAL Hub zurückgemeldet.

Unterstützt der Connector Multi-Parcel-Sendungen?

Ja! Sie können mehrere Pakete pro Sendung erstellen. Jedes Paket erhält eine eigene Tracking-Nummer. Alle Pakete einer Sendung werden unter einer gemeinsamen Sendungsnummer zusammengefasst.

Was kostet die Nutzung der UPS API?

Die UPS API selbst ist kostenlos. Sie zahlen nur die regulären UPS-Versandkosten gemäß Ihrem Vertrag.

Kann ich das Label-Format nachträglich ändern?

Das Format (GIF/PNG/ZPL/EPL/SPL) wird beim Erstellen des Labels festgelegt. Um ein anderes Format zu erhalten, müssen Sie das Label stornieren und neu erstellen.

Was ist der Unterschied zwischen UPS Express und DHL Express?

Beide sind internationale Expressversand-Dienste. Der merchantCENTRAL Hub ist versanddienstleister-unabhängig — Sie können je nach Bedarf UPS oder DHL (oder beide) als Shipment Provider einrichten.

Support

Wenn Sie ein Problem nicht lösen können:

Activity Log prüfen: Öffnen Sie das merchantCENTRAL Activity Log und filtern Sie nach UPS
UPS-Fehlernachricht: Die API gibt meist eine spezifische englische Fehlermeldung zurück — suchen Sie danach im UPS Developer Documentation
Administrator kontaktieren: Für Setup-Änderungen oder Credential-Probleme
UPS-Support: Für kontobezogene Fragen oder Service-Verfügbarkeit