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 delocation
eperson
para o destino de envio.ORIGIN
: As informações delocation
para a origem do envio. Aperson
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. UsarDAP
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.
- Se você usar nossa garantia de landed cost, esse valor deve ser sempre
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 sempreZONOS_PREFERRED
.
Adicionar envio calculado: Se deseja que a Zonos calcule o custo de envio para você, substitua o
shipmentRatingCreateWorkflow
peloshipmentRatingCalculateWorkflow
. Adicione ocartonizeWorkflow
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.
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.
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.
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 oserviceLevel
está habilitado e é suportado pelomethod
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.
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.
Mutação
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
{
"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"
}
]
}
]
}
}
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.