Endpoints
Solicitar cotações de envio
POST | https://api.iglobalstores.com/2.0/shipping-quotes - Crie uma nova solicitação de cotações de envio para itens no carrinho de compras que inclui taxas de importação e impostos, além de informações de verificação de restrições de itens.
Solicitação HTTPS
| Campo | Observações |
|---|---|
| Método HTTP | POST |
| URL do Endpoint | https://api.iglobalstores.com/2.0/shipping-quotes |
| Protocolo | HTTPS |
| Formato da mensagem | JSON |
| Cabeçalho HTTP de Aceitação | Accept: application/json |
| Cabeçalho HTTP de Token de Segurança | serviceToken: seu-valor-de-token-de-segurança-de-testeAdicione um cabeçalho à sua solicitação HTTPS chamado serviceToken com um valor do seu Token de API de Segurança de Teste. (Entre em contato com seu Gerente de Conta para obter este token) |
| Cabeçalho HTTP de Tipo de Conteúdo | Content-Type: application/jsonComo você estará enviando dados JSON para o serviço, adicione um cabeçalho à sua solicitação HTTPS chamado Content-Type com um valor de application/json |
PARES DE CHAVE/VALOR JSON no corpo da solicitação
Formato da Mensagem: JSON
Exemplo de solicitaçã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
{
"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"
}
}
Definições de JSON de solicitação
| Campo | Notas |
|---|---|
boxCount | Este campo descreve as caixas que serão usadas para enviar o pedido. Não se espera que um comerciante saiba isso no momento do pedido; no entanto, se for conhecido, pode ser passado no seguinte formato específico.Valor de exemplo: 22x15x15(1),8x8x4(2),32x22x14(1)Formato: Lista separada por vírgulas das dimensões e quantidade das caixas. No exemplo acima, há um total de 4 caixas. A primeira caixa da lista terá 22 polegadas de comprimento, 15 polegadas de largura e 15 polegadas de altura. Haverá apenas uma caixa usada para esse tamanho. Haverá duas caixas de tamanho 8x8x4 polegadas. É aceitável passar a mesma dimensão de caixa várias vezes se isso for mais fácil para você, assim: “22x15x15(1),22x15x15(1)”, o que significa 2 caixas de tamanho 22x15x15 polegadas. |
items OBRIGATÓRIO | Uma lista de mapas de itens |
items[index].brandName | O nome da marca do item específico ajudará nosso mecanismo de regras a determinar melhor se uma restrição se aplica ao item para o país de destino. Mesmo que o nome da marca de um item corresponda ou não textualmente a uma restrição específica, nosso mecanismo de regras usará o SKU do item e/ou productId para decidir melhor se o item está de fato restrito no país de destino. Por favor, envie o nome da marca, se disponível. Valores de exemplo: “Oakley” ou “Nike” ou null |
items[index].cartItemId OBRIGATÓRIO | Este campo é obrigatório para identificar o item, especificamente dentro da lista de itens. Pode ser tão simples quanto um valor de índice. Usaremos este cartItemId para identificar um item se ele estiver restrito na resposta JSON. Portanto, certifique-se de que você é capaz de identificar o mesmo item em seu carrinho por este cartItemId que você está nos passando. Valores de exemplo: 1 ou 2 ou 3 |
items[index].category | As categorias de produtos - o produto específico do qual faz parte. A categoria ajudará nosso mecanismo de regras a determinar melhor se uma restrição se aplica ao item para o país de destino. Mesmo que a categoria de um item corresponda ou não textualmente a uma restrição específica, nosso mecanismo de regras usará o SKU do item e/ou productId para decidir melhor se o item está de fato restrito no país de destino. Formato: Uma lista de nomes de categorias separada por pipe. Cada nome de categoria pode ter uma ou mais palavras. Se um item existir em mais de uma categoria, por favor, liste ambas separadas por um caractere pipe “”. Valores de exemplo: “Óculos de sol” ou “Acessórios de noiteBolsas” |
items[index].countryOfOrigin | O país de origem é o país onde o item foi fabricado ou de onde originalmente veio. O país de origem ajudará nosso mecanismo de regras a determinar melhor se uma restrição se aplica ao item para o país de destino. Alguns países não permitem tipos específicos de mercadorias de outros países específicos. Valores de exemplo: “CN” para China ou “US” para Estados Unidos ou nulo |
items[index].detailedDescription OBRIGATÓRIO | Este campo é simplesmente texto, mas deve incluir o máximo de informações possível sobre o item sendo comprado. Por exemplo, o nome completo e o código do item, se aplicável, a cor ou outras opções selecionadas, conteúdo material e qualquer texto descritivo que você tenha para o item. Existem muitos tipos diferentes de restrições de importação em países estrangeiros, como sapatos de couro na Itália. Às vezes, a única maneira de identificar esses itens restritos é através da detailedDescription. Observação: Mesmo que a detailedDescription de um item corresponda ou não textualmente a uma restrição específica, nosso mecanismo de regras usará o SKU do item e/ou productId para decidir melhor se o item está de fato restrito no país de destino. Para obter os melhores resultados, envie o máximo de informações possível no campo detailedDescription. Valor de exemplo: “Tory Burch, Robinson – Double Zip’ Tote, cor: New Carnival, conteúdo material: couro, O couro rico em cores confere um apelo visual atraente a uma bolsa estruturada de forma ordenada, com hardware de logotipo e alças enroladas para um visual completamente sofisticado. Fecho magnético com compartimentos de zíper duplo. Bolsos internos com zíper, de parede e para celular. Pés de metal protetores. Couro. Por Tory Burch; importado.” |
items[index].height | Esta é a altura do seu item. Há outro campo chamado dimensionalUnits, onde você especifica polegadas ou centímetros para essa medida. Forneça sem vírgulas e com no máximo duas casas decimais. Valor de exemplo: 25.5 Suas tarifas de envio serão as mais precisas se você passar este campo. |
items[index].hsCode | Este é o Código HS que identifica o item para países estrangeiros. Passar o hsCode ajudará a identificar corretamente o direito de importação rate para o item específico. Não é necessário se não estiver disponível - cuidaremos disso se você não tiver. Formato: Um código de 10 dígitos ou 6 dígitos; pode incluir os caracteres separadores “.” ou não. Valores de exemplo: “20.4560.0000” ou “20.4560” ou “204560” (códigos de 10 ou 6 dígitos são aceitáveis) |
items[index].length | Este é o comprimento do seu item. Há outro campo chamado dimensionalUnits, onde você especifica polegadas ou centímetros para essa medida. Forneça sem vírgulas e com no máximo duas casas decimais. Valor de exemplo: 25.5 Suas tarifas de envio serão as mais precisas se você passar este campo. |
items[index].productId | Este é o ID do seu produto para o item específico. Nosso mecanismo de regras usará esse valor como um ID para vincular informações do item aprendidas ao seu item. Valor de exemplo: “17898-675235” Por favor, passe pelo menos o productID ou o SKU. Passar ambos é preferível. |
items[index].quantity OBRIGATÓRIO | Esta é a quantidade sendo comprada no item específico. Forneça como um inteiro positivo, sem vírgulas e sem casas decimais. Valores de exemplo: 1 ou 9999 (preferimos que você venda mais itens do que menos!) |
items[index].sku | Este é o seu SKU para o item específico. Nosso mecanismo de regras usará esse valor como um ID para vincular informações do item aprendidas ao seu item. Valor de exemplo: “oakley-125” Por favor, passe pelo menos o productId ou o SKU. Passar ambos é preferível. |
items[index].unitPrice OBRIGATÓRIO | Este é o preço unitário do seu item em USD (dólares americanos). Forneça sem vírgulas, sem o sinal de dólar “$” e com duas casas decimais. Valor de exemplo: 2102.99 |
items[index].weight | Este é o peso do seu item. Existe outro campo chamado weightUnits, onde você especifica libras, onças, gramas ou quilogramas para essa medição. Por favor, forneça sem vírgulas e com no máximo duas casas decimais. Valor de exemplo: 4.2. Suas taxas de envio serão as mais precisas se você passar este campo. |
items[index].weightUnits | Padrão é "LB" para libras. A unidade de medida para o valor do peso. Se definido como nulo, "LB" (libras) será assumido. Valores de exemplo: "LB" para libras, "OZ" para onças, "G" para gramas, "KG" para quilogramas ou nulo. |
items[index].width | Esta é a largura do seu item. Existe outro campo chamado dimensionalUnits, onde você especifica polegadas ou centímetros para essa medição. Por favor, forneça sem vírgulas e com no máximo duas casas decimais. Valor de exemplo: 25.5. Suas taxas de envio serão as mais precisas se você passar este campo. |
shipFromAddress | Se passado como nulo, usaremos um shipFromAddress padrão associado à sua conta de comerciante. Este é o endereço de onde o pedido será enviado, ou seja, seu armazém. Este é um mapa contendo os seguintes campos de endereço: address1, address2, address3, city, state, stateCode, postalCode, countryCode. Esses campos contidos são obrigatórios ou não, com base no país. O endpoint de localização retorna quais campos de endereço específicos são necessários ou não para cada país. Observação: stateCode nunca é necessário e não é declarado no endpoint de localização. Você pode passar stateCode, se disponível. |
shippingAmountOverride | Isso é usado apenas se você souber o custo de envio antes de chamar a API. Está em USD (dólares americanos). Por favor, forneça sem vírgulas, sem o símbolo de dólar "$" e com duas casas decimais. Este recurso não funcionará sem configurá-lo com um representante da Zonos. Valor de exemplo: 212.99. |
shipToAddress OBRIGATÓRIO | Este é o endereço para onde o pedido será enviado. Este é um mapa contendo os seguintes campos de endereço: name, address1, address2, address3, city, state, stateCode, postalCode, countryCode. Esses campos contidos são obrigatórios ou não, com base no país. O endpoint de localização retorna quais campos de endereço específicos são necessários para cada país. Observação: name e stateCode nunca são necessários e não são declarados no endpoint de localização. Você pode passar name e/ou stateCode, se disponíveis. |
Resposta HTTPS
Formato da mensagem: JSON
Exemplo de resposta apenas para Canadá e Austrália
Nota: As respostas reais conterão todos os países suportados.
Exemplo de solicitaçã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
{
"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
}
]
}
Definições JSON de resposta
| Campo | Notas |
|---|---|
shippingQuotes | Esta é uma lista de mapas de cotação de frete. |
shippingQuotes[index].carrier | A transportadora para a qual a cotação de frete é específica. Só é definida como nula se o comerciante solicitou a configuração de perfis de frete genéricos, não específicos para uma transportadora. As cotações de frete não precisam ser específicas para uma transportadora; mas podem ser. Entre em contato com seu Gerente de Conta para obter ajuda na configuração de seus perfis de frete. Valores de exemplo: UPS ou FEDEX ou DHL ou USPS ou CAPOST ou null |
shippingQuotes[index].displayName | Nome de exibição para a opção de frete, adequado para ser exibido ao comprador. Esses valores são personalizáveis para o comerciante. Entre em contato com seu Gerente de Conta para fazer isso. Valor de exemplo: "Entrega Expressa em 2-4 Dias" |
shippingQuotes[index].duty | O valor do imposto de importação incluído no dutyTaxTotal. Este valor está em USD, não conterá vírgulas e terá duas casas decimais. Valor de exemplo: 8.29 |
shippingQuotes[index].dutyTaxBrokerageFee | Este é o valor que o corretor de importação estrangeiro irá cobrar para processar seus impostos de importação. Este valor está incluído no dutyTaxTotal. O valor está em USD, não conterá vírgulas e terá duas casas decimais. Valor de exemplo: 5.00 |
shippingQuotes[index].duyTaxCarrierPrepaymentFee | Este é o valor que a transportadora irá cobrar para prepay os impostos de importação para o país importador. Este valor está incluído no dutyTaxTotal. O valor está em USD, não conterá vírgulas e terá duas casas decimais. Valor de exemplo: 5.00 |
shippingQuotes[index].duyTaxEnabled | Se esta cotação de frete permite que o comprador prepay seus impostos de importação. Se definido como false, o dutyTaxTotal deve ser ignorado. Valores de exemplo: true ou false |
shippingQuotes[index].duyTaxForced | Se esta cotação de frete obriga o comprador a prepay seus impostos de importação. Se definido como true, você deve incluir o dutyTaxTotal no pedido, explicando ao comprador que é necessário com esta opção de frete específica. Se definido como false, você pode permitir que o comprador escolha se deseja prepay seus impostos de importação. Valores de exemplo: true ou false |
shippingQuotes[index].dutyTaxTotal | O custo total de impostos e taxas para a cotação de frete fornecida. O imposto e a taxa podem ser opcionais, não disponíveis ou obrigatórios para a cotação de frete fornecida. Este valor não está incluído no shippingTotal. Este valor está em USD, não conterá vírgulas e terá duas casas decimais. Valor de exemplo: 19.55 |
shippingQuotes[index].dutyTaxUnderDeMinimis | Se o total do pedido, usando esta opção de frete específica, está abaixo do valor de minimis tanto do imposto/IVA quanto do imposto de importação. Se definido como true, o dutyTaxTotal será definido como 0.00, e você deve informar ao cliente que não haverá impostos de importação devidos em seu pedido. Além disso, force o pré-pagamento de impostos e taxas, pois o custo é de 0.00. |
shippingQuotes[index].id | Um identificador para a cotação de frete específica; um UUID de 36 caracteres. Valor de exemplo: bcdbdbcd-0145-4d3b-a54e-0de3cdce5a0a |
shippingQuotes[index].restrictedItems | Esta é uma lista de mapas, contendo detalhes sobre quaisquer itens no carrinho que estão restritos usando esta cotação de envio específica. Cada item restrito tem um reasonCode. A razão pode ou não ser específica para a opção de envio. Algumas razões para restrições de itens são devido a leis de importação do país, restrições de marca ou até mesmo regras criadas pelo comerciante. Sempre que uma opção de envio é escolhida pelo comprador, os itens do carrinho devem ser cruzados com a lista de restrictedItems da cotação de envio. Se algum dos itens do carrinho estiver restrito, uma mensagem deve ser exibida ao comprador, e o(s) item(s) restrito(s) deve(m) ser removido(s) do total do pedido, etc. |
shippingQuotes[index].restrictedItems[index].cartItemId | Este é o cartItemId do JSON de solicitação de um item de carrinho restrito. Você deve ser capaz de vincular este cartItemId a um item específico no carrinho do seu comprador. Valores de exemplo: 1 ou 2 ou 3 |
shippingQuotes[index].restrictedItems[index].message | Esta é uma mensagem que pode ser exibida ao comprador sobre o motivo pelo qual o item está restrito. Essas mensagens são personalizáveis pelo comerciante. Entre em contato com seu representante da Zonos para obter detalhes. Valor de exemplo: “Não podemos vender produtos Oakley para o seu país.” |
shippingQuotes[index].restrictedItems[index].reasonCode | Este é o código de motivo para o item estar restrito. As restrições são sempre específicas do país e nossos códigos de motivo deixam isso claro. Valores de exemplo: BRAND_COUNTRY ou IMPORT_COUNTRY ou EXPORT_COUNTRY ou CARRIER_COUNTRY ou MERCHANT_COUNTRY. BRAND_COUNTRY significa que você especificou que não pode vender uma marca para um conjunto específico de países. IMPORT_COUNTRY significa que o país importador não permitirá a importação do item. EXPORT_COUNTRY significa que o país exportador (geralmente Estados Unidos) não permitirá a exportação do item. CARRIER_COUNTRY significa que a transportadora específica não transportará o item. MERCHANT_COUNTRY significa que você configurou uma regra de restrição personalizada que o item acionou. |
shippingQuotes[index].shippingTotal | O custo total do envio para a cotação de envio fornecida. As cotações de envio também podem ter um valor de dutyTaxTotal, que não está incluído neste shippingTotal. Este valor está em USD, não conterá vírgulas e conterá duas casas decimais. Valor de exemplo: 25.82 |
shippingQuotes[index].taxOrVat | O valor do imposto ou VAT incluído no dutyTaxTotal. Para alguns países, isso é um imposto; para outros, é um VAT. Este valor está em USD, não conterá vírgulas e conterá duas casas decimais. Valor de exemplo: 4.35 |
API Legacy de Landed Cost
Saiba como a API Legacy de Landed Cost funciona.As informações abaixo são para nossa API Legacy de Landed Cost. Consulte nossa API de Landed Cost para a versão mais recente.
O endpoint de cotações de envio aceita detalhes sobre o carrinho do comprador, retorna cotações de envio completas com taxas de importação e impostos, e verifica os itens em busca de restrições. Essas cotações de envio retornadas são baseadas em perfis de envio configurados antes do uso deste endpoint da API.
Temos perfis de envio padrão para fins de teste, mas você precisará trabalhar com seu Gerente de Conta para configurar os perfis de envio e configurações reais que sua empresa deseja usar.