DOCS

Calcule landed cost - GraphQL

Landed Cost•
InícioPara provedores de logística Landed Cost Calcule landed cost - GraphQL

Calcule um landed cost

Calcule impostos, taxas e encargos com GraphQL.

GraphQL

Zonos calcula o total do landed cost para remessas, que inclui impostos, taxas e quaisquer encargos adicionais que alfândegas, corretores ou transportadoras possam cobrar. Muitas vezes garantimos esses cálculos pagando a conta de impostos, taxas e encargos nós mesmos, enquanto cobramos de você exatamente o que calculamos. Em casos raros, nossos cálculos podem ser usados sem nossa garantia, onde você assume qualquer diferença entre nosso cálculo e a conta de impostos e taxas.

Prepare a entrada da mutação 

Calcular um landed cost via API GraphQL envolve várias etapas; organizamos essas etapas em fluxos de trabalho. No final, você terá tudo o que precisa para fazer uma chamada para obter um landed cost com base no destino de envio, itens no carrinho e envio.

Cada fluxo de trabalho precisa de dados de entrada específicos. O GraphQL permite que você inclua mais informações do que o necessário; consulte nossa referência completa da API para ver todos os campos possíveis. Os campos obrigatórios estão marcados como tal em nossa referência da API, mas essa marcação se aplica apenas aos campos necessários para a funcionalidade. Alguns campos adicionais são necessários ao usar nossa garantia.

Abaixo, listamos todos os campos obrigatórios para calcular um landed cost garantido. Certifique-se de ter essas informações prontas.

Entradas obrigatórias para cálculos garantidos

partyCreateWorkflowInput

O partyCreateWorkflowInput identifica as partes envolvidas e suas localizações. Veja o esquema completo em nossa referência da API GraphQL. Os campos obrigatórios são:

  • location
    • administrativeAreaCode: O código do estado ou província, em duas letras. Apenas obrigatório para CA e BR.
    • countryCode: O código ISO de duas letras do país.
    • line1: A primeira linha do endereço.
    • postalCode: O código postal ou CEP do endereço.
  • person
    • email: O endereço de e-mail da pessoa.
    • firstName: O primeiro nome da pessoa.
    • lastName: O sobrenome da pessoa.
    • phone: O número de telefone da pessoa.
  • type
    • DESTINATION: As informações de location & person para o destino de envio.
    • ORIGIN: As informações de location para a origem do envio. A person associada à origem do envio não é necessária.
itemCreateWorkflowInput

O itemCreateWorkflowInput lista os itens no carrinho. Existem muitos campos opcionais (veja todas as possibilidades em nossa referência da API), mas os campos abaixo são obrigatórios.

  • amount: O preço do item.
  • currencyCode: O código da moeda para o valor do item.
  • quantity: A quantidade do item.
  • Um dos seguintes (qualquer que seja definido como sua preferência de chave de item. Sua chave de item conecta informações armazenadas no Catálogo ao item no carrinho e é usada durante a criação de etiquetas.)
    • productId: O ID do produto do item.
    • sku: O SKU do item.

As measurements (WEIGHT, LENGTH, WIDTH, HEIGHT) são necessárias apenas se você quiser cartonizar seus itens ao obter uma classificação de envio.

cartonsCreateWorkflowInput

O cartonsCreateWorkflowInput requer apenas a própria entrada. Veja o esquema completo em nossa referência da API GraphQL para ver todos os valores que podem ser passados. É importante passar as dimensões e o peso da caixa se a Zonos estiver calculando o custo de envio.

shipmentRatingCreateWorkflowInput

Este fluxo de trabalho é usado quando você já conhece o serviço de envio e o custo; se você quiser que a Zonos calcule esses custos para os serviços que você ativou, substitua este fluxo de trabalho e use o shipmentRatingCalculateWorkflow em vez disso.

O shipmentRatingCreateWorkflowInput comunica o custo de envio. Veja o esquema completo em nossa referência da API GraphQL. Os campos obrigatórios são:

  • amount: O custo de envio.
  • currencyCode: O código da moeda do custo de envio.
  • serviceLevelCode: O código que indica o nível de serviço de envio usado na classificação de envio.
landedCostWorkflowInput

O landedCostWorkflowInput dita as preferências para o cálculo do landed cost. Veja o esquema completo em nossa referência da API GraphQL. Os campos obrigatórios são:

  • calculationMethod: Indica sua preferência de como você planeja enviar: DDP (impostos e taxas pré-pagos) ou DAP (ou os impostos e taxas são pagos na entrega, ou se um esquema de remessa se aplica, eles são remetidos via um ID fiscal).
    • Se você usar nossa garantia de landed cost, este valor deve ser sempre DDP_PREFERRED, que fornecerá uma cotação DDP quando possível e uma cotação DAP se uma DDP não for permitida. Usar DAP em vez disso pode resultar em custos de importação não sendo mais garantidos, pois isso geralmente resulta em impostos e taxas pagos na entrega.
  • endUse: Indica se os bens estão sendo vendidos para outra empresa (FOR_RESALE) ou para uso final com um consumidor (NOT_FOR_RESALE).
  • tariffRate: Indica o método que a Zonos deve usar para calcular as taxas de tarifa para esta cotação, no caso de haver uma gama de taxas de tarifa que poderiam ser aplicadas. *Ao usar nossa garantia de landed cost, isso deve ser sempre ZONOS_PREFERRED.

Adicionar envio calculado: Se você quiser que a Zonos calcule o custo de envio para você, substitua o shipmentRatingCreateWorkflow pelo shipmentRatingCalculateWorkflow. Adicione o cartonizeWorkflow se você quiser que a Zonos organize seus itens em caixas antes de encontrar o custo de envio (usado para peso dimensional).

Opções ao calcular um landed cost

GraphQL oferece a flexibilidade de personalizar a solicitação de acordo com sua preferência. Existem algumas opções para como você incluir códigos HS e custos de envio na solicitação.

Códigos HS

Os códigos HS impactam as taxas de imposto e, portanto, são obrigatórios. Você pode passar o código HS para cada item ou deixar Classify gerá-los.

Passar códigos HS para cada item

Zonos recomenda fortemente o uso de códigos HS específicos para produtos, pois isso leva a uma citação de landed cost mais precisa. Se você souber seus códigos HS, passe o hsCode para cada item durante o itemCreateWorkflow.

Se você passar um código HS, Zonos o validará em tempo real ao obter uma citação de landed cost. Se o código HS que você forneceu for inválido (ou seja, não existir), Zonos irá re-classify seu item em tempo real e usará o novo código HS válido em vez do que você forneceu.

Se você precisar de ajuda para gerar códigos HS para seus produtos, aprenda sobre Zonos Classify e como solicitar uma classificação.

Gerar códigos HS com Classify

Se você não passar um hsCode para Zonos, primeiro verificaremos o Zonos Catalog para ver se você tem um código HS armazenado para seu item. Se você não tiver, chamaremos Classify para gerar uma classificação que alimentará seu cálculo de landed cost com base nos seguintes campos de detalhes do produto do itemCreateWorkflow: description, category e material. Se os campos de detalhes do seu produto não forem detalhados o suficiente para gerar uma classificação com base na pontuação de confiança do Classify's, o código HS padrão atribuído à sua loja será utilizado.

Por padrão, se você não fornecer um hsCode e chamarmos Classify, o hsCode gerado pelo Classify não será retornado na resposta, pois será utilizado apenas internamente para gerar seu landed cost. No entanto, se você tiver uma assinatura do Classify, retornaremos o código HS do Classify's em sua resposta de landed cost.

Custo de envio

Tanto o nível de serviço de envio quanto seu custo impactam os impostos, taxas e encargos e, portanto, são obrigatórios. Zonos pode calcular o envio ou você pode nos passar essa informação.

Calcular envio

Para que Zonos calcule os custos de envio, use o shipmentRatingCalculateWorkflow. As opções de envio retornadas na resposta de envio calculado corresponderão aos serviceLevels que você atribuiu aos perfis de envio no Dashboard.

Solução de problemas: Se você está esperando um serviceLevel na resposta, mas ele não aparece, verifique se o serviceLevel está habilitado e é suportado pelo method que você selecionou.

Adicione o cartonizeWorkflow (que não tem entradas) se você quiser que Zonos classifique seus itens em caixas antes de encontrar o custo de envio (usado para peso dimensional.

Passar custos de envio

Se você souber o serviceLevel e o amount para um envio, pode passar esses valores na parte do shipmentRatingCreateWorkflow da solicitação. Usaremos esses valores para calcular quaisquer taxas de transportadora associadas e retorná-las na resposta.

Enviar a mutação 

Uma vez que você tenha os dados de entrada necessários, envie a mutação GraphQL para o endpoint da API usando sua biblioteca ou ferramenta de cliente escolhida. Aqui estão alguns exemplos de como você pode estruturar a mutação.

Use esta solicitação quando você estiver fazendo com que Zonos calcule o custo de envio como parte da solicitação de Landed Cost. Nós então calcularemos os impostos e taxas sobre o envio se forem avaliados pelo país de destino.

Mutação

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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
mutation {
  partyCreateWorkflow(
    input: [
      {
        location: {
          administrativeArea: "Utah"
          administrativeAreaCode: "UT"
          countryCode: US
          line1: "345 N 2450 E"
          line2: "#151"
          locality: "St George"
          postalCode: "84790"
        }
        type: ORIGIN
      }
      {
        location: {
          administrativeArea: "BC"
          administrativeAreaCode: "BC"
          countryCode: CA
          line1: "27 Sussex Dr."
          locality: "Victoria"
          postalCode: "V8T 2V9"
        }
        person: {
          email: "test@gmail.com"
          firstName: "firstName"
          lastName: "lastName"
          phone: "5022303021"
          companyName: "goProTest"
          metadata: { key: "key", value: "value" }
        }
        type: DESTINATION
      }
      {
        type: PAYOR
        location: {
          administrativeArea: "ON"
          administrativeAreaCode: "ON"
          countryCode: CA
          latitude: 1.2
          line1: "asdf"
          line2: "asdf"
          locality: "locality"
          longitude: 3423.2
          postalCode: "M4C 1A1"
        }
        person: {
          email: "test@gmail.com"
          firstName: "firstName"
          lastName: "lastName"
          phone: "5022303021"
          companyName: "goProTest"
          metadata: { key: "key", value: "value" }
        }
      }
    ]
  ) {
    type
    id
    organization
  }

  itemCreateWorkflow(
    input: [
      {
        amount: 69
        currencyCode: USD
        countryOfOrigin: US
        quantity: 1
        productId: "productId"
        hsCode: "1006.30"
        description: "description"
        measurements: [
          { type: WIDTH, value: 2, unitOfMeasure: CENTIMETER }
          { type: WEIGHT, value: 2, unitOfMeasure: POUND }
        ]
      }
      {
        amount: 62
        currencyCode: CAD
        countryOfOrigin: US
        hsCode: "1006.30"
        quantity: 1
        productId: "productId2"
        description: "description2"
        measurements: [
          { type: WIDTH, value: 2, unitOfMeasure: CENTIMETER }
          { type: WEIGHT, value: 2, unitOfMeasure: POUND }
        ]
      }
    ]
  ) {
    id
    amount
  }
  cartonizeWorkflow {
    id
    type
    items {
      item {
        id
      }
    }
  }
  shipmentRatingCalculateWorkflow {
    id
    amount
  }
  landedCostCalculateWorkflow(
    input: { endUse: FOR_RESALE, method: DAP, tariffRate: ZONOS_PREFERRED }
  ) {
    id
    duties {
      amount
      currency
    }
    taxes {
      amount
      currency
    }
    fees {
      amount
      currency
    }
  }
}

Resposta

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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
{
  "data": {
    "partyCreateWorkflow": [
      {
        "type": "ORIGIN",
        "id": "party_749959ae-b9ff-4de4-b4ac-59cc990c53ba",
        "organization": "organization_dbb64939-12d7-4f12-98ea-7ae5b21acfd0"
      },
      {
        "type": "DESTINATION",
        "id": "party_cd7ff245-76b6-464f-a7bf-151ebe1f8833",
        "organization": "organization_dbb64939-12d7-4f12-98ea-7ae5b21acfd0"
      },
      {
        "type": "PAYOR",
        "id": "party_00e63a9e-9735-44d9-b129-3b3e76c5df25",
        "organization": "organization_dbb64939-12d7-4f12-98ea-7ae5b21acfd0"
      }
    ],
    "itemCreateWorkflow": [
      {
        "id": "item_eb27f071-de8b-4578-9db9-ae69aaf9be3e",
        "amount": 69
      },
      {
        "id": "item_fffa8ba8-cc8d-4e13-bed6-55044a71c115",
        "amount": 62
      }
    ],
    "cartonizeWorkflow": [
      {
        "id": "carton_b34b29c1-ce27-464b-b91b-df8e4a696312",
        "type": "PACKAGE",
        "items": [
          {
            "item": {
              "id": "item_eb27f071-de8b-4578-9db9-ae69aaf9be3e"
            }
          },
          {
            "item": {
              "id": "item_fffa8ba8-cc8d-4e13-bed6-55044a71c115"
            }
          }
        ]
      }
    ],
    "shipmentRatingCalculateWorkflow": [
      {
        "id": "shipment_rating_96787309-9510-43cc-b4fa-c341ff80f4cc",
        "amount": 173.2
      },
      {
        "id": "shipment_rating_b0ccb109-7794-4c7c-b5cc-e2cfbbc5c8ac",
        "amount": 190.1
      }
    ],
    "landedCostCalculateWorkflow": [
      {
        "id": "landed_cost_74d3ce11-bff2-4326-9e6f-368e03ac88b4",
        "duties": [
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "taxes": [
          {
            "amount": 3.45,
            "currency": "USD"
          },
          {
            "amount": 3.1,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "fees": [
          {
            "amount": 0.13,
            "currency": "USD"
          },
          {
            "amount": 1.44,
            "currency": "USD"
          }
        ]
      },
      {
        "id": "landed_cost_7bbfd354-028c-457f-8c8e-c81bb8fa09a0",
        "duties": [
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "taxes": [
          {
            "amount": 3.45,
            "currency": "USD"
          },
          {
            "amount": 3.1,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          },
          {
            "amount": 0.0,
            "currency": "USD"
          }
        ],
        "fees": [
          {
            "amount": 0.13,
            "currency": "USD"
          },
          {
            "amount": 1.44,
            "currency": "USD"
          }
        ]
      }
    ]
  }
}

Esta página foi útil?

Agendar uma demonstração

Dúvidas?

Obter suporte
© 2025 Zonoszonos.com
Nesta página:
  • Calcule um landed cost
  • Prepare a entrada da mutação
  • Enviar a mutação