Sendungen

Erstellen Sie eine oder mehrere Sendungen in einer einzigen Anfrage. Die API validiert alle Felder, generiert Paketnummern, reichert Routing-Daten an und gibt PDF-Etiketten zurück.

Endpunkt	Authentifizierung
POST /api/v1/shipments	Bearer JWT-Token erforderlich

---

Sendung erstellen

Anfrage

Content-Type: application/json Body: Array von Sendungsobjekten

[
  {
    "invoicingNumber": "12345678",
    "serviceCode": "PSD",
    "sender": { },
    "receiver": { },
    "parcelInfo": [ ],
    "customsData": { },
    "printOptions": { }
  }
]

Sendungs-Hauptfelder

Feld	Typ	Länge	Pflichtfeld	Beschreibung
invoicingNumber	String	1–20	Ja	Kundenrechnungsnummer
numberOfParcels	Integer	1–2 Stellen	Ja	Gesamtpakete
serviceCode	String	—	Ja	DPD-Servicecode (PSD, PSI, PL, PBOX, RET)
mpsId	String	—	Nein	Master-Sendungs-ID zur Gruppierung
customerReferenceNumber1	String	0–35	Nein	Kundenreferenz 1. Gekürzt, nicht abgewiesen
customerReferenceNumber2	String	0–35	Nein	Kundenreferenz 2. Gekürzt, nicht abgewiesen
customerReferenceNumber3	String	0–35	Nein	Kundenreferenz 3. Gekürzt, nicht abgewiesen
customerReferenceNumber4	String	0–35	Nein	Kundenreferenz 4. Gekürzt, nicht abgewiesen
shipmentNote	String	—	Nein	Sendungsnotiz
parcelShopId	String	—	Bedingt	Erforderlich für Paketshop-Lieferdienste
clientSoftware	String	1–30	Ja	Name der Client-Anwendung
clientVersion	String	1–10	Ja	Version der Client-Anwendung
identificationNumber	String	0–100	Nein	Ihre eigene Kennung für diese Sendung, wird in failed[] zurückgegeben

Einige Grenzen werden nicht durchgesetzt

Adressnamen, Strassenzeilen, Hausnummer sowie die Paket- und Kundenreferenzen werden nicht abgewiesen, wenn sie zu lang sind. Der Wert wird stillschweigend auf die Grenze gekürzt, und es wird kein Fehler gemeldet. Hat die Anfrage andere Probleme, erhalten Sie stattdessen diese Fehler, die mit dem zu langen Feld nichts zu tun zu haben scheinen. Erzwingen Sie diese Längen in Ihrem eigenen Code.

So werden Feldlängen geprüft

Die Spalte Länge zeigt die Grenze, die die API anwendet. Ein Gedankenstrich bedeutet, dass die Länge nicht geprüft wird.

• invoicingNumber, clientSoftware, clientVersion und identificationNumber werden geprüft, bevor der Batch verarbeitet wird. Ein zu langer Wert weist die gesamte Anfrage mit 400 ab.
• Alle anderen Grenzen werden pro Sendung geprüft. Ein zu langer Wert lässt diese Sendung mit einem Eintrag in fieldErrors[] fehlschlagen, und die Anfrage liefert 207 (oder 400, wenn jede Sendung fehlgeschlagen ist).
• Felder, die in den Tabellen als gekürzt markiert sind, sind die Ausnahme: sie werden gekürzt, nicht abgewiesen.
• Das Paketgewicht weight wird gegen ein produktabhängiges Maximum geprüft, siehe die Gewichtstabelle unten.

Adressfelder (Absender / Empfänger / Rücksendung)

Feld	Typ	Länge	Pflichtfeld	Hinweise
name	String	1–35	Ja	Firmen- oder Personenname. Gekürzt, nicht abgewiesen
name2	String	0–35	Nein	Zusätzliche Namenszeile. Gekürzt, nicht abgewiesen
contact	String	0–35	Nein	Kontaktperson. Gekürzt, nicht abgewiesen
countryCode	String	2	Ja	ISO 3166-1 Alpha-2
stateCode	String	—	Bedingt	Pflichtfeld für US/CA
zipCode	String	1–9	Ja	Postleitzahl
city	String	1–35	Ja	Stadt. Gekürzt, nicht abgewiesen
street	String	1–35	Ja	Strassenname und Hausnummer. Gekürzt, nicht abgewiesen
street2	String	0–35	Nein	Zusätzliche Adresszeile. Gekürzt, nicht abgewiesen
houseNumber	String	0–8	Bedingt	Pflichtfeld für NL. Gekürzt, nicht abgewiesen
phone	String	0–35	Bedingt	Pflichtfeld für GB — internationales Format
email	String	0–100	Bedingt	Pflichtfeld für Nicht-CH/LI-Länder (ausser GB)
eori	String	—	Bedingt	Pflichtfeld für GB/NO international
vat	String	—	Bedingt	Pflichtfeld für GB/NO international (Nicht-CH)
language	String	—	Nein	ISO 639-1 (DE, EN, FR, IT)
reference	String	—	Nein	Adressreferenz
note	String	0–70	Nein	Zustellanweisungen
gln	String	—	Nein	Global Location Number

Paketinformationen (parcelInfo[])

Array von Paketobjekten — ein Eintrag pro physischem Paket. Die Anzahl der Einträge sollte numberOfParcels entsprechen.

Feld	Typ	Länge	Pflichtfeld	Beschreibung
serviceCode	String	—	Ja	Service-Code auf Paketebene — siehe Services und Optionen
optionCodes	Array<String>	—	Nein	Zusätzliche Service-Optionscodes — siehe Services und Optionen
content	String	—	Nein	Paketinhaltsbeschreibung (PCONTENT)
weight	Integer	—	Ja	Paketgewicht in Gramm — das Maximum hängt vom Produkt ab, siehe unten
reference1	String	0–35	Nein	Paketreferenz 1. Gekürzt, nicht abgewiesen
reference2	String	0–35	Nein	Paketreferenz 2. Gekürzt, nicht abgewiesen
reference3	String	0–35	Nein	Paketreferenz 3. Gekürzt, nicht abgewiesen
reference4	String	0–35	Nein	Paketreferenz 4. Gekürzt, nicht abgewiesen
higherInsurance	Object	—	Nein	Zusatzleistung Höherversicherung (siehe unten)
limitedQuantities	Object	—	Nein	Daten zu begrenzten Mengen (Gefahrgut) (siehe unten)

Maximales Paketgewicht — weight wird in Gramm gesendet, und ein Paket über diesen Grenzen wird mit einem Feldfehler auf weight abgewiesen:

Produkt	Inland	International
PSD	35 kg	20 kg
PL	2 kg	2 kg
PBOX	5 kg	5 kg
Alle anderen Produkte	35 kg	31,5 kg

higherInsurance-Felder:

Feld	Typ	Länge	Pflichtfeld	Beschreibung
amount	Number	—	Ja	Versicherter Betrag
currency	String	—	Ja	ISO-4217-Währungscode

limitedQuantities-Felder:

Feld	Typ	Länge	Pflichtfeld	Beschreibung
unNumber	String	0–4	Bedingt	UN-Gefahrgutnummer (z. B. 1234). Pflichtfeld für internationale Sendungen mit der Option LQ
code	String	0–5	Nein	Verpackungscode (z. B. C1)
packagingGroup	String	—	Bedingt	Verpackungsgruppe (z. B. I, II, III). Pflichtfeld für internationale Sendungen mit der Option LQ
klass	String	0–6	Nein	Gefahrgutklasse (z. B. 8)
subWeight	Integer	0–6	Nein	Substanzgewicht

Hinweise:

• Kein Feld hat einen Standardwert — weggelassene Felder bleiben leer.
• Für internationale (nicht-inländische) Sendungen mit der Serviceoption LQ sind unNumber und packagingGroup Pflichtfelder; andernfalls sind alle Felder optional.
• Erlaubte Zeichen für unNumber, code, klass, subWeight: Buchstaben, Ziffern, Leerzeichen sowie . ( ) / _ | -. packagingGroup hat keine Längen- oder Zeichenbeschränkung.
• Integrationshinweis (Feldzuordnung, von dieser API nicht validiert): Bei der Migration vom Shivah-WS-Block <hazardous> entsprechen sich die Felder wie folgt — identificationUnNo → unNumber, identificationClass → klass, packingGroup → packagingGroup, packingCode → code, hazardousWeight → subWeight.

Zolldaten (customsData)

Erforderlich für internationale Sendungen (nicht-inländische Verzollung).

Feld	Typ	Länge	Pflichtfeld	Beschreibung
shipmentType	String	1–2	Ja	Pakettyp (PARCELTYPE) — siehe Werte unten
value	Number	—	Ja	Zollwert der Waren (CAMOUNT)
currency	String	—	Nein	ISO-4217-Währung für value
valueEx	Number	—	Nein	Zusätzlicher Zollwert (CAMOUNTEX)
currencyEx	String	—	Nein	ISO-4217-Währung für valueEx
reasonForExport	String	1–35	Ja	Ausfuhrgrund-Code — siehe Werte unten
termsOfDelivery	String	1–35	Ja	Incoterms / Lieferbedingungen (CTERMS) — siehe Werte unten
clearanceCleared	String	1–35	Ja	Verzollungs-Flag — siehe Werte unten
opCode	String	—	Nein	Operationscode
preAlertStatus	String	—	Nein	Pre-Alert-Status
content	String	—	Nein	Zollinhaltsbeschreibung (CCONTENT)
paper	String	—	Nein	Dokumenten-Flag (CPAPER)
highLowValue	String	—	Nein	High/Low-Value-Indikator
invoiceNumber	String	0–35	Nein	Handelsrechnungsnummer (CINVOICE)
date	Date (yyyy-MM-dd)	—	Ja	Rechnungsdatum (CINVOICEDATE)
exportMRN	String	0–209	Nein	Export Movement Reference Number (SHIPMRN)
documentTypes	Array<String>	—	Nein	Zolldokumenttypen
comment	String	—	Nein	Zollkommentar (CCOMMENT)
comment2	String	—	Nein	Registrierung im Zielland (DESTCOUNTRYREG)
senderHMRC	String	0–209	Nein	HMRC-Registrierung des Absenders
senderInvoicingAddress	Object	—	Nein	Rechnungsadresse des Absenders (Adressobjekt)
receiverInvoicingAddress	Object	—	Nein	Rechnungsadresse des Empfängers (Adressobjekt)
numberOfInvoiceLines	Integer	—	Nein	Anzahl der Rechnungspositionen (NUMBEROFARTICLE)
invoiceLines	Array<Object>	—	Bedingt	Rechnungspositionen (siehe unten). Anzahl zwischen Paketanzahl und Paketanzahl + 20

shipmentType-Werte:

Wert	Beschreibung
D	Dokument
P	Nicht-Dokument

reasonForExport-Werte:

Wert	Beschreibung
01	Verkauf (Standard)
02	Rückgabe / Ersatz
03	Geschenk

termsOfDelivery-Werte:

Wert	Beschreibung
01	DAP, nicht verzollt
02	DDP, verzollt (inkl. Zölle, exkl. Steuern)
03	DDP, verzollt (inkl. Zölle und Steuern)
05	Ab Werk (EXW)
06	DAP
07	DAP erweitert — Zölle und Steuern vom Empfänger im Voraus bezahlt

clearanceCleared-Werte:

Wert	Beschreibung
N	Nein
F	Frei
E	Ausfuhrverzollt
T	Transitverzollt
I	Einfuhrverzollt
H	Hybrid

invoiceLines[]-Felder:

Feld	Typ	Länge	Pflichtfeld	Beschreibung
natureOfGoods	String	0–200	Nein	Art der Waren (CCONTENT)
hsCode	String	6 oder 8 Ziffern	Nein	HS-Zolltarifcode
productCode	String	—	Nein	Produktcode (CPRODCODE)
amount	Number	13 Stellen + 2 Dezimalstellen	Nein	Positionsbetrag (CAMOUNTLINE)
grossWeight	Integer	bis zu 5 Stellen	Nein	Bruttogewicht (CGROSSWEIGHT)
qItems	Integer	bis zu 5 Stellen	Ja	Artikelmenge
countryOfOrigin	String	0–3	Nein	ISO-Ursprungsland (CORIGIN)

Druckoptionen

Feld	Typ	Pflichtfeld	Beschreibung
paperSize	String	Nein	Etikettengrösse: A4 oder A6 (Standard: A6)
printerLanguage	String	Nein	Ausgabeformat: PDF, ZPL oder EPL (Standard: PDF)
printerResolution	Integer	Nein	Druckauflösung in dpi für ZPL/EPL-Ausgabe — 150, 200/203, 300 oder 600 (Standard 200; andere Werte in 72–600 werden akzeptiert, fallen aber auf 200 dpi zurück; bei PDF ignoriert)
startPosition	String	Nein	Etikettenposition auf A4-Blatt: UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT
dropOffType	String	Nein	Etiketteninhalt: FULL_LABEL (Standard, vollständiges Versandetikett), QR_CODE (digitales PNG-QR-Etikett) oder BOTH
splitLabels	Boolean	Nein	Wenn true, enthält jeder Eintrag in parcelNumbers[] ein eigenes label statt eines einzelnen zusammengeführten label (Standard: false, siehe Etiketten pro Paketnummer)
includeBarcode	Boolean	Nein	Wenn true, enthält jeder Eintrag in parcelNumbers[] zusätzlich den barcode, der auf dem Etikett dieses Pakets gedruckt wird (Standard: false, siehe Routing-Barcode in der Antwort)

Hinweis: Druckoptionen gelten für die gesamte Anfrage — verwendet wird das erste gesetzte printOptions in der Sendungsliste.

Etikettenformat & -grösse: Die Begriffe labelFormat/labelSize entsprechen printerLanguage (Format) und paperSize (Grösse). Unterstützte Formate sind PDF (Standard), ZPL und EPL; unterstützte Grössen sind A4 und A6. Ein dropOffType von QR_CODE/BOTH liefert ein digitales PNG-QR-Etikett. Die entsprechenden Shivah-WS-Felder sind printerLanguage (PDF/ZPL) und paperFormat — siehe ShipmentService.

---

Antwort

201 Created – alle Sendungen erfolgreich erstellt. Standardmäßig werden alle Etiketten in das übergeordnete Feld label (Base64) zusammengeführt:

{
  "tracingId": "TRACE-123",
  "label": "base64-encoded-labels...",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [
        { "serviceCode": "B2B", "number": "05305000123456" },
        { "serviceCode": "B2B", "number": "05305000123457" }
      ]
    }
  ],
  "failed": []
}

207 Multi-Status – Teilerfolg. Jeder Eintrag in failed[] enthält eine identificationNumber (spiegelt den vom Client übergebenen Wert, sofern der Eingabe-Eintrag einen hatte) und einen errorCode; Feldfehler erscheinen als flaches fieldErrors[]-Array, wobei jeder Eintrag seinen eigenen path trägt — derselbe code kann bei mehreren path-Werten auftreten (z. B. sowohl sender.email als auch receiver.email):

{
  "tracingId": "TRACE-456",
  "label": "base64-encoded-labels...",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [ { "serviceCode": "B2B", "number": "05305000123456" } ]
    }
  ],
  "failed": [
    {
      "identificationNumber": "client-supplied-id-9",
      "errorCode": "SYS-VALIDATION-FAILURE",
      "fieldErrors": [
        {
          "path": "receiver.countryCode",
          "code": "SHP-VAL-COUNTRYCODE-ALLOWED-CHARACTERS",
          "message": "Country code contains invalid characters."
        },
        {
          "path": "receiver.email",
          "code": "SHP-VAL-EMAIL-REQUIRED",
          "message": "Email address is required."
        }
      ]
    }
  ]
}

Ein vorübergehender Fehler (ohne fieldErrors – ein Ausfall ist kein Feldproblem) sieht dagegen so aus:

{
  "identificationNumber": "client-supplied-id-11",
  "errorCode": "SHP-ROUTING-ENGINE-UNAVAILABLE",
  "reason": "SHP-ROUTING-ENGINE-UNAVAILABLE: Routing engine is temporarily unavailable. Please try again."
}

Statuscodes:

Code	Beschreibung
201 Created	Alle Sendungen erfolgreich erstellt
207 Multi-Status	Teilerfolg
400 Bad Request	Ungültige Anfrage, oder alle Positionen der Sammelanfrage sind fehlgeschlagen — unabhängig von der Ursache, auch bei einem Ausfall der Routing-Engine
401 Unauthorized	Token fehlt oder ungültig

Etiketten pro Paketnummer

Mit "printOptions": { "splitLabels": true } entfällt das übergeordnete label, und jeder Eintrag in parcelNumbers[] enthält ein eigenes Base64-label mit ausschließlich den für diese Paketnummer erzeugten Etiketten:

{
  "tracingId": "TRACE-123",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [
        {
          "serviceCode": "B2B",
          "number": "05305000123456",
          "label": "base64-encoded-label..."
        },
        {
          "serviceCode": "B2B",
          "number": "05305000123457",
          "label": "base64-encoded-label..."
        }
      ]
    }
  ],
  "failed": []
}

• Funktioniert mit allen Etikettenformaten und Papiergrößen. Bei PDF-Ausgabe mit paperSize: A4 erhält jede Paketnummer ein eigenes A4-Dokument statt mehrerer Etiketten auf einem Blatt.
• Retouren- und Swap-Paketnummern erscheinen als eigene Einträge in parcelNumbers[] und enthalten ihre eigenen Etiketten.
• Ohne das Flag (oder mit splitLabels: false) bleibt die Antwort unverändert: ein zusammengeführtes übergeordnetes label, kein label-Feld innerhalb von parcelNumbers[].

Routing-Barcode in der Antwort

Mit "printOptions": { "includeBarcode": true } enthält jeder Eintrag in parcelNumbers[] zusätzlich das Feld barcode — den exakten Code128-Inhalt des Routing-Barcodes, der auf dem Etikett dieses Pakets gedruckt wird, also genau das, was ein Scanner vom Etikett liest:

{
  "tracingId": "TRACE-123",
  "label": "base64-encoded-labels...",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [
        {
          "serviceCode": "B2B",
          "number": "05305000123456",
          "barcode": "%000815305305000123456420756"
        }
      ]
    }
  ],
  "failed": []
}

Der Wert besteht aus dem Kennzeichen % gefolgt von 27 Zeichen:

Teil	Länge	Inhalt
Kennzeichen	1	Immer %
Postleitzahl	7	PLZ des Empfängers, in Großbuchstaben und links mit 0 aufgefüllt
Paketnummer	14	Die Paketnummer dieses Eintrags
SO-Code	3	Routing-Servicecode dieses Pakets
Land	3	ISO-3166-Nummerncode des Zustelllandes

• Die lesbare Zeile unter dem Barcode auf dem Etikett enthält zusätzlich eine Prüfziffer (IEC 7064 mod 37,36) und Vierergruppen; das Feld barcode enthält beides nicht.
• Retouren- und Swap-Paketnummern tragen den Barcode ihres eigenen Etiketts: dieses routet über einen anderen SO-Code und über die PLZ des Retourenempfängers, nicht über die Werte des Hinweg-Pakets.
• Unabhängig von printerLanguage, paperSize, splitLabels und dropOffType.
• Ohne das Flag (oder mit includeBarcode: false) entfällt das Feld barcode vollständig.
• Der Barcode setzt eine geroutete Sendung voraus. Sind die Routing-Daten eines Pakets unvollständig, wird der Eintrag ohne barcode zurückgegeben, statt die Anfrage abzubrechen.

---

Beispiel

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "invoicingNumber": "12345678",
      "serviceCode": "PSD",
      "numberOfParcels": 1,
      "sender": {
        "name": "Sender AG",
        "countryCode": "CH",
        "zipCode": "8000",
        "city": "Zürich",
        "street": "Industriestrasse 25"
      },
      "receiver": {
        "name": "Receiver GmbH",
        "countryCode": "DE",
        "zipCode": "10115",
        "city": "Berlin",
        "street": "Alexanderplatz 1",
        "email": "info@receiver.de"
      },
      "parcelInfo": [
        { "weight": 2500 }
      ],
      "printOptions": {
        "paperSize": "A6"
      }
    }
  ]'