Ordini di ritiro

Creare ordini di ritiro pianificati e ricorrenti. DPD ritirerà i pacchi dal vostro indirizzo nei giorni e nelle fasce orarie specificati.

Endpoint	Autenticazione
`POST /api/v1/pickup-orders`	Token JWT Bearer obbligatorio

Richiesta

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

Corpo: List<PickupOrderDTO>

Campi

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
`invoicingNumber`	String	1–20	Obbligatorio	Numero di fatturazione cliente
`pickupDate`	String	10	Obbligatorio	Data di ritiro pianificata (`yyyy-MM-dd`), deve essere futura
`weekDay`	Integer	—	Facoltativo	Giorno della settimana (1=Lun … 7=Dom). Calcolato automaticamente da `pickupDate` se omesso
`fromTime1`	String	5	Facoltativo	Inizio fascia oraria mattutina (`HH:mm`)
`toTime1`	String	5	Facoltativo	Fine fascia oraria mattutina (`HH:mm`)
`fromTime2`	String	5	Facoltativo	Inizio fascia oraria pomeridiana (`HH:mm`)
`toTime2`	String	5	Facoltativo	Fine fascia oraria pomeridiana (`HH:mm`)
`address`	AddressDTO	—	Obbligatorio	Indirizzo del luogo di ritiro
`numberOfParcels`	Integer	—	Obbligatorio	Numero di pacchi previsto (1–99)
`tour`	String	0–50	Facoltativo	Identificatore tour/percorso
`clientSoftware`	String	1–30	Obbligatorio	Nome dell'applicazione client. La richiesta viene rifiutata se il valore è assente o vuoto
`clientVersion`	String	1–10	Obbligatorio	Versione dell'applicazione client. La richiesta viene rifiutata se il valore è assente o vuoto

Fasce orarie

È possibile specificare fino a due fasce orarie (mattina e pomeriggio). Lasciare vuoti i campi del pomeriggio per una singola fascia continua.

Fascia	Campi	Esempio
Mattina	`fromTime1` / `toTime1`	`08:00` / `12:00`
Pomeriggio	`fromTime2` / `toTime2`	`13:00` / `17:00`

Esempio

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/pickup-orders?lang=it_CH" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "invoicingNumber": "12345678",
      "pickupDate": "<next working day, yyyy-MM-dd>",
      "weekDay": 5,
      "fromTime1": "08:00",
      "toTime1": "12:00",
      "fromTime2": "13:00",
      "toTime2": "17:00",
      "numberOfParcels": 15,
      "address": {
        "name": "Magazzino Sede A",
        "countryCode": "CH",
        "zipCode": "6900",
        "city": "Lugano",
        "street": "Via Industria 45",
        "phone": "+41441234567",
        "email": "magazzino@azienda.ch",
        "reference": "WAREHOUSE-A"
      },
      "tour": "TOUR-TI-SUD",
      "clientSoftware": "Customer App",
      "clientVersion": "4.0.0"
    }
  ]'

Risposta

201 Created — tutti gli ordini creati:

{
  "tracingId": "TRACE-321",
  "success": [
    { "tracingId": "123456789" }
  ],
  "failed": []
}

Ogni elemento di success[] contiene il tracingId assegnato all'ordine creato e identificationNumber restituito quando l'elemento della richiesta ne forniva uno. Un elemento di successo non contiene il campo id — 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 con errori a livello di campo. 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-322",
  "success": [],
  "failed": [
    {
      "identificationNumber": "client-supplied-id-5",
      "errorCode": "SYS-VALIDATION-FAILURE",
      "fieldErrors": [
        {
          "path": "numberOfParcels",
          "code": "SHP-VAL-NUMBEROFPARCELS-MAX-CHARACTERS",
          "message": "Number of parcels exceeds the maximum allowed length."
        },
        {
          "path": "address.countryCode",
          "code": "SHP-VAL-COUNTRYCODE-REQUIRED",
          "message": "Country code is required."
        }
      ]
    }
  ]
}

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

{
  "identificationNumber": "client-supplied-id-7",
  "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`	Tutti gli ordini di ritiro creati
`207 Multi-Status`	Alcuni riusciti, altri falliti
`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

Differenza con le richieste di ritiro

	Ordini di ritiro	Richieste di ritiro
Frequenza	Ricorrente (piano settimanale)	Una tantum
Fasce orarie	Fino a 2 (mattina + pomeriggio)	Definite da DPD
Limite pacchi	99	999
Campo peso	Non richiesto	Facoltativo (grammi)

Richiesta​

Campi​

Fasce orarie​

Esempio​

Risposta​

Differenza con le richieste di ritiro​