Passa al contenuto principale

Problemi comuni

Risposte rapide ai problemi di integrazione più frequenti.

Autenticazione​

401 Unauthorized ad ogni richiesta​

Causa: Il token è assente, scaduto o malformato.

Soluzione:

  1. Verificare che l'intestazione inviata sia corretta: Authorization: Bearer <token> (con la parola Bearer)
  2. Verificare se il token è scaduto — usare /api/v1/login-extended per vedere il campo expireAt
  3. Effettuare nuovamente l'accesso con /api/v1/login per ottenere un nuovo token

Il token scade troppo rapidamente​

Causa: Il TTL del token è configurato lato server.

Soluzione: Contattare il proprio referente DPD per regolare il TTL del token per il proprio account. Nel frattempo, implementare una logica di rinnovo del token che effettui nuovamente l'accesso prima della scadenza.

Spedizioni​

400 Bad Request — errore di validazione​

Causa: Un campo obbligatorio è assente o non supera la validazione.

Soluzione: Verificare l'oggetto fieldErrors nella risposta — indica esattamente quale campo è fallito e perché:

{
  "fieldErrors": {
    "receiver.email": ["REQUIRED_FOR_INTERNATIONAL"],
    "receiver.countryCode": ["NOT_SUPPORTED"]
  }
}

Requisiti comuni dei campi:

  • email è obbligatorio per tutte le destinazioni non-CH/LI (eccetto GB)
  • phone è obbligatorio per le destinazioni GB (formato internazionale: +44...)
  • houseNumber è obbligatorio per le destinazioni NL
  • stateCode è obbligatorio per le destinazioni US/CA

207 Multi-Status — fallimento parziale del batch​

Causa: In una richiesta batch alcune spedizioni sono riuscite e altre sono fallite.

Soluzione: Verificare l'array failed nella risposta per i fieldErrors di ogni elemento. L'array success contiene le spedizioni create con i relativi numeri di pacco ed etichette.

L'etichetta è vuota o non viene stampata​

Causa: Discrepanza tra printOptions.paperSize e la vostra stampante.

Soluzione: Impostare paperSize esplicitamente nella richiesta:

  • "A4" — foglio A4 intero (più etichette per pagina, usare startPosition: UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT)
  • "A6" — stampanti per etichette termiche

Punti di ritiro​

Risultati vuoti nella ricerca per indirizzo​

Causa: Nessun punto trovato entro il raggio di ricerca predefinito di 5 km, oppure l'indirizzo non è stato risolto.

Soluzione:

  1. Provare a fornire sia zipCode sia city — l'API ricade sul codice postale se l'indirizzo completo non può essere geocodificato
  2. Rimuovere i filtri di servizio/tipo per ampliare la ricerca
  3. Impostare hideClosed: false per includere i punti eventualmente chiusi temporaneamente

404 Not Found per l'ID del punto di ritiro​

Causa: L'ID del punto non esiste o non è più attivo.

Soluzione: Effettuare nuovamente la ricerca per indirizzo o coordinate per ottenere gli ID dei punti attuali. Gli ID dei punti di ritiro possono cambiare quando i punti chiudono o riaprono.

Tracciamento​

404 Not Found per numero di pacco​

Causa: I dati di tracciamento non sono ancora disponibili oppure il numero di pacco è errato.

Soluzione:

  1. Verificare il numero di pacco dalla risposta di creazione della spedizione (success[].parcelNumber)
  2. Attendere qualche minuto dopo la creazione della spedizione affinché il tracciamento diventi disponibile
  3. Verificare che il formato del numero di pacco sia corretto (es. 05305000123456)

Richieste di ritiro e ordini di ritiro​

pickupDate rifiutato​

Causa: La data è nel passato o è formattata in modo errato.

Soluzione: Usare il formato yyyy-MM-dd e assicurarsi che la data sia almeno quella di domani nel fuso orario europeo.

Generale​

Errori HTTPS / SSL​

Tutte le chiamate API devono usare HTTPS. I certificati autofirmati non sono accettati in produzione.

Limitazione delle richieste (429 Too Many Requests)​

Implementare un backoff esponenziale nella propria applicazione. Considerare la memorizzazione nella cache dei dati dei punti di ritiro (che cambiano di rado) per ridurre le chiamate API.

Ancora bloccati?​

Contattare il supporto DPD includendo:

  • Il tracingId dalla risposta API (o l'intero corpo della risposta di errore)
  • L'endpoint chiamato e l'ora approssimativa della richiesta
  • Il proprio ambiente di integrazione (dev/staging/production)