DOCS

Calculate landed cost graphql

/

Calcular um landed cost

Calcule impostos, taxas e tarifas com GraphQL.

GraphQL

A Zonos calcula o total do landed cost para remessas, que inclui impostos, taxas e quaisquer taxas adicionais que a alfândega, corretores ou transportadoras possam cobrar. Frequentemente garantimos esses cálculos pagando a fatura de impostos, taxas e tarifas nós mesmos, cobrando 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 fatura 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 e obter um landed cost com base no destino de envio, itens no carrinho e envio.

Cada fluxo de trabalho requer dados de entrada específicos. O GraphQL permite incluir 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 são marcados como tal em nossa referência da API, mas essa marca 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 necessário para CA e BR.
    • countryCode: O código de duas letras ISO do país.
    • line1: A primeira linha do endereço.
    • postalCode: O código postal 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 e 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 de moeda para o valor do item.
  • quantity: A quantidade do item.
  • Um dos seguintes (o que for definido como sua preferência de chave do item. Sua chave de item conecta informações armazenadas no Catálogo ao item no carrinho e é usada durante a criação da etiqueta.)
    • 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ê deseja empacotar seus itens ao obter uma classificação de remessa.

shipmentRatingCreateWorkflowInput

Este fluxo de trabalho é usado quando você já conhece o serviço de envio e o custo; se deseja que a Zonos calcule esses custos para os serviços que você habilitou, 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 de moeda do custo de envio.
  • serviceLevelCode: O código que indica o nível de serviço de envio usado na classificação de remessa.
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 para como planeja enviar: DDP (impostos e taxas pré-pagos) ou DAP (os impostos e taxas são pagos na entrega, ou se houver um esquema de remessa, eles são remetidos via ID fiscal).
    • Se você usar nossa garantia de landed cost, esse 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 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 tarifas para esta cotação, no caso de haver uma faixa de tarifas que possam ser aplicadas. *Ao usar nossa garantia de landed cost, isso deve ser sempre ZONOS_PREFERRED.

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

Opções ao calcular um landed cost

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

Códigos HS

Os códigos HS impactam as taxas de importação e, portanto, são necessários. Você pode passar o código HS para cada item ou deixar que Classify os gere.

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 cotação de landed cost mais precisa. Se você conhece 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 cotação de landed cost. Se o código HS fornecido for inválido (ou seja, não existir), Zonos re-classify seu item em tempo real e usará o novo código HS válido em vez do fornecido.

Se precisar de ajuda para gerar códigos HS para seus produtos, saiba mais 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 Catálogo Zonos para ver se você tem um código HS armazenado para seu item. Se não tiver, chamaremos Classify para gerar uma classificação para alimentar o cálculo do seu 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á usado.

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

Custo de envio

Tanto o nível de serviço de envio quanto seu custo impactam as taxas, impostos e tarifas e, portanto, são necessá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 do cálculo de envio corresponderão aos serviceLevels que você atribuiu aos perfis de envio no Dashboard.

Solução de problemas: Se você estiver esperando um serviceLevel na resposta, mas ele não aparecer, 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 organize seus itens em caixas antes de encontrar o custo de envio (usado para peso dimensional.

Passar custos de envio

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

Enviar a mutação 

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

Envio calculado
Envio manual

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?