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: https://label-print-shipments.dpd.ch Versione API: v1 Autenticazione: 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
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):

{
  "tracingId": "TRACE-123",
  "success": [],
  "failed": [
    {
      "id": 2,
      "fieldErrors": {
        "field.name": ["error_code"]
      }
    }
  ]
}

Lingue supportate

Passare l'header o il parametro di query locale per ottenere messaggi e descrizioni di tracciamento localizzati:

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

Ambienti

Ambiente	URL di base
Produzione	`https://label-print-shipments.dpd.ch`
Staging	`https://label-print-shipments-st.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/v3/api-docs`
OpenAPI YAML	`https://label-print-shipments.dpd.ch/v3/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

Riferimento API​

Avvio rapido​

1. Ottenere un token di accesso​

2. Chiamare un qualsiasi endpoint API​

Concetti comuni​

Validazione degli indirizzi​

Codici servizio​

Risposte di errore​

Lingue supportate​

Ambienti​

Limitazione della frequenza​

OpenAPI / Swagger​

Buone pratiche​