Endpoints
Richiesta di preventivi di spedizione
POST | https://api.iglobalstores.com/2.0/shipping-quotes - Crea una nuova richiesta per preventivi di spedizione su articoli nel carrello della spesa che includono dazi e tasse di importazione più informazioni sulla verifica delle restrizioni degli articoli.
Richiesta HTTPS
| Campo | Note |
|---|---|
| Metodo HTTP | POST |
| URL dell'endpoint | https://api.iglobalstores.com/2.0/shipping-quotes |
| Protocollo | HTTPS |
| Formato messaggio | JSON |
| Intestazione HTTP di accettazione | Accept: application/json |
| Intestazione HTTP del token di sicurezza | serviceToken: your-test-token-valueAggiungi un'intestazione alla tua richiesta HTTPS chiamata serviceToken con un valore del tuo Test Security API Token. (Contatta il tuo Account Manager per questo token) |
| Intestazione HTTP Content-Type | Content-Type: application/jsonPoiché invierai dati JSON al servizio, aggiungi un'intestazione alla tua richiesta HTTPS chiamata Content-Type con un valore di application/json |
Coppie CHIAVE/VALORE JSON nel corpo della richiesta
Formato messaggio: JSON
Esempio di richiesta
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
"boxCount": null,
"items": [
{
"cartItemId": 1,
"detailedDescription": "description including options, material content, etc",
"category": "sunglasses",
"productId": "17898-675234",
"sku": "oakley-123",
"unitPrice": 199.0,
"quantity": 1,
"length": 2.5,
"width": 6.5,
"height": 2.5,
"dimensionalUnits": null,
"weight": 4,
"weightUnits": "OZ",
"hsCode": null,
"brandName": "Oakley",
"countryOfOrigin": "CN"
},
{
"cartItemId": 2,
"detailedDescription": "description including options, material content, etc",
"category": "sunglasses",
"productId": "17898-675235",
"sku": "oakley-125",
"unitPrice": 179.0,
"quantity": 1,
"length": 2.5,
"width": 6.5,
"height": 2.5,
"dimensionalUnits": null,
"weight": 4,
"weightUnits": "OZ",
"hsCode": null,
"brandName": "Oakley",
"countryOfOrigin": "CN"
}
],
"shippingAmountOverride": null,
"shipFromAddress": null,
"shipToAddress": {
"name": "John Doe",
"address1": "123 S West Elm St",
"address2": null,
"address3": null,
"city": "Calgary",
"state": "Alberta",
"stateCode": "AB",
"postalCode": "T2P 5G8",
"countryCode": "CA"
}
}
Definizioni JSON della richiesta
| Campo | Note |
|---|---|
boxCount | Questo campo descrive le scatole che verranno utilizzate per spedire l'ordine. Non ci si aspetta che un commerciante conosca questo al momento dell'ordine; tuttavia, se è noto, può essere passato nel seguente formato specifico. Esempio di valore: 22x15x15(1),8x8x4(2),32x22x14(1) Formato: Elenco separato da virgole delle dimensioni delle scatole e del conteggio. Nell'esempio sopra, ci sono un totale di 4 scatole. La prima scatola nell'elenco sarà lunga 22 pollici, larga 15 pollici e alta 15 pollici. Ci sarà solo una scatola utilizzata per quella dimensione. Ci saranno due scatole di dimensione 8x8x4 pollici. È accettabile passare la stessa dimensione della scatola più volte se è facile per te, come questo: “22x15x15(1),22x15x15(1)”, il che significa 2 scatole di dimensione 22x15x15 pollici. |
items OBBLIGATORIO | Un elenco di mappe di articoli |
items[index].brandName | Il nome del marchio dell'articolo specifico aiuterà il nostro motore di regole a determinare al meglio se si applica una restrizione all'articolo per il paese di destinazione. Anche se il nome del marchio di un articolo corrisponde o meno testualmente a una restrizione specifica, il nostro motore di regole utilizzerà lo SKU dell'articolo e/o productId per decidere meglio se l'articolo è effettivamente soggetto a restrizioni nel paese di destinazione. Si prega di inviare il nome del marchio se disponibile. Esempi di valori: “Oakley” o “Nike” o null |
items[index].cartItemId OBBLIGATORIO | Questo campo è necessario per identificare l'articolo, specificamente all'interno dell'elenco degli articoli. Può essere semplice come un valore di indice. Utilizzeremo questo cartItemId per identificare un articolo se è soggetto a restrizioni nella risposta JSON. Quindi assicurati di poter identificare lo stesso articolo nel tuo carrello tramite questo cartItemId che ci stai passando. Esempi di valori: 1 o 2 o 3 |
items[index].category | Le categorie di prodotto - il prodotto specifico di cui fa parte. La categoria aiuterà il nostro motore di regole a determinare al meglio se si applica una restrizione all'articolo per il paese di destinazione. Anche se la categoria di un articolo corrisponde o meno testualmente a una restrizione specifica, il nostro motore di regole utilizzerà lo SKU dell'articolo e/o productId per decidere meglio se l'articolo è effettivamente soggetto a restrizioni nel paese di destinazione. Formato: Un elenco separato da pipe dei nomi delle categorie. Ogni nome di categoria può essere composto da una o più parole. Se un articolo esiste in più di una categoria, si prega di elencarle entrambe separate da un carattere pipe “”. Esempi: valori “Occhiali da sole” o “Accessori da seraBorse” |
items[index].countryOfOrigin | Il paese di origine è il paese in cui l'articolo è stato realizzato o da cui proviene originariamente. Il paese di origine aiuterà il nostro motore di regole a determinare al meglio se si applica una restrizione all'articolo per il paese di destinazione. Alcuni paesi non consentono specifici tipi di beni provenienti da altri paesi specifici. Valori di esempio: “CN” per la Cina o “US” per gli Stati Uniti o null |
items[index].detailedDescription REQUIRED | Questo campo è semplicemente testo, ma dovrebbe includere quante più informazioni possibili sull'articolo acquistato. Ad esempio, il nome completo e il codice articolo se applicabile, il colore o altre opzioni selezionate, il contenuto del materiale e qualsiasi testo descrittivo che hai per l'articolo. Ci sono molti diversi tipi di restrizioni all'importazione nei paesi esteri, come le scarpe in pelle in Italia. A volte, l'unico modo per catturare questi articoli soggetti a restrizioni è attraverso il detailedDescription. Nota: Anche se il detailedDescription di un articolo corrisponde o meno testualmente a una restrizione specifica, il nostro motore di regole utilizzerà lo SKU dell'articolo e/o il productId per decidere meglio se l'articolo è effettivamente soggetto a restrizioni nel paese di destinazione. Per i migliori risultati, si prega di inviare quante più informazioni possibili nel campo detailedDescription. Valore di esempio: “Tory Burch, Robinson – Tote con doppia zip, colore: New Carnival, contenuto del materiale: pelle, La pelle ricca di colore conferisce un fascino accattivante a una tote ben strutturata, rifinita con hardware logo e manici arrotolati per un aspetto completamente sofisticato. Chiusura a scatto magnetico con scomparti a doppia zip. Tasche interne con zip, a parete e per cellulare. Piedini protettivi in metallo. Pelle. Di Tory Burch; importato.” |
items[index].height | Questa è l'altezza del tuo articolo. C'è un altro campo chiamato dimensionalUnits, in cui specificare pollici o centimetri per questa misura. Si prega di fornire senza virgole e con non più di due decimali. Valore di esempio: 25.5 Le tue tariffe di spedizione saranno le più accurate se fornisci questo campo. |
items[index].hsCode | Questo è il codice HS che identifica l'articolo nei paesi esteri. Passare l'hsCode aiuterà a identificare correttamente il giusto dazio all'importazione rate per l'articolo specifico. Non è richiesto se non disponibile – ci occuperemo noi se non lo hai. Formato: codice di 10 o 6 cifre; può includere i caratteri separatori “.” oppure no. Valori di esempio: “20.4560.0000” o “20.4560” o “204560” (sono accettabili codici di 10 o 6 cifre) |
items[index].length | Questa è la lunghezza del tuo articolo. C'è un altro campo chiamato dimensionalUnits, in cui specificare pollici o centimetri per questa misura. Si prega di fornire senza virgole e con non più di due decimali. Valore di esempio: 25.5 Le tue tariffe di spedizione saranno le più accurate se fornisci questo campo. |
items[index].productId | Questo è il tuo ID prodotto per l'articolo specifico. Il nostro motore di regole utilizzerà questo valore come ID per collegare le informazioni apprese sull'articolo al tuo articolo. Valore di esempio: “17898-675235” Si prega di fornire almeno il productID o lo SKU. È preferibile fornire entrambi. |
items[index].quantity REQUIRED | Questa è la quantità acquistata per l'articolo specifico. Si prega di fornire come intero positivo, senza virgole e senza decimali. Valori di esempio: 1 o 9999 (preferiamo che tu venda più articoli che meno!) |
items[index].sku | Questo è il tuo SKU per l'articolo specifico. Il nostro motore di regole utilizzerà questo valore come ID per collegare le informazioni apprese sull'articolo al tuo articolo. Valore di esempio: “oakley-125” Si prega di fornire almeno il productId o lo SKU. È preferibile fornire entrambi. |
items[index].unitPrice REQUIRED | Questo è il prezzo unitario del tuo articolo in USD (dollari statunitensi). Si prega di fornire senza virgole, senza il simbolo del dollaro “$”, e con due decimali. Valore di esempio: 2102.99 |
items[index].weight | Questo è il peso del tuo articolo. C'è un altro campo chiamato weightUnits, dove specifichi libbre, once, grammi o chilogrammi per questa misurazione. Si prega di fornire senza virgole e con non più di due decimali. Esempio di valore: 4.2 Le tue tariffe di spedizione saranno le più accurate se fornisci questo campo. |
items[index].weightUnits | Predefinito su “LB” per libbre. L'unità di misura per il valore del peso. Se impostato su null, si assumerà “LB” (libbre). Esempi di valori: “LB” per libbre o “OZ” per once o “G” per grammi o “KG” per chilogrammi o null |
items[index].width | Questa è la larghezza del tuo articolo. C'è un altro campo chiamato dimensionalUnits, dove specifichi pollici o centimetri per questa misurazione. Si prega di fornire senza virgole e con non più di due decimali. Esempio di valore: 25.5 Le tue tariffe di spedizione saranno le più accurate se fornisci questo campo. |
shipFromAddress | Se passato come null, utilizzeremo un shipFromAddress predefinito associato al tuo account commerciante. Questo è l'indirizzo da cui verrà spedito l'ordine, cioè il tuo magazzino. Questo è una mappa contenente i seguenti campi di indirizzo: address1, address2, address3, city, state, stateCode, postalCode, countryCode. Questi campi contenuti sono richiesti o meno, a seconda del paese. L'endpoint di localizzazione restituisce quali specifici campi di indirizzo sono richiesti o meno per ciascun paese. Nota: stateCode non è mai richiesto e non è dichiarato nell'endpoint di localizzazione. Puoi passare stateCode, se disponibile. |
shippingAmountOverride | Questo è utilizzato solo se conosci il costo di spedizione prima di chiamare l'API. È in USD (dollari statunitensi). Si prega di fornire senza virgole, senza il simbolo del dollaro “$”, e con due decimali. Questa funzionalità non funzionerà senza impostarla con un rappresentante Zonos. Esempio di valore: 212.99 |
shipToAddress RICHIESTO | Questo è l'indirizzo a cui verrà spedito l'ordine. Questa è una mappa contenente i seguenti campi di indirizzo: name, address1, address2, address3, city, state, stateCode, postalCode, countryCode. Questi campi contenuti sono richiesti o meno a seconda del paese. L'endpoint di localizzazione restituisce quali specifici campi di indirizzo sono richiesti per ciascun paese. Nota: name e stateCode non sono mai richiesti e non sono dichiarati nell'endpoint di localizzazione. Puoi passare name e/o stateCode, se disponibile. |
HTTPS response
Formato del messaggio: JSON
Esempio di risposta solo per Canada e Australia
Nota: Le risposte effettive conterranno tutti i paesi supportati.
Esempio di richiesta
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
"shippingQuotes": [
{
"id": "bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a",
"carrier": "UPS",
"conversionRate": 1.32,
"currencyCode": "CAD",
"displayName": "Express Air 2-4 Day Delivery",
"duty": 10.2,
"dutyTaxBrokerageFee": 5.0,
"dutyTaxCarrierPrepaymentFee": 5.0,
"dutyTaxEnabled": true,
"dutyTaxForced": false,
"dutyTaxTotal": 29.38,
"dutyTaxUnderDeminimus": false,
"restrictedItems": [
{
"cartItemId": 1,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
},
{
"cartItemId": 2,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
}
],
"shippingTotal": 23.62,
"taxOrVat": 9.18
},
{
"id": "80c57724-ab4e-4997-8477-08b668fef103",
"carrier": "USPS",
"conversionRate": 1.32,
"currencyCode": "CAD",
"displayName": "Post 5-10 Day Delivery",
"duty": 9.2,
"dutyTaxBrokerageFee": 5.0,
"dutyTaxCarrierPrepaymentFee": 5.0,
"dutyTaxEnabled": true,
"dutyTaxForced": false,
"dutyTaxTotal": 27.38,
"dutyTaxUnderDeminimus": false,
"restrictedItems": [
{
"cartItemId": 1,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
},
{
"cartItemId": 2,
"message": "We are unable to sell Oakley products to your country.",
"reasonCode": "BRAND_COUNTRY"
}
],
"shippingTotal": 13.62,
"taxOrVat": 8.18
}
]
}
Definizioni JSON di risposta
| Campo | Note |
|---|---|
shippingQuotes | Questa è un elenco di mappe di preventivi di spedizione. |
shippingQuotes[index].carrier | Il vettore specifico per il quale è valido il preventivo di spedizione. Impostato su null solo se il commerciante ha richiesto di avere profili di spedizione generici, non specifici per un vettore. I preventivi di spedizione non devono essere specifici per un vettore; ma possono esserlo. Contatta il tuo Account Manager per assistenza nella configurazione dei profili di spedizione. Esempi di valori: UPS o FEDEX o DHL o USPS o CAPOST o null |
shippingQuotes[index].displayName | Nome visualizzato per l'opzione di spedizione, adatto per essere mostrato all'acquirente. Questi valori sono personalizzabili per il commerciante. Contatta il tuo Account Manager per farlo. Esempio di valore: “Consegna aerea espressa 2-4 giorni” |
shippingQuotes[index].duty | L'importo dei dazi doganali inclusi nel dutyTaxTotal. Questo importo è in USD, non conterrà virgole e avrà due decimali. Esempio di valore: 8.29 |
shippingQuotes[index] .dutyTaxBrokerageFee | Questo è ciò che il broker di importazione estero ti addebiterà per elaborare i tuoi dazi e tasse di importazione. Questo importo è incluso nel dutyTaxTotal. L'importo è in USD, non conterrà virgole e avrà due decimali. Esempio di valore: 5.00 |
shippingQuotes[index] .duyTaxCarrierPrepaymentFee | Questo è ciò che il vettore ti addebiterà per prepay i dazi e le tasse al paese di importazione. Questo importo è incluso nel dutyTaxTotal. Questo importo è in USD, non conterrà virgole e avrà due decimali. Esempio di valore: 5.00 |
shippingQuotes[index] .duyTaxEnabled | Se questo preventivo di spedizione consente all'acquirente di prepay i propri dazi e tasse di importazione. Se impostato su false, il dutyTaxTotal deve essere ignorato. Esempi di valori: true o false |
shippingQuotes[index] .duyTaxForced | Se questo preventivo di spedizione costringe l'acquirente a prepay i propri dazi e tasse di importazione. Se impostato su true, dovresti includere il dutyTaxTotal nell'ordine, spiegando all'acquirente che è richiesto con questa specifica opzione di spedizione. Se impostato su false, puoi consentire all'acquirente di scegliere se desidera prepay i propri dazi e tasse di importazione. Esempi di valori: true o false |
shippingQuotes[index].dutyTaxTotal | Il costo totale di dazi e tasse per il preventivo di spedizione fornito. Dazi e tasse possono essere opzionali, non disponibili o obbligatori per il preventivo di spedizione fornito. Questo importo non è incluso nel shippingTotal. Questo importo è in USD, non conterrà virgole e avrà due decimali. Esempio di valore: 19.55 |
shippingQuotes[index] .dutyTaxUnderDeMinimis | Se il totale dell'ordine, utilizzando questa specifica opzione di spedizione, è al di sotto sia dell'importo de minimis per le tasse/IVA che dell'importo de minimis per i dazi. Se impostato su true, il dutyTaxTotal sarà impostato su 0.00, e dovresti informare il cliente che non ci saranno dazi o tasse di importazione dovuti sul loro ordine. Inoltre, forzare il pagamento anticipato di dazi e tasse, poiché il costo è 0.00. |
shippingQuotes[index].id | Un identificatore per il preventivo di spedizione specifico; un UUID di 36 caratteri. Esempio di valore: bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a |
shippingQuotes[index].restrictedItems | Questa è un elenco di mappe, contenente dettagli su eventuali articoli nel carrello che sono limitati utilizzando questa specifica offerta di spedizione. Ogni articolo limitato ha un reasonCode. Il motivo può essere specifico o meno per l'opzione di spedizione. Alcuni motivi per le restrizioni sugli articoli sono dovuti alle leggi sull'importazione del paese, alle restrizioni del marchio o persino alle regole create dal commerciante. Ogni volta che un'opzione di spedizione viene scelta dallo shopper, gli articoli del carrello devono essere confrontati con l'elenco restrictedItems dell'offerta di spedizione. Se uno degli articoli del carrello è limitato, un messaggio deve essere visualizzato allo shopper e l'articolo/i limitato/i devono essere rimossi dal totale dell'ordine, ecc. |
shippingQuotes[index] .restrictedItems[index].cartItemId | Questo è il cartItemId dalla richiesta JSON di un articolo limitato nel carrello. Dovresti essere in grado di collegare questo cartItemId a un articolo specifico nel carrello del tuo shopper. Esempi di valori: 1 o 2 o 3 |
shippingQuotes[index] .restrictedItems[index].message | Questo è un messaggio che può essere visualizzato allo shopper riguardo al motivo per cui l'articolo è limitato. Questi messaggi sono personalizzabili dal commerciante. Si prega di contattare il tuo rappresentante Zonos per ulteriori dettagli. Esempio di valore: “Non possiamo vendere prodotti Oakley al tuo paese.” |
shippingQuotes[index] .restrictedItems[index].reasonCode | Questo è il codice di motivo per cui l'articolo è limitato. Le restrizioni sono sempre specifiche per il paese e i nostri codici di motivo lo rendono ovvio. Esempi di valori: BRAND_COUNTRY o IMPORT_COUNTRY o EXPORT_COUNTRY o CARRIER_COUNTRY o MERCHANT_COUNTRY. BRAND_COUNTRY significa che hai specificato che non puoi vendere un marchio a un insieme specifico di paesi. IMPORT_COUNTRY significa che il paese importatore non permetterà l'importazione dell'articolo. EXPORT_COUNTRY significa che il paese esportatore (di solito gli Stati Uniti) non permetterà l'esportazione dell'articolo. CARRIER_COUNTRY significa che il vettore specifico non porterà l'articolo. MERCHANT_COUNTRY significa che hai impostato una regola di restrizione personalizzata che l'articolo ha attivato. |
shippingQuotes[index] .shippingTotal | Il costo totale della spedizione per la data offerta di spedizione. Le offerte di spedizione possono anche avere un importo dutyTaxTotal, che non è incluso in questo shippingTotal. Questo importo è in USD, non conterrà virgole e conterrà due decimali. Esempio di valore: 25.82 |
shippingQuotes[index].taxOrVat | L'importo della tassa o dell'IVA inclusa nel dutyTaxTotal. Per alcuni paesi, si tratta di una tassa; per altri, è un'IVA. Questo importo è in USD, non conterrà virgole e conterrà due decimali. Esempio di valore: 4.35 |
API Legacy Landed Cost
Scopri come funziona l'API Legacy Landed Cost.Le informazioni di seguito sono per la nostra API Legacy Landed Cost. Vedi la nostra API Landed Cost per l'ultima versione.
L'endpoint shipping-quotes accetta dettagli sul carrello del tuo acquirente, restituisce preventivi di spedizione completi di dazi e tasse di importazione e verifica gli articoli per eventuali restrizioni. Questi preventivi di spedizione restituiti si basano su profili di spedizione che sono stati impostati prima dell'uso di questo endpoint API.
Abbiamo profili di spedizione predefiniti per scopi di test, ma dovrai lavorare con il tuo Account Manager per impostare i profili di spedizione e le impostazioni reali che la tua azienda desidera utilizzare.