Fehlerbehebung & FAQ
Hier finden Sie Lösungen für häufige Probleme mit dem GLS Connector sowie allgemeine Fragen.
Verbindungsprobleme
"Authentication failed" (HTTP 401)
| Mögliche Ursache | Lösung |
|---|---|
| Benutzername oder Passwort falsch | Prüfen Sie die Credentials im GLS-Setup |
| Zugangsdaten abgelaufen | Kontaktieren Sie Ihren GLS-Ansprechpartner |
| Sandbox-Credentials für Produktiv-URL | Stellen Sie sicher, dass Sandbox Mode korrekt gesetzt ist |
"Authorization failed" (HTTP 403)
| Mögliche Ursache | Lösung |
|---|---|
| Kein Zugang zu diesem API-Endpunkt | Prüfen Sie die Berechtigungen mit Ihrem GLS-Ansprechpartner |
| Contact ID nicht freigeschaltet | Contact ID von GLS bestätigen lassen |
"Test Connection" schlägt fehl
Schritt-für-Schritt-Diagnose:
- Sandbox Mode prüfen: Ist der richtige Modus aktiviert?
- API Base URL prüfen: Die URL muss auf den GLS-Server zeigen
- Sandbox:
https://shipit-wbm-sandbox01.gls-group.eu:443/backend/rs - Produktiv: Von GLS bereitgestellt
- Sandbox:
- Credentials prüfen: Username und Passwort korrekt?
- Contact ID prüfen: GLS-Kundennummer eingetragen?
- Netzwerk prüfen: Kann der BC-Server die GLS-URL erreichen?
- Firewall/Proxy: Ist die GLS-URL in der Firewall freigegeben?
Verbindungstest-Methode
Der Test nutzt den AllowedServices-Endpoint als Proxy, da GLS keinen dedizierten Health-Check bietet. Wenn dieser Endpoint antwortet, ist die Verbindung aktiv.
Label-Erstellung
Fehler in HTTP-Headers (GLS-Besonderheit)
GLS-spezifisch: Fehler in HTTP-Headers
Im Gegensatz zu DHL, UPS und DPD liefert GLS Fehlermeldungen in den HTTP-Response-Headers, nicht im JSON-Body. Der Connector extrahiert diese automatisch aus den Headers X-GLS-ErrorCode, X-GLS-ErrorMessage und X-GLS-ErrorArgs.
Häufige API-Fehler
| Fehlercode | Nachricht | Lösung |
|---|---|---|
INVALID_ADDRESS |
Ungültige Empfängeradresse | PLZ, Ort und Land prüfen |
WEIGHT_EXCEEDED |
Gewicht überschritten | Max. 31,5 kg pro Paket; für schwere Sendungen GLS Freight verwenden |
SERVICE_NOT_ALLOWED |
Service nicht erlaubt | Diesen VAS für die Route deaktivieren |
PARCELS_ALREADY_EXIST |
Sendung existiert bereits | Prüfen, ob Label bereits erstellt wurde |
CONTACT_ID_INVALID |
Contact ID ungültig | Contact ID im Setup prüfen |
Validierungsfehler (lokal)
Diese Fehler werden vor dem API-Aufruf erkannt:
| Fehlermeldung | Ursache | Lösung |
|---|---|---|
| Missing GLS API credentials | Username/Passwort fehlt | Credentials im Setup eingeben |
| Contact ID is required | Keine Contact ID | Contact ID im Setup eintragen |
| Shipper Name 1 is required | Absendername fehlt | Absenderadresse vervollständigen |
| Ship-to Name is required | Empfängername fehlt | Name eingeben |
| Ship-to Post Code is required | PLZ fehlt | Postleitzahl eingeben |
| Ship-to City is required | Ort fehlt | Stadt eingeben |
| Ship-to Country Code is required | Ländercode fehlt | ISO-2 Ländercode eingeben |
| Weight must be greater than 0 | Gewicht = 0 und kein Default | Gewicht eingeben oder Default im Setup setzen |
| ParcelShop ID is required | ShopDelivery aktiv, aber keine ID | ParcelShop ID eingeben |
| Cash Amount must be greater than 0 | Nachnahme aktiv, Betrag = 0 | Nachnahmebetrag eingeben |
| Liability Amount must be greater than 0 | Versicherung aktiv, Betrag = 0 | Versicherungssumme eingeben |
Stornierungsprobleme
"Cancellation failed — parcel already in transit"
Sendungen können nur storniert werden, bevor GLS das Paket physisch übernommen hat. Sobald das Paket gescannt wurde, ist eine Stornierung über die API nicht mehr möglich.
Alternative: Kontaktieren Sie direkt den GLS-Kundenservice.
"Track ID not found"
- Prüfen Sie, ob die Track-ID korrekt ist
- Sandbox-Labels können nicht mit dem Produktiv-Endpunkt storniert werden (und umgekehrt)
Tagesabschluss (EndOfDay)
"No shipments found for end of day"
| Ursache | Lösung |
|---|---|
| Keine offenen Sendungen für den Tag | Prüfen Sie, ob Labels erstellt wurden |
| Falsches Datum | Das Datum muss dem Tag der Label-Erstellung entsprechen |
| Sendungen bereits abgeschlossen | EndOfDay wurde bereits durchgeführt |
Manifest-PDF fehlt
- Der Tagesabschluss liefert ein PDF-Dokument zurück
- Prüfen Sie, ob die Antwort der GLS API korrekt war
- Bei Fehlern steht die Ursache in den HTTP-Response-Headers
Gewichts- und Maßprobleme
Gewicht wird falsch übertragen
| Problem | Ursache | Lösung |
|---|---|---|
| Gewicht viel zu hoch | Hub speichert in Gramm, GLS erwartet kg | Der Connector rechnet automatisch um (÷ 1000) |
| Gewicht = 0 | Kein Gewicht angegeben | Gewicht eingeben oder Default-Gewicht im Setup setzen |
| Gewicht > 31,5 kg | GLS-Limit überschritten | Auf GLS Freight umstellen oder Paket aufteilen |
Gewichtsformat
Der Hub speichert Gewichte in Gramm (Integer). Der GLS Connector rechnet automatisch in Kilogramm (Dezimal) um. Beispiel: 2500 g → 2,500 kg.
Ländercodes
Falscher Ländercode-Fehler
GLS verwendet ISO alpha-2 Ländercodes:
| Richtig (GLS) | Falsch | Land |
|---|---|---|
DE |
DEU |
Deutschland |
AT |
AUT |
Österreich |
CH |
CHE |
Schweiz |
FR |
FRA |
Frankreich |
Business Central verwendet standardmäßig bereits ISO alpha-2, daher ist normalerweise keine Umrechnung nötig. Wenn Sie jedoch ISO-3-Codes in Ihrem System konfiguriert haben, müssen Sie diese auf ISO-2 umstellen.
Vergleich mit anderen Carriern
| Carrier | Ländercode-Format |
|---|---|
| GLS | ISO-2 (DE, AT) |
| DHL | ISO-3 (DEU, AUT) |
| UPS | ISO-2 (DE, AT) |
| DPD | ISO-3 (DEU, AUT) |
Sandbox vs. Produktiv
Wie wechsle ich von Sandbox zu Produktiv?
- Öffnen Sie die GLS-Setup-Seite
- Deaktivieren Sie Sandbox Mode
- Geben Sie die Produktiv-URL ein (von GLS bereitgestellt)
- Klicken Sie auf Test Connection
Produktiv-URL
Die Produktiv-URL wird nicht automatisch eingetragen (anders als die Sandbox-URL). Sie erhalten sie von Ihrem GLS-Ansprechpartner.
Sandbox-Labels funktionieren nicht zum Versand
Normal — Sandbox-Labels haben keine gültigen Track-IDs und werden von GLS nicht physisch verarbeitet. Sie dienen nur zum Testen.
Label-Format-Probleme
Label wird nicht korrekt gedruckt
| Format | Drucker-Typ | Empfehlung |
|---|---|---|
| Normaler PC-Drucker (Laser/Inkjet) | Standard für die meisten Anwender | |
| PNG | Normaler PC-Drucker | Alternative zu PDF |
| Zebra (ZPL) | Zebra-Thermodrucker | Nur für Zebra-Drucker! |
ZPL-Template stimmt nicht
Wenn Sie Zebra-Drucker verwenden, prüfen Sie das Template Set im Setup:
| Drucker | Template Set |
|---|---|
| Zebra mit 200 dpi | ZPL 200 dpi |
| Zebra mit 300 dpi | ZPL 300 dpi |
| Kein Zebra | None |
Template Set nur für ZPL
Setzen Sie das Template Set nur, wenn Sie das Label-Format Zebra (ZPL) verwenden. Für PDF und PNG muss es auf None stehen.
Content-Type-Header
Fehler bei API-Kommunikation
GLS erwartet einen speziellen Content-Type-Header:
Content-Type: application/glsVersion1+json
Accept: application/glsVersion1+json, application/json
Diese Header werden automatisch vom Connector gesetzt. Wenn Sie jedoch eigene Erweiterungen über die Integration Events (OnBeforeCreateGLSParcel) bauen, stellen Sie sicher, dass diese Header nicht überschrieben werden.
Allgemeine FAQ
Welche GLS-API-Version wird verwendet?
Der Connector nutzt die GLS ShipIT REST API v3.2.9.
Brauche ich einen separaten GLS API-Vertrag?
Ja. Sie benötigen einen GLS Geschäftskunden-Vertrag mit API-Zugang (ShipIT). Kontaktieren Sie Ihren GLS-Ansprechpartner.
Kann ich mehrere GLS-Konten verwenden?
Aktuell unterstützt der Connector ein GLS-Konto pro Business Central-Mandant.
Werden Tracking-Nummern automatisch zurückgemeldet?
Ja, die Track-ID wird nach der Label-Erstellung automatisch im Shipment Label gespeichert und die Tracking-URL generiert.
Muss ich den Tagesabschluss machen?
Ja, der Tagesabschluss (EndOfDay) ist bei GLS erforderlich. Er erzeugt das Manifest-PDF, das der GLS-Fahrer bei der Abholung benötigt.
Kann GLS auch Retouren-Labels erstellen?
Nicht als eigenständiges Retourenlabel. GLS bietet den ShopReturn-Service an, der beim Erstellen des Versandlabels ein Retourenlabel automatisch beilegt. Siehe Zusatzleistungen → ShopReturn.
Was kostet die GLS API?
Die API selbst ist kostenlos. Sie zahlen nur die regulären GLS-Versandkosten gemäß Ihrem Vertrag.
Label erneut drucken — geht das?
GLS liefert das Label nur einmalig beim Erstellen. Es kann später nicht erneut von der GLS API heruntergeladen werden. Das Label ist aber in Business Central gespeichert und kann dort jederzeit erneut gedruckt werden.
Support
Wenn Sie ein Problem nicht lösen können:
- Status im Setup prüfen:
Last Error MessageundLast Error DateTimezeigen den letzten API-Fehler - Activity Log prüfen: Öffnen Sie das merchantCENTRAL Activity Log und filtern Sie nach
GLS - GLS-Fehlernachricht analysieren: Die GLS API gibt spezifische Fehlercodes in HTTP-Headers zurück
- Administrator kontaktieren: Für Setup-Änderungen oder Credential-Probleme
- GLS-Support: Für kontobezogene Fragen, Contact ID oder Service-Verfügbarkeit