Passa al contenuto principale

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: POST /api/v1/shipments Autenticazione: 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​

CampoTipoLunghezzaObbligatorioDescrizione
invoicingNumberString1–20ObbligatorioNumero di fatturazione cliente
numberOfParcelsInteger—ObbligatorioNumero totale di pacchi (1–99)
serviceCodeString—ObbligatorioCodice servizio DPD (PSD, PSI, PL, PBOX, RET)
mpsIdString—FacoltativoID Master Parcel Shipment per il raggruppamento
customerReferenceNumber1String0–35FacoltativoRiferimento cliente 1
customerReferenceNumber2String0–35FacoltativoRiferimento cliente 2
customerReferenceNumber3String0–35FacoltativoRiferimento cliente 3
customerReferenceNumber4String0–35FacoltativoRiferimento cliente 4
shipmentNoteString0–255FacoltativoNota sulla spedizione
parcelShopIdString—CondizionaleRichiesto per i servizi di consegna in punto di ritiro
clientSoftwareString—FacoltativoNome dell'applicazione client
clientVersionString—FacoltativoVersione dell'applicazione client

Campi indirizzo (mittente / destinatario / reso)​

CampoTipoLunghezzaObbligatorioNote
nameString1–35ObbligatorioNome azienda o persona
name2String0–35FacoltativoRiga nome aggiuntiva
contactString0–35FacoltativoPersona di contatto
countryCodeString2ObbligatorioISO 3166-1 alpha-2
stateCodeString2CondizionaleObbligatorio per US/CA
zipCodeString1–9ObbligatorioCodice postale
cityString1–35ObbligatorioCittà
streetString1–35ObbligatorioNome e numero civico
street2String0–35FacoltativoRiga indirizzo aggiuntiva
houseNumberString0–8CondizionaleObbligatorio per NL
phoneString0–30CondizionaleObbligatorio per GB — formato internazionale +CCNNNNNN
emailString0–50CondizionaleObbligatorio per i paesi non-CH/LI (eccetto GB)
eoriString0–22CondizionaleObbligatorio per spedizioni internazionali GB/NO
vatString0–20CondizionaleObbligatorio per spedizioni internazionali GB/NO (non-CH)
languageString2FacoltativoISO 639-1 (DE, EN, FR, IT)
referenceString0–35FacoltativoRiferimento indirizzo
noteString0–70FacoltativoIstruzioni di consegna
glnString0–13FacoltativoGlobal Location Number

Informazioni sui colli (parcelInfo[])​

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

CampoTipoLunghezzaObbligatorioDescrizione
serviceCodeString—ObbligatorioCodice servizio a livello di collo
optionCodesArray<String>—FacoltativoCodici opzione di servizio aggiuntivi
contentString—FacoltativoDescrizione del contenuto del collo (PCONTENT)
weightInteger—FacoltativoPeso del collo in grammi
reference1String0–35FacoltativoRiferimento collo 1
reference2String0–35FacoltativoRiferimento collo 2
reference3String—FacoltativoRiferimento collo 3
reference4String—FacoltativoRiferimento collo 4
higherInsuranceObject—FacoltativoServizio aggiuntivo di assicurazione integrativa (vedi sotto)
limitedQuantitiesObject—FacoltativoDati quantità limitate (merci pericolose) (vedi sotto)

Campi higherInsurance:

CampoTipoLunghezzaObbligatorioDescrizione
amountNumber—ObbligatorioImporto assicurato
currencyString3ObbligatorioCodice valuta ISO 4217

Campi limitedQuantities:

CampoTipoLunghezzaObbligatorioDescrizione
unNumberString—FacoltativoNumero ONU merci pericolose
codeString—FacoltativoCodice sostanza
packagingGroupString—FacoltativoGruppo di imballaggio
klassString—FacoltativoClasse di merci pericolose
subWeightInteger—FacoltativoPeso della sostanza

Dati doganali (customsData)​

Obbligatorio per le spedizioni internazionali (sdoganamento non nazionale).

CampoTipoLunghezzaObbligatorioDescrizione
shipmentTypeString1ObbligatorioTipo di collo (PARCELTYPE)
valueNumber—ObbligatorioValore doganale della merce (CAMOUNT)
currencyString3FacoltativoValuta ISO 4217 per value
valueExNumber—FacoltativoValore doganale aggiuntivo (CAMOUNTEX)
currencyExString3FacoltativoValuta ISO 4217 per valueEx
reasonForExportString2ObbligatorioCodice motivo di esportazione
termsOfDeliveryString2ObbligatorioIncoterms / condizioni di consegna (CTERMS)
clearanceClearedString1ObbligatorioFlag di sdoganamento
opCodeString3FacoltativoCodice operazione
preAlertStatusString3FacoltativoStato pre-alert
contentString0–35FacoltativoDescrizione del contenuto doganale (CCONTENT)
paperString1FacoltativoFlag documento (CPAPER)
highLowValueString1FacoltativoIndicatore valore alto/basso
invoiceNumberString0–35FacoltativoNumero di fattura commerciale (CINVOICE)
dateDate (yyyy-MM-dd)—ObbligatorioData fattura (CINVOICEDATE)
exportMRNString0–209FacoltativoExport Movement Reference Number (SHIPMRN)
documentTypesArray<String>≤20 vociFacoltativoTipi di documenti doganali
commentString0–70FacoltativoCommento doganale (CCOMMENT)
comment2String0–70FacoltativoRegistrazione nel paese di destinazione (DESTCOUNTRYREG)
senderHMRCString0–15FacoltativoRegistrazione HMRC del mittente
senderInvoicingAddressObject—FacoltativoIndirizzo di fatturazione del mittente (oggetto indirizzo)
receiverInvoicingAddressObject—FacoltativoIndirizzo di fatturazione del destinatario (oggetto indirizzo)
numberOfInvoiceLinesInteger—FacoltativoNumero di righe fattura (NUMBEROFARTICLE)
invoiceLinesArray<Object>—CondizionaleRighe fattura (vedi sotto). Numero compreso tra il numero di colli e il numero di colli + 20

Campi invoiceLines[]:

CampoTipoLunghezzaObbligatorioDescrizione
natureOfGoodsString0–200FacoltativoNatura delle merci (CCONTENT)
hsCodeString0–11FacoltativoCodice tariffario SA
productCodeString0–255FacoltativoCodice prodotto (CPRODCODE)
amountNumber—FacoltativoImporto riga (CAMOUNTLINE)
grossWeightInteger—FacoltativoPeso lordo (CGROSSWEIGHT)
qItemsInteger—ObbligatorioQuantità di articoli
countryOfOriginString3FacoltativoPaese di origine ISO (CORIGIN)

Opzioni di stampa​

CampoTipoObbligatorioDescrizione
paperSizeStringFacoltativoA4 o A6 (predefinito: A4)
startPositionStringFacoltativoPosizione etichetta sul foglio A4: UPPER_LEFT, UPPER_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT

Risposta​

201 Created — tutte le spedizioni create:

{
  "tracingId": "TRACE-123",
  "success": [
    {
      "id": 1,
      "parcelNumber": "05305000123456",
      "label": "base64-encoded-PDF..."
    }
  ],
  "failed": []
}

207 Multi-Status — successo parziale:

{
  "tracingId": "TRACE-456",
  "success": [ { "id": 1, "parcelNumber": "05305000123456", "label": "..." } ],
  "failed": [
    {
      "id": 2,
      "fieldErrors": {
        "receiver.countryCode": ["NOT_SUPPORTED"],
        "receiver.email": ["REQUIRED_FOR_INTERNATIONAL"]
      }
    }
  ]
}

Codici di stato:

CodiceDescrizione
201 CreatedTutte le spedizioni create con successo
207 Multi-StatusAlcune riuscite, altre fallite
400 Bad RequestPayload della richiesta non valido
401 UnauthorizedToken mancante o non valido

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"
      }
    }
  ]'

Stampa manifesto​

Genera un PDF di manifesto che elenca le spedizioni consegnate a DPD per un determinato numero di fatturazione. Supporta la tracciabilità del ritiro giornaliero — il file viene restituito come allegato PDF ed è destinato a essere stampato e conservato con i pacchi.

Endpoint: POST /api/v1/shipments/print-manifest Produce: application/pdf Autenticazione: Token JWT Bearer obbligatorio

L'endpoint restituisce solo le spedizioni di proprietà dell'utente autenticato. Filtrare il risultato con un intervallo di date (fromDate/toDate, applicato a importedAt) e/o un elenco esplicito di parcelNumbers — almeno uno dei due filtri è obbligatorio.

Richiesta​

Content-Type: application/json

{
  "invoicingNumber": "12345678",
  "fromDate": "2026-03-25",
  "toDate": "2026-04-29",
  "parcelNumbers": ["05305000123456", "05305000123457"],
  "address": {
    "reference": "PICKUP-001"
  },
  "printSettings": {
    "printRecipientReference": true,
    "printParcelReference1": true,
    "printParcelReference2": true,
    "printUserName": true,
    "printWeight": true,
    "sortOrderForManifest": "CONSIGNEE_ZIP"
  }
}
CampoTipoObbligatorioDescrizione
invoicingNumberStringObbligatorioNumero di fatturazione che delimita il manifesto
fromDateData (yyyy-MM-dd)CondizionaleLimite inferiore inclusivo di importedAt. Obbligatorio se parcelNumbers non è fornito. Deve essere fornito insieme a toDate
toDateData (yyyy-MM-dd)CondizionaleLimite superiore inclusivo di importedAt. Obbligatorio se parcelNumbers non è fornito. Deve essere fornito insieme a fromDate
parcelNumbersArray<String>CondizionaleRestringe il manifesto a specifici numeri di pacco. Obbligatorio se non viene fornito alcun intervallo di date
addressOggettoFacoltativoIndirizzo di ritiro che delimita il manifesto. Viene letto solo reference; tutti gli altri campi dell'indirizzo sono ignorati. Il riferimento viene risolto in base alla configurazione cliente. Se omesso e il risultato copre più ritiri, viene utilizzato il primo ritiro trovato e le altre spedizioni vengono silenziosamente scartate
printSettingsOggettoObbligatorioImpostazioni di stampa applicate al manifesto generato

Campi printSettings​

CampoTipoObbligatorioDescrizione
printRecipientReferenceBooleanFacoltativoStampa la colonna riferimento destinatario
printParcelReference1BooleanFacoltativoStampa il riferimento pacco 1
printParcelReference2BooleanFacoltativoStampa il riferimento pacco 2
printUserNameBooleanFacoltativoStampa il nome utente sul manifesto
printWeightBooleanFacoltativoStampa la colonna peso del pacco
sortOrderForManifestEnumObbligatorioOrdinamento delle spedizioni sul manifesto

Valori di sortOrderForManifest:

ValoreDescrizione
CONSIGNEE_ZIPOrdinamento per CAP del destinatario
CONSIGNEE_COUNTRYOrdinamento per paese del destinatario
CONSIGNEE_NAMEOrdinamento per nome del destinatario
REFERENCE_1Ordinamento per riferimento pacco 1
PARCEL_NUMBEROrdinamento per numero di pacco

Caso d'uso comune — manifesto di oggi​

Il caso di integrazione più frequente è la generazione del manifesto per le spedizioni importate oggi, appena prima del ritiro da parte del corriere. Impostare fromDate e toDate sulla data odierna (giorni UTC) e omettere parcelNumbers per includere tutte le spedizioni di quel numero di fatturazione in quella giornata:

{
  "invoicingNumber": "12345678",
  "fromDate": "2026-05-26",
  "toDate": "2026-05-26",
  "printSettings": {
    "printRecipientReference": true,
    "printParcelReference1": true,
    "printUserName": true,
    "printWeight": true,
    "sortOrderForManifest": "CONSIGNEE_ZIP"
  }
}
TODAY=$(date -u +%F)
curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments/print-manifest" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -o manifest.pdf \
  -d "{
    \"invoicingNumber\": \"12345678\",
    \"fromDate\": \"$TODAY\",
    \"toDate\": \"$TODAY\",
    \"printSettings\": {
      \"printRecipientReference\": true,
      \"printParcelReference1\": true,
      \"printUserName\": true,
      \"printWeight\": true,
      \"sortOrderForManifest\": \"CONSIGNEE_ZIP\"
    }
  }"

Note:

  • fromDate/toDate vengono confrontati con importedAt in UTC (dall'inizio alla fine della giornata). Le spedizioni importate dopo la mezzanotte UTC del giorno di calendario successivo nel fuso orario locale non appariranno.
  • Fornire address: {"reference": "PICKUP-001"} per limitare a un ritiro specifico quando l'utente ne ha più di uno.

Risposta​

200 OK — manifesto generato; il corpo è il flusso PDF.

HeaderValore
Content-Typeapplication/pdf
Content-Dispositionattachment; filename="manifest.pdf"
Content-LengthDimensione del PDF in byte

Codici di stato​

CodiceDescrizione
200 OKManifesto generato
400 Bad RequestFiltro mancante o non valido (ad es. solo fromDate o toDate impostato, fromDate successivo a toDate, né intervallo di date né parcelNumbers forniti, printSettings mancante, address.reference non risolvibile)
401 UnauthorizedToken mancante o non valido
404 Not FoundNessuna spedizione corrisponde al filtro, o nessuna corrisponde al ritiro richiesto

Esempio​

curl -X POST "https://label-print-shipments.dpd.ch/api/v1/shipments/print-manifest" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -o manifest.pdf \
  -d '{
    "invoicingNumber": "12345678",
    "fromDate": "2026-03-25",
    "toDate": "2026-04-29",
    "parcelNumbers": ["05305000123456", "05305000123457"],
    "address": {
      "reference": "PICKUP-001"
    },
    "printSettings": {
      "printRecipientReference": true,
      "printParcelReference1": true,
      "printParcelReference2": true,
      "printUserName": true,
      "printWeight": true,
      "sortOrderForManifest": "CONSIGNEE_ZIP"
    }
  }'