Expéditions

Créez une ou plusieurs expéditions en une seule requête. L'API valide tous les champs, génère les numéros de colis, enrichit les données de routage et retourne des étiquettes PDF.

Point de terminaison	Authentification
POST /api/v1/shipments	Jeton JWT Bearer requis

---

Créer une expédition

Requête

Content-Type: application/json Corps: tableau d'objets expédition

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

Champs principaux de l'expédition

Champ	Type	Longueur	Obligatoire	Description
invoicingNumber	String	1–20	Oui	Numéro de facturation client
numberOfParcels	Integer	1–2 chiffres	Oui	Nombre total de colis
serviceCode	String	—	Oui	Code service DPD (PSD, PSI, PL, PBOX, RET)
mpsId	String	—	Non	Identifiant Master Parcel Shipment pour regroupement
customerReferenceNumber1	String	0–35	Non	Référence client 1. Tronqué, non rejeté
customerReferenceNumber2	String	0–35	Non	Référence client 2. Tronqué, non rejeté
customerReferenceNumber3	String	0–35	Non	Référence client 3. Tronqué, non rejeté
customerReferenceNumber4	String	0–35	Non	Référence client 4. Tronqué, non rejeté
shipmentNote	String	—	Non	Note sur l'expédition
parcelShopId	String	—	Conditionnel	Requis pour les services de livraison en point relais
clientSoftware	String	1–30	Oui	Nom de l'application cliente
clientVersion	String	1–10	Oui	Version de l'application cliente
identificationNumber	String	0–100	Non	Votre propre identifiant pour cet envoi, renvoyé dans failed[]

Certaines limites ne sont pas appliquées

Les noms d'adresse, les lignes de rue, le numéro de rue ainsi que les références de colis et de client ne sont pas rejetés lorsqu'ils sont trop longs. La valeur est coupée silencieusement à la limite et aucune erreur n'est signalée. Si la requête présente d'autres problèmes, vous obtenez ces erreurs à la place, qui peuvent sembler sans rapport avec le champ trop long. Appliquez ces longueurs dans votre propre code.

Comment les longueurs de champs sont vérifiées

La colonne Longueur indique la limite appliquée par l'API. Un tiret signifie que la longueur n'est pas vérifiée.

• invoicingNumber, clientSoftware, clientVersion et identificationNumber sont vérifiés avant le traitement du lot. Une valeur trop longue rejette toute la requête avec 400.
• Toutes les autres limites sont vérifiées par envoi. Une valeur trop longue fait échouer cet envoi avec une entrée dans fieldErrors[], et la requête renvoie 207 (ou 400 si tous les envois ont échoué).
• Les champs marqués tronqué dans les tableaux sont l'exception : ils sont raccourcis, pas rejetés.
• Le poids du colis weight est vérifié par rapport à un maximum propre au produit, voir le tableau des poids ci-dessous.

Champs d'adresse (expéditeur / destinataire / retour)

Champ	Type	Longueur	Obligatoire	Remarques
name	String	1–35	Oui	Nom de la société ou de la personne. Tronqué, non rejeté
name2	String	0–35	Non	Ligne de nom supplémentaire. Tronqué, non rejeté
contact	String	0–35	Non	Personne de contact. Tronqué, non rejeté
countryCode	String	2	Oui	ISO 3166-1 alpha-2
stateCode	String	—	Conditionnel	Requis pour US/CA
zipCode	String	1–9	Oui	Code postal
city	String	1–35	Oui	Ville. Tronqué, non rejeté
street	String	1–35	Oui	Nom et numéro de rue. Tronqué, non rejeté
street2	String	0–35	Non	Ligne d'adresse supplémentaire. Tronqué, non rejeté
houseNumber	String	0–8	Conditionnel	Requis pour NL. Tronqué, non rejeté
phone	String	0–35	Conditionnel	Requis pour GB — format international
email	String	0–100	Conditionnel	Requis pour les pays non-CH/LI (sauf GB)
eori	String	—	Conditionnel	Requis pour GB/NO à l'international
vat	String	—	Conditionnel	Requis pour GB/NO à l'international (non-CH)
language	String	—	Non	ISO 639-1 (DE, EN, FR, IT)
reference	String	—	Non	Référence d'adresse
note	String	0–70	Non	Instructions de livraison
gln	String	—	Non	Global Location Number

Informations sur les colis (parcelInfo[])

Tableau d'objets colis — une entrée par colis physique. Le nombre d'entrées doit correspondre à numberOfParcels.

Champ	Type	Longueur	Obligatoire	Description
serviceCode	String	—	Oui	Code de service au niveau du colis — voir Services et options
optionCodes	Array<String>	—	Non	Codes d'options de service supplémentaires — voir Services et options
content	String	—	Non	Description du contenu du colis (PCONTENT)
weight	Integer	—	Oui	Poids du colis en grammes — le maximum dépend du produit, voir ci-dessous
reference1	String	0–35	Non	Référence colis 1. Tronqué, non rejeté
reference2	String	0–35	Non	Référence colis 2. Tronqué, non rejeté
reference3	String	0–35	Non	Référence colis 3. Tronqué, non rejeté
reference4	String	0–35	Non	Référence colis 4. Tronqué, non rejeté
higherInsurance	Object	—	Non	Service supplémentaire d'assurance complémentaire (voir ci-dessous)
limitedQuantities	Object	—	Non	Données de quantités limitées (marchandises dangereuses) (voir ci-dessous)

Poids maximal du colis — weight est envoyé en grammes, et un colis au-delà de ces limites est rejeté avec une erreur sur le champ weight :

Produit	National	International
PSD	35 kg	20 kg
PL	2 kg	2 kg
PBOX	5 kg	5 kg
Tous les autres produits	35 kg	31,5 kg

Champs higherInsurance :

Champ	Type	Longueur	Obligatoire	Description
amount	Number	—	Oui	Montant assuré
currency	String	—	Oui	Code devise ISO 4217

Champs limitedQuantities :

Champ	Type	Longueur	Obligatoire	Description
unNumber	String	0–4	Conditionnel	Numéro ONU de marchandises dangereuses (p. ex. 1234). Obligatoire pour les envois internationaux avec l'option LQ
code	String	0–5	Non	Code d'emballage (p. ex. C1)
packagingGroup	String	—	Conditionnel	Groupe d'emballage (p. ex. I, II, III). Obligatoire pour les envois internationaux avec l'option LQ
klass	String	0–6	Non	Classe de marchandises dangereuses (p. ex. 8)
subWeight	Integer	0–6	Non	Poids de la substance

Remarques :

• Aucun champ n'a de valeur par défaut — les champs omis restent vides.
• Pour les envois internationaux (non nationaux) avec l'option de service LQ, unNumber et packagingGroup sont obligatoires ; sinon tous les champs sont facultatifs.
• Caractères autorisés pour unNumber, code, klass, subWeight : lettres, chiffres, espace et . ( ) / _ | -. packagingGroup n'a aucune restriction de longueur ou de caractères.
• Conseil d'intégration (correspondance de champs, non validée par cette API) : lors de la migration depuis le bloc Shivah WS <hazardous>, les champs correspondent comme suit — identificationUnNo → unNumber, identificationClass → klass, packingGroup → packagingGroup, packingCode → code, hazardousWeight → subWeight.

Données douanières (customsData)

Requis pour les envois internationaux (dédouanement non national).

Champ	Type	Longueur	Obligatoire	Description
shipmentType	String	1–2	Oui	Type de colis (PARCELTYPE) — voir valeurs ci-dessous
value	Number	—	Oui	Valeur en douane des marchandises (CAMOUNT)
currency	String	—	Non	Devise ISO 4217 pour value
valueEx	Number	—	Non	Valeur en douane supplémentaire (CAMOUNTEX)
currencyEx	String	—	Non	Devise ISO 4217 pour valueEx
reasonForExport	String	1–35	Oui	Code de motif d'exportation — voir valeurs ci-dessous
termsOfDelivery	String	1–35	Oui	Incoterms / conditions de livraison (CTERMS) — voir valeurs ci-dessous
clearanceCleared	String	1–35	Oui	Indicateur de dédouanement — voir valeurs ci-dessous
opCode	String	—	Non	Code d'opération
preAlertStatus	String	—	Non	Statut de pré-alerte
content	String	—	Non	Description du contenu douanier (CCONTENT)
paper	String	—	Non	Indicateur de document (CPAPER)
highLowValue	String	—	Non	Indicateur de valeur haute/basse
invoiceNumber	String	0–35	Non	Numéro de facture commerciale (CINVOICE)
date	Date (yyyy-MM-dd)	—	Oui	Date de facture (CINVOICEDATE)
exportMRN	String	0–209	Non	Export Movement Reference Number (SHIPMRN)
documentTypes	Array<String>	—	Non	Types de documents douaniers
comment	String	—	Non	Commentaire douanier (CCOMMENT)
comment2	String	—	Non	Enregistrement dans le pays de destination (DESTCOUNTRYREG)
senderHMRC	String	0–209	Non	Enregistrement HMRC de l'expéditeur
senderInvoicingAddress	Object	—	Non	Adresse de facturation de l'expéditeur (objet adresse)
receiverInvoicingAddress	Object	—	Non	Adresse de facturation du destinataire (objet adresse)
numberOfInvoiceLines	Integer	—	Non	Nombre de lignes de facture (NUMBEROFARTICLE)
invoiceLines	Array<Object>	—	Conditionnel	Lignes de facture (voir ci-dessous). Nombre compris entre le nombre de colis et le nombre de colis + 20

Valeurs de shipmentType :

Valeur	Description
D	Document
P	Marchandise (non-document)

Valeurs de reasonForExport :

Valeur	Description
01	Vente (par défaut)
02	Retour / remplacement
03	Cadeau

Valeurs de termsOfDelivery :

Valeur	Description
01	DAP, non dédouané
02	DDP, rendu droits acquittés (droits inclus, taxes exclues)
03	DDP, rendu droits acquittés (droits et taxes inclus)
05	Départ usine (EXW)
06	DAP
07	DAP amélioré — droits et taxes prépayés par le destinataire

Valeurs de clearanceCleared :

Valeur	Description
N	Non
F	Franco
E	Dédouané à l'exportation
T	Dédouané en transit
I	Dédouané à l'importation
H	Hybride

Champs invoiceLines[] :

Champ	Type	Longueur	Obligatoire	Description
natureOfGoods	String	0–200	Non	Nature des marchandises (CCONTENT)
hsCode	String	6 ou 8 chiffres	Non	Code tarifaire SH
productCode	String	—	Non	Code produit (CPRODCODE)
amount	Number	13 chiffres + 2 décimales	Non	Montant de la ligne (CAMOUNTLINE)
grossWeight	Integer	jusqu'à 5 chiffres	Non	Poids brut (CGROSSWEIGHT)
qItems	Integer	jusqu'à 5 chiffres	Oui	Quantité d'articles
countryOfOrigin	String	0–3	Non	Pays d'origine ISO (CORIGIN)

Options d'impression

Champ	Type	Obligatoire	Description
paperSize	String	Non	Taille de l'étiquette : A4 ou A6 (défaut : A6)
printerLanguage	String	Non	Format de sortie : PDF, ZPL ou EPL (défaut : PDF)
printerResolution	Integer	Non	Résolution d'impression en dpi pour la sortie ZPL/EPL — 150, 200/203, 300 ou 600 (défaut 200 ; les autres valeurs de 72–600 sont acceptées mais retombent à 200 dpi ; ignoré pour PDF)
startPosition	String	Non	Position de l'étiquette sur la feuille A4 : UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT
dropOffType	String	Non	Contenu de l'étiquette : FULL_LABEL (défaut, étiquette d'expédition complète), QR_CODE (étiquette QR PNG numérique) ou BOTH
splitLabels	Boolean	Non	Si true, la réponse contient une étiquette par entrée de parcelNumbers[] au lieu d'un seul champ label fusionné (défaut : false, voir Étiquettes par numéro de colis)
includeBarcode	Boolean	Non	Si true, chaque entrée de parcelNumbers[] contient aussi le barcode imprimé sur l'étiquette de ce colis (défaut : false, voir Code-barres de routage dans la réponse)

Remarque : les options d'impression s'appliquent à toute la requête — le premier printOptions renseigné dans la liste des expéditions est utilisé.

Format et taille d'étiquette : les termes labelFormat/labelSize correspondent à printerLanguage (format) et paperSize (taille). Les formats pris en charge sont PDF (défaut), ZPL et EPL ; les tailles prises en charge sont A4 et A6. Un dropOffType QR_CODE/BOTH renvoie une étiquette QR PNG numérique. Les champs Shivah WS équivalents sont printerLanguage (PDF/ZPL) et paperFormat — voir ShipmentService.

---

Réponse

201 Created — toutes les expéditions créées. Par défaut, toutes les étiquettes sont fusionnées dans le champ label de premier niveau (base64) :

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

207 Multi-Status — succès partiel. Chaque entrée de failed[] porte une identificationNumber (reprend la valeur fournie par le client, lorsque l'élément d'entrée en avait une) et un errorCode ; les violations de champ apparaissent comme un tableau fieldErrors[] plat, chaque entrée portant son propre path — le même code peut apparaître à plusieurs path (p. ex. à la fois sender.email et 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."
        }
      ]
    }
  ]
}

Un échec transitoire (sans fieldErrors — une panne n'est pas un problème de champ) se présente ainsi :

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

Codes de statut :

Code	Description
201 Created	Toutes les expéditions créées avec succès
207 Multi-Status	Certaines ont réussi, d'autres ont échoué
400 Bad Request	Charge utile de requête invalide, ou tous les éléments du lot ont échoué — quelle que soit la cause, y compris une panne du moteur de routage
401 Unauthorized	Jeton manquant ou invalide

Étiquettes par numéro de colis

Avec "printOptions": { "splitLabels": true }, le champ label de premier niveau est omis et chaque entrée de parcelNumbers[] contient sa propre label base64 avec uniquement les étiquettes générées pour ce numéro de colis :

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

• Fonctionne avec tous les formats d'étiquette et tailles de papier. En sortie PDF avec paperSize: A4, chaque numéro de colis reçoit son propre document A4 au lieu de plusieurs étiquettes sur une même feuille.
• Les numéros de colis de retour et de swap apparaissent comme des entrées distinctes dans parcelNumbers[] avec leurs propres étiquettes.
• Sans le flag (ou avec splitLabels: false), la réponse reste inchangée : une seule label fusionnée de premier niveau, aucun champ label dans parcelNumbers[].

Code-barres de routage dans la réponse

Avec "printOptions": { "includeBarcode": true }, chaque entrée de parcelNumbers[] contient aussi le champ barcode — le contenu Code128 exact du code-barres de routage imprimé sur l'étiquette de ce colis, c'est-à-dire ce qu'un scanner lit sur l'étiquette :

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

La valeur est l'indicatif % suivi de 27 caractères :

Partie	Longueur	Contenu
Indicatif	1	Toujours %
Code postal	7	Code postal du destinataire, en majuscules et complété à gauche par des 0
Numéro de colis	14	Le numéro de colis de cette entrée
Code SO	3	Code de service de routage de ce colis
Pays	3	Code numérique ISO 3166 du pays de livraison

• La ligne lisible sous le code-barres sur l'étiquette ajoute une clé de contrôle (IEC 7064 mod 37,36) et des groupes de quatre ; le champ barcode ne contient ni l'une ni l'autre.
• Les numéros de colis de retour et de swap portent le code-barres de leur propre étiquette, qui route sur un autre code SO et sur le code postal du destinataire du retour, et non sur les valeurs du colis aller.
• Indépendant de printerLanguage, paperSize, splitLabels et dropOffType.
• Sans le flag (ou avec includeBarcode: false), le champ barcode est entièrement omis.
• Le code-barres nécessite une expédition routée. Si les données de routage d'un colis sont incomplètes, l'entrée est renvoyée sans barcode au lieu de faire échouer la requête.

---

Exemple

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"
      }
    }
  ]'