Richieste di ritiro

Pianificare un ritiro una tantum di pacchi dal proprio indirizzo. DPD ritirerà i pacchi alla data richiesta entro una fascia oraria specificata.

Endpoint	Autenticazione
POST /api/v1/collection-requests	Token JWT Bearer obbligatorio

---

Richiesta

Parametro di query: lang (facoltativo) — localizza i messaggi di errore (es. de_CH, en_US, fr_CH, it_CH)

Corpo: List<CollectionRequestDTO>

Campi

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
id	Long	—	Facoltativo	Identificatore della richiesta per il tracciamento nella risposta
invoicingNumber	String	1–20	Obbligatorio	Il vostro numero di fatturazione cliente DPD
pickupDate	String	10	Obbligatorio	Data di ritiro richiesta (yyyy-MM-dd), deve essere una data futura
referenceNumber	String	0–50	Facoltativo	Il vostro numero di riferimento interno
note	String	0–255	Facoltativo	Istruzioni speciali di ritiro
sender	AddressDTO	—	Obbligatorio	Indirizzo presso cui verranno ritirati i pacchi
receiver	AddressDTO	—	Obbligatorio	Indirizzo di destinazione finale
requester	AddressDTO	—	Facoltativo	Persona che richiede il ritiro (predefinito: il destinatario)
numberOfParcels	Integer	—	Obbligatorio	Numero di pacchi previsto. L'API non impone alcun intervallo di valori
weight	Integer	—	Facoltativo	Peso totale di tutti i pacchi in grammi
serviceCode	String	—	Obbligatorio	Deve essere presente, ma il valore viene ignorato — le richieste di ritiro sono sempre create come B2B
clientSoftware	String	1–30	Obbligatorio	Nome della tua applicazione. La richiesta viene rifiutata se il valore è assente o vuoto
clientVersion	String	1–10	Obbligatorio	Versione della tua applicazione. La richiesta viene rifiutata se il valore è assente o vuoto

---

Esempio

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/collection-requests?lang=it_CH" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "invoicingNumber": "12345678",
      "pickupDate": "<next working day, yyyy-MM-dd>",
      "serviceCode": "B2B",
      "numberOfParcels": 5,
      "weight": 25000,
      "clientSoftware": "My Integration",
      "clientVersion": "1.0.0",
      "sender": {
        "name": "Società Mittente SA",
        "countryCode": "CH",
        "zipCode": "6900",
        "city": "Lugano",
        "street": "Via Industria 25",
        "phone": "+41441234567"
      },
      "receiver": {
        "name": "Società Destinataria SRL",
        "countryCode": "IT",
        "zipCode": "20121",
        "city": "Milano",
        "street": "Via Monte Napoleone 1"
      }
    }
  ]'

---

Risposta

201 Created — tutte le richieste create:

{
  "tracingId": "TRACE-789",
  "success": [
    { "tracingId": "BPsEYzTIZ" }
  ],
  "failed": []
}

Ogni elemento di success[] contiene il tracingId assegnato alla richiesta creata e identificationNumber restituito quando l'elemento della richiesta ne forniva uno. Un elemento di successo non contiene né id né referenceNumber — id compare solo negli elementi failed[].

I campi null vengono omessi dalle risposte, quindi un elemento di successo contiene spesso soltanto tracingId.

207 Multi-Status — successo parziale. Ogni voce di failed[] porta un identificationNumber (riprende il valore fornito dal client, quando l'elemento di input ne aveva uno) e un errorCode; le violazioni di campo compaiono come un array fieldErrors[] piatto, con ogni voce che porta il proprio path:

{
  "tracingId": "TRACE-790",
  "success": [],
  "failed": [
    {
      "identificationNumber": "client-supplied-id-4",
      "errorCode": "SYS-VALIDATION-FAILURE",
      "fieldErrors": [
        {
          "path": "pickup.date",
          "code": "SHP-VAL-PICKUP-DATE-INVALID",
          "message": "Pickup date is invalid."
        }
      ]
    }
  ]
}

Un errore transitorio (senza fieldErrors — un'interruzione non è un problema di campo) si presenta invece così:

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

Codici di stato:

Codice	Descrizione
201 Created	Tutte le richieste di ritiro create
207 Multi-Status	Alcune riuscite, altre fallite
400 Bad Request	Errore di validazione, oppure tutti gli elementi del lotto sono falliti — indipendentemente dalla causa, anche in caso di guasto del motore di instradamento
401 Unauthorized	Token mancante o non valido

---

Note

• pickupDate deve essere una data futura; le date passate vengono rifiutate
• weight è espresso in grammi (es. 25000 = 25 kg)
• La validazione dell'indirizzo segue le stesse regole specifiche per paese di Spedizioni (numero civico NL, telefono GB, email per non-CH/LI, ecc.)