Product Feed - Topsort Documentation

Un product feed te permite compartir tu catálogo con Topsort, sincronizar datos y mantener campañas actualizadas. Durante el proceso de integración puedes proporcionarnos la URL de tu product feed y nos aseguraremos de que tu catálogo permanezca actualizado. Nuestra plataforma soporta varios formatos:

Google Product Data Specification.
Tab separated values (TSV).
Comma separated values (CSV).

Topsort fetches data from a product feed

Si tu catálogo de productos ya está en una plataforma de terceros como Algolia o VTEX, podemos integrarnos directamente con ellos para actualizaciones y sincronización, asegurando que la información del producto sea precisa. Para instrucciones detalladas sobre cómo configurar estas conexiones y requisitos específicos para cada plataforma, consulta la sección “Integraciones de Terceros - Partners” de nuestra documentación.

Google Product Data Specification

Comparte tu catálogo con Topsort usando feeds de productos de Google existentes. Soportamos la Google Product Data Specification.

TSV y CSV

Soportamos compartir tu catálogo usando feeds TSV y CSV. Las instrucciones en esta sección aplican a ambos formatos.

¿Qué formato deberías usar?Recomendamos que uses TSV sobre CSV. CSV es más propenso a errores debido a que las comas a menudo están presentes en los datos del catálogo.Si el nombre de tu producto o nombre de categoría contiene comas, debes usar TSV.

Columnas Soportadas

Nombre	Requerido	Por Defecto	Descripción
`id`	sí	-	Identificador único para cada producto.
`active`	no	true	Si el producto puede ser parte de campañas o subastas. Los productos inactivos se eliminarán de las campañas existentes.
`title`	sí	-	Nombre del producto
`category.0.name`	sí	-	Nombre de categoría de la categoría principal para este producto.
`category.0.id`	no	Slug del nombre de categoría	ID de la categoría principal para este producto.
`vendor.0.name`	sí si no usas `seller_name`	-	Vendedor del producto. Esta es la entidad que tiene su propio presupuesto para anunciar este producto y compite con otros vendedores.
`vendor.0.id`	sí si no usas `seller_name`	Slug del nombre de vendedor	ID del vendedor de este producto.
`seller_name`	sí si no usas `vendor.0.name`		Nombre de vendedor del producto, mismo valor que `vendor.0.name`.
`google_product_category`	sí	Categorías proporcionadas en Formato de Taxonomía de Google.
`price`	no	-	Precio del producto.
`image_link`	no	-	URL a una imagen del producto.
`availability`	no	-	Estado de stock. Debe ser uno de `in stock`, `out of stock` o `preorder`.
`description`	no	-	Descripción detallada del producto.

Las categorías pueden proporcionarse de varias formas. Pero solo una es requerida. Puedes asociar un producto con más categorías y vendedores. Consulta la sección a continuación.

Ejemplos de archivos

Ejemplo 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	Green Mask	Green Mask for removing imperfections, use during night or day	1710000087	Derma Laboratories		10000087	Skin Care	61	Beauty & Health	https://i.postimg.cc/0QxMWmbd/shampoo.png	23935.29	out of stock
1302	Cleanser Gel	N/A	17829100	Shiny Laboratories		10000087	Skin care			https://i.postimg.cc/0QxMWmbd/shampoo.png	16050.42	in stock

Ejemplo 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,Green Mask,"Green Mask for removing imperfections, use during night or day",1710000087,Derma Laboratories,,10000087,Skin Care,61,Beauty & Health,https://i.postimg.cc/0QxMWmbd/shampoo.png,23935.29,out of stock
1302,Cleanser Gel,N/A,17829100,Shiny Laboratories,,10000087,Skin care,,,https://i.postimg.cc/0QxMWmbd/shampoo.png,16050.42,in stock

Múltiples categorías y vendedores

Los productos pueden asociarse con múltiples categorías y/o vendedores. Como habrás notado, las columnas de categoría y vendedor contienen índices. Puedes agregar columnas adicionales de categoría y/o vendedor siempre que aumentes el índice apropiadamente. Por ejemplo, un producto con tres categorías y dos vendedores tendría al menos estas columnas:

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

Formato de Taxonomía de Google

Alternativamente, puedes usar el Formato de Taxonomía de Google como nombres de categorías. Esto te permite describir relaciones jerárquicas más complejas. Por ejemplo, esta jerarquía:

Apparel & Accessories > Clothing > Dresses

Resultará en tres categorías:

[
  {
    "id": "apparel-and-accessories",
    "name": "Apparel & Accessories",
    "path": "apparel_and_accessories"
  },
  {
    "id": "clothing",
    "name": "Clothing",
    "path": "apparel_and_accessories.clothing",
    "parentId": "apparel-and-accessories"
  },
  {
    "id": "dresses",
    "name": "Dresses",
    "path": "apparel_and_accessories.clothing.dresses",
    "parentId": "clothing"
  }
]

El campo path es preferido para nuevas integraciones. El campo parentId sigue siendo completamente compatible — no hay planes de eliminarlo.

Alojar tu product feed

Tu product feed debe ser continuamente accesible para Topsort para que podamos mantener nuestros datos actualizados. Actualmente podemos acceder a product feeds públicos o feeds protegidos usando Basic HTTP Authorization. Además, usa los headers de respuesta ETag para ayudarnos a determinar si un product feed ha sido actualizado desde la última obtención.

Eliminar productos

Los productos pueden “eliminarse de forma suave” configurando la propiedad active en false. Esto puede hacerse tanto vía la API como vía el product feed. Los productos inactivos no se incluirán en nuevas campañas o subastas y se eliminarán de cualquier campaña activa de la que formen parte. Para eliminar permanentemente productos del sistema de Topsort, usa la API.

Slugs generados

Cuando las categorías o vendedores no tienen un ID, generamos uno al vuelo.

Preferible usar IDs explícitosSe recomienda proporcionar los IDs explícitamente en tu product feed, estos IDs se usan como referencias al gestionar campañas y subastas.Si usas IDs generados necesitarás usar el mismo algoritmo en el lado del marketplace para crear tales referencias.

Estos IDs usan un slug derivado del nombre. Un slug es una cadena formateada en kebab case que es adecuada para inclusión en URLs. Por ejemplo, Hello world se convierte en hello-world. El formato está basado en la biblioteca npm slugify.

Herramientas para desarrolladores

Los marketplaces que envían su catálogo mediante un product feed pueden abrir Dev Tools > Catálogo en el Panel de Administración del marketplace para monitorear el estado de la ingesta sin abrir un ticket de soporte. La pestaña Catálogo muestra las métricas clave de sincronización de un vistazo:

Hora de la última sincronización: cuándo se ejecutó la sincronización de catálogo más reciente
Duración media de la sincronización: cuánto suelen tardar las sincronizaciones
Tasa de éxito: en las últimas 14 ejecuciones
Ejecuciones de sincronización recientes: cada ingesta con cuántos registros se procesaron u omitieron

Con esta vista, los equipos de ingeniería pueden confirmar que los feeds se ejecutan según lo previsto y detectar rápidamente fallos o ejecuciones con muchos registros omitidos.

​Google Product Data Specification

​TSV y CSV

​Columnas Soportadas

​Ejemplos de archivos

​Ejemplo TSV usando vendor.0.name

​Ejemplo CSV usando vendor.0.name

​Múltiples categorías y vendedores

​Formato de Taxonomía de Google

​Alojar tu product feed

​Eliminar productos

​Slugs generados

​Herramientas para desarrolladores

Google Product Data Specification

TSV y CSV

Columnas Soportadas

Ejemplos de archivos

Ejemplo TSV usando vendor.0.name

Ejemplo CSV usando vendor.0.name

Múltiples categorías y vendedores

Formato de Taxonomía de Google

Alojar tu product feed

Eliminar productos

Slugs generados

Herramientas para desarrolladores