Monte o catálogo da sua Verified Account de forma programática, diretamente a partir do seu próprio sistema.
A Catalog API é uma das três formas de montar o catálogo da sua Verified Account, e é a opção para remetentes com recursos de desenvolvimento e um sistema que já contém os dados dos seus produtos—um ERP, WMS, PIM ou plataforma de envio. Esse sistema continua sendo a fonte da verdade e grava os produtos diretamente na Zonos, em vez de sincronizá-los a partir de uma integração com canal ou de enviar um arquivo CSV. Se você vende por meio de um canal compatível, ou prefere não escrever código, essas duas opções montam o mesmo catálogo com menos trabalho.
Os itens criados pela API são tratados exatamente como os itens de qualquer outra origem—depois que um item está no seu catálogo, para a Zonos não importa como ele chegou lá. Cada um é classificado para fins aduaneiros se você não informou um código HS, verificado quanto aos requisitos das Partner Government Agencies (PGA) dos EUA e usado para calcular os impostos e tributos de importação dos envios em que aparece.
Uma parte disso fica fora da API. Quando a verificação de PGA sinaliza um item como Needs attention, o questionário de conformidade por trás desse alerta precisa ser respondido e confirmado no Dashboard—não existe API para isso, e a Zonos preenche previamente o que pode, de modo que a maior parte do trabalho é revisar e confirmar. A pessoa que cria esta integração geralmente não é a mesma que resolve esses alertas, então planeje que alguém da sua organização os trate no Dashboard depois que o seu catálogo for carregado. Itens sinalizados não são impedidos de ser enviados, mas resolvê-los antes de enviar é o que evita que um envio fique retido na fronteira dos EUA.
Crie um item de catálogo para cada produto que você envia.
Garanta que cada item tenha um identificador que a sua transportadora postal repassará.
Quando os dados do seu envio chegam à Zonos, cada linha é vinculada ao item de catálogo correspondente, e os dados de produto desse item são aplicados ao cálculo.
Se você enviar um produto cujo SKU ou product ID já exista, a Zonos atualiza esse produto em vez de adicionar um segundo. Novas tentativas e execuções repetidas são seguras.
Por outro lado, dois produtos diferentes que compartilhem um SKU ou product ID serão mesclados em um só. Verifique se há duplicatas nos seus dados antes de uma carga em massa.
Campos
Campo↕
Obrigatório↕
Descrição↕
sku
Sim*
Seu identificador exclusivo do produto. *Cada produto precisa de um SKU, de um product ID ou de ambos.
productId
Sim*
O identificador do produto na sua plataforma. *Cada produto precisa de um SKU, de um product ID ou de ambos.
name
Sim
O nome do produto.
customsDescription
Recomendado
O que o produto é, em termos simples, para a declaração aduaneira. Use “Camiseta de algodão”, não “Summer Vibes Tee”.
countryOfOrigin
Recomendado
O código ISO de 2 letras do local onde o produto foi fabricado. Necessário para calcular o imposto de importação com precisão.
measurements
Recomendado
Peso e dimensões, usados para cotação de frete e declaração aduaneira.
hsCode
Não
O código HS universal de 6 dígitos. Se você omiti-lo, a Zonos classifica o produto com base no nome e na descrição.
amount
Não
O preço do produto como número.
currencyCode
Não
O código ISO de 3 letras da moeda do preço. Obrigatório quando você informa amount.
itemType
Não
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE ou PARTIAL_ITEM. Evita que itens não físicos sejam declarados como mercadoria.
provinceOfOrigin
Não
O estado ou a província de origem do produto. Exigido por alguns países de destino.
productComposition
Não
Uma lista de {material, percentage}. Sem ela, produtos têxteis não podem ser classificados além de 6 dígitos.
catalogItemUrl
Não
Um link para a página do produto no seu site. Melhora a precisão da classificação.
imageUrl
Não
Uma URL publicamente acessível da imagem do produto. Melhora a precisão da classificação.
A Zonos vincula cada linha do envio a um item de catálogo usando seus identificadores, nesta ordem: product ID, depois SKU e, por fim, nome. Mantenha os identificadores que você usa precisos e consistentes entre o seu catálogo e os dados que você envia à sua transportadora.
Os envios postais têm uma restrição adicional. A Zonos recebe um conjunto limitado de campos das transportadoras postais e, em muitas rotas, a descrição aduaneira é o único campo que chega com alguma informação específica do produto. Uma descrição idêntica em todo o seu catálogo não consegue identificar nada por si só.
Acrescente seu product ID ou SKU ao final da descrição aduaneira que você envia à sua transportadora.
Men's bifold wallet, cowhide leather - 123456
O identificador acrescentado deve corresponder exatamente ao productId ou ao sku do item de catálogo correspondente.
Os campos de descrição são curtos. Os envios pelo Canada Post, por exemplo, permitem cerca de 49 caracteres, então encurte a parte descritiva se os seus identificadores forem longos. O identificador importa mais do que o texto.
Definir o customsDescription do item com o mesmo texto que você envia à sua transportadora não é obrigatório, mas torna os dois lados diretamente comparáveis quando uma linha não é vinculada e você precisa descobrir o motivo.
A vinculação costuma falhar quando:
O identificador não consta na descrição.
O identificador não corresponde a nenhum productId ou sku do seu catálogo.
O identificador é truncado pelo limite de caracteres da transportadora.
A formatação muda entre os envios.
Esse comportamento ainda está sendo finalizado e pode mudar antes do lançamento.
Observação: Os campos omitidos permanecem inalterados, o que torna as atualizações parciais seguras. Enviar null não apaga um valor; ele é ignorado. Você pode sobrescrever um valor com outro, mas não pode esvaziá-lo pela API. Entre em contato com seu representante da Zonos se precisar limpar um campo.
Catalog API
Catalog API
Monte o catálogo da sua Verified Account de forma programática, diretamente a partir do seu próprio sistema.
A Catalog API é uma das três formas de montar o catálogo da sua Verified Account, e é a opção para remetentes com recursos de desenvolvimento e um sistema que já contém os dados dos seus produtos—um ERP, WMS, PIM ou plataforma de envio. Esse sistema continua sendo a fonte da verdade e grava os produtos diretamente na Zonos, em vez de sincronizá-los a partir de uma integração com canal ou de enviar um arquivo CSV. Se você vende por meio de um canal compatível, ou prefere não escrever código, essas duas opções montam o mesmo catálogo com menos trabalho.
Os itens criados pela API são tratados exatamente como os itens de qualquer outra origem—depois que um item está no seu catálogo, para a Zonos não importa como ele chegou lá. Cada um é classificado para fins aduaneiros se você não informou um código HS, verificado quanto aos requisitos das Partner Government Agencies (PGA) dos EUA e usado para calcular os impostos e tributos de importação dos envios em que aparece.
Uma parte disso fica fora da API. Quando a verificação de PGA sinaliza um item como Needs attention, o questionário de conformidade por trás desse alerta precisa ser respondido e confirmado no Dashboard—não existe API para isso, e a Zonos preenche previamente o que pode, de modo que a maior parte do trabalho é revisar e confirmar. A pessoa que cria esta integração geralmente não é a mesma que resolve esses alertas, então planeje que alguém da sua organização os trate no Dashboard depois que o seu catálogo for carregado. Itens sinalizados não são impedidos de ser enviados, mas resolvê-los antes de enviar é o que evita que um envio fique retido na fronteira dos EUA.
Como funciona
Crie um item de catálogo para cada produto que você envia.
Garanta que cada item tenha um identificador que a sua transportadora postal repassará.
Quando os dados do seu envio chegam à Zonos, cada linha é vinculada ao item de catálogo correspondente, e os dados de produto desse item são aplicados ao cálculo.
Criar itens de catálogo
catalogItemCreateaceita uma lista, portanto você pode enviar muitos produtos em uma única requisição.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Enviar o mesmo produto duas vezes
Se você enviar um produto cujo SKU ou product ID já exista, a Zonos atualiza esse produto em vez de adicionar um segundo. Novas tentativas e execuções repetidas são seguras.
Por outro lado, dois produtos diferentes que compartilhem um SKU ou product ID serão mesclados em um só. Verifique se há duplicatas nos seus dados antes de uma carga em massa.
Campos
skuproductIdnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEouPARTIAL_ITEM. Evita que itens não físicos sejam declarados como mercadoria.provinceOfOriginproductComposition{material, percentage}. Sem ela, produtos têxteis não podem ser classificados além de 6 dígitos.catalogItemUrlimageUrlTorne seus itens identificáveis
A Zonos vincula cada linha do envio a um item de catálogo usando seus identificadores, nesta ordem: product ID, depois SKU e, por fim, nome. Mantenha os identificadores que você usa precisos e consistentes entre o seu catálogo e os dados que você envia à sua transportadora.
Os envios postais têm uma restrição adicional. A Zonos recebe um conjunto limitado de campos das transportadoras postais e, em muitas rotas, a descrição aduaneira é o único campo que chega com alguma informação específica do produto. Uma descrição idêntica em todo o seu catálogo não consegue identificar nada por si só.
Acrescente seu product ID ou SKU ao final da descrição aduaneira que você envia à sua transportadora.
O identificador acrescentado deve corresponder exatamente ao
productIdou aoskudo item de catálogo correspondente.Os campos de descrição são curtos. Os envios pelo Canada Post, por exemplo, permitem cerca de 49 caracteres, então encurte a parte descritiva se os seus identificadores forem longos. O identificador importa mais do que o texto.
Definir o
customsDescriptiondo item com o mesmo texto que você envia à sua transportadora não é obrigatório, mas torna os dois lados diretamente comparáveis quando uma linha não é vinculada e você precisa descobrir o motivo.A vinculação costuma falhar quando:
productIdouskudo seu catálogo.Atualizar itens de catálogo
catalogItemUpdateusa o mesmo tipo de entrada que a criação. Envie apenas os campos que você deseja alterar.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Consultar seus itens
A consulta
catalogItemaceitaid,productIdousku. Use-a para confirmar quais dados a Zonos tem de um produto.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Excluir itens de catálogo
catalogItemDeleterecebe IDs de itens de catálogo da Zonos, não seus SKUs ou product IDs. Obtenha o ID primeiro com a consultacatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Relacionados
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Esta página foi útil?