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: POST /api/v1/shipments Authentification: 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	—	Oui	Nombre total de colis (1–99)
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
customerReferenceNumber2	String	0–35	Non	Référence client 2
customerReferenceNumber3	String	0–35	Non	Référence client 3
customerReferenceNumber4	String	0–35	Non	Référence client 4
shipmentNote	String	0–255	Non	Note sur l'expédition
parcelShopId	String	—	Conditionnel	Requis pour les services de livraison en point relais
clientSoftware	String	—	Non	Nom de l'application cliente
clientVersion	String	—	Non	Version de l'application cliente

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
name2	String	0–35	Non	Ligne de nom supplémentaire
contact	String	0–35	Non	Personne de contact
countryCode	String	2	Oui	ISO 3166-1 alpha-2
stateCode	String	2	Conditionnel	Requis pour US/CA
zipCode	String	1–9	Oui	Code postal
city	String	1–35	Oui	Ville
street	String	1–35	Oui	Nom et numéro de rue
street2	String	0–35	Non	Ligne d'adresse supplémentaire
houseNumber	String	0–8	Conditionnel	Requis pour NL
phone	String	0–30	Conditionnel	Requis pour GB — format international +CCNNNNNN
email	String	0–50	Conditionnel	Requis pour les pays non-CH/LI (sauf GB)
eori	String	0–22	Conditionnel	Requis pour GB/NO à l'international
vat	String	0–20	Conditionnel	Requis pour GB/NO à l'international (non-CH)
language	String	2	Non	ISO 639-1 (DE, EN, FR, IT)
reference	String	0–35	Non	Référence d'adresse
note	String	0–70	Non	Instructions de livraison
gln	String	0–13	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
optionCodes	Array<String>	—	Non	Codes d'options de service supplémentaires
content	String	—	Non	Description du contenu du colis (PCONTENT)
weight	Integer	—	Non	Poids du colis en grammes
reference1	String	0–35	Non	Référence colis 1
reference2	String	0–35	Non	Référence colis 2
reference3	String	—	Non	Référence colis 3
reference4	String	—	Non	Référence colis 4
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)

Champs higherInsurance :

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

Champs limitedQuantities :

Champ	Type	Longueur	Obligatoire	Description
unNumber	String	—	Non	Numéro ONU de marchandises dangereuses
code	String	—	Non	Code de substance
packagingGroup	String	—	Non	Groupe d'emballage
klass	String	—	Non	Classe de marchandises dangereuses
subWeight	Integer	—	Non	Poids de la substance

Données douanières (customsData)

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

Champ	Type	Longueur	Obligatoire	Description
shipmentType	String	1	Oui	Type de colis (PARCELTYPE)
value	Number	—	Oui	Valeur en douane des marchandises (CAMOUNT)
currency	String	3	Non	Devise ISO 4217 pour value
valueEx	Number	—	Non	Valeur en douane supplémentaire (CAMOUNTEX)
currencyEx	String	3	Non	Devise ISO 4217 pour valueEx
reasonForExport	String	2	Oui	Code de motif d'exportation
termsOfDelivery	String	2	Oui	Incoterms / conditions de livraison (CTERMS)
clearanceCleared	String	1	Oui	Indicateur de dédouanement
opCode	String	3	Non	Code d'opération
preAlertStatus	String	3	Non	Statut de pré-alerte
content	String	0–35	Non	Description du contenu douanier (CCONTENT)
paper	String	1	Non	Indicateur de document (CPAPER)
highLowValue	String	1	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>	≤20 entrées	Non	Types de documents douaniers
comment	String	0–70	Non	Commentaire douanier (CCOMMENT)
comment2	String	0–70	Non	Enregistrement dans le pays de destination (DESTCOUNTRYREG)
senderHMRC	String	0–15	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

Champs invoiceLines[] :

Champ	Type	Longueur	Obligatoire	Description
natureOfGoods	String	0–200	Non	Nature des marchandises (CCONTENT)
hsCode	String	0–11	Non	Code tarifaire SH
productCode	String	0–255	Non	Code produit (CPRODCODE)
amount	Number	—	Non	Montant de la ligne (CAMOUNTLINE)
grossWeight	Integer	—	Non	Poids brut (CGROSSWEIGHT)
qItems	Integer	—	Oui	Quantité d'articles
countryOfOrigin	String	3	Non	Pays d'origine ISO (CORIGIN)

Options d'impression

Champ	Type	Obligatoire	Description
paperSize	String	Non	A4 ou A6 (défaut : A4)
startPosition	String	Non	Position de l'étiquette sur la feuille A4 : UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT

---

Réponse

201 Created — toutes les expéditions créées :

{
  "tracingId": "TRACE-123",
  "success": [
    {
      "id": 1,
      "parcelNumber": "05305000123456",
      "label": "base64-encoded-PDF..."
    }
  ],
  "failed": []
}

207 Multi-Status — succès partiel :

{
  "tracingId": "TRACE-456",
  "success": [ { "id": 1, "parcelNumber": "05305000123456", "label": "..." } ],
  "failed": [
    {
      "id": 2,
      "fieldErrors": {
        "receiver.countryCode": ["NOT_SUPPORTED"],
        "receiver.email": ["REQUIRED_FOR_INTERNATIONAL"]
      }
    }
  ]
}

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
401 Unauthorized	Jeton manquant ou invalide

---

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

---

Imprimer le manifeste

Génère un PDF de manifeste listant les expéditions remises à DPD pour un numéro de facturation donné. Assure la traçabilité de l'enlèvement du jour — le fichier est retourné sous forme de pièce jointe PDF et est destiné à être imprimé et joint aux colis.

Point de terminaison: POST /api/v1/shipments/print-manifest Produit: application/pdf Authentification: Jeton JWT Bearer requis

Le point de terminaison renvoie uniquement les expéditions appartenant à l'utilisateur authentifié. Filtrez le résultat avec une plage de dates (fromDate/toDate, appliquée à importedAt) et/ou une liste explicite de parcelNumbers — au moins l'un des deux filtres est requis.

Requête

Content-Type: application/json

{
  "invoicingNumber": "12345678",
  "fromDate": "2026-03-25",
  "toDate": "2026-04-29",
  "parcelNumbers": ["05305000123456", "05305000123457"],
  "address": {
    "reference": "PICKUP-001"
  },
  "printSettings": {
    "printRecipientReference": true,
    "printParcelReference1": true,
    "printParcelReference2": true,
    "printUserName": true,
    "printWeight": true,
    "sortOrderForManifest": "CONSIGNEE_ZIP"
  }
}

Champ	Type	Obligatoire	Description
invoicingNumber	String	Oui	Numéro de facturation délimitant le manifeste
fromDate	Date (yyyy-MM-dd)	Conditionnel	Borne inférieure inclusive de importedAt. Requis si parcelNumbers n'est pas fourni. Doit être fourni avec toDate
toDate	Date (yyyy-MM-dd)	Conditionnel	Borne supérieure inclusive de importedAt. Requis si parcelNumbers n'est pas fourni. Doit être fourni avec fromDate
parcelNumbers	Array<String>	Conditionnel	Restreint le manifeste à des numéros de colis spécifiques. Requis si aucune plage de dates n'est fournie
address	Objet	Non	Adresse d'enlèvement délimitant le manifeste. Seul reference est lu ; tous les autres champs d'adresse sont ignorés. La référence est résolue via la configuration client. Si omise et que le résultat couvre plusieurs enlèvements, le premier enlèvement rencontré est utilisé et les autres expéditions sont silencieusement écartées
printSettings	Objet	Oui	Paramètres d'impression appliqués au manifeste généré

Champs printSettings

Champ	Type	Obligatoire	Description
printRecipientReference	Boolean	Non	Imprimer la colonne référence du destinataire
printParcelReference1	Boolean	Non	Imprimer la référence colis 1
printParcelReference2	Boolean	Non	Imprimer la référence colis 2
printUserName	Boolean	Non	Imprimer le nom de l'utilisateur sur le manifeste
printWeight	Boolean	Non	Imprimer la colonne poids du colis
sortOrderForManifest	Enum	Oui	Ordre de tri des expéditions sur le manifeste

Valeurs de sortOrderForManifest :

Valeur	Description
CONSIGNEE_ZIP	Tri par code postal du destinataire
CONSIGNEE_COUNTRY	Tri par pays du destinataire
CONSIGNEE_NAME	Tri par nom du destinataire
REFERENCE_1	Tri par référence colis 1
PARCEL_NUMBER	Tri par numéro de colis

Cas d'usage courant — manifeste du jour

Le cas d'intégration le plus fréquent est la génération du manifeste pour les expéditions importées aujourd'hui, juste avant l'enlèvement par le chauffeur. Définissez fromDate et toDate sur la date du jour (jours UTC) et omettez parcelNumbers pour inclure toutes les expéditions de ce numéro de facturation pour ce jour :

{
  "invoicingNumber": "12345678",
  "fromDate": "2026-05-26",
  "toDate": "2026-05-26",
  "printSettings": {
    "printRecipientReference": true,
    "printParcelReference1": true,
    "printUserName": true,
    "printWeight": true,
    "sortOrderForManifest": "CONSIGNEE_ZIP"
  }
}

TODAY=$(date -u +%F)
curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments/print-manifest" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -o manifest.pdf \
  -d "{
    \"invoicingNumber\": \"12345678\",
    \"fromDate\": \"$TODAY\",
    \"toDate\": \"$TODAY\",
    \"printSettings\": {
      \"printRecipientReference\": true,
      \"printParcelReference1\": true,
      \"printUserName\": true,
      \"printWeight\": true,
      \"sortOrderForManifest\": \"CONSIGNEE_ZIP\"
    }
  }"

Remarques :

• fromDate/toDate sont comparés à importedAt en UTC (du début à la fin de la journée). Les expéditions importées après minuit UTC du jour calendaire suivant dans votre fuseau local n'apparaîtront pas.
• Fournissez address: {"reference": "PICKUP-001"} pour cibler un enlèvement spécifique lorsque l'utilisateur en a plusieurs.

Réponse

200 OK — manifeste généré ; le corps de la réponse est le flux PDF.

En-tête	Valeur
Content-Type	application/pdf
Content-Disposition	attachment; filename="manifest.pdf"
Content-Length	Taille du PDF en octets

Codes de statut

Code	Description
200 OK	Manifeste généré
400 Bad Request	Filtre manquant ou invalide (p. ex. seul fromDate ou toDate défini, fromDate après toDate, ni plage de dates ni parcelNumbers fourni, printSettings manquant, address.reference non résoluble)
401 Unauthorized	Jeton manquant ou invalide
404 Not Found	Aucune expédition ne correspond au filtre ou à l'enlèvement demandé

Exemple

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments/print-manifest" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -o manifest.pdf \
  -d '{
    "invoicingNumber": "12345678",
    "fromDate": "2026-03-25",
    "toDate": "2026-04-29",
    "parcelNumbers": ["05305000123456", "05305000123457"],
    "address": {
      "reference": "PICKUP-001"
    },
    "printSettings": {
      "printRecipientReference": true,
      "printParcelReference1": true,
      "printParcelReference2": true,
      "printUserName": true,
      "printWeight": true,
      "sortOrderForManifest": "CONSIGNEE_ZIP"
    }
  }'