Punti di ritiro

Cercare punti di ritiro DPD (parcel shop, locker, punti di servizio) per indirizzo o coordinate GPS.

Percorso base	Autenticazione
/api/v1/parcel-shop	Token JWT Bearer obbligatorio

---

Riepilogo endpoint

Metodo	Endpoint	Descrizione
GET	/api/v1/parcel-shop/{parcelShopId}	Ottenere un punto di ritiro specifico per ID
POST	/api/v1/parcel-shop/address	Cercare punti di ritiro per indirizzo
POST	/api/v1/parcel-shop/coordinates	Cercare punti di ritiro per coordinate GPS

---

GET /api/v1/parcel-shop/{parcelShopId}

Recuperare i dettagli di un punto di ritiro specifico.

Parametro di percorso: parcelShopId — es. FR64548. È accettata anche la forma numerica restituita come parcelShopId nelle risposte (es. 70825452535256).

Parametro di query: lang (facoltativo) — en, de, fr o it. Determina weekDay e services[].description. In mancanza, si usa Accept-Language e infine la lingua predefinita della business unit.

curl -X GET "https://label-print-shipments.dpd.ch/api/v1/parcel-shop/FR64548?lang=it" \
  -H "Authorization: Bearer <jwt_token>"

Risposta 200 OK (orari di apertura ridotti a due giorni):

{
  "id": "FR64548",
  "parcelShopId": 70825452535256,
  "name": "Chris’music",
  "order": 1,
  "distance": 0,
  "type": 100,
  "countryNum": "250",
  "address": {
    "countryCode": "FR",
    "zipCode": "71500",
    "city": "LOUHANS",
    "street": "RUE DES BORDES",
    "street2": "",
    "street3": "",
    "houseNumber": "57",
    "language": "FR"
  },
  "locationHint": "",
  "mapUrl": "",
  "available": "partial",
  "latitude": 46.624802,
  "longitude": 5.224876,
  "openingHours": [
    {
      "weekDay": "Lunedì",
      "openMorning": "09:30",
      "closeMorning": "12:00",
      "openAfternoon": "14:00",
      "closeAfternoon": "19:00"
    },
    {
      "weekDay": "Venerdì",
      "openMorning": "09:30",
      "closeMorning": "12:00"
    }
  ],
  "holidays": [
    { "start": "15/08/2026", "end": "29/08/2026" }
  ],
  "services": [
    { "code": "100", "available": true, "description": "Ritiro del Destinatario" },
    { "code": "200", "available": true, "description": "Ricevimento del pacco pagato online è possibile" },
    { "code": "991", "available": true, "description": "Assunzione del ritorno e possibile" }
  ]
}

Note sulla struttura della risposta:

• I campi senza valore vengono omessi, mai restituiti come null. Nell'esempio la voce di venerdì non ha openAfternoon né closeAfternoon, perché quel giorno ha un'unica fascia di apertura. Non dare per scontato che una chiave sia presente.
• Le date in holidays usano il formato dd/MM/yyyy, non ISO 8601. Il resto dell'API usa date ISO.
• parcelShopId è la codifica numerica di id; entrambi indicano lo stesso punto di ritiro.
• weekDay e services[].description sono localizzati in base a lang.

Codici di stato: 200 OK | 401 Unauthorized | 404 Not Found

---

POST /api/v1/parcel-shop/address

Cercare punti di ritiro vicino a un indirizzo. Risultati ordinati per distanza (dal più vicino).

Corpo della richiesta:

Campo	Tipo	Obbligatorio	Descrizione	Predefinito
country	String (2)	Obbligatorio	Codice paese ISO	—
zipCode	String	Obbligatorio	Codice postale	—
city	String	Facoltativo	Nome città	—
street	String	Facoltativo	Nome via	—
destCountryCode	String	Facoltativo	Paese di destinazione per il filtraggio dei servizi	—
weight	String	Facoltativo	Peso del pacco in kg	—
services	String	Facoltativo	Codici servizio separati da virgola	—
type	String	Facoltativo	Filtro per tipo di punto di ritiro	—
limit	Integer	Facoltativo	Numero massimo di risultati	25
availabilityDate	String	Facoltativo	Verifica la disponibilità alla data (yyyy-MM-dd)	—
hideClosed	Boolean	Facoltativo	Escludere i punti attualmente chiusi	false

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/parcel-shop/address?lang=it_CH" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "CH",
    "zipCode": "6900",
    "city": "Lugano",
    "limit": 10
  }'

Codici di stato: 200 OK (può restituire un elenco vuoto) | 400 Bad Request | 401 Unauthorized

---

POST /api/v1/parcel-shop/coordinates

Cercare punti di ritiro vicino a coordinate GPS. Stesso filtraggio e formato di risposta della ricerca per indirizzo.

Corpo della richiesta:

Campo	Tipo	Obbligatorio	Descrizione
latitude	Double	Obbligatorio	Latitudine GPS (da −90 a 90)
longitude	Double	Obbligatorio	Longitudine GPS (da −180 a 180)
destCountryCode	String	Facoltativo	Paese di destinazione
limit	Integer	Facoltativo	Numero massimo di risultati (predefinito: 25)
hideClosed	Boolean	Facoltativo	Escludere i punti chiusi (predefinito: false)
availabilityDate	String	Facoltativo	Verifica la disponibilità alla data

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/parcel-shop/coordinates" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 46.0050,
    "longitude": 8.9470,
    "limit": 10,
    "hideClosed": true
  }'

Codici di stato: 200 OK | 400 Bad Request | 401 Unauthorized

---

Tipi di punto di ritiro

type non è definito da questa API. Il valore viene trasmesso invariato dal servizio DPD PUDO a monte, sia nella risposta sia nel filtro di richiesta opzionale type, che utilizzano quindi lo stesso spazio di valori.

Tipo	Descrizione
100	DPD Pickup Point
200	DPD Locker
300	Negozio partner (es. ufficio postale)
400	Service Point

Considerare l'elenco incompleto e non chiuso: questi valori appartengono al servizio a monte, quindi non rifiutare un valore che non si riconosce.

type è un campo distinto da services[].code, anche se entrambi usano numeri di tre cifre. Un punto di ritiro con "type": 100 può avere qualsiasi combinazione di codici servizio.

Per filtrare per tipo di punto di ritiro, usare un valore osservato in una risposta per la stessa regione, non un valore ipotizzato.

---

Esempi di codice

Selettore di punto di ritiro in un modulo di spedizione:

async function searchParcelShops(zipCode, city) {
  const response = await fetch(
    'https://label-print-shipments.dpd.ch/api/v1/parcel-shop/address',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ country: 'CH', zipCode, city, limit: 10 })
    }
  );
  return response.json();
}

Ricerca basata su mappa:

function findNearby(lat, lng) {
  return fetch('https://label-print-shipments.dpd.ch/api/v1/parcel-shop/coordinates', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ latitude: lat, longitude: lng, limit: 20, hideClosed: true })
  }).then(r => r.json());
}