Prepara tu feed de productos

Esta guía explica cómo dar formato a los datos de tus productos para The Comparator. Un feed limpio y preciso garantiza que tus ofertas se emparejen correctamente con los componentes de hardware en nuestra base de datos normalizada.

1. Qué es un feed de productos

Un feed de productos es un archivo de datos estructurado que contiene el inventario actual, precios y disponibilidad de stock de tu tienda.

• Un registro = una oferta: Cada fila u objeto representa una variante específica de un componente de hardware.
• Identificadores estables: El SKU o ID de tus productos no debe cambiar entre actualizaciones del feed. Esto permite a nuestro sistema rastrear el historial de precios y disponibilidad sin generar registros duplicados.
• Independencia del Motor de Valor: Enviar un feed registra tu tienda en nuestros bloques de comparación de “Dónde Comprar”. No altera la Puntuación de Valor ni la posición orgánica de ningún producto, las cuales se calculan de manera estrictamente algorítmica.

2. Métodos de envío compatibles

Actualmente, la integración de una nueva tienda requiere un proceso de incorporación asistida. Proporcionas la URL o el archivo del feed y nuestro equipo de integración configura el mapeo de importación.

3. Referencia exacta de campos

Nuestro pipeline de importación acepta los siguientes campos. Asegúrate de que las columnas de tu feed o las claves JSON correspondan con estas definiciones.

4. Reglas para IDs de producto estables

Tu campo id es la clave principal que vincula tu oferta con nuestra base de datos.

• No cambies el ID cuando cambie el precio o el estado de stock de un producto.
• No reutilices un ID antiguo para un modelo de hardware diferente.
• No uses números de fila ni generes UUIDs aleatorios en cada exportación.
• Caracteres permitidos: Alfanuméricos, guiones y guiones bajos ([A-Za-z0-9_-]). Máximo 64 caracteres.

5. Títulos de productos de hardware

El emparejamiento de hardware recurre al análisis de títulos cuando no se dispone de GTIN o MPN. Redacta títulos técnicos y precisos en lugar de eslóganes publicitarios.

GPU (Tarjetas Gráficas)

Incluye ensamblador (AIB), modelo exacto del chip GPU, capacidad de VRAM y sufijos (Ti, SUPER, XT, XTX).

• Correcto: ASUS TUF Gaming GeForce RTX 4070 Ti SUPER OC 16GB
• Incorrecto: Increíble Tarjeta Gráfica Gamer RTX 4070 - ¡Mejor Oferta!

CPU (Procesadores)

Incluye Marca, número exacto de modelo y sufijos (K, KF, F, X, X3D).

• Correcto: AMD Ryzen 7 7800X3D Boxed
• Incorrecto: Procesador Rápido AMD de 8 Núcleos para PC

SSD (Discos de Estado Sólido)

Incluye Marca, Serie/Modelo, Capacidad, Factor de Forma e Interfaz.

• Correcto: Samsung 990 PRO 2TB NVMe M.2 PCIe 4.0 SSD
• Incorrecto: Disco Duro Interno Ultrarrápido de 2TB

RAM (Memoria)

Incluye Marca, Serie, Capacidad Total, Número de Módulos, Generación y Velocidad.

• Correcto: G.SKILL Trident Z5 RGB 32GB (2x16GB) DDR5 6000MHz CL30
• Incorrecto: Kit de Memoria RAM de Alta Velocidad de 32GB

Placas Base

Incluye Marca, Modelo, Chipset, Socket y revisión de conectividad Wi-Fi.

• Correcto: MSI MAG B650 TOMAHAWK WIFI ATX AM5 Motherboard
• Incorrecto: Placa Base Gamer MSI AM5

6. Identificadores de producto (GTIN, MPN, Marca)

• GTIN (EAN / UPC): Deben ser identificadores GS1 válidos. No introduzcas SKUs internos en el campo GTIN.
• MPN: Incluye el número de parte exacto del fabricante (ej. 100-100000910WOF). No elimines guiones ni sufijos.
• Marca: Nombre canónico del fabricante (ej. ASUS, Gigabyte, MSI, AMD, Intel, NVIDIA, Western Digital).

7. Precio y moneda

• Formato: Número decimal simple sin símbolos de moneda (ej. 599.99, no $599.99).
• Moneda: Actualmente solo se admite USD.
• Coincidencia con la Página de Destino: El precio en el feed debe coincidir con el precio mostrado en tu página de producto. Los precios ocultos condicionados a cupones en el checkout están prohibidos.

8. Mapeo de disponibilidad

Normalizamos la disponibilidad de tu tienda en estados internos estandarizados:

9. Estándares de condición

The Comparator clasifica las ofertas en tres categorías de condición:

• New: Producto nuevo a estrenar, precintado de fábrica con garantía total del fabricante.
• Refurbished: Reacondicionado por el fabricante o la tienda. Debe indicarse explícitamente.
• Used: Producto de segunda mano o usado.

10. Requisitos de URLs de producto

• Deben dirigir directamente a la página individual del producto (no a páginas de búsqueda o categorías).
• Deben ser accesibles públicamente sin inicio de sesión, cookies obligatorias ni bloqueos por captcha.
• Deben utilizar URLs HTTPS canónicas y limpias.

11. Requisitos de URLs de imágenes

• URL directa al archivo de imagen (.jpg, .png, .webp) mediante HTTPS.
• No deben dirigir a visores HTML ni requerir autenticación.

12. Variantes, kits y paquetes

• Kits de RAM y SSDs: Indica la capacidad total exacta y el desglose de módulos (ej. 32GB (2x16GB)).
• Combos de Componentes y PCs Premontados: NO COMPATIBLES. Nuestro pipeline (isComboListing) rechaza automáticamente combos de CPU+Placa, cajas y PCs completos. Envía únicamente componentes individuales.

13. Políticas de actualización y eliminación

• Intervalo de Sincronización: Sincronización estándar cada 24 horas. Cuentas prioritarias sincronizan cada hora.
• Filas Faltantes: Si un SKU de producto desaparece en 2 descargas consecutivas, se marca como out_of_stock.
• Feeds Inactivos: Si la descarga de un feed falla durante más de 48 horas, todas las ofertas de la tienda se ocultan temporalmente hasta restablecer el servicio.

14. Etapas del proceso de validación

Nuestro sistema valida los datos a través de 3 niveles de severidad:

[Descarga del Feed] ➔ [Procesamiento] ➔ [Validación de Esquema] ➔ [Mapeo de Hardware] ➔ [Publicación]

• 🔴 Error (Bloqueante): SKU ausente, precio malformado o JSON/XML ilegible. La oferta es rechazada.
• 🟡 Advertencia (No bloqueante): Falta enlace de imagen o GTIN. La oferta se publica, pero se marca para revisión manual.
• 🔵 Información: Sugerencias para optimizar el formato de los títulos.

15. Solución de errores comunes

16. Lista de comprobación previa al envío

• Los IDs de producto (SKUs) son estables, únicos y no están vacíos.
• Los precios son números decimales sin símbolos como $.
• La moneda está configurada explícitamente en USD.
• La disponibilidad de stock es precisa (in_stock / out_of_stock).
• Los títulos contienen especificaciones exactas (VRAM, Modelo, Sufijos).
• Se proporciona al menos un identificador (gtin o mpn) por fila.
• Se excluyen combos y equipos premontados.
• Las URLs de producto abren directamente sin autenticación.

17. Archivos de ejemplo listos para usar

Descarga nuestros feeds de muestra validados para comprobar tu configuración:

• 📄 Descargar Feed CSV de Ejemplo
• 📄 Descargar Feed JSON de Ejemplo
• 📄 Descargar Feed XML de Google Merchant de Ejemplo

Puedes validar tus feeds de muestra localmente ejecutando:

node scripts/test_sample_feeds.js