L'API Shipping order create è un'API RESTful che ti permette di creare un ordine di spedizione per generare un'etichetta di spedizione e un codice di tracciamento per un pacco.
POST /v1/shipping-orders
Esempio di richiesta
{ "orderReferenceId": "EXMPL0001234", "currency": "EUR", "options": { "weightUnit": "g", "dimensionUnit": "mm", "label": { "format": "pdf" } }, "partner": { "clientName": "ExampleCustomer" }, "shippingMethod": { "uid": "", "carrier": "", "tier": "standard" }, "receiver": { "person": { "firstName": "Foo", "lastName": "Bar", "company": "", "email": "[email protected]", "phone": "01273552886" }, "address": { "country": "GB", "state": "East Sussex", "city": "Brighton", "postcode": "BN1 8YQ", "addressLine1": "11 London Rd", "addressLine2": "", "addressLine3": "", "street": "London Rd", "houseNumber": "11", "suburb": null }, "customs": { "vatNumber": null } }, "sender": { "person": { "firstName": "", "lastName": "", "company": "Example Company", "email": "[email protected]", "phone": "01666 123456" }, "address": { "country": "DE", "state": "", "city": "Donauwörth", "postcode": "86609", "addressLine1": "Am Wassergraben 11", "addressLine2": null, "addressLine3": null, "street": "Am Wassergraben", "houseNumber": "11", "suburb": null }, "customs": { "vatNumber": "DE123456789000", "iossNumber": null, "eoriNumber": "GB987654321000", "pcccNumber": null, "australianBusinessNumber": null } }, "packages": [ { "packageReferenceId": "EXMPL0001234-0-1", "grossWeight": 810, "netWeight": 760, "length": 229, "width": 200, "height": 36, "boxType": "rectangle", "volumetricWeight": 700, "items": [ { "itemReferenceId": "EXMPL0001234-0-1-ITEM1", "description": "Mug", "value": 18.42, "quantity": 4, "weight": 760, "hsCode": "44199090", "countryOfOrigin": "DE" } ] } ]}Esempio di risposta riuscita
{ "orderId": "fb7c0bf6-bdb1-4443-b5db-7263793be32b", "orderReferenceId": "EXMPL0001234", "shippingMethod": { "carrier": "UPS", "uid": "ups_standard_tariff" }, "packages": [ { "packageReferenceId": "EXMPL0001234-0-1", "trackingNumber": "EXMPL0001234TRCKNUM", "trackingUrl": "https://www.ups.com/track?track=yes&trackNums=EXMPL0001234TRCKNUM&loc=en_US&requester=ST", "label": { "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf", "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS.pdf", "contentType": "application/pdf" }, "documents": [ { "documentType": "invoice", "fileName": "18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf", "fileUrl": "https://s3-eu-west-1.amazonaws.com/printcloud.storage-test/label/18437f55ec0cd1b64ae6a0eabf03e21b67a57ea1_UPS_invoice.pdf", "contentType": "application/pdf" } ], "totalCost": { "value": 2.56, "currency": "EUR" } } ]}Esempio di risposta di errore
{ "orderReferenceId": "EXMPL0001234", "code": "PUBLIC_API_ERROR", "message": "Processing error", "detail": { "code": "UPS_API_ERROR", "message": { "status": { "title": "Bad Request", "status": 400, "detail": "0 of 1 shipment successfully created.", "statusCode": 400 }, "items": [ { "sstatus": { "title": "Bad Request", "status": 400, "statusCode": 400 }, "validationMessages": [ { "property": "packages[0].items[0].hsCode", "validationMessage": "Parameter hsCode must be between 4 and 11 characters long.", "validationState": "Error" } ] } ] } }, "errors": [ { "code": "IS_BLANK_ERROR", "reference": "receiver.address.country", "message": "This value should not be blank." }, { "code": "IS_BLANK_ERROR", "reference": "receiver.address.city", "message": "This value should not be blank." }, { "code": "MISSING_FIELD_ERROR", "reference": "packages[EXMPL0001234-0-1][length]", "message": "This field is missing." } ]}Richiesta
Parametro | Tipologia | Descrizione |
orderReferenceId (obbligatorio) | string | ID univoco per l'ordine di spedizione. ID fornito da te. |
valuta (obbligatorio) | string | Valuta dell'ordine di spedizione in formato a 3 lettere. |
opzioni (opzionale) | Opzioni | Parametri opzionali. |
partner (opzionale) | Compagno | Dettagli del partner. |
shippingMethod (obbligatorio) | ShippingMethod | Dettagli del metodo di spedizione. |
destinatario (obbligatorio) | Destinatario | Dettagli del destinatario. |
mittente (obbligatorio) | Mittente | Dettagli del mittente. |
pacchetti (obbligatorio) | Pacchetto[] | Dettagli del pacchetto. |
Opzioni
Parametro | Tipologia | Descrizione |
unità di peso (opzionale) | string | Unità di peso. Scelte disponibili: g, kg, oz, lb. Impostazione predefinita: g. |
dimensionUnit (opzionale) | string | Unità di lunghezza. Scelte disponibili: mm, cm, in. Impostazione predefinita: mm. |
etichetta (opzionale) | Etichetta | Impostazioni del formato dell'etichetta. |
Etichetta
Parametro | Tipologia | Descrizione |
Formato (opzionale) | string | Formato dell'etichetta. Scelte disponibili: pdf, zpl (*). Predefinito: pdf. |
Nota: formati diversi dal PDF potrebbero non essere abilitati per alcuni corrieri.
Compagno
Parametro | Tipologia | Descrizione |
Nome del cliente (opzionale) | string | Profilo cliente per la spedizione. |
ShippingMethod
Parametro | Tipologia | Descrizione |
uid (opzionale*) | string | Da utilizzare per un metodo di spedizione specifico, ad esempio amazon_shipping_24. |
corriere (opzionale) | string | Nome del corriere di spedizione, ad esempio Amazon, DHL |
livello (obbligatorio*) | string | Livello dell'opzione di spedizione. Scelte disponibili: standard, express. |
Nota: *Utilizza tier per la selezione ottimizzata del corriere di Gelato. Se utilizzi tier, lascia vuoto uid e viceversa.
Ricevitore
Parametro | Tipologia | Descrizione |
persona (obbligatorio) | ReceiverPerson | Dati personali del destinatario. |
indirizzo (obbligatorio) | Indirizzo | Dettagli dell'indirizzo del destinatario. |
Personalizzazioni (opzionale) | Dogana del destinatario | Dettagli doganali del destinatario. |
Mittente
Parametro | Tipologia | Descrizione |
persona (obbligatorio) | MittentePersona | Dati personali del mittente. |
indirizzo (obbligatorio) | Indirizzo | Dettagli dell'indirizzo del mittente. |
Dogana (necessaria per la spedizione internazionale) | MittenteDogana | Dettagli doganali del mittente. |
ReceiverPerson
Parametro | Tipologia | Descrizione |
Nome (obbligatorio) | string | Nome della persona destinataria. |
Cognome (obbligatorio) | string | Cognome della persona destinataria. |
azienda (opzionale) | string | Il titolo dell'azienda. |
email (opzionale*) | string | Indirizzo e-mail della persona. Può essere utilizzato per le notifiche di spedizione. |
telefono (opzionale*) | string | Numero di telefono della persona. Può essere utilizzato per le notifiche di spedizione. |
Nota: *Email e telefono possono essere campi obbligatori a seconda del corriere scelto
MittentePersona
Parametro | Tipologia | Descrizione |
Nome (opzionale) | string | Nome della persona mittente. |
Cognome (opzionale) | string | Cognome della persona mittente. |
azienda (obbligatorio) | string | Il titolo dell'azienda mittente. |
email (opzionale*) | string | Indirizzo e-mail della persona/azienda mittente. |
telefono (opzionale*) | string | Numero di telefono della persona/azienda mittente. |
Nota: *Email e telefono possono essere campi obbligatori a seconda del corriere scelto
Indirizzo
Parametro | Tipologia | Descrizione |
paese (obbligatorio) | string | Codice paese in formato a 2 lettere. |
Stato (opzionale*) | string | Stato/contea/regione. |
città (obbligatorio) | string | Città. |
codice postale (obbligatorio) | string | Codice postale. |
addressLine1 (obbligatorio) | string | Prima riga dell'indirizzo postale. Dovrebbe includere via e numero civico. |
addressLine2 (opzionale) | string | Seconda riga dell'indirizzo postale. Numero di appartamento/ufficio/piano. |
addressLine3 (opzionale) | string | Terza riga dell'indirizzo postale. |
via (opzionale*) | string | Via (obbligatorio per indirizzi in Germania). |
Numero civico (opzionale*) | string | Numero civico (obbligatorio per indirizzi in Germania). |
sobborgo (opzionale*) | string | Sobborgo (obbligatorio per indirizzi AU/NZ). |
Nota: *Questi campi opzionali sono obbligatori per alcuni Paesi e corrieri.
DoganaDestinatario
Parametro | Tipologia | Descrizione |
Partita IVA (opzionale) | string | Numero di partita IVA del destinatario. |
MittenteDogana
Parametro | Tipologia | Descrizione |
Partita IVA (opzionale*) | string | Numero di partita IVA del mittente. |
iossNumber (opzionale*) | string | Numero IOSS del mittente. |
Numero EORI (opzionale*) | string | Numero EORI del mittente. |
pcccNumber (opzionale*) | string | Numero PCCC del mittente. |
australianBusinessNumber (opzionale*) | string | Numero aziendale australiano del mittente. |
Nota: *A seconda del paese di invio e di ricezione, questi campi possono essere obbligatori.
Pacchetto
Parametro | Tipologia | Descrizione |
packageReferenceId (obbligatorio) | string | ID del pacco fornito dal partner. |
Peso lordo (obbligatorio) | numero | Peso dell'imballaggio + peso degli articoli (in grammi per impostazione predefinita). |
Peso netto (opzionale) | numero | Peso degli articoli (in grammi per impostazione predefinita). |
Lunghezza (obbligatorio) | numero | Lunghezza del pacco (in mm per impostazione predefinita). |
larghezza (obbligatorio) | numero | Larghezza della confezione (in mm per impostazione predefinita). |
altezza (obbligatorio) | numero | Altezza del pacco (in mm per impostazione predefinita). |
volumetricWeight (opzionale) | numero | Peso calcolato in base alle dimensioni del pacco (in grammi per impostazione predefinita). |
Tipo di scatola (opzionale) | string | Forma della scatola (ad esempio: rettangolo, tubo). |
valore (necessario per la spedizione internazionale) | numero | Valore totale di tutti gli articoli nel pacco (nella valuta selezionata). |
articoli (necessari per la spedizione internazionale) | Articolo[] | Elenco degli articoli inclusi nel pacco. |
Articolo*
Parametro | Tipologia | Descrizione |
itemReferenceId (obbligatorio) | string | ID fornito dal partner dell'articolo del pacchetto. |
Descrizione (obbligatorio) | string | Descrizione dell'articolo. |
quantità (obbligatorio) | numero | Quantità dell'articolo. |
valore (obbligatorio) | numero | Valore dell'articolo (nella valuta selezionata). |
peso (obbligatorio) | numero | Peso dell'articolo (in grammi per impostazione predefinita). |
hsCode (obbligatorio) | string | Codice del Sistema Armonizzato (Wiki). |
Paese di origine (obbligatorio) | string | Codice paese in formato a 2 lettere dove è stato prodotto l'articolo. |
Nota: *Tutti i parametri dell'articolo sono richiesti solo per la spedizione internazionale.
Risposta riuscita
Parametro | Tipologia | Descrizione |
orderId | string | ID univoco per l'ordine di spedizione nel nostro sistema. |
ID riferimento ordine | string | ID univoco per l'ordine di spedizione fornito da te. |
Metodo di spedizione | ResponseShippingMethod | Metodo di spedizione utilizzato per l'ordine di spedizione. |
pacchetti | ResponsePackage[] | Imballaggi utilizzati per l'ordine di spedizione. |
ResponseShippingMethod
Parametro | Tipologia | Descrizione |
corriere | string | Corriere utilizzato per creare un ordine. |
uid | string | UID del metodo di spedizione utilizzato per creare un ordine. |
ResponsePackage
Parametro | Tipologia | Descrizione |
packageReferenceId | string | ID del pacco fornito dal partner. |
Numero di tracciamento | string | Numero di tracking fornito dal corriere. |
trackingUrl | string | URL di tracciamento fornito dal corriere. |
etichetta | Etichetta | Etichetta di spedizione per l'ordine di spedizione. |
Documenti (opzionale) | ResponseDocument[] | Documenti per l'ordine di spedizione. |
totalCost (opzionale) | ResponseTotalCost | Costo stimato per la spedizione del pacco. |
Etichetta di risposta
Parametro | Tipologia | Descrizione |
fileName | string | Nome del file dell'etichetta. |
fileUrl | string | URL per scaricare l'etichetta. |
Tipo di contenuto | string | Tipo di contenuto dell'etichetta. |
ResponseDocument
Parametro | Tipologia | Descrizione |
documentType | string | Tipo di documento (ad es. fattura). |
fileName | string | Nome del file del documento. |
fileUrl | string | URL per scaricare il documento. |
Tipo di contenuto | string | Tipo di contenuto del documento. |
ResponseTotalCost
Parametro | Tipologia | Descrizione |
valore (opzionale) | numero | Costo stimato della spedizione del pacco. (opzionale) |
valuta (opzionale) | string | Valuta |
Risposta di errore
Parametro | Tipologia | Descrizione |
ID riferimento ordine | string | ID univoco per l'ordine di spedizione fornito da te. |
codice | string | Codice di errore. |
messaggio | string | Messaggio di errore. |
dettaglio (opzionale) | oggetto | Messaggio di errore dettagliato (oggetto JSON di una struttura arbitraria ). |
errori (opzionale) | ResponseErrorDetails[] | Elenco di errori. |
ResponseErrorDetails
Parametro | Tipologia | Descrizione |
codice | string | Codice di errore. |
messaggio | string | Messaggio di errore |
riferimento (opzionale) | string | ID di riferimento. |
Passaggio successivo: 🔗[GCL] API di logistica - Creazione di una bozza di ordine di spedizione
📝 Non era quello che cercavi?
Aiutaci a migliorare questo articolo, inviaci un'email a [email protected] — ricordati di includere il titolo dell'articolo.