Construa 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 construir o catálogo da sua Verified Account, e é a opção indicada para expedidores com recursos de desenvolvimento e um sistema que já contém os dados dos seus produtos—um ERP, WMS, PIM ou plataforma de expedição. Esse sistema continua a ser a fonte de verdade e grava os produtos diretamente na Zonos, em vez de os sincronizar a partir de uma integração de canal ou de carregar um ficheiro CSV. Se vende através de um canal suportado, ou se prefere não escrever código, essas duas opções constroem o mesmo catálogo com menos trabalho.
Os itens criados através da API são tratados exatamente como os itens de qualquer outra origem—a partir do momento em que um item está no seu catálogo, para a Zonos é indiferente como lá chegou. Cada item é classificado para efeitos aduaneiros se não tiver indicado um código HS, verificado quanto aos requisitos das Partner Government Agencies (PGA) dos EUA e utilizado para calcular os direitos aduaneiros e impostos das remessas em que aparece.
Há uma parte deste processo que fica fora da API. Quando a verificação de PGA assinala um item como Needs attention, o questionário de conformidade associado a esse alerta tem de ser respondido e confirmado no Dashboard—não existe API para isso, e a Zonos preenche previamente o que consegue, pelo que a maior parte do trabalho consiste em rever e confirmar. A pessoa que desenvolve esta integração normalmente não é a mesma que resolve esses alertas, por isso planeie que alguém da sua organização os trate no Dashboard depois de o seu catálogo ser carregado. Os itens assinalados não estão impedidos de ser expedidos, mas resolvê-los antes da expedição é o que evita que uma remessa fique retida na fronteira dos EUA.
Crie um item de catálogo para cada produto que expede.
Certifique-se de que cada item inclui um identificador que a sua transportadora postal transmitirá.
Quando os dados da sua remessa chegam à Zonos, cada linha é associada ao respetivo item de catálogo e os dados de produto desse item são aplicados ao cálculo.
Criar itens de catálogo
catalogItemCreate aceita uma lista, pelo que pode enviar vários produtos num único pedido.
Se enviar um produto cujo SKU ou ID de produto já exista, a Zonos atualiza esse produto em vez de adicionar um segundo. As novas tentativas e as execuções repetidas são seguras.
Em contrapartida, dois produtos diferentes que partilhem o mesmo SKU ou ID de produto serão fundidos num só. Verifique se existem duplicados nos seus dados antes de um carregamento em massa.
O seu identificador único do produto. *Cada produto precisa de um SKU, de um ID de produto ou de ambos.
productId
Sim*
O identificador do produto na sua plataforma. *Cada produto precisa de um SKU, de um ID de produto ou de ambos.
manufacturerProductId
Só na UE
O identificador não normalizado do produto atribuído pelo fabricante (NS-PID). Obrigatório em remessas B2C para a UE com valor igual ou inferior a 150 EUR.
gtin
Só na UE
O identificador normalizado do produto atribuído pelo fabricante (S-PID), apenas dígitos. Obrigatório em remessas B2C para a UE com valor igual ou inferior a 150 EUR, se o produto tiver código de barras.
name
Sim
O nome do produto.
customsDescription
Recomendado
O que o produto é, em termos simples, para a declaração aduaneira. Utilize “T-shirt de algodão” e 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 os direitos aduaneiros com precisão.
measurements
Recomendado
Peso e dimensões, utilizados para o cálculo de tarifas de envio e para a declaração aduaneira.
hsCode
Não
O código HS universal de 6 dígitos. Se o omitir, a Zonos classifica o produto com base no nome e na descrição.
amount
Não
O preço do produto, em formato numérico.
currencyCode
Não
O código ISO de 3 letras da moeda do preço. Obrigatório quando indica 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, os produtos têxteis não podem ser classificados para além de 6 dígitos.
catalogItemUrl
Não
Uma ligação para a página do produto no seu site. Melhora a precisão da classificação.
imageUrl
Não
Um URL de acesso público para a imagem do produto. Melhora a precisão da classificação.
Adicionar identificadores de produto da UE (PIDs)
Se envia para a UE com a sua Verified Account, a UE exige identificadores de produto (PIDs) nas remessas entre empresas e consumidores (B2C) com valor igual ou inferior a 150 EUR, a partir de 1 de novembro de 2026. Guarde-os nos seus itens de catálogo. Na maioria das Verified Accounts, o seu operador postal envia à Zonos os dados da remessa, e a Zonos associa cada item da remessa ao seu catálogo e aplica os identificadores que guardou, pelo que não precisa de enviar nada adicional no momento da expedição.
Identificador↕
O que é↕
Campo da API↕
Obrigatório?↕
Identificador do produto atribuído pelo comerciante (M-PID)
O seu SKU ou código de artigo
sku
Sempre
Identificador não normalizado do produto atribuído pelo fabricante (NS-PID)
O número de modelo ou de peça do fabricante. Se for o próprio fabricante do produto, utilize o seu número de modelo ou de peça.
manufacturerProductId
Sempre
Identificador normalizado do produto atribuído pelo fabricante (S-PID)
O código de barras (UPC, EAN ou ISBN)
gtin
Só se o produto tiver um
Envie os identificadores com catalogItemCreate para produtos novos. Para produtos que já estão no seu catálogo, envie-os com catalogItemUpdate, que aceita os mesmos campos. Faça corresponder o sku de cada item ao SKU que utiliza em todos os outros sistemas, para que a Zonos consiga ligar os dois.
Envie o gtin apenas com dígitos, sem hífenes nem espaços. Os valores UPC, EAN, JAN e ISBN de 13 dígitos vão todos neste mesmo campo. Se tiver um ISBN de 10 dígitos, envie a versão de 13 dígitos.
Se um produto não tiver código de barras, omita o gtin em vez de enviar uma cadeia vazia, reutilizar o seu SKU ou preenchê-lo com texto de substituição como N/A.
A Zonos associa cada linha da remessa a um item de catálogo através dos seus identificadores, por esta ordem: ID de produto, depois SKU e, por fim, nome. Mantenha os identificadores que utiliza exatos e consistentes entre o seu catálogo e os dados que envia à sua transportadora.
As remessas 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 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ó.
A forma de formatar o identificador nos dados de remessa que envia à sua transportadora depende do seu operador postal, porque cada operador associa as remessas ao seu catálogo de forma diferente. Aceda a todos os operadores postais e selecione o seu. A respetiva página mostra como funciona a associação para esse operador e exatamente o que deve enviar.
Definir o customsDescription do item com o mesmo texto que envia à sua transportadora não é obrigatório, mas torna os dois lados diretamente comparáveis quando uma linha não é associada e precisa de perceber porquê.
A associação falha frequentemente quando:
O identificador que o seu operador postal utiliza para a associação não consta dos dados da remessa.
O identificador não corresponde exatamente a nada no seu catálogo.
O identificador é truncado pelo limite de caracteres da transportadora.
A formatação muda entre remessas.
Este comportamento ainda está a ser finalizado e pode mudar antes do lançamento.
Atualizar itens de catálogo
catalogItemUpdate utiliza o mesmo tipo de entrada que a criação. Envie apenas os campos que pretende alterar.
Nota: Os campos omitidos permanecem inalterados, o que torna as atualizações parciais seguras. Enviar null não apaga um valor; é simplesmente ignorado. Pode substituir um valor por outro, mas não o pode esvaziar através da API. Contacte o seu representante da Zonos se precisar de limpar um campo.
Consultar os seus itens
A consulta catalogItem aceita id, productId ou sku. Utilize-a para confirmar os dados que a Zonos tem de um produto.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Eliminar itens de catálogo
catalogItemDelete recebe IDs de itens de catálogo da Zonos, e não os seus SKUs ou IDs de produto. Obtenha primeiro o ID com a consulta catalogItem.
Catalog API
Catalog API
Construa 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 construir o catálogo da sua Verified Account, e é a opção indicada para expedidores com recursos de desenvolvimento e um sistema que já contém os dados dos seus produtos—um ERP, WMS, PIM ou plataforma de expedição. Esse sistema continua a ser a fonte de verdade e grava os produtos diretamente na Zonos, em vez de os sincronizar a partir de uma integração de canal ou de carregar um ficheiro CSV. Se vende através de um canal suportado, ou se prefere não escrever código, essas duas opções constroem o mesmo catálogo com menos trabalho.
Os itens criados através da API são tratados exatamente como os itens de qualquer outra origem—a partir do momento em que um item está no seu catálogo, para a Zonos é indiferente como lá chegou. Cada item é classificado para efeitos aduaneiros se não tiver indicado um código HS, verificado quanto aos requisitos das Partner Government Agencies (PGA) dos EUA e utilizado para calcular os direitos aduaneiros e impostos das remessas em que aparece.
Há uma parte deste processo que fica fora da API. Quando a verificação de PGA assinala um item como Needs attention, o questionário de conformidade associado a esse alerta tem de ser respondido e confirmado no Dashboard—não existe API para isso, e a Zonos preenche previamente o que consegue, pelo que a maior parte do trabalho consiste em rever e confirmar. A pessoa que desenvolve esta integração normalmente não é a mesma que resolve esses alertas, por isso planeie que alguém da sua organização os trate no Dashboard depois de o seu catálogo ser carregado. Os itens assinalados não estão impedidos de ser expedidos, mas resolvê-los antes da expedição é o que evita que uma remessa fique retida na fronteira dos EUA.
Como funciona
Crie um item de catálogo para cada produto que expede.
Certifique-se de que cada item inclui um identificador que a sua transportadora postal transmitirá.
Quando os dados da sua remessa chegam à Zonos, cada linha é associada ao respetivo item de catálogo e os dados de produto desse item são aplicados ao cálculo.
Criar itens de catálogo
catalogItemCreateaceita uma lista, pelo que pode enviar vários produtos num único pedido.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Enviar o mesmo produto duas vezes
Se enviar um produto cujo SKU ou ID de produto já exista, a Zonos atualiza esse produto em vez de adicionar um segundo. As novas tentativas e as execuções repetidas são seguras.
Em contrapartida, dois produtos diferentes que partilhem o mesmo SKU ou ID de produto serão fundidos num só. Verifique se existem duplicados nos seus dados antes de um carregamento em massa.
Campos
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEouPARTIAL_ITEM. Evita que itens não físicos sejam declarados como mercadoria.provinceOfOriginproductComposition{material, percentage}. Sem ela, os produtos têxteis não podem ser classificados para além de 6 dígitos.catalogItemUrlimageUrlAdicionar identificadores de produto da UE (PIDs)
Se envia para a UE com a sua Verified Account, a UE exige identificadores de produto (PIDs) nas remessas entre empresas e consumidores (B2C) com valor igual ou inferior a 150 EUR, a partir de 1 de novembro de 2026. Guarde-os nos seus itens de catálogo. Na maioria das Verified Accounts, o seu operador postal envia à Zonos os dados da remessa, e a Zonos associa cada item da remessa ao seu catálogo e aplica os identificadores que guardou, pelo que não precisa de enviar nada adicional no momento da expedição.
skumanufacturerProductIdgtinEnvie os identificadores com
catalogItemCreatepara produtos novos. Para produtos que já estão no seu catálogo, envie-os comcatalogItemUpdate, que aceita os mesmos campos. Faça corresponder oskude cada item ao SKU que utiliza em todos os outros sistemas, para que a Zonos consiga ligar os dois.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtinEnvie o
gtinapenas com dígitos, sem hífenes nem espaços. Os valores UPC, EAN, JAN e ISBN de 13 dígitos vão todos neste mesmo campo. Se tiver um ISBN de 10 dígitos, envie a versão de 13 dígitos.Se um produto não tiver código de barras, omita o
gtinem vez de enviar uma cadeia vazia, reutilizar o seu SKU ou preenchê-lo com texto de substituição comoN/A.Se chamar diretamente a Landed Cost API, também pode incluir estes identificadores no seu pedido de landed cost. A maioria das Verified Accounts não o faz, porque é o operador postal que envia à Zonos os dados da remessa.
Para saber o que o regulamento exige, consulte o guia de identificadores de produto da UE.
Torne os seus itens identificáveis
A Zonos associa cada linha da remessa a um item de catálogo através dos seus identificadores, por esta ordem: ID de produto, depois SKU e, por fim, nome. Mantenha os identificadores que utiliza exatos e consistentes entre o seu catálogo e os dados que envia à sua transportadora.
As remessas 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 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ó.
A forma de formatar o identificador nos dados de remessa que envia à sua transportadora depende do seu operador postal, porque cada operador associa as remessas ao seu catálogo de forma diferente. Aceda a todos os operadores postais e selecione o seu. A respetiva página mostra como funciona a associação para esse operador e exatamente o que deve enviar.
Definir o
customsDescriptiondo item com o mesmo texto que envia à sua transportadora não é obrigatório, mas torna os dois lados diretamente comparáveis quando uma linha não é associada e precisa de perceber porquê.A associação falha frequentemente quando:
Atualizar itens de catálogo
catalogItemUpdateutiliza o mesmo tipo de entrada que a criação. Envie apenas os campos que pretende alterar.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Consultar os seus itens
A consulta
catalogItemaceitaid,productIdousku. Utilize-a para confirmar os dados que a Zonos tem de um produto.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Eliminar itens de catálogo
catalogItemDeleterecebe IDs de itens de catálogo da Zonos, e não os seus SKUs ou IDs de produto. Obtenha primeiro o ID com a consultacatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Relacionado
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Esta página foi útil?