SendLabel API Migration

Migration von nativen DHL-APIs zur SendLabel-API

Zuerst den Aenderungsumfang einschaetzen und dann entscheiden, ob eine DHL-Compat-Migration mit wenig Aufwand oder der direkte Wechsel zur Unified-API sinnvoller ist.

Zurueck zum Help Center API-Dokumentation oeffnen API-Zugangsseite oeffnen

Migrationsfazit

- Wenn der Kunde nur Einzel-Sendungen erstellt und Labels abruft, beschraenkt sich die Migration meist auf Domain, Authentifizierung und eine kleine Payload-Pruefung.

- Bei starker Abhaengigkeit von nativen DHL-Fehlercodes, Multi-Sendungs-Requests, kontoweiten Manifesten oder separaten Produktlinien steigt der Aufwand deutlich.

- Der sicherste Weg ist meist zuerst die DHL-Compat-Routen von SendLabel zu nutzen und spaeter auf die Unified-Endpunkte zu wechseln.

Empfohlener Migrationspfad

- Phase 1: Base URL, Auth-Header und Kernpfade auf SendLabel umstellen.

- Phase 2: zuerst `orders / labels / senders` stabilisieren, damit der Hauptfluss durchlaeuft.

- Phase 3: Idempotenz, Fehlerbehandlung und Abstimmung der Abrechnung nachziehen und dann ueber den Wechsel zur Unified-API entscheiden.

Typische Endpunkt-Zuordnung

From

DHL orders

SendLabel `/api/compat/dhl-parcel-de/orders`

DHL labels

SendLabel `/api/compat/dhl-parcel-de/labels`

DHL senders

SendLabel `/api/compat/dhl-parcel-de/v1/senders`

DHL default sender

SendLabel `/api/compat/dhl-parcel-de/v1/senders/default`

DHL manifests

SendLabel `/api/compat/dhl-parcel-de/manifests`

New unified flow

SendLabel `/api/v1/shipments/import`

Migrationsvergleich

Diese Tabelle eignet sich als praktische Checkliste fuer die technische Aufwandsschaetzung.

Thema	DHL nativ	SendLabel API	Was der Client aendern muss
Authentifizierung	Direkte Nutzung von DHL API Key / Secret und nativen Auth-Headern.	Umstellung auf einen SendLabel API Key, meist per `Authorization: Bearer <API_KEY>`.	Request-Header und Secret-Handling muessen angepasst werden.
Base URL	Aufruf der offiziellen DHL-Domains.	Stattdessen die SendLabel-Domain verwenden.	Die Basis-Domain austauschen und idealerweise konfigurierbar halten.
Endpoint-Pfade	DHL-native orders / labels / senders / manifests verwenden.	Bevorzugt die DHL-Compat-Routen von SendLabel nutzen oder fuer neue Projekte direkt `/api/v1/shipments/import`.	Mindestens die Pfade neu zuordnen.
Versand-Payload	Feldnamen, Verschachtelung und Enums folgen der nativen DHL-Struktur.	Compat-Routen bleiben nahe an DHL, normalisieren Eingaben aber dennoch.	Meist reicht eine kleine Feldpruefung; tiefe DHL-spezifische Annahmen brauchen ggf. eine Mapping-Schicht.
Mehrere Sendungen pro Request	Manche Clients senden mehrere Sendungen in einem Request.	Die aktuelle DHL-Compat-`orders`-Route eignet sich eher fuer Einzel-Sendungen; fuer Batch besser der Unified-Import.	Bei Abhaengigkeit von Multi-Sendungs-Requests muss auf Einzelaufrufe oder die Unified-API umgestellt werden.
Label-Rueckgabe	Der Client erwartet eventuell das native DHL-Labelverhalten.	API-Clients arbeiten typischerweise direkt mit `labelBase64`; spaeterer Download ueber das Label-Endpoint bleibt moeglich.	Falls der Client einen direkten PDF-Stream erwartet, ist ein zusaetzlicher Decode- oder Download-Schritt noetig.
Sender-Verwaltung	Direkte Nutzung der in DHL hinterlegten Sender.	Nutzung des SendLabel-Sender-Systems; Compat-Sender-Routen senken den Migrationsaufwand.	Sender muessen meist uebernommen oder neu angelegt und die Default-Logik angepasst werden.
Manifest-Semantik	Einige Clients verstehen Manifeste als DHL-kontoweite Artefakte.	SendLabel stellt Manifeste derzeit eher aus Kunden-/Systemsicht bereit.	Bei Erwartung kontoweiter Manifest-Sammlungen muss die fachliche Erwartung neu abgestimmt werden.
Adressvalidierung	Clients geben Adressen eventuell direkt ungeprueft an DHL weiter.	SendLabel standardisiert, splittet und validiert Adressen vor der Erstellung.	Adressprobleme koennen frueher sichtbar werden; Validierungsfehler sollten an ERP/WMS-Nutzer weitergegeben werden.
Fehlerbehandlung	Der Code haengt moeglicherweise direkt an nativen DHL-Fehlercodes und Feldern.	Compatibility-Fehler nutzen jetzt eine Zwei-Spuren-Struktur: DHL-aehnliche Felder bleiben moeglichst erhalten und zusaetzlich wird ein normierter `sendlabelError`-Block geliefert.	Wenn der Client native DHL-Fehlerfelder hart codiert auswertet, sollte das angepasst werden; bevorzugt zuerst `sendlabelError` lesen und alte Felder nur als Rueckfall beibehalten.
Idempotenz und Retries	Viele Clients wiederholen Requests bei Timeout einfach erneut.	Explizite Nutzung von `Idempotency-Key`, damit SendLabel Duplikate sicher behandeln kann.	Dringende Empfehlung: Idempotenzschluessel in das ERP/WMS-Request-Modell aufnehmen.
Abrechnung und Rechnungen	Die Abrechnung lief bisher moeglicherweise direkt zwischen Kunde und DHL.	Nach der Umstellung laufen Sendungen in das Guthaben-, Kreditlimit- und Sammelrechnungsmodell von SendLabel.	Der Kunde muss das neue Abstimmungs- und Rechnungsmodell akzeptieren, insbesondere Wochenabrechnung oder limitgetriggerte Rechnungen.
Pickup / Postnumber / Tracking	Einige Clients betrachten diese Faehigkeiten standardmaessig als Teil von Shipping.	Diese Funktionen bleiben getrennte Produktlinien und sollten nicht automatisch als Teil von Shipping angenommen werden.	Falls der Client diese APIs nutzt, muessen Freischaltung und Tests separat bestaetigt werden.

Implementierungsnahe Endpunkt-Gegenueberstellung

Dieser Abschnitt ist fuer Entwickler gedacht. Jede Zeile zeigt die empfohlene Zielroute, Header-Aenderungen, Request-/Response-Unterschiede und die uebliche Eingriffstiefe im Code.

Originaler DHL-Endpunkt	Empfohlener SendLabel-Endpunkt	Header-/Auth-Aenderung	Request-Aenderung	Response-Aenderung	Code-Aenderungsgrad
POST DHL orders	POST /api/compat/dhl-parcel-de/orders	Native DHL-Auth-Header durch SendLabel API-Key-Auth ersetzen.	Die Payload bleibt grob aehnlich, die aktuelle Spiegelroute unterstuetzt aber nur eine Sendung pro Request; Multi-Sendungs-Clients muessen splitten oder zur Unified-API wechseln.	Die Antwort enthaelt SendLabel-Kompatibilitaetsinfos und lokale Auftragssemantik; nicht nur auf native DHL-Felder verlassen.	Mittel
GET DHL labels	GET /api/compat/dhl-parcel-de/labels	Ebenfalls auf SendLabel API Key umstellen.	Als Suchparameter `shipment`, `shipmentNumber`, `trackingNumber` oder `orderId` verwenden.	Diese Spiegelroute liefert standardmaessig einen PDF-Stream; bei spaeterem Wechsel zur Unified-API kann auch `labelBase64` genutzt werden.	Niedrig
GET/POST DHL manifests	GET/POST /api/compat/dhl-parcel-de/manifests	Auf SendLabel API Key umstellen.	Abruf per Datum oder shipmentNumber bleibt moeglich, der Scope ist aber kundenspezifisch statt kontoweit.	Das gelieferte Manifest und die Zuordnung bleiben nutzbar, fachlich muss aber geprueft werden, ob ein kontoweites Gesamtmanifest benoetigt wird.	Mittel
GET/POST DHL senders	GET/POST /api/compat/dhl-parcel-de/v1/senders	Auf SendLabel API Key umstellen.	Vorhandene Sender muessen aus dem DHL-Konto in das SendLabel-Sender-System uebernommen werden.	Die Antworten basieren auf SendLabel-Sendern; Primärschluessel sollten nicht mit nativen DHL-Sender-IDs gleichgesetzt werden.	Mittel
POST DHL default sender	POST /api/compat/dhl-parcel-de/v1/senders/default	Auf SendLabel API Key umstellen.	Der Default-Sender ist nicht mehr der DHL-Kontowert, sondern ein SendLabel-seitiger Standard.	Die Antwort spiegelt die SendLabel-seitige Default-Sender-Auswahl wider.	Niedrig
POST DHL batch shipment creation	POST /api/v1/shipments/import	Auf SendLabel API Key umstellen und `Idempotency-Key` verpflichtend machen.	Es ist eine Umstellung von der nativen DHL-Struktur auf das Unified-Format von SendLabel noetig, inklusive `carrier`, `shipments[]`, Adress- und Paketfeldern.	Die Antwort folgt dem Unified-Import-Modell mit `results[]`, Execution Mode sowie ggf. `labelBase64` oder lokalen orderIds.	Hoch

Header-Beispiele

Korrekte Header reichen oft fuer die erste Integrationsrunde. Diese Beispiele zeigen die minimale Umstellung von nativen DHL-Requests auf SendLabel-Compat oder Unified.

Beispiel fuer native DHL-Header

Der urspruengliche Client ruft DHL meist direkt auf und sendet native DHL-Auth-Header.

POST /orders HTTP/1.1
Host: api-eu.dhl.com
Content-Type: application/json
DHL-API-Key: <DHL_API_KEY>
DHL-API-Secret: <DHL_API_SECRET>

{ ... }

Beispiel fuer SendLabel-Compat-Header

Fuer den Weg mit wenig Aenderung sollten zuerst Domain und Auth auf SendLabel umgestellt werden, waehrend die Payload moeglichst nah bleibt.

POST /api/compat/dhl-parcel-de/orders HTTP/1.1
Host: api.sendlabel.example
Authorization: Bearer <SENDLABEL_API_KEY>
Content-Type: application/json
Idempotency-Key: erp-order-20260623-10001

{ ... }

Beispiel fuer SendLabel-Unified-Header

Wenn der Kunde einen groesseren Umbau akzeptiert, nutzt die Unified-API dieselbe Auth-Art, aber ein anderes Payload-Modell.

POST /api/v1/shipments/import HTTP/1.1
Host: api.sendlabel.example
Authorization: Bearer <SENDLABEL_API_KEY>
Content-Type: application/json
Idempotency-Key: erp-order-20260623-10001

{ ... }

Before-/After-Request-Beispiele

Dieser Abschnitt kann direkt an Entwickler auf Kundenseite gehen. Fuer wenig Aenderung zuerst Compat nutzen und spaeter bei Bedarf fuer UPS und DHL gemeinsam auf Unified Import wechseln.

Beispiel 1: Native DHL-Einzelsendung

Dies ist ein typischer Ausgangspunkt: eine Sendung direkt im nativen DHL-Payload-Stil senden.

{
  "profile": "STANDARD_GRUPPENPROFIL",
  "shipments": [
    {
      "product": "V01PAK",
      "billingNumber": "22222222220101",
      "refNo": "ERP-10001",
      "shipper": {
        "name1": "ACME GmbH",
        "addressStreet": "Musterstrasse",
        "addressHouse": "12",
        "postalCode": "53113",
        "city": "Bonn",
        "country": "DE"
      },
      "consignee": {
        "name1": "Max Mustermann",
        "addressStreet": "Hauptstrasse",
        "addressHouse": "8",
        "postalCode": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "details": {
        "weight": {
          "uom": "kg",
          "value": 1.2
        }
      }
    }
  ]
}

Beispiel 2: SendLabel-Compat mit minimaler Aenderung

Bei einer Migration mit wenig Aufwand bleibt die Sendungsstruktur nahe an DHL, waehrend die Zielroute auf SendLabel-Compat umgestellt und pro Request nur eine Sendung geschickt wird.

{
  "profile": "STANDARD_GRUPPENPROFIL",
  "shipments": [
    {
      "product": "V01PAK",
      "billingNumber": "22222222220101",
      "refNo": "ERP-10001",
      "shipper": {
        "name1": "ACME GmbH",
        "addressStreet": "Musterstrasse",
        "addressHouse": "12",
        "postalCode": "53113",
        "city": "Bonn",
        "country": "DE"
      },
      "consignee": {
        "name1": "Max Mustermann",
        "addressStreet": "Hauptstrasse",
        "addressHouse": "8",
        "postalCode": "10115",
        "city": "Berlin",
        "country": "DE"
      },
      "details": {
        "weight": {
          "uom": "kg",
          "value": 1.2
        }
      }
    }
  ]
}

Beispiel 3: Umgestellte SendLabel-Unified-Anfrage

Wenn der Kunde eine gemeinsame Struktur fuer DHL, UPS und weitere Carrier nutzen moechte, eignet sich das Unified-Import-Payload besser.

{
  "carrier": "dhl",
  "service": "parcel_de",
  "shipments": [
    {
      "shipper": {
        "name": "ACME GmbH",
        "address1": "Musterstrasse 12",
        "postalCode": "53113",
        "city": "Bonn",
        "countryCode": "DE"
      },
      "recipient": {
        "name": "Max Mustermann",
        "address1": "Hauptstrasse 8",
        "postalCode": "10115",
        "city": "Berlin",
        "countryCode": "DE"
      },
      "parcel": {
        "weightKg": 1.2
      },
      "references": {
        "customerReference": "ERP-10001"
      },
      "options": {
        "labelFormat": "pdf"
      }
    }
  ]
}

Beispiel 4: Wichtige Felder der Unified-Antwort

Die Unified-Antwort ist keine native DHL-Payload mehr. ERP/WMS-Clients sollten mindestens lokale orderId-, Tracking- und labelBase64-Felder auslesen.

{
  "results": [
    {
      "ok": true,
      "carrier": "dhl",
      "orderId": "ord_123456",
      "trackingNumber": "00340434161234567890",
      "labelBase64": "<base64-pdf>",
      "executionMode": "sync"
    }
  ]
}

curl-Beispiele

Diese Befehle eignen sich fuer die erste technische Abstimmung. Zuerst Auth, Routen und Label-Download pruefen, danach den Produktiv-Client anpassen.

curl-Beispiel 1: Compat fuer Einzelsendung

Geeignet fuer eine Migration mit wenig Aufwand. Die DHL-nahe Payload bleibt weitgehend erhalten, nur Zielroute und Authentifizierung werden umgestellt.

curl -X POST "https://api.sendlabel.example/api/compat/dhl-parcel-de/orders" \
  -H "Authorization: Bearer <SENDLABEL_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-order-20260623-10001" \
  --data @dhl-compat-order.json

curl-Beispiel 2: Unified Import

Geeignet fuer Kunden, die ein gemeinsames Request-Modell fuer DHL, UPS und weitere Carrier nutzen wollen.

curl -X POST "https://api.sendlabel.example/api/v1/shipments/import" \
  -H "Authorization: Bearer <SENDLABEL_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-order-20260623-10001" \
  --data @sendlabel-unified-order.json

curl-Beispiel 3: Label per Trackingnummer laden

Wenn der Client vorerst beim PDF-Download bleibt, kann das Compat-Label-Endpunkt weiter mit Trackingnummer genutzt werden.

curl -L "https://api.sendlabel.example/api/compat/dhl-parcel-de/labels?trackingNumber=00340434161234567890" \
  -H "Authorization: Bearer <SENDLABEL_API_KEY>" \
  --output label.pdf

Beispieldateien

Wenn Entwickler zunaechst mit den curl-Befehlen auf dieser Seite testen, zeigt diese Tabelle, wofuer jede Beispieldatei gedacht ist und zu welchem Endpunkt sie gehoert.

Dateiname	Zweck	Ziel-Endpunkt
dhl-compat-order.json	Wird fuer das Compat-Beispiel einer Einzelsendung genutzt und behaelt die DHL-nahe Feldstruktur bei.	POST /api/compat/dhl-parcel-de/orders
sendlabel-unified-order.json	Wird fuer das Unified-Import-Beispiel genutzt und eignet sich fuer Kunden mit gemeinsamem UPS-/DHL-Modell.	POST /api/v1/shipments/import
label.pdf	Ausgabedatei fuer das Compat-Label-Download-Beispiel, praktisch fuer schnelle manuelle Pruefungen.	GET /api/compat/dhl-parcel-de/labels

Feldmapping-Kurzuebersicht

Diese Tabelle hilft bei der Aufwandsschaetzung. Sie zeigt haeufige DHL-Felder, deren Zustand im Compat-Modus und die uebliche Zielstruktur im Unified-Modell.

Typisches DHL-Feld	SendLabel Compat	SendLabel Unified	Hinweis
shipments[0].product	shipments[0].product	service	Bei Compat bleibt es fast unveraendert; bei Unified wird auf SendLabel-Servicekennungen umgestellt.
shipments[0].billingNumber	shipments[0].billingNumber	not passed by customer in most cases	Bei Compat meist weiter vorhanden; bei Unified muss die DHL-Abrechnungsnummer normalerweise nicht direkt mitgegeben werden.
shipments[0].refNo	shipments[0].refNo	shipments[0].references.customerReference	Die Kundenreferenz sollte erhalten bleiben, der Feldpfad aendert sich jedoch im Unified-Modell.
shipments[0].shipper.name1	shipments[0].shipper.name1	shipments[0].shipper.name	Compat behaelt die Form bei; Unified normalisiert auf ein allgemeines Namensfeld.
shipments[0].shipper.addressStreet + addressHouse	shipments[0].shipper.addressStreet + addressHouse	shipments[0].shipper.address1	Unified bevorzugt eine einzeilige Adresse; getrennte Strasse/Hausnummer sollten in einer Mapping-Schicht zusammengefuehrt werden.
shipments[0].consignee.*	shipments[0].consignee.*	shipments[0].recipient.*	Das Empfaengerobjekt heisst im Unified-Modell `recipient`.
shipments[0].details.weight.value	shipments[0].details.weight.value	shipments[0].parcel.weightKg	Das Gewichtsfeld wechselt von der nativen DHL-Verschachtelung in das direkte Parcel-Modell.
label response document	PDF stream from labels endpoint	results[0].labelBase64	Wenn ERP/WMS einen separaten Download-Request vermeiden will, eignet sich Unified besser, da das Base64-Label direkt zurueckgegeben werden kann.
native DHL error fields	compat response + SendLabel wrapper	unified import result/errors	DHL-native Fehler sollten nicht mehr exklusiv hart codiert geparst werden; besser ist eine gemeinsame Anpassungsschicht.

Vergleich erfolgreicher Antworten

Diese Beispiele zeigen Entwicklern, dass nach der Migration nicht mehr ausschliesslich native DHL-Erfolgsfelder hart codiert ausgewertet werden sollten.

Erfolgsbeispiel 1: DHL-nativer Stil

Altsysteme lesen oft direkt native DHL-Felder wie Sendungsnummer, Label-Dokumente und Statusstrukturen aus.

{
  "shipments": [
    {
      "shipmentNo": "00340434161234567890",
      "shipmentLabel": {
        "format": "PDF",
        "data": "<base64-pdf>"
      },
      "status": {
        "statusCode": 2000,
        "statusText": "OK"
      }
    }
  ]
}

Erfolgsbeispiel 2: SendLabel Compat

Compat bleibt nahe an der DHL-Semantik, kann aber zusaetzlich SendLabel-Kompatibilitaetsdaten und lokale Auftragssemantik enthalten.

{
  "orderId": "ord_123456",
  "trackingNumber": "00340434161234567890",
  "labelBase64": "<base64-pdf>",
  "Compatibility": {
    "provider": "DHL",
    "route": "/api/compat/dhl-parcel-de/orders"
  }
}

Erfolgsbeispiel 3: SendLabel Unified

Unified orientiert sich nicht mehr primär an nativen DHL-Antworten, sondern an einem gemeinsamen Ergebnisformat fuer DHL, UPS und weitere Carrier.

{
  "results": [
    {
      "ok": true,
      "carrier": "dhl",
      "service": "parcel_de",
      "orderId": "ord_123456",
      "trackingNumber": "00340434161234567890",
      "labelBase64": "<base64-pdf>",
      "executionMode": "sync"
    }
  ]
}

Checkliste vor dem Cutover

- Festlegen, ob der Kunde mit `DHL compat` startet oder direkt auf den Unified-Import wechselt.

- Test-Key bereitstellen und `Idempotency-Key` fuer alle relevanten Requests verlangen.

- Sender-Setup, Labelformat, Adressfelder, Referenzlaenge und Fehlerzweige pruefen.

- Falls der Kunde auch Pickup / Postnumber / Tracking nutzt, diese separat freischalten und testen.

- Vor dem Go-live sowohl Dry Run als auch Live Test durchfuehren und danach Billing- und Rechnungslogik abstimmen.