API-Dokumentation
API-Spezifikation, Testfälle und Excel-Sammelimport.
Basis-URL: https://www.sendlabel.de
Authentifizierung: Authorization: Bearer <API_KEY>
Schnellstart
1) Admin erstellt einen API Key unter /admin/api-keys und gibt ihn an den Kunden.
2) Optional: Absender anlegen und als Standard setzen (dann muss der Absender nicht bei jedem Request mitgesendet werden).
3) POST /api/v1/shipments/import (DHL-Validierung + Job in Queue).
4) Status abfragen über /api/v1/jobs oder /api/v1/orders/{orderId}.
Endpoints
- Absender-Adressbuch: GET/POST /api/v1/senders
- Standard-Absender setzen: POST /api/v1/senders/default
- Import + Label-Erstellung (DHL validate + Queue): POST /api/v1/shipments/import
- Jobs: GET /api/v1/jobs?ids=job_1,job_2
- Auftrag: GET /api/v1/orders/{orderId}
- Label PDF: GET /api/v1/labels?orderId={orderId}
Carrier
- DHL_PARCEL_DE: DHL Paket (Inland/EU)
- DHL_KLEINPAKET: DHL Kleinpaket (nur DE, ≤1 kg)
- DP_INTL: Deutschland → International (Deutsche Post International, ohne EU)
Feld-Aliase (Kompatibilität)
Wir akzeptieren gängige Aliase. Absender kann z.B. als sender / shipper / ship_from / address_from / from gesendet werden. Die Sendungsliste kann shipments / items / orders / packages heißen. Aliase lassen sich pro API Key im Admin-Bereich erweitern.
DHL Validierung & Fehler (Leitcode)
Vor der Erstellung wird DHL validate aufgerufen. Wenn eine Fehlermeldung Leitcode enthält, liegt es meist an inkonsistenten PLZ/Ort/Straße/Hausnummer-Angaben.
Hinweis: DHL kann warning-Meldungen zurückgeben (z. B. automatische Korrektur von „Warenpost“ zu „DHL Kleinpaket“). Wenn das Label im Response enthalten ist, sollten warnings die Label-Speicherung und Ausgabe nicht verhindern.
Wenn Ihr ERP/WMS Straße und Hausnummer nicht sauber trennt, versuchen wir die Trennung aus street1. Falls das fehlschlägt, senden Sie bitte explizit streetName + streetNo.
Test: Import & Label-Erstellung (Absender wird weggelassen, Standard-Absender wird genutzt)
curl -X POST "https://www.sendlabel.de/api/v1/shipments/import" \
-H "Authorization: Bearer <API_KEY>" \
-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 }
}
]
}'In labelPrintFormat senden Sie einfach den DHL-Formatcode. Häufige Werte sind A4 | 210 x 297 mm, A5 | 148 x 210 mm, 910-300-600 | 103 x 199 mm und 100x70mm | 100 x 70 mm.
Excel Sammelimport (Web-Oberfläche)
Für Nutzer ohne API: Auf der Seite „Sendung erstellen“ gibt es „Batch Import (Excel)“. Daten in Excel pflegen und die Datei direkt hochladen. Das System liest das erste Arbeitsblatt und übernimmt die Sendungen in den Warenkorb, damit sie gesammelt bezahlt und gedruckt werden können.