Feed de Produtos - Topsort Documentation

Um feed de produtos permite que você compartilhe seu catálogo com o Topsort, sincronize dados e mantenha campanhas atualizadas. Durante o processo de integração, você pode nos fornecer a url do seu feed de produtos e garantiremos que seu catálogo permaneça atualizado. Nossa plataforma suporta vários formatos:

Especificação de Dados de Produto do Google.
Valores separados por tabulação (TSV).
Valores separados por vírgula (CSV).

Topsort busca dados de um feed de produtos

Se seu catálogo de produtos já estiver em uma plataforma de terceiros como Algolia ou VTEX, podemos integrar diretamente com eles para atualizações e sincronização, garantindo que as informações do produto sejam precisas. Para instruções detalhadas sobre como configurar essas conexões e requisitos específicos para cada plataforma, consulte a seção “Integrações de Terceiros - Parceiros” da nossa documentação.

Especificação de Dados de Produto do Google

Compartilhe seu catálogo com o Topsort usando feeds de produtos do Google existentes. Suportamos a Especificação de Dados de Produto do Google.

TSV e CSV

Suportamos o compartilhamento do seu catálogo usando feeds TSV e CSV. As instruções nesta seção aplicam-se a ambos os formatos.

Qual formato você deve usar?Recomendamos que você use TSV em vez de CSV. CSV é mais propenso a erros devido às vírgulas que frequentemente estão presentes nos dados do catálogo.Se o nome do seu produto ou nome de categoria contiver vírgulas, você deve usar TSV.

Colunas Suportadas

Nome	Obrigatório	Padrão	Descrição
`id`	sim	-	Identificador único para cada produto.
`active`	não	true	Se o produto pode fazer parte de campanhas ou leilões. Produtos inativos serão removidos das campanhas existentes.
`title`	sim	-	Nome do produto
`category.0.name`	sim	-	Nome da categoria da categoria primária para este produto.
`category.0.id`	não	Slug do nome da categoria	ID da categoria primária para este produto.
`vendor.0.name`	sim se não usar `seller_name`	-	Fornecedor do produto. Esta é a entidade que tem seu próprio orçamento para anunciar este produto e compete com outros fornecedores.
`vendor.0.id`	sim se não usar `seller_name`	Slug do nome do fornecedor	ID do fornecedor deste produto.
`seller_name`	sim se não usar `vendor.0.name`		Nome do fornecedor do produto, mesmo valor que `vendor.0.name`.
`google_product_category`	sim	Categorias fornecidas no Formato de Taxonomia do Google.
`price`	não	-	Preço do produto.
`image_link`	não	-	URL para uma imagem do produto.
`availability`	não	-	Status do estoque. Deve ser um de `in stock`, `out of stock` ou `preorder`.
`description`	não	-	Descrição detalhada do produto.

As categorias podem ser fornecidas de várias maneiras. Mas apenas uma é obrigatória. Você pode associar um produto a mais categorias e fornecedores. Veja a seção abaixo.

Exemplos de arquivo

Exemplo TSV usando vendor.0.name

id	name	description	vendor.0.id	vendor.0.name	vendor.0.image_link	category.0.id	category.0.name	category.1.id	category.1.name	image_link	price	availability
1293	Máscara Verde	Máscara Verde para remover imperfeições, use durante a noite ou dia	1710000087	Derma Laboratories		10000087	Cuidados com a Pele	61	Beleza e Saúde	https://i.postimg.cc/0QxMWmbd/shampoo.png	23935.29	out of stock
1302	Gel de Limpeza	N/A	17829100	Shiny Laboratories		10000087	Cuidados com a pele			https://i.postimg.cc/0QxMWmbd/shampoo.png	16050.42	in stock

Exemplo CSV usando vendor.0.name

id,name,description,vendor.0.id,vendor.0.name,vendor.0.image_link,category.0.id,category.0.name,category.1.id,category.1.name,image_link,price,availability
1293,Máscara Verde,"Máscara Verde para remover imperfeições, use durante a noite ou dia",1710000087,Derma Laboratories,,10000087,Cuidados com a Pele,61,Beleza e Saúde,https://i.postimg.cc/0QxMWmbd/shampoo.png,23935.29,out of stock
1302,Gel de Limpeza,N/A,17829100,Shiny Laboratories,,10000087,Cuidados com a pele,,,https://i.postimg.cc/0QxMWmbd/shampoo.png,16050.42,in stock

Múltiplas categorias e fornecedores

Produtos podem ser associados com múltiplas categorias e/ou fornecedores. Como você deve ter notado, as colunas de categoria e fornecedor contêm índices. Você pode adicionar colunas adicionais de categoria e/ou fornecedor desde que aumente o índice apropriadamente. Por exemplo, um produto com três categorias e dois fornecedores teria pelo menos estas colunas:

category.0.id
category.1.id
category.2.id
vendor.0.id
vendor.1.id

Formato de Taxonomia do Google

Alternativamente, você pode usar o Formato de Taxonomia do Google como nomes de categoria. Isso permite descrever relacionamentos hierárquicos mais complexos. Por exemplo, esta hierarquia:

Vestuário e Acessórios > Roupas > Vestidos

Resultará em três categorias:

[
  {
    "id": "vestuario-e-acessorios",
    "name": "Vestuário e Acessórios",
    "path": "vestuario_e_acessorios"
  },
  {
    "id": "roupas",
    "name": "Roupas",
    "path": "vestuario_e_acessorios.roupas",
    "parentId": "vestuario-e-acessorios"
  },
  {
    "id": "vestidos",
    "name": "Vestidos",
    "path": "vestuario_e_acessorios.roupas.vestidos",
    "parentId": "roupas"
  }
]

O campo path é preferido para novas integrações. O campo parentId continua totalmente suportado — não há planos de removê-lo.

Hospedando seu feed de produtos

Seu feed de produtos precisa estar continuamente acessível ao Topsort para que possamos manter nossos dados atualizados. Atualmente podemos acessar feeds de produtos públicos ou feeds protegidos usando Autorização HTTP Básica. Além disso, use os cabeçalhos de resposta ETag para nos ajudar a determinar se um feed de produtos foi atualizado desde a última busca.

Excluindo produtos

Produtos podem ser “excluídos suavemente” definindo a propriedade active como false. Isso pode ser feito tanto via API quanto via feed de produtos. Produtos inativos não serão incluídos em novas campanhas ou leilões e serão removidos de quaisquer campanhas ativas das quais fazem parte. Para excluir permanentemente produtos do sistema do Topsort, use a API.

Slugs gerados

Quando categorias ou fornecedores não têm um ID, geramos um automaticamente.

Prefira usar IDs explícitosÉ recomendado fornecer os IDs explicitamente no seu feed de produtos, esses IDs são usados como referências ao gerenciar campanhas e leilões.Se você usar IDs gerados, precisará usar o mesmo algoritmo do lado do marketplace para criar tais referências.

Esses IDs usam um slug derivado do nome. Um slug é uma string formatada em kebab case que é adequada para inclusão em URLs. Por exemplo, Olá mundo se torna ola-mundo. O formato é baseado na biblioteca npm slugify.

Ferramentas de Desenvolvedor

Marketplaces que enviam seu catálogo por meio de um product feed podem abrir Dev Tools > Catálogo no Painel de Administração do marketplace para monitorar a saúde da ingestão sem abrir um chamado de suporte. A aba Catálogo exibe as principais métricas de sincronização em um só lugar:

Horário da última sincronização: quando a sincronização de catálogo mais recente foi executada
Duração média da sincronização: quanto tempo as sincronizações normalmente levam
Taxa de sucesso: nas últimas 14 execuções
Execuções de sincronização recentes: cada ingestão com quantos registros foram processados ou ignorados

Com essa visão, as equipes de engenharia podem confirmar que os feeds estão sendo executados conforme o cronograma e identificar rapidamente falhas ou execuções com muitos registros ignorados.

​Especificação de Dados de Produto do Google

​TSV e CSV

​Colunas Suportadas

​Exemplos de arquivo

​Exemplo TSV usando vendor.0.name

​Exemplo CSV usando vendor.0.name

​Múltiplas categorias e fornecedores

​Formato de Taxonomia do Google

​Hospedando seu feed de produtos

​Excluindo produtos

​Slugs gerados

​Ferramentas de Desenvolvedor

Especificação de Dados de Produto do Google

TSV e CSV

Colunas Suportadas

Exemplos de arquivo

Exemplo TSV usando vendor.0.name

Exemplo CSV usando vendor.0.name

Múltiplas categorias e fornecedores

Formato de Taxonomia do Google

Hospedando seu feed de produtos

Excluindo produtos

Slugs gerados

Ferramentas de Desenvolvedor