Zum Hauptinhalt springen

API-Probleme

Fehler und Lösungen für Integrationen über die REST-API von DPD Label Print.

hinweis

Wenn Sie Online Label Print oder die Label Print App verwenden und nicht die API, siehe Login Issues, File Import Issues oder Printer Issues.

Authentifizierung​

HTTP 401 Unauthorized​

{
  "status": 401,
  "error": "Unauthorized",
  "message": "JWT token is missing or invalid"
}

Checkliste:

PrüfungErwartet
Header-NameAuthorization (grosses A)
Header-Wert-PräfixBearer (mit Leerzeichen nach Bearer)
Token-QuelleFeld token aus der Antwort von /api/v1/login
Token nicht abgelaufenexpireAt über /api/v1/login-extended prüfen
Keine zusätzlichen ZeichenLeerzeichen vor/nach dem Token-String entfernen

HTTP 401 – Token abgelaufen​

Token haben eine serverseitig konfigurierte TTL. Nach Ablauf gibt jede Anfrage 401 zurück.

Lösung: Erneut authentifizieren:

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "ihr_benutzer", "password": "ihr_passwort"}'

Vorbeugung – proaktiv vor Ablauf erneuern:

const tokenExpiry = new Date(loginResponse.expireAt);

async function getValidToken() {
  const fiveMinuteBuffer = 5 * 60 * 1000;
  if (Date.now() > tokenExpiry.getTime() - fiveMinuteBuffer) {
    await reAuthenticate();
  }
  return currentToken;
}

Token läuft zu schnell ab​

Ursache: Die Token-TTL ist serverseitig konfiguriert.

Lösung: Wenden Sie sich an Ihren DPD-Ansprechpartner, um die Token-TTL anzupassen. Implementieren Sie in der Zwischenzeit eine Token-Erneuerungslogik, die vor Ablauf eine erneute Authentifizierung durchführt.

HTTP 400 – Benutzername oder Passwort fehlt​

{
  "status": 400,
  "errors": [{ "field": "username", "message": "must not be blank" }]
}

Lösung: Stellen Sie sicher, dass sowohl username als auch password im Anfrage-Body vorhanden und nicht leer sind.

HTTP 403 – Forbidden (login-extended)​

{
  "status": 403,
  "message": "Auto-login context is missing"
}

Ursache: /api/v1/login-extended erfordert einen Auto-Login-Kontext, der für Ihr Konto nicht eingerichtet ist.

Lösung: Verwenden Sie stattdessen /api/v1/login, oder wenden Sie sich an Ihren DPD-Ansprechpartner.

Anmeldedaten korrekt, aber trotzdem 401?​

  1. Prüfen Sie, ob Sie die richtige Umgebungs-URL verwenden (dev vs. staging vs. production)
  2. Stellen Sie sicher, dass Ihr Konto aktiv ist – kontaktieren Sie den DPD-Support
  3. Prüfen Sie, ob Ihre IP-Adresse für den API-Zugriff freigeschaltet werden muss

Sendungen​

400 Bad Request – Validierungsfehler​

Ursache: Ein Pflichtfeld fehlt oder schlägt bei der Validierung fehl.

Lösung: Prüfen Sie das Array fieldErrors in der Antwort — es ist eine flache Liste, ein Eintrag pro Verstoss, jeweils mit eigenem path, code und message (derselbe code kann bei mehreren path-Werten auftreten, z. B. sowohl sender.email als auch receiver.email):

{
  "fieldErrors": [
    { "path": "receiver.email", "code": "SHP-VAL-EMAIL-REQUIRED", "message": "Email address is required." },
    { "path": "receiver.countryCode", "code": "SHP-VAL-COUNTRYCODE-ALLOWED-CHARACTERS", "message": "Country code contains invalid characters." }
  ]
}

Häufige Pflichtfelder:

  • email ist für alle Ziele ausserhalb CH/LI erforderlich (ausser GB)
  • phone ist für GB-Ziele erforderlich (internationales Format: +44...)
  • houseNumber ist für NL-Ziele erforderlich
  • stateCode ist für US/CA-Ziele erforderlich

207 Multi-Status – Teilweise fehlgeschlagen​

Ursache: Bei einer Batch-Anfrage waren einige Sendungen erfolgreich, andere nicht.

Lösung: Prüfen Sie das Array failed in der Antwort für feldspezifische fieldErrors. Nutzen Sie die identificationNumber jedes Eintrags (spiegelt den vom Client übergebenen Wert, sofern der Eingabe-Eintrag einen hatte) zur Zuordnung eines Fehlers zum Eingabe-Eintrag. Das Array success enthält erstellte Sendungen mit Paketnummern und Etiketten. Sind stattdessen alle Positionen fehlgeschlagen, lautet die Antwort immer 400 Bad Request — unabhängig von der Ursache, auch bei einem Ausfall der Routing-Engine, der weiterhin pro Position über errorCode: SHP-ROUTING-ENGINE-UNAVAILABLE gemeldet wird.

Etiketten​

Etiketten in der API-Antwort​

Eine erfolgreiche Sendungserstellung gibt jedes Etikett als Base64-kodierte PDF-Zeichenkette im Feld success[].label zurück.

{
  "success": [
    {
      "id": 1,
      "parcelNumber": "05305000123456",
      "label": "JVBERi0xLjQKJeLjz9MK..."
    }
  ]
}

Etikett dekodieren und speichern​

Shell:

echo "JVBERi0xLjQK..." | base64 --decode > label.pdf

JavaScript (Browser):

function downloadLabel(base64Label, parcelNumber) {
  const bytes = atob(base64Label);
  const array = new Uint8Array(bytes.length);
  for (let i = 0; i < bytes.length; i++) array[i] = bytes.charCodeAt(i);

  const blob = new Blob([array], { type: 'application/pdf' });
  const url = URL.createObjectURL(blob);

  const a = document.createElement('a');
  a.href = url;
  a.download = `label-${parcelNumber}.pdf`;
  a.click();
  URL.revokeObjectURL(url);
}

Java:

byte[] pdfBytes = Base64.getDecoder().decode(labelBase64);
Files.write(Path.of("label-" + parcelNumber + ".pdf"), pdfBytes);

Das richtige Etikettenformat wählen​

Setzen Sie printOptions.paperSize in Ihrer Sendungsanfrage:

FormatWertAnwendungsfall
A4"A4"Standard-Bürodrucker. Bis zu 4 Etiketten pro Blatt – Position über startPosition steuern (UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT)
Thermodruck / A6"A6"Direkt-Thermoetikett-Drucker (Zebra, Citizen usw.)
"printOptions": {
  "paperSize": "A6"
}

Mehrere Etiketten auf einem A4-Blatt​

Wenn Sie mehrere Sendungen drucken, platzieren Sie diese auf A4-Blättern, um Papier zu sparen:

[
  { ..., "printOptions": { "paperSize": "A4", "startPosition": "UPPER_LEFT" } },
  { ..., "printOptions": { "paperSize": "A4", "startPosition": "UPPER_RIGHT" } },
  { ..., "printOptions": { "paperSize": "A4", "startPosition": "BOTTOM_LEFT" } },
  { ..., "printOptions": { "paperSize": "A4", "startPosition": "BOTTOM_RIGHT" } }
]

Etikett leer, unbedruckt oder beschädigt​

Ursache 1: printOptions.paperSize stimmt nicht mit Ihrem Drucker überein.

Lösung: Setzen Sie paperSize explizit – "A4" für ganze Blätter (mit startPosition), "A6" für Thermoetikettendrucker.

Ursache 2: Base64-Dekodierfehler – zusätzliche Leerzeichen oder Zeilenumbrüche in der Zeichenkette.

Lösung: Alle Leerzeichen vor der Dekodierung entfernen:

const cleanBase64 = base64String.replace(/\s+/g, '');

Ursache 3: PDF-Viewer-Kompatibilität.

Lösung: Versuchen Sie, das PDF in einem anderen Viewer zu öffnen. Etiketten sind gültige PDF 1.4+-Dateien.

Ursache 4: DPI-Konflikt beim Thermodrucker.

Lösung: Konfigurieren Sie Ihren Drucker auf 203 oder 300 DPI (siehe Druckerhandbuch). Das Etikettenformat ist für Standard-DPD-Thermodrucker ausgelegt.

Paketshops​

Leere Ergebnisse bei der Adresssuche​

Ursache: Keine Shops im Standard-Suchradius (5 km) gefunden, oder die Adresse konnte nicht aufgelöst werden.

Lösung:

  1. Geben Sie sowohl zipCode als auch city an
  2. Entfernen Sie Service-/Typfilter, um die Suche zu erweitern
  3. Setzen Sie hideClosed: false, um auch temporär geschlossene Shops einzuschliessen

404 Not Found für Paketshop-ID​

Ursache: Die Shop-ID existiert nicht oder ist nicht mehr aktiv.

Lösung: Führen Sie eine neue Suche per Adresse oder Koordinaten durch, um aktuelle Shop-IDs zu erhalten.

Sendungsverfolgung​

404 Not Found für Paketnummer​

Ursache: Verfolgungsdaten sind noch nicht verfügbar oder die Paketnummer ist falsch.

Lösung:

  1. Überprüfen Sie die Paketnummer aus der Sendungserstellungs-Antwort (success[].parcelNumber)
  2. Warten Sie einige Minuten nach der Sendungserstellung
  3. Prüfen Sie das Format der Paketnummer (z.B. 05305000123456)

Abholaufträge und Abholbestellungen​

pickupDate wird abgelehnt​

Ursache: Das Datum liegt in der Vergangenheit oder hat ein falsches Format.

Lösung: Verwenden Sie das Format yyyy-MM-dd und stellen Sie sicher, dass das Datum mindestens der morgige Tag in der europäischen Zeitzone ist.

Allgemein​

HTTPS / SSL-Fehler​

Alle API-Aufrufe müssen HTTPS verwenden. Selbstsignierte Zertifikate werden in der Produktion nicht akzeptiert.

Rate Limiting (429 Too Many Requests)​

Implementieren Sie exponentielles Backoff. Cachen Sie Paketshop-Daten, da diese sich selten ändern.