DOCS

Calcola landed cost - GraphQL

Landed Cost•
HomePer i fornitori di logistica Landed Cost Calcola landed cost - GraphQL

Calcola un landed cost

Calcola dazi, tasse e commissioni con GraphQL.

GraphQL

Zonos calcola il totale del landed cost per spedizioni internazionali, inclusi dazi, tasse e eventuali commissioni aggiuntive addebitate da dogane, broker o vettori. Nella maggior parte dei casi, garantiamo questi calcoli pagando noi stessi la bolletta finale e addebitandoti esattamente quanto abbiamo calcolato. In alcuni casi, puoi utilizzare il nostro landed cost senza garanzia, il che significa che ti assumi la responsabilità per qualsiasi differenza tra il nostro calcolo e le spese effettive.

Prepara la richiesta 

Calcolare un landed cost tramite API richiede diversi input, che abbiamo organizzato in flussi di lavoro. Una volta completato, sarai in grado di effettuare una singola richiesta per restituire un landed cost basato sulla destinazione di spedizione, sugli articoli nel carrello e sui dettagli di spedizione.

Ogni flusso di lavoro ha i propri input richiesti. GraphQL ti consente di passare più dati del necessario, ma solo alcuni campi sono richiesti per restituire un landed cost. Questi sono chiaramente contrassegnati nella nostra riferimento API per vedere tutti i campi possibili.

Nota che alcuni campi sono richiesti in modo condizionale se desideri che il tuo calcolo sia garantito.

Di seguito, abbiamo delineato tutti i campi richiesti per calcolare un landed cost garantito. Assicurati che queste informazioni siano incluse prima di effettuare la tua richiesta.

Input richiesti per calcoli garantiti

partyCreateWorkflowInput

Il partyCreateWorkflowInput identifica le parti coinvolte e le loro posizioni. Visualizza lo schema completo nella nostra API GraphQL riferimento. I campi richiesti sono:

  • location
    • administrativeAreaCode: Il codice dello stato o della provincia, in due lettere. Richiesto solo per CA e BR.
    • countryCode: Il codice ISO a due lettere del paese.
    • line1: La prima riga dell'indirizzo.
    • postalCode: Il codice postale o il CAP dell'indirizzo.
  • person
    • email: L'indirizzo email della persona.
    • firstName: Il nome della persona.
    • lastName: Il cognome della persona.
    • phone: Il numero di telefono della persona.
  • type
    • DESTINATION: Le informazioni su location & person per la destinazione di spedizione.
    • ORIGIN: Le informazioni su location per l'origine della spedizione. La person associata all'origine della spedizione non è richiesta.
itemCreateWorkflowInput

Il itemCreateWorkflowInput elenca gli articoli nel carrello. Ci sono molti campi opzionali (vedi tutte le possibilità nella nostra riferimento API), ma i campi di seguito sono richiesti.

  • amount: Il valore di un'unità singola del prodotto spedito, prima di essere moltiplicato per la quantità. Nota che questo differisce dalla definizione postale di un articolo postale. Se la quantity dell'articolo è 1, questo è il costo totale dell'articolo. Se la quantity dell'articolo è >1, l'API moltiplicherà l'amount dell'articolo per la quantity dell'articolo per ottenere il totale per la riga dell'articolo. Non inserire il prezzo totale di tutte le unità dell'articolo in amount.
  • currencyCode: Il codice della valuta per l'importo dell'articolo.
  • quantity: La quantità dell'articolo. L'API moltiplicherà l'amount dell'articolo per la quantity dell'articolo per ottenere il totale per la riga dell'articolo.
  • countryOfOrigin: Il paese in cui è stato prodotto l'articolo.
  • Uno dei seguenti (quello impostato come tua preferenza di chiave articolo. La tua chiave articolo collega le informazioni memorizzate nel Catalogo all'articolo nel carrello e viene utilizzata durante la creazione dell'etichetta.)
    • productId: L'ID del prodotto dell'articolo.
    • sku: Lo SKU dell'articolo.

Le measurements (WEIGHT, LENGTH, WIDTH, HEIGHT) sono richieste solo se desideri cartonizzare i tuoi articoli quando ottieni una valutazione di spedizione.

cartonsCreateWorkflowInput

Il cartonsCreateWorkflowInput richiede solo l'input stesso. Visualizza lo schema completo nella nostra API GraphQL riferimento per vedere tutti i valori che possono essere passati. È importante passare le dimensioni e il peso del cartone se Zonos sta calcolando il costo di spedizione.

shipmentRatingCreateWorkflowInput

Questo flusso di lavoro viene utilizzato quando conosci già il servizio di spedizione e il costo; se desideri che Zonos calcoli questi costi per i servizi che hai abilitato, sostituisci questo flusso di lavoro e utilizza invece il shipmentRatingCalculateWorkflow.

Il shipmentRatingCreateWorkflowInput comunica il costo di spedizione. Visualizza lo schema completo nella nostra API GraphQL riferimento. I campi richiesti sono:

  • amount: Il costo di spedizione.
  • currencyCode: Il codice della valuta del costo di spedizione.
  • serviceLevelCode: Il codice che indica il livello di servizio di spedizione utilizzato nella valutazione della spedizione.
landedCostWorkFlowInput

Il landedCostWorkFlowInput determina le preferenze per il calcolo del landed cost. Visualizza lo schema completo nella nostra API GraphQL riferimento. I campi richiesti sono:

  • calculationMethod: Indica la tua preferenza per come intendi spedire: DDP (dazi e tasse prepagati) o DAP (i dazi e le tasse sono pagati alla consegna, o se si applica uno schema di rimborso, vengono rimborsati tramite un codice fiscale).
    • Se utilizzi la nostra garanzia di landed cost, questo valore dovrebbe sempre essere DDP_PREFERRED, che fornirà un preventivo DDP quando possibile e un preventivo DAP se un DDP non è consentito. Utilizzare invece DAP potrebbe comportare che i costi di sbarco non siano più garantiti, poiché ciò comporta tipicamente dazi e tasse pagati alla consegna.
  • endUse: Indica se le merci vengono vendute a un'altra azienda (FOR_RESALE) o per uso finale con un consumatore (NOT_FOR_RESALE).
  • tariffRate: Indica il metodo che Zonos dovrebbe utilizzare per calcolare le tariffe doganali per questo preventivo, nel caso ci sia un intervallo di tariffe doganali che potrebbero essere applicate. *Quando utilizzi la nostra garanzia di landed cost, questo dovrebbe sempre essere ZONOS_PREFERRED.

Aggiungi spedizione calcolata: Se desideri che Zonos calcoli il costo di spedizione per te, sostituisci il shipmentRatingCreateWorkflow con il shipmentRatingCalculateWorkflow. Aggiungi il cartonizeWorkflow se desideri che Zonos ordini i tuoi articoli in cartoni prima di trovare il costo di spedizione (utilizzato per peso dimensionale).

Codice HS e opzioni di spedizione

GraphQL ti offre la flessibilità di personalizzare la richiesta secondo le tue preferenze. Ci sono un paio di opzioni su come includere codici HS e costi di spedizione nella richiesta.

Codici HS

I codici HS influenzano le tariffe doganali e sono quindi richiesti. Puoi passare il codice HS per ciascun articolo o lasciare che Classify li generi.

Passa i codici HS per ciascun articolo

Zonos raccomanda vivamente di utilizzare codici HS specifici per prodotto poiché ciò porta a una quotazione di landed cost più accurata. Se conosci i tuoi codici HS, passa il hsCode per ciascun item durante il itemCreateWorkflow.

Se passi un codice HS, Zonos lo convaliderà al volo quando richiedi una quotazione di landed cost. Se il codice HS fornito è non valido (significa che non esiste), Zonos ri-classify il tuo articolo al volo e utilizzerà il nuovo codice HS valido invece di quello fornito.

Se hai bisogno di aiuto per generare codici HS per i tuoi prodotti, scopri di più su Zonos Classify e come richiedere una classificazione.

Genera codici HS con Classify

Se non passi a Zonos un hsCode, controlleremo prima il Zonos Catalog per vedere se hai un codice HS memorizzato per il tuo articolo. Se non ce l'hai, chiameremo Classify per generare una classificazione per alimentare il tuo calcolo di landed cost basato sui seguenti campi di dettaglio del prodotto nel itemCreateWorkflow: description, category e material. Se i campi di dettaglio del tuo prodotto non sono sufficientemente dettagliati per generare una classificazione basata sul punteggio di fiducia di Classify's, verrà utilizzato il codice HS predefinito assegnato al tuo negozio.

Costo di spedizione

Sia il livello di servizio di spedizione che il suo costo influenzano i dazi, le tasse e le spese e sono quindi richiesti. Zonos può calcolare la spedizione o puoi passarci queste informazioni.

Calcola la spedizione

Per far calcolare a Zonos i costi di spedizione, utilizza il shipmentRatingCalculateWorkflow. Le opzioni di spedizione restituite nella risposta di spedizione calcolata corrisponderanno ai serviceLevels che hai assegnato ai profili di spedizione nel Dashboard.

Risoluzione dei problemi: Se ti aspetti un serviceLevel nella risposta ma non appare, assicurati che il serviceLevel sia abilitato e sia supportato dal method che hai selezionato.

Aggiungi il cartonizeWorkflow (che non ha input) se desideri che Zonos ordini i tuoi articoli in cartoni prima di trovare il costo di spedizione (utilizzato per peso dimensionale.

Passa i costi di spedizione

Se conosci il serviceLevel e l'amount per una spedizione, puoi passarli nella porzione shipmentRatingCreateWorkflow della richiesta. Utilizzeremo quei valori per calcolare eventuali spese associate al corriere e restituirli nella risposta.

Richiedi un landed cost tramite API 

Una volta che hai i dati di input richiesti, invia la mutazione GraphQL all'endpoint API utilizzando la libreria o lo strumento client scelto. Ecco alcuni esempi di come puoi strutturare la mutazione.

Utilizza questa richiesta quando stai facendo calcolare a Zonos il costo di spedizione come parte della richiesta di Landed Cost. Calcoleremo quindi dazi e tasse sulla spedizione se sono valutati dal paese di destinazione.

Mutazione

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
mutation CalculateLandedCost(
  $parties: [PartyCreateWorkflowInput!]!
  $items: [ItemCreateWorkflowInput!]!
  $landedCostConfig: LandedCostWorkFlowInput!
) {
  partyCreateWorkflow(input: $parties) {
    type
    id
    organization
  }
  itemCreateWorkflow(input: $items) {
    id
    amount
    productId
  }
  cartonizeWorkflow {
    id
    type
    items {
      item {
        id
      }
    }
  }
  shipmentRatingCalculateWorkflow {
    id
    amount
  }
  landedCostCalculateWorkflow(input: $landedCostConfig) {
    id
    duties {
      amount
      currency
      note
    }
    taxes {
      amount
      currency
      note
    }
    fees {
      amount
      currency
      note
    }
  }
}

Variabili

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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
{
  "parties": [
    {
      "location": {
        "administrativeArea": "Utah",
        "administrativeAreaCode": "UT",
        "countryCode": "US",
        "line1": "345 N 2450 E",
        "line2": "#151",
        "locality": "St George",
        "postalCode": "84790"
      },
      "type": "ORIGIN"
    },
    {
      "location": {
        "administrativeArea": "New South Wales",
        "administrativeAreaCode": "NSW",
        "countryCode": "AU",
        "line1": "123 George Street",
        "line2": "Apartment 5B",
        "locality": "Sydney",
        "postalCode": "2000"
      },
      "person": {
        "email": "aussie.customer@gmail.com",
        "firstName": "James",
        "lastName": "Thompson",
        "phone": "+61412345678",
        "companyName": "Sydney Trading Co",
        "metadata": { "key": "customer_type", "value": "premium" }
      },
      "type": "DESTINATION"
    },
    {
      "type": "PAYOR",
      "location": {
        "administrativeArea": "Victoria",
        "administrativeAreaCode": "VIC",
        "countryCode": "AU",
        "latitude": -37.8136,
        "line1": "456 Collins Street",
        "line2": "Suite 12",
        "locality": "Melbourne",
        "longitude": 144.9631,
        "postalCode": "3000"
      },
      "person": {
        "email": "billing@reallysilkstore.com.au",
        "firstName": "Sarah",
        "lastName": "Mitchell",
        "phone": "+61398765432",
        "companyName": "Really Silk Store",
        "metadata": { "key": "billing_contact", "value": "primary" }
      }
    }
  ],
  "items": [
    {
      "amount": 120,
      "currencyCode": "USD",
      "countryOfOrigin": "US",
      "quantity": 1,
      "productId": "productId1",
      "hsCode": null,
      "description": "leather wallet",
      "measurements": [
        { "type": "WIDTH", "value": 1, "unitOfMeasure": "CENTIMETER" },
        { "type": "LENGTH", "value": 2, "unitOfMeasure": "CENTIMETER" },
        { "type": "HEIGHT", "value": 4, "unitOfMeasure": "CENTIMETER" },
        { "type": "WEIGHT", "value": 1, "unitOfMeasure": "POUND" }
      ]
    },
    {
      "amount": 55,
      "currencyCode": "USD",
      "countryOfOrigin": "US",
      "quantity": 1,
      "productId": "productId2",
      "hsCode": "6206.30",
      "description": "t-shirt",
      "measurements": [
        { "type": "WIDTH", "value": 4, "unitOfMeasure": "CENTIMETER" },
        { "type": "LENGTH", "value": 4, "unitOfMeasure": "CENTIMETER" },
        { "type": "HEIGHT", "value": 5, "unitOfMeasure": "CENTIMETER" },
        { "type": "WEIGHT", "value": 1.5, "unitOfMeasure": "POUND" }
      ]
    }
  ],
  "landedCostConfig": {
    "calculationMethod": "DDP_PREFERRED",
    "endUse": "NOT_FOR_RESALE",
    "tariffRate": "ZONOS_PREFERRED"
  }
}

Risposta

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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
{
  "data": {
    "partyCreateWorkflow": [
      {
        "type": "ORIGIN",
        "id": "party_01044774-758f-4021-b8dd-e17d97609647",
        "organization": "organization_1ff864e0-58cf-4efa-9031-e8c323cf4c0e"
      },
      {
        "type": "DESTINATION",
        "id": "party_0m6wgfjmhbnf2",
        "organization": "organization_1ff864e0-58cf-4efa-9031-e8c323cf4c0e"
      },
      {
        "type": "PAYOR",
        "id": "party_0m6wgfjn5bnfh",
        "organization": "organization_1ff864e0-58cf-4efa-9031-e8c323cf4c0e"
      }
    ],
    "itemCreateWorkflow": [
      {
        "id": "item_0m6wgfjpfw9fz",
        "amount": 120,
        "productId": "productId1"
      },
      {
        "id": "item_0m6wgfjpfw9g0",
        "amount": 55,
        "productId": "productId2"
      }
    ],
    "cartonizeWorkflow": [
      {
        "id": "carton_0m6wgfme53aqb",
        "type": "PACKAGE",
        "items": [
          {
            "item": {
              "id": "item_0m6wgfjpfw9g0"
            }
          },
          {
            "item": {
              "id": "item_0m6wgfjpfw9fz"
            }
          }
        ]
      }
    ],
    "shipmentRatingCalculateWorkflow": [
      {
        "id": "shipment_rating_0m6wgfmghvhh1",
        "amount": 24.8864
      }
    ],
    "landedCostCalculateWorkflow": [
      {
        "id": "landed_cost_7730b476-1307-4d14-8f76-3b37bd162054",
        "duties": [],
        "taxes": [
          {
            "amount": 5.5,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 0.7822,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 12,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 1.7065,
            "currency": "USD",
            "note": null
          }
        ],
        "fees": [
          {
            "amount": 0,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 0.8,
            "currency": "USD",
            "note": null
          },
          {
            "amount": 0,
            "currency": "USD",
            "note": null
          }
        ]
      }
    ]
  },
  "errors": []
}

Prossimo passo: Crea un ordine

Dopo aver calcolato un landed cost e ricevuto il landedCostId dalla risposta API, dovresti creare un ordine per finalizzare la transazione nel sistema Zonos. Usa la mutazione orderCreate e passa il landedCostId dal tuo preventivo. Scopri di più su creazione di ordini.

Richiedi un landed cost nel Dashboard 

Puoi anche calcolare i costi di sbarco direttamente nel Zonos Dashboard senza utilizzare l'API. Questo è utile per testare i calcoli, formare il tuo team o ottenere preventivi rapidi per le richieste dei clienti.

Il Dashboard utilizza gli stessi endpoint API descritti sopra, quindi i risultati corrisponderanno a quelli che otterresti da chiamate API dirette. Questo lo rende un ottimo modo per convalidare la tua integrazione API o esplorare come diversi input influenzano i calcoli.

Utilizzo del calcolatore del Dashboard

Con il calcolatore landed cost nel Dashboard, puoi ottenere preventivi con tariffe di spedizione calcolate, creare preventivi con costi di spedizione noti o elaborare più preventivi in blocco.

Usa questo flusso quando conosci il livello di servizio di spedizione e il costo per la tua spedizione.

  1. Vai a Dashboard → Ordini → Preventivi
  2. Clicca su Nuovo preventivo
  3. Opzionale — Modifica la posizione del tuo indirizzo di partenza
  4. Seleziona un Paese di destinazione dal menu a discesa
  5. Inserisci l'importo di spedizione
    • Il livello di servizio è facoltativo; aggiungerlo ci consente di calcolare le spese del vettore applicabili
  6. Aggiungi i dettagli dell'articolo per la spedizione
    • Quando inserisci una descrizione, classifichiamo automaticamente classify il prodotto e generiamo un codice HS
    • Puoi sovrascrivere il codice HS generato se necessario
    • Per più articoli, clicca su Salva e aggiungi un altro. Altrimenti, clicca su Salva
  7. Opzionale — Clicca su Altre opzioni per cambiare:
    • Tipo di vendita in Per rivendita
    • Modalità di consegna in Spese di consegna non pagate
  8. Clicca su Ottieni preventivo
    • Per apportare modifiche, clicca su Modifica modulo e modifica i dettagli
    • Clicca di nuovo su Ottieni preventivo per aggiornare

Un preventivo landed cost apparirà a destra, inclusi i costi di prodotto, spedizione e importazione. Espandi il preventivo per vedere le suddivisioni dettagliate di articoli, spedizione, dazi, tasse e spese. Tutti i preventivi sono salvati nella pagina dei preventivi per riferimento futuro.

Modifica preventivi esistenti: Clicca su Preventivo di nuovo in alto a destra per modificare un preventivo esistente invece di partire da zero.

Vantaggi dell'utilizzo del Dashboard

  • Nessuna codifica richiesta — Genera preventivi attraverso un'interfaccia user-friendly
  • Formazione del team — Aiuta i membri del team non tecnici a comprendere i componenti del landed cost
  • Validazione API — Verifica che la tua integrazione API produca risultati attesi
  • Supporto clienti — Genera rapidamente preventivi per le richieste dei clienti
  • Elaborazione in blocco — Gestisci più calcoli in modo efficiente (in arrivo)

I preventivi del Dashboard includono le stesse suddivisioni dettagliate disponibili tramite l'API, rendendolo un ottimo complemento alla tua integrazione automatizzata.

Questa pagina è stata utile?

Prenota una demo
© 2025 Zonoszonos.com
In questa pagina:
  • Calcola un landed cost
  • Prepara la richiesta
  • Richiedi un landed cost tramite API
  • Richiedi un landed cost nel Dashboard