API DPD Label Print Spedizioni

Il Webservice DPD Label Print (REST API) consente l'integrazione lato server dei servizi di spedizione DPD nella vostra piattaforma ERP, CRM o e-commerce — senza richiedere l'applicazione desktop. Generate etichette, tracciate i pacchi e pianificate i ritiri in modo programmatico.

L'API spedizioni consente di integrare i servizi di spedizione DPD nelle proprie applicazioni — inclusi creazione di spedizioni, tracciamento, ricerca punti di ritiro e pianificazione dei ritiri.

URL di base	Versione API	Autenticazione
https://label-print-shipments.dpd.ch	v1	Token JWT Bearer (vedere Autenticazione)

---

Riferimento API

API	Endpoint	Descrizione
Autenticazione	2	Accesso utente e generazione token JWT
Spedizioni	1	Creare spedizioni con generazione automatica etichette
Manifesti	1	Generare un PDF di manifesto per le spedizioni consegnate a DPD
Tracciamento	1	Dati di tracciamento dei pacchi in tempo reale
Punti di ritiro	3	Cercare e ottenere dettagli dei punti di ritiro
Richieste di ritiro	1	Pianificare ritiri di pacchi una tantum
Ordini di ritiro	1	Creare pianificazioni di ritiro ricorrenti

---

Avvio rapido

1. Ottenere un token di accesso

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "il_vostro_utente",
    "password": "la_vostra_password"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "..."
}

2. Chiamare un qualsiasi endpoint API

Includere il token in ogni richiesta:

curl -X GET "https://label-print-shipments.dpd.ch/api/v1/tracking/05305000123456" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

---

Concetti comuni

Validazione degli indirizzi

Tutti i campi dell'indirizzo seguono regole coerenti:

{
  "name": "Nome azienda",       // obbligatorio, max 35 caratteri
  "countryCode": "CH",          // obbligatorio, codice ISO a 2 lettere
  "zipCode": "8000",            // obbligatorio, max 9 caratteri
  "city": "Zürich",             // obbligatorio, max 35 caratteri
  "street": "Bahnhofstrasse 1", // obbligatorio, max 35 caratteri
  "phone": "+41441234567",      // obbligatorio per GB
  "email": "info@azienda.ch"    // obbligatorio per non-CH/LI
}

Requisiti specifici per paese:

• NL: houseNumber è obbligatorio
• GB: phone è obbligatorio (formato internazionale)
• US/CA: stateCode è obbligatorio
• Non-CH/LI: email è obbligatorio (eccetto GB)

Codici servizio

Codice	Servizio	Descrizione
B2B	DPD CLASSIC	Consegna nazionale e internazionale standard
B2BI	DPD CLASSIC International	Spedizione B2B internazionale
B2BP	DPD CLASSIC Predict	Con notifica al destinatario
PM2	DPD CLASSIC Guarantee	Consegna garantita entro le 18:00
B2C	DPD COMFORT	Con notifica al destinatario
HOME	DPD HOME	Con notifica al destinatario
AM1	DPD EXPRESS 10:00	Consegna garantita entro le 10:00
AM2	DPD EXPRESS 12:00	Consegna garantita entro le 12:00
PSD	DPD SHOP	Consegna in punto di ritiro
PL	DPD PARCEL LETTER	Piccoli articoli, max 2 kg
PBOX	DPD PARCELBOX	GPS + foto, max 5 kg
RET	Reso	Reso merci
CR	Collection Request	Ritiro dal cliente al cliente finale
LQ	Limited Quantities	Merci pericolose (quantità limitate)
SWAP	SWAP	Sostituzione rapida per merci rifiutate
TYRE	Pneumatici	Spedizione di pneumatici in volume

Risposte di errore

Tutti gli endpoint restituiscono oggetti di errore coerenti:

{
  "timestamp": "2025-10-30T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/shipments"
}

207 Multi-Status — successo parziale (alcuni elementi riusciti, altri falliti). Ogni voce di failed[] porta un identificationNumber (riprende il valore fornito dal client, quando l'elemento di input ne aveva uno — è il modo per ricollegare un errore all'elemento di input) e un errorCode, oltre a un array fieldErrors[] piatto (ogni voce con il proprio path) oppure un reason testuale:

{
  "tracingId": "TRACE-123",
  "success": [],
  "failed": [
    {
      "identificationNumber": "client-supplied-id-9",
      "errorCode": "SYS-VALIDATION-FAILURE",
      "fieldErrors": [
        {
          "path": "receiver.email",
          "code": "SHP-VAL-EMAIL-REQUIRED",
          "message": "Email address is required."
        }
      ]
    }
  ]
}

Un lotto in cui tutti gli elementi falliscono restituisce sempre 400 Bad Request, indipendentemente dalla causa — anche in caso di guasto del motore di instradamento, che resta segnalato per singolo elemento tramite errorCode: SHP-ROUTING-ENGINE-UNAVAILABLE. Vedi Spedizioni per la tabella completa dei codici di stato.

Lingue supportate

Passare il parametro di query lang — o un header Accept-Language — per ottenere messaggi e descrizioni di tracciamento localizzati:

Lingua	Valori lang
Tedesco	de_CH, de_DE
Inglese	en_US, en_GB
Francese	fr_CH, fr_FR
Italiano	it_CH, it_IT

La regione è facoltativa — de funziona come de_CH. I valori non riconosciuti ricadono sull'inglese.

---

Ambienti

Ambiente	URL di base
Produzione	https://label-print-shipments.dpd.ch
Staging	https://label-print-st-shipments.dpd.ch

---

Limitazione della frequenza

Tutti gli endpoint sono soggetti a limitazione della frequenza. Il superamento dei limiti restituisce 429 Too Many Requests.

Header	Descrizione
X-RateLimit-Limit	Numero massimo di richieste consentite nella finestra
X-RateLimit-Remaining	Richieste rimanenti nella finestra corrente
X-RateLimit-Reset	Timestamp Unix in cui la finestra si reimposta

Raccomandazioni:

• Memorizzare nella cache i dati dei punti di ritiro (cambiano di rado) per ridurre le chiamate API
• Implementare un back-off esponenziale quando si riceve una risposta 429
• Utilizzare richieste di spedizione in batch invece di chiamate singole quando possibile

---

OpenAPI / Swagger

La documentazione API interattiva e le specifiche leggibili dalla macchina sono disponibili direttamente su ogni servizio:

Risorsa	URL
Swagger UI	https://label-print-shipments.dpd.ch/swagger-ui/index.html
OpenAPI JSON	https://label-print-shipments.dpd.ch/api-docs
OpenAPI YAML	https://label-print-shipments.dpd.ch/api-docs.yaml

---

Buone pratiche

• Token: conservare in modo sicuro, aggiornare prima della scadenza, non esporre mai negli URL o nei log
• Limitazione della frequenza: gestire 429 Too Many Requests con back-off esponenziale; memorizzare nella cache i dati dei punti di ritiro
• Gestione degli errori: verificare i codici di stato HTTP; implementare la logica di ritentativo per gli errori 5xx
• Validazione: validare i dati lato client prima dell'invio; prestare attenzione alle regole specifiche per paese
• Batching: utilizzare la creazione di spedizioni in batch per ridurre al minimo i round trip e il consumo del limite di frequenza