SendLabel API Docs
SendLabel API-Dokumentation fuer ERP / WMS
Eine klarere Doku-Struktur: zuerst den Integrationspfad waehlen, danach Kernendpunkte, Ausfuehrungsmodi, Compatibility-Routen und Beispiel-Requests lesen.
Integrationsmodus
Unified + Compat API
Ausfuehrung
validate / dry_run / production
Lieferumfang
PDF + tracking + cancel
Zielsysteme
ERP / WMS / OMS
Ueberblick
Basis-URL, Authentifizierung und Compatibility-Pfade zuerst klaeren, damit die Umsetzung reibungsloser laeuft.
Basis-URL
https://www.sendlabel.de
Alle API-Pfade bauen auf dieser Domain auf.
OpenAPI
https://www.sendlabel.de/openapi.json
Maschinenlesbare Spezifikation fuer Postman, Insomnia und Code-Generatoren.
Unified API
https://www.sendlabel.de/api/v1
Empfohlen fuer neue Integrationen.
DHL-Compat-Basis
https://www.sendlabel.de/api/compat/dhl-parcel-de
Enthaelt sowohl native-nahe Mirrors fuer `/orders /labels /manifests /pickup` als auch `/v1/*`-Ressourcenaliase.
UPS-Compat-Basis
https://www.sendlabel.de/api/compat/ups
Enthaelt native-nahe Mirrors fuer `/security /shipments /track /rating /pickup` sowie `/v1/*`-Ressourcenaliase.
- - Unterstuetzte Authentifizierung: Authorization: Bearer <API_KEY> / X-API-Key / Basic(base64(prefix:key)) / dhl-api-key / x-ibm-client-id + x-ibm-client-secret
- - Jeder API-Key akzeptiert zusaetzlich virtuelle client_id-Aliase wie sendlabel_<API_KEY_PREFIX>, ups_<API_KEY_PREFIX> und dhl_<API_KEY_PREFIX>.
- - Mit bestehendem DHL-/UPS-Client zuerst die Compat-Routen ansehen; bei neuen Projekten zuerst /api/v1 verwenden.
- - Fehlerantworten der Compatibility-Schicht nutzen jetzt einen Zwei-Spuren-Vertrag: DHL-/UPS-aehnliche Felder bleiben erhalten und zusaetzlich wird ein normierter `sendlabelError`-Block geliefert.
Zuerst den Integrationspfad waehlen
Dieser Block ist im neuen Layout der wichtigste Einstiegspunkt.
Neues Projekt / neue API
Bevorzugt /api/v1. Felder und Fehlerstruktur sind einheitlicher und spaeter leichter zu pflegen.
Bestehender nativer DHL-/UPS-Flow im ERP / WMS
Bevorzugt /api/compat/{provider}/v1, damit moeglichst nur Basis-URL und Auth geaendert werden muessen.
Schnellstart
In dieser Reihenfolge gelingt der erste Dry Run mit wenig Reibung.
- 1. API-Key unter /admin/api-keys anlegen und passende Scopes vergeben.
- 2. Optional: einen Absender anlegen und als Standard setzen.
- 3. /api/v1/shipments/import zuerst mit validate_only oder dry_run testen.
- 4. Danach /api/v1/jobs pollen oder /api/v1/orders/{orderId} lesen.
API-Selbsttest fuer Kunden
Nach dem Login koennen Kunden ihr eigenes JSON direkt unter `/profile/api` testen, bevor ein vollstaendiger Client gebaut wird. Der Validator unterstuetzt jetzt SendLabel Unified, DHL Compat und UPS Compat.
- - SendLabel Unified: ideal zum Testen unserer generischen API, indem das JSON fuer `/api/v1/shipments/import` direkt eingefuegt wird.
- - DHL / UPS Compat: geeignet fuer Kunden mit nativen Carrier-Clients. Das Standardbeispiel kann beibehalten oder durch die echte Payload ersetzt werden.
- - Fuer SendLabel Unified sollten `validate_only` oder `dry_run` genutzt werden; kontrollierte Live-Tests bleiben vorerst auf DHL / UPS Compat beschraenkt.
Beispiel fuer Unified-API-Selbsttest
POST /api/profile/api-validator
Content-Type: application/json
{
"token": "slk_xxx",
"suite": "sendlabel_unified_v1",
"scenario": "import_address_review",
"executionMode": "dry_run",
"requestPayload": {
"carrier": "DHL_PARCEL_DE",
"labelPrintFormat": "A4",
"buyerType": "b2c",
"sender": {
"name": "SendLabel Demo GmbH",
"street1": "Lindenstr. 5",
"postalCode": "70173",
"city": "Stuttgart",
"countryCode": "DE"
},
"shipments": [
{
"reference": "ERP-SELF-TEST-001",
"recipient": {
"name": "Max Mustermann",
"street1": "Lindenstr. 5, 1.OG links, c/o Mann",
"postalCode": "70173",
"city": "Stuttgart",
"countryCode": "DE"
},
"parcel": { "weightKg": 1.2, "lengthCm": 30, "widthCm": 20, "heightCm": 10 }
}
]
}
}Ausfuehrungsmodi und Sicherheit
Firmenkunden sollten validate_only, dry_run und production als drei klar getrennte Integrationsstufen behandeln.
validate_only
Nur validieren. Kein Auftrag, keine Zahlung, kein Queue-Job.
dry_run
Liefert erwartete Aktion und Preis ohne echte Seiteneffekte.
production
Echte Ausfuehrung mit realem Auftrag, Zahlung und Label-Erstellung.
- - Der Ausfuehrungsmodus kann ueber X-SendLabel-Execution-Mode oder body.executionMode gesetzt werden.
- - Bei Import- / Cancel-POSTs sollte Idempotency-Key mitgesendet werden.
- - Innerhalb von 24 Stunden liefert dieselbe Kombination aus API-Key, Idempotency-Key und Request-Body die urspruengliche Antwort.
- - Unified Import und UPS-Compat-Import sind derzeit auf 300 Requests pro 60 Sekunden und API-Key begrenzt; bei Ueberschreitung wird 429 mit Retry-After-Header zurueckgegeben.
- - Ein einzelner Request unterstuetzt zwar bis zu 1000 Sendungen, empfohlen sind jedoch 50-200 Sendungen pro Batch, damit Retry, Fehlersuche und Latenz stabiler bleiben.
- - Fuer /api/v1/jobs wird ein Polling-Intervall von 2-5 Sekunden empfohlen; auch dieser Endpunkt liefert 429 + Retry-After, daher sollte bei Drosselung mit 2s -> 5s -> 10s zurueckgesetzt werden.
Einheitliche Fehlerstruktur
{
"ok": false,
"error": {
"code": "rate_limited",
"message": "Too many requests. Please retry later.",
"details": {
"retryAfterSeconds": 31,
"limit": 300,
"windowSeconds": 60
}
}
}Unified-API-Endpunkte
Die Unified API ist produktorientiert und eignet sich am besten fuer neue Kunden, neue Projekte und eigene Middleware.
Adressbuch und Stammdaten
GET
/api/v1/senders
Absenderliste lesen.
POST
/api/v1/senders
Absenderadresse anlegen.
POST
/api/v1/senders/default
Standard-Absender setzen.
Haupt-Workflow
POST
/api/v1/shipments/import
Sendungen importieren, validieren und Label-Erstellung ausloesen.
GET
/api/v1/jobs?ids=job_1,job_2
Status asynchroner Jobs abrufen.
GET
/api/v1/orders/{orderId}
Auftragsdetails, Label-Zusammenfassung und Tracking-Snapshot lesen.
GET
/api/v1/labels?orderId={orderId}
Label-PDF direkt herunterladen.
GET
/api/v1/orders/{orderId}/tracking
Tracking lesen; DHL unterstuetzt ?refresh=now.
POST
/api/v1/orders/{orderId}/cancel
Remote-Storno anfordern; benoetigt cancel:write.
Compatibility-Routen
Die langen Routelisten sind jetzt nach Carrier gruppiert, damit die passenden Endpunkte schneller gefunden werden.
DHL Parcel DE / Pickup Compatibility
https://www.sendlabel.de/api/compat/dhl-parcel-de/v1/*
Ressourcenaliase fuer senders / shipments/import / jobs / orders / tracking / cancel / labels; hilfreich fuer eine schrittweise Migration aelterer Systeme in das Unified-Ressourcenmodell.
https://www.sendlabel.de/api/compat/dhl-parcel-de/orders
Akzeptiert native DHL POST /orders-Payloads.
https://www.sendlabel.de/api/compat/dhl-parcel-de/orders?validate=true
Validiert nur Adresse und Daten, ohne echte Sendung zu erstellen.
https://www.sendlabel.de/api/compat/dhl-parcel-de/labels?shipment={shipmentNumber}
Gibt das PDF direkt per Shipmentnummer zurueck.
https://www.sendlabel.de/api/compat/dhl-parcel-de/manifests
Unterstuetzt Manifest- / Closeout-Erzeugung und Abfrage.
https://www.sendlabel.de/api/compat/dhl-parcel-de/pickup/v3/orders
Pickup-Auftraege anlegen und interne Auftraege automatisch zuordnen.
https://www.sendlabel.de/api/compat/dhl-parcel-de/pickup/v3/orders/{pickupId}
Pickup stornieren und Rueckerstattung abschliessen.
UPS Compatibility
https://www.sendlabel.de/api/compat/ups/v1/*
Ressourcenaliase fuer senders / shipments/import / jobs / orders / tracking / cancel / labels, geeignet fuer eine schrittweise Migration in das Unified-Ressourcenmodell.
https://www.sendlabel.de/api/compat/ups/security/v1/oauth/token
Mit API-Key-Praefix und vollem Key ein access_token holen.
https://www.sendlabel.de/api/compat/ups/v1/shipments/import
UPS-Sendungen ueber das normalisierte JSON-Format importieren und bei Erfolg Label/Tracking sofort zurueckgeben.
https://www.sendlabel.de/api/compat/ups/shipments/v1/ship
Akzeptiert native ShipmentRequest-Payloads und erstellt die Sendung synchron.
https://www.sendlabel.de/api/compat/ups/shipments/v1/labels/{shipmentIdentificationNumber}
PDF direkt ueber die Trackingnummer ausgeben.
https://www.sendlabel.de/api/compat/ups/shipments/v1/void/cancel/{shipmentIdentificationNumber}
UPS-Sendung direkt ueber die Trackingnummer stornieren.
https://www.sendlabel.de/api/compat/ups/track/v1/details/{inquiryNumber}
UPS-aehnliche Tracking-Abfrage.
https://www.sendlabel.de/api/compat/ups/rating/v1/Shop
Mehrservice-Tarife zurueckgeben.
UPS Label-API-Integration
Wenn ueber unsere API echte UPS-Label erzeugt werden sollen, gibt es zwei empfohlene Wege: Unified API fuer neue Systeme und UPS-Compat fuer bestehende native UPS-Clients.
Empfohlener UPS-Pfad
- - Neue Integrationen: bevorzugt `/api/v1/shipments/import`, weil Payload und Fehlerstruktur einheitlicher sind.
- - Bestehende native UPS-Integrationen: bevorzugt `/api/compat/ups/...`; meist muessen nur Basis-URL und Authentifizierung ersetzt werden.
- - Vor dem Go-live zuerst mit `validate_only` oder `dry_run` pruefen, damit Adressnormalisierung, Service-Code und Scopes stimmen.
- - Fuer die Live-Ausfuehrung werden `shipments:import` und `mode:production` benoetigt; fuer Remote-Storno zusaetzlich `cancel:write`.
- - Bei hochfrequenten Batch-Aufrufen sollte der Client zunaechst auf 300 Requests pro Minute und API-Key gedrosselt werden und Retry-After fuer Backoff beachten.
Option 1: UPS-Label ueber die Unified API erstellen
Dies ist der empfohlene Weg fuer neue Kunden. Nach der Erstellung kann ueber `results[].orderId / jobId` weiter auf Auftrag, Job und Label zugegriffen werden.
curl -X POST "https://www.sendlabel.de/api/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-SendLabel-Execution-Mode: production" \
-H "Idempotency-Key: ups-erp-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"carrier": "UPS",
"labelPrintFormat": "A4",
"senderId": "addr_sender_default",
"shipments": [
{
"reference": "UPS-ERP-0001",
"recipient": {
"name": "Erika Mustermann",
"company": "Muster GmbH",
"street1": "Lindenstr. 5",
"postalCode": "70173",
"city": "Stuttgart",
"countryCode": "DE",
"email": "erika@example.com",
"phone": "+49 151 23456789"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 30,
"widthCm": 20,
"heightCm": 10
}
}
]
}'Option 2: UPS-Compat Auth-Beispiel
Bei vorhandenem UPS-OAuth-aehnlichem Client zuerst ueber die gespiegelt Token-Route ein kurzlebiges Bearer-Token holen. Als `client_id` wird `ups_<API_KEY_PREFIX>` empfohlen, als `client_secret` der volle API-Key.
curl -X POST "https://www.sendlabel.de/api/compat/ups/security/v1/oauth/token" \
-u "ups_<API_KEY_PREFIX>:<API_KEY>" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials"Option 2: UPS-Compat-Import-Beispiel
Wenn der Kunde bereits unser UPS-Compat-Import-JSON verwendet, liefert diese Route jetzt ebenfalls Label / Tracking sofort nach erfolgreicher UPS-Erstellung zurueck und fuehrt die Abrechnung danach asynchron aus.
curl -X POST "https://www.sendlabel.de/api/compat/ups/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-SendLabel-Execution-Mode: production" \
-H "Idempotency-Key: ups-compat-import-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"carrier": "UPS",
"labelPrintFormat": "A4",
"senderId": "addr_sender_default",
"shipments": [
{
"reference": "UPS-COMPAT-0001",
"recipient": {
"name": "Erika Mustermann",
"company": "Muster GmbH",
"street1": "Lindenstr. 5",
"postalCode": "70173",
"city": "Stuttgart",
"countryCode": "DE",
"email": "erika@example.com",
"phone": "+49 151 23456789"
},
"parcel": {
"weightKg": 1.5,
"lengthCm": 30,
"widthCm": 20,
"heightCm": 10
}
}
]
}'UPS-Compat Versandbeispiel
Diese Route akzeptiert UPS-aehnliche `ShipmentRequest`-Payloads und liefert zusaetzlich `ShipmentResponse.Compatibility`, damit internes `orderId`, `labelUrl` und Adresspruefungen ruecklesbar sind.
curl -X POST "https://www.sendlabel.de/api/compat/ups/shipments/v1/ship" \
-H "Authorization: Bearer <UPS_COMPAT_ACCESS_TOKEN>" \
-H "X-SendLabel-Execution-Mode: production" \
-H "Idempotency-Key: ups-native-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"ShipmentRequest": {
"Shipment": {
"Shipper": {
"Name": "SendLabel Demo GmbH",
"AttentionName": "Warehouse Team",
"Phone": { "Number": "+497111234567" },
"Address": {
"AddressLine": ["Lindenstr. 5"],
"PostalCode": "70173",
"City": "Stuttgart",
"CountryCode": "DE"
}
},
"ShipFrom": {
"Name": "SendLabel Demo GmbH",
"AttentionName": "Warehouse Team",
"Phone": { "Number": "+497111234567" },
"Address": {
"AddressLine": ["Lindenstr. 5"],
"PostalCode": "70173",
"City": "Stuttgart",
"CountryCode": "DE"
}
},
"ShipTo": {
"Name": "Erika Mustermann",
"AttentionName": "Erika Mustermann",
"Phone": { "Number": "+4915123456789" },
"Address": {
"AddressLine": ["Lindenstr. 5"],
"PostalCode": "70173",
"City": "Stuttgart",
"CountryCode": "DE"
}
},
"Service": { "Code": "11" },
"Package": [{
"PackagingType": { "Code": "02" },
"PackageWeight": { "Weight": "1.5" },
"Dimensions": { "Length": "30", "Width": "20", "Height": "10" }
}]
},
"LabelSpecification": {
"LabelImageFormat": { "Code": "PDF" }
}
}
}'Erfolgsantworten und Felder fuer asynchrone Abrechnung
Erfolgsantwort fuer Unified UPS Import
{
"ok": true,
"created": 1,
"total": 1,
"executionMode": "production",
"sideEffectsSuppressed": false,
"results": [
{
"index": 0,
"reference": "UPS-ERP-0001",
"ok": true,
"orderId": "ord_ups_20260001",
"jobId": "job_settlement_20260001",
"jobType": "api_async_settlement",
"trackingNumber": "1Z12345E0205271688",
"labelUrl": "https://www.sendlabel.de/api/v1/labels?orderId=ord_ups_20260001",
"asyncSettlement": {
"status": "pending",
"jobId": "job_settlement_20260001"
},
"notes": [
"UPS shipment created successfully. Billing settlement continues asynchronously in the background."
]
}
]
}Erfolgsantwort fuer UPS-Compat-Import
{
"ok": true,
"created": 1,
"total": 1,
"executionMode": "production",
"sideEffectsSuppressed": false,
"results": [
{
"index": 0,
"reference": "UPS-COMPAT-0001",
"ok": true,
"orderId": "ord_ups_20260002",
"jobId": "job_settlement_20260002",
"jobType": "api_async_settlement",
"trackingNumber": "1Z12345E0205271689",
"labelUrl": "https://www.sendlabel.de/api/compat/ups/v1/labels?orderId=ord_ups_20260002",
"asyncSettlement": {
"status": "pending",
"jobId": "job_settlement_20260002"
},
"notes": [
"UPS shipment created successfully. Billing settlement continues asynchronously in the background."
]
}
]
}- - `results[].trackingNumber` und `results[].labelUrl` bedeuten, dass UPS die Sendung bereits erfolgreich erstellt hat und das Label sofort angezeigt oder heruntergeladen werden kann.
- - `results[].asyncSettlement.status = pending` bedeutet, dass Belastung / Kreditabbuchung im Hintergrund weiterlaeuft.
- - Falls die asynchrone Abrechnung letztlich fehlschlaegt, versucht das System automatisch erneut, sendet nach mehrfachen Fehlern Alarm-E-Mails und versucht anschliessend automatisch das UPS-Label zu voiden.
Hauefige Folge-Endpunkte nach UPS-Erstellung
- - Nach Erstellung ueber die Unified API: `GET /api/v1/jobs?ids=<jobId>` fuer den Jobstatus pollen.
- - Auftragsdetails mit `GET /api/v1/orders/{orderId}` lesen; UPS-Compat-Clients koennen auch `GET /api/compat/ups/v1/orders/{orderId}` verwenden.
- - Das Label-PDF ueber `GET /api/v1/labels?orderId={orderId}` oder die UPS-Compat-Route `GET /api/compat/ups/v1/labels?orderId={orderId}` herunterladen.
- - Tracking ueber `GET /api/v1/orders/{orderId}/tracking` oder `GET /api/compat/ups/v1/orders/{orderId}/tracking` lesen.
- - UPS-Label remote stornieren ueber `POST /api/v1/orders/{orderId}/cancel` oder trackingbasiert ueber `DELETE /api/compat/ups/shipments/v1/void/cancel/{shipmentIdentificationNumber}`.
Carrier und Adresslogik
Dieser Abschnitt behaelt die wichtigen Geschaeftsregeln, ist aber kuerzer und leichter zu scannen.
Carrier und Services
- - DHL_PARCEL_DE: DHL Paket (Inland / EU)
- - DHL_KLEINPAKET: DHL Kleinpaket (nur DE, <= 1 kg)
- - DP_INTL: Deutsche Post International (Deutschland in Nicht-EU-Laender)
- - Fuer UPS bevorzugt die Compat-Routen verwenden, besonders bei bestehendem nativen UPS-Client.
Adressvalidierung und Aufteilung
- - Vor der echten DHL-Label-Erstellung wird validate aufgerufen und moeglichst ein feldgenauer Fehler zurueckgegeben.
- - Wenn der Fehler Leitcode enthaelt, sind PLZ, Ort, Strasse oder Hausnummer meist inkonsistent.
- - Das System versucht, street1 in streetName + streetNo + addressExtra aufzuteilen, zum Beispiel Lindenstr. 5, 1.OG links, c/o Mann.
- - Die UPS-Compat-Routen nutzen dieselbe Aufteilungslogik, damit c/o, Etage oder Klingel nicht in der Hauptstrasse landen.
Beispiel-Request und Response
Der haeufigste Dry-Run-Request und die Standard-Response stehen zusammen, damit Implementierer schneller kopieren und testen koennen.
Request-Beispiel: dry_run Import und Preisvorschau
curl -X POST "https://www.sendlabel.de/api/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-H "X-SendLabel-Execution-Mode: dry_run" \
-H "Idempotency-Key: erp-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"carrier": "DHL_PARCEL_DE",
"labelPrintFormat": "A4",
"buyerType": "b2b",
"shipments": [
{
"reference": "ERP-0001",
"recipient": {
"name": "Max Mustermann",
"street1": "Dingelberg 18",
"postalCode": "38444",
"city": "Wolfsburg",
"countryCode": "DE",
"email": "max@example.com",
"phone": "+49 176 23414739"
},
"parcel": { "weightKg": 1.8, "lengthCm": 30, "widthCm": 20, "heightCm": 10 }
}
]
}'Response-Beispiel: Standardstruktur
{
"ok": true,
"created": 0,
"total": 1,
"executionMode": "dry_run",
"sideEffectsSuppressed": true,
"results": [
{
"index": 0,
"reference": "ERP-0001",
"ok": true,
"simulated": true,
"wouldCreateShipment": true,
"estimatedAmount": { "currency": "EUR", "amount": 6.23 },
"notes": ["Dry run completed. No order, label, payment, or queue job was created."]
}
]
}- - In production enthaelt results[] normalerweise orderId und jobId.
- - UPS dry_run kann auch estimatedService zurueckgeben; bei niedriger Adress-Sicherheit koennen notes und addressReview erscheinen.
- - Hauefige labelPrintFormat-Werte: A4, A5, 910-300-600, 100x70mm.
Auftrags-Lifecycle und Webhooks
Abfrage, Storno, Webhooks und Signaturregeln sind jetzt in einem Bereich zusammengefasst.
Auftrag und Storno
- - GET /api/v1/orders/{orderId}: liefert Auftragsdetails, Label-Zusammenfassung, Tracking-Snapshot und die oeffentliche Tracking-URL.
- - GET /api/v1/orders/{orderId}/tracking: Tracking lesen; DHL unterstuetzt ?refresh=now.
- - POST /api/v1/orders/{orderId}/cancel: Remote-Storno anfordern; der API-Key braucht cancel:write.
Webhook
- - Webhook-URL, Eventliste und gemeinsames Secret werden am API-Key konfiguriert.
- - Unterstuetzte Events: order.created, order.cancelled, label.created, tracking.updated.
- - Header: x-sendlabel-event, x-sendlabel-timestamp, x-sendlabel-signature.
- - Signaturformel: HMAC_SHA256(webhookSecret, timestamp + '.' + rawBody).
- - Webhooks werden asynchron ueber Hintergrund-Jobs zugestellt und bei Fehlern automatisch erneut versucht.
Batch-Import im Web
Ein klarer Einstieg fuer Nicht-API-Kunden, damit die Web-Oberflaeche nicht uebersehen wird.
- - Auf der Seite „Sendung erstellen“ den Bereich „Batch Import (Excel)“ nutzen.
- - Das System liest das erste Arbeitsblatt, uebernimmt die Daten in den Warenkorb und fuehrt danach die gemeinsame Zahlung und Label-Erstellung aus.