Spedizioni

Creare una o più spedizioni in una singola richiesta. L'API valida tutti i campi, genera i numeri di pacco, arricchisce i dati di instradamento e restituisce etichette PDF.

Endpoint	Autenticazione
POST /api/v1/shipments	Token JWT Bearer obbligatorio

---

Crea spedizione

Richiesta

Content-Type: application/json Corpo: array di oggetti spedizione

[
  {
    "invoicingNumber": "12345678",
    "serviceCode": "PSD",
    "sender": { },
    "receiver": { },
    "parcelInfo": [ ],
    "customsData": { },
    "printOptions": { }
  }
]

Campi principali della spedizione

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
invoicingNumber	String	1–20	Obbligatorio	Numero di fatturazione cliente
numberOfParcels	Integer	1–2 cifre	Obbligatorio	Numero totale di pacchi
serviceCode	String	—	Obbligatorio	Codice servizio DPD (PSD, PSI, PL, PBOX, RET)
mpsId	String	—	Facoltativo	ID Master Parcel Shipment per il raggruppamento
customerReferenceNumber1	String	0–35	Facoltativo	Riferimento cliente 1. Troncato, non rifiutato
customerReferenceNumber2	String	0–35	Facoltativo	Riferimento cliente 2. Troncato, non rifiutato
customerReferenceNumber3	String	0–35	Facoltativo	Riferimento cliente 3. Troncato, non rifiutato
customerReferenceNumber4	String	0–35	Facoltativo	Riferimento cliente 4. Troncato, non rifiutato
shipmentNote	String	—	Facoltativo	Nota sulla spedizione
parcelShopId	String	—	Condizionale	Richiesto per i servizi di consegna in punto di ritiro
clientSoftware	String	1–30	Obbligatorio	Nome dell'applicazione client
clientVersion	String	1–10	Obbligatorio	Versione dell'applicazione client
identificationNumber	String	0–100	Facoltativo	Il tuo identificativo per questa spedizione, restituito in failed[]

Alcuni limiti non vengono applicati

I nomi dell'indirizzo, le righe della via, il numero civico e i riferimenti di collo e cliente non vengono rifiutati quando sono troppo lunghi. Il valore viene tagliato silenziosamente al limite e non viene segnalato alcun errore. Se la richiesta presenta altri problemi, ricevi quegli errori al suo posto, che possono sembrare non collegati al campo troppo lungo. Applica queste lunghezze nel tuo codice.

Come vengono verificate le lunghezze dei campi

La colonna Lunghezza indica il limite applicato dall'API. Un trattino significa che la lunghezza non viene verificata.

• invoicingNumber, clientSoftware, clientVersion e identificationNumber vengono verificati prima dell'elaborazione del lotto. Un valore troppo lungo rifiuta l'intera richiesta con 400.
• Tutti gli altri limiti vengono verificati per singola spedizione. Un valore troppo lungo fa fallire quella spedizione con una voce in fieldErrors[], e la richiesta restituisce 207 (o 400 se tutte le spedizioni sono fallite).
• I campi contrassegnati come troncato nelle tabelle sono l'eccezione: vengono accorciati, non rifiutati.
• Il peso del collo weight viene verificato rispetto a un massimo specifico per prodotto, vedi la tabella dei pesi qui sotto.

Campi indirizzo (mittente / destinatario / reso)

Campo	Tipo	Lunghezza	Obbligatorio	Note
name	String	1–35	Obbligatorio	Nome azienda o persona. Troncato, non rifiutato
name2	String	0–35	Facoltativo	Riga nome aggiuntiva. Troncato, non rifiutato
contact	String	0–35	Facoltativo	Persona di contatto. Troncato, non rifiutato
countryCode	String	2	Obbligatorio	ISO 3166-1 alpha-2
stateCode	String	—	Condizionale	Obbligatorio per US/CA
zipCode	String	1–9	Obbligatorio	Codice postale
city	String	1–35	Obbligatorio	Città. Troncato, non rifiutato
street	String	1–35	Obbligatorio	Nome e numero civico. Troncato, non rifiutato
street2	String	0–35	Facoltativo	Riga indirizzo aggiuntiva. Troncato, non rifiutato
houseNumber	String	0–8	Condizionale	Obbligatorio per NL. Troncato, non rifiutato
phone	String	0–35	Condizionale	Obbligatorio per GB — formato internazionale
email	String	0–100	Condizionale	Obbligatorio per i paesi non-CH/LI (eccetto GB)
eori	String	—	Condizionale	Obbligatorio per spedizioni internazionali GB/NO
vat	String	—	Condizionale	Obbligatorio per spedizioni internazionali GB/NO (non-CH)
language	String	—	Facoltativo	ISO 639-1 (DE, EN, FR, IT)
reference	String	—	Facoltativo	Riferimento indirizzo
note	String	0–70	Facoltativo	Istruzioni di consegna
gln	String	—	Facoltativo	Global Location Number

Informazioni sui colli (parcelInfo[])

Array di oggetti collo — una voce per ogni collo fisico. Il numero di voci deve corrispondere a numberOfParcels.

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
serviceCode	String	—	Obbligatorio	Codice servizio a livello di collo — vedi Servizi e opzioni
optionCodes	Array<String>	—	Facoltativo	Codici opzione di servizio aggiuntivi — vedi Servizi e opzioni
content	String	—	Facoltativo	Descrizione del contenuto del collo (PCONTENT)
weight	Integer	—	Obbligatorio	Peso del collo in grammi — il massimo dipende dal prodotto, vedi sotto
reference1	String	0–35	Facoltativo	Riferimento collo 1. Troncato, non rifiutato
reference2	String	0–35	Facoltativo	Riferimento collo 2. Troncato, non rifiutato
reference3	String	0–35	Facoltativo	Riferimento collo 3. Troncato, non rifiutato
reference4	String	0–35	Facoltativo	Riferimento collo 4. Troncato, non rifiutato
higherInsurance	Object	—	Facoltativo	Servizio aggiuntivo di assicurazione integrativa (vedi sotto)
limitedQuantities	Object	—	Facoltativo	Dati quantità limitate (merci pericolose) (vedi sotto)

Peso massimo del collo — weight viene inviato in grammi, e un collo oltre questi limiti viene rifiutato con un errore sul campo weight:

Prodotto	Nazionale	Internazionale
PSD	35 kg	20 kg
PL	2 kg	2 kg
PBOX	5 kg	5 kg
Tutti gli altri prodotti	35 kg	31,5 kg

Campi higherInsurance:

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
amount	Number	—	Obbligatorio	Importo assicurato
currency	String	—	Obbligatorio	Codice valuta ISO 4217

Campi limitedQuantities:

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
unNumber	String	0–4	Condizionale	Numero ONU merci pericolose (es. 1234). Obbligatorio per le spedizioni internazionali con l'opzione LQ
code	String	0–5	Facoltativo	Codice di imballaggio (es. C1)
packagingGroup	String	—	Condizionale	Gruppo di imballaggio (es. I, II, III). Obbligatorio per le spedizioni internazionali con l'opzione LQ
klass	String	0–6	Facoltativo	Classe di merci pericolose (es. 8)
subWeight	Integer	0–6	Facoltativo	Peso della sostanza

Note:

• Nessun campo ha un valore predefinito — i campi omessi restano vuoti.
• Per le spedizioni internazionali (non nazionali) con l'opzione di servizio LQ, unNumber e packagingGroup sono obbligatori; altrimenti tutti i campi sono facoltativi.
• Caratteri consentiti per unNumber, code, klass, subWeight: lettere, cifre, spazio e . ( ) / _ | -. packagingGroup non ha limiti di lunghezza o restrizioni sui caratteri.
• Indicazione di integrazione (corrispondenza dei campi, non validata da questa API): durante la migrazione dal blocco Shivah WS <hazardous>, i campi corrispondono come segue — identificationUnNo → unNumber, identificationClass → klass, packingGroup → packagingGroup, packingCode → code, hazardousWeight → subWeight.

Dati doganali (customsData)

Obbligatorio per le spedizioni internazionali (sdoganamento non nazionale).

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
shipmentType	String	1–2	Obbligatorio	Tipo di collo (PARCELTYPE) — vedi valori sotto
value	Number	—	Obbligatorio	Valore doganale della merce (CAMOUNT)
currency	String	—	Facoltativo	Valuta ISO 4217 per value
valueEx	Number	—	Facoltativo	Valore doganale aggiuntivo (CAMOUNTEX)
currencyEx	String	—	Facoltativo	Valuta ISO 4217 per valueEx
reasonForExport	String	1–35	Obbligatorio	Codice motivo di esportazione — vedi valori sotto
termsOfDelivery	String	1–35	Obbligatorio	Incoterms / condizioni di consegna (CTERMS) — vedi valori sotto
clearanceCleared	String	1–35	Obbligatorio	Flag di sdoganamento — vedi valori sotto
opCode	String	—	Facoltativo	Codice operazione
preAlertStatus	String	—	Facoltativo	Stato pre-alert
content	String	—	Facoltativo	Descrizione del contenuto doganale (CCONTENT)
paper	String	—	Facoltativo	Flag documento (CPAPER)
highLowValue	String	—	Facoltativo	Indicatore valore alto/basso
invoiceNumber	String	0–35	Facoltativo	Numero di fattura commerciale (CINVOICE)
date	Date (yyyy-MM-dd)	—	Obbligatorio	Data fattura (CINVOICEDATE)
exportMRN	String	0–209	Facoltativo	Export Movement Reference Number (SHIPMRN)
documentTypes	Array<String>	—	Facoltativo	Tipi di documenti doganali
comment	String	—	Facoltativo	Commento doganale (CCOMMENT)
comment2	String	—	Facoltativo	Registrazione nel paese di destinazione (DESTCOUNTRYREG)
senderHMRC	String	0–209	Facoltativo	Registrazione HMRC del mittente
senderInvoicingAddress	Object	—	Facoltativo	Indirizzo di fatturazione del mittente (oggetto indirizzo)
receiverInvoicingAddress	Object	—	Facoltativo	Indirizzo di fatturazione del destinatario (oggetto indirizzo)
numberOfInvoiceLines	Integer	—	Facoltativo	Numero di righe fattura (NUMBEROFARTICLE)
invoiceLines	Array<Object>	—	Condizionale	Righe fattura (vedi sotto). Numero compreso tra il numero di colli e il numero di colli + 20

Valori di shipmentType:

Valore	Descrizione
D	Documento
P	Merce (non-documento)

Valori di reasonForExport:

Valore	Descrizione
01	Vendita (predefinito)
02	Reso / sostituzione
03	Regalo

Valori di termsOfDelivery:

Valore	Descrizione
01	DAP, non sdoganato
02	DDP, reso sdoganato (dazi inclusi, tasse escluse)
03	DDP, reso sdoganato (dazi e tasse inclusi)
05	Franco fabbrica (EXW)
06	DAP
07	DAP avanzato — dazi e tasse prepagati dal destinatario

Valori di clearanceCleared:

Valore	Descrizione
N	No
F	Franco
E	Sdoganato all'esportazione
T	Sdoganato in transito
I	Sdoganato all'importazione
H	Ibrido

Campi invoiceLines[]:

Campo	Tipo	Lunghezza	Obbligatorio	Descrizione
natureOfGoods	String	0–200	Facoltativo	Natura delle merci (CCONTENT)
hsCode	String	6 o 8 cifre	Facoltativo	Codice tariffario SA
productCode	String	—	Facoltativo	Codice prodotto (CPRODCODE)
amount	Number	13 cifre + 2 decimali	Facoltativo	Importo riga (CAMOUNTLINE)
grossWeight	Integer	fino a 5 cifre	Facoltativo	Peso lordo (CGROSSWEIGHT)
qItems	Integer	fino a 5 cifre	Obbligatorio	Quantità di articoli
countryOfOrigin	String	0–3	Facoltativo	Paese di origine ISO (CORIGIN)

Opzioni di stampa

Campo	Tipo	Obbligatorio	Descrizione
paperSize	String	Facoltativo	Dimensione etichetta: A4 o A6 (predefinito: A6)
printerLanguage	String	Facoltativo	Formato di output: PDF, ZPL o EPL (predefinito: PDF)
printerResolution	Integer	Facoltativo	Risoluzione di stampa in dpi per l'output ZPL/EPL — 150, 200/203, 300 o 600 (predefinito 200; altri valori in 72–600 sono accettati ma tornano a 200 dpi; ignorato per PDF)
startPosition	String	Facoltativo	Posizione etichetta sul foglio A4: UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT
dropOffType	String	Facoltativo	Contenuto etichetta: FULL_LABEL (predefinito, etichetta di spedizione completa), QR_CODE (etichetta QR PNG digitale) o BOTH
splitLabels	Boolean	Facoltativo	Se true, la risposta restituisce un'etichetta per ogni voce di parcelNumbers[] invece di un unico campo label unificato (predefinito: false, vedi Etichette separate per numero di collo)
includeBarcode	Boolean	Facoltativo	Se true, ogni voce di parcelNumbers[] contiene anche il barcode stampato sull'etichetta di quel collo (predefinito: false, vedi Barcode di routing nella risposta)

Nota: le opzioni di stampa valgono per l'intera richiesta — viene usato il primo printOptions presente nella lista delle spedizioni.

Formato e dimensione etichetta: i termini labelFormat/labelSize corrispondono a printerLanguage (formato) e paperSize (dimensione). I formati supportati sono PDF (predefinito), ZPL ed EPL; le dimensioni supportate sono A4 e A6. Un dropOffType QR_CODE/BOTH restituisce un'etichetta QR PNG digitale. I campi Shivah WS equivalenti sono printerLanguage (PDF/ZPL) e paperFormat — vedi ShipmentService.

---

Risposta

201 Created — tutte le spedizioni create. Per impostazione predefinita tutte le etichette sono unite nel campo label di primo livello (base64):

{
  "tracingId": "TRACE-123",
  "label": "base64-encoded-labels...",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [
        { "serviceCode": "B2B", "number": "05305000123456" },
        { "serviceCode": "B2B", "number": "05305000123457" }
      ]
    }
  ],
  "failed": []
}

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 — lo stesso code può comparire a più path (ad es. sia sender.email che receiver.email):

{
  "tracingId": "TRACE-456",
  "label": "base64-encoded-labels...",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [ { "serviceCode": "B2B", "number": "05305000123456" } ]
    }
  ],
  "failed": [
    {
      "identificationNumber": "client-supplied-id-9",
      "errorCode": "SYS-VALIDATION-FAILURE",
      "fieldErrors": [
        {
          "path": "receiver.countryCode",
          "code": "SHP-VAL-COUNTRYCODE-ALLOWED-CHARACTERS",
          "message": "Country code contains invalid characters."
        },
        {
          "path": "receiver.email",
          "code": "SHP-VAL-EMAIL-REQUIRED",
          "message": "Email address is required."
        }
      ]
    }
  ]
}

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

{
  "identificationNumber": "client-supplied-id-11",
  "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 spedizioni create con successo
207 Multi-Status	Alcune riuscite, altre fallite
400 Bad Request	Payload della richiesta non valido, 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

Etichette separate per numero di collo

Con "printOptions": { "splitLabels": true } il campo label di primo livello viene omesso e ogni voce di parcelNumbers[] contiene la propria label base64 con solo le etichette generate per quel numero di collo:

{
  "tracingId": "TRACE-123",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [
        {
          "serviceCode": "B2B",
          "number": "05305000123456",
          "label": "base64-encoded-label..."
        },
        {
          "serviceCode": "B2B",
          "number": "05305000123457",
          "label": "base64-encoded-label..."
        }
      ]
    }
  ],
  "failed": []
}

• Funziona con tutti i formati di etichetta e dimensioni carta. Con output PDF e paperSize: A4 ogni numero di collo riceve un proprio documento A4 invece di più etichette sullo stesso foglio.
• I numeri di collo di reso e swap compaiono come voci separate in parcelNumbers[] e contengono le proprie etichette.
• Senza il flag (o con splitLabels: false) la risposta resta invariata: un'unica label unificata di primo livello, nessun campo label dentro parcelNumbers[].

Barcode di routing nella risposta

Con "printOptions": { "includeBarcode": true } ogni voce di parcelNumbers[] contiene anche il campo barcode — l'esatto contenuto Code128 del barcode di routing stampato sull'etichetta di quel collo, cioè ciò che uno scanner legge dall'etichetta:

{
  "tracingId": "TRACE-123",
  "label": "base64-encoded-labels...",
  "success": [
    {
      "tracingId": "05305000123456",
      "parcelNumbers": [
        {
          "serviceCode": "B2B",
          "number": "05305000123456",
          "barcode": "%000815305305000123456420756"
        }
      ]
    }
  ],
  "failed": []
}

Il valore è il contrassegno % seguito da 27 caratteri:

Parte	Lunghezza	Contenuto
Contrassegno	1	Sempre %
Codice postale	7	CAP del destinatario, in maiuscolo e completato a sinistra con 0
Numero di collo	14	Il numero di collo di questa voce
Codice SO	3	Codice di servizio di routing di questo collo
Paese	3	Codice numerico ISO 3166 del paese di consegna

• La riga leggibile sotto il barcode sull'etichetta aggiunge una cifra di controllo (IEC 7064 mod 37,36) e raggruppa le cifre a quattro; il campo barcode non contiene nessuna delle due cose.
• I numeri di collo di reso e swap riportano il barcode della propria etichetta, che instrada su un codice SO diverso e sul CAP del destinatario del reso, non sui valori del collo di andata.
• Indipendente da printerLanguage, paperSize, splitLabels e dropOffType.
• Senza il flag (o con includeBarcode: false) il campo barcode viene omesso completamente.
• Il barcode richiede una spedizione instradata. Se i dati di routing di un collo sono incompleti, la voce viene restituita senza barcode invece di far fallire la richiesta.

---

Esempio

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "invoicingNumber": "12345678",
      "serviceCode": "PSD",
      "numberOfParcels": 1,
      "sender": {
        "name": "Sender AG",
        "countryCode": "CH",
        "zipCode": "8000",
        "city": "Zürich",
        "street": "Industriestrasse 25"
      },
      "receiver": {
        "name": "Receiver GmbH",
        "countryCode": "DE",
        "zipCode": "10115",
        "city": "Berlin",
        "street": "Alexanderplatz 1",
        "email": "info@receiver.de"
      },
      "parcelInfo": [
        { "weight": 2500 }
      ],
      "printOptions": {
        "paperSize": "A6"
      }
    }
  ]'