Academia de Tiendas | PC Part Comparator

Gestiona tu feed y resultados de mapeo

Mon, 01 Jan 0001 00:00:00 +0000

Gestiona tu feed y resultados de mapeo

The Comparator utiliza un flujo de trabajo de integración asistida y gestión operativa. En este momento no disponemos de un panel de autoservicio o inicio de sesión para tiendas.

Esta guía explica cómo interactúa tu tienda con nuestro equipo de integración, cómo leer tus informes de mapeo en CSV y cómo enviar correcciones.

1. Resumen del Flujo Operativo

Dado que el emparejamiento de hardware exige máxima precisión técnica, nuestro equipo de ingeniería gestiona el pipeline de ingesta.

[1. Enviar Feed] ➔ [2. Ingesta y Validación] ➔ [3. Informe CSV de Mapeo] ➔ [4. Enviar Correcciones] ➔ [5. Sincronización en Vivo]

Enviar Solicitud y Feed: Envías la solicitud de tu tienda y la URL del feed mediante .
Ingesta Inicial del Pipeline: Nuestro sistema descarga tu feed, valida las reglas de esquema e intenta emparejar las ofertas con nuestra base de datos de referencia (ref_specs.json).
Recibir Informe CSV de Mapeo: Nuestro equipo te envía por correo electrónico un informe CSV con los artículos emparejados, ambiguos y rechazados.
Revisar y Corregir: Revisas el CSV, actualizas los MPN/GTIN faltantes en tu catálogo o anotas las correcciones, y lo respondes a retailers@thecomparator.tech.
Publicación y Sincronización: Aplicamos tus correcciones a la configuración del pipeline (corrections.json). Tus productos emparejados aparecen activos en las tablas de comparación.

2. Interfaz de Integración y Capturas

Interfaz de Solicitud de Tienda (`/retailers/apply/`)

Al registrar tu tienda, envías tus datos a través de nuestro formulario de solicitud de socios:

Figura 1: El formulario de solicitud de socios. El texto de confirmación indica que no se requiere inicio de sesión en un portal ni llamadas de configuración en esta etapa.

Referencia de Requisitos del Feed (`/retailers/feed-requirements/`)

Puedes consultar las directrices técnicas para formatos de feed en cualquier momento:

Figura 2: La página de requisitos técnicos de feed con el detalle de las estructuras CSV, JSON y XML aceptadas.

3. Interpretación del Informe de Mapeo (Formato CSV)

Tras procesar tu feed, nuestro equipo genera un Informe de Mapeo en formato CSV.

Estructura del Informe de Mapeo CSV

Encabezado	Valor de Ejemplo	Descripción
`sku`	`GPU-4070S-01`	Tu identificador interno de producto (SKU).
`feed_title`	`ASUS TUF Gaming GeForce RTX 4070 Ti SUPER OC 16GB`	Título original del producto en tu feed.
`matched_model`	`NVIDIA GeForce RTX 4070 Ti SUPER`	Modelo canónico en la base de datos de The Comparator.
`status`	`Matched`	Resultado del procesamiento (`Matched`, `Ambiguous`, `Review`, `Rejected`).
`issue_code`	`NONE`	Código de diagnóstico para advertencias o rechazos.
`live_url`	`https://thecomparator.tech/gpu/rtx-4070-ti-super/`	Página de The Comparator donde se publica la oferta.

4. Significado de Estados y Códigos de Diagnóstico

Definiciones de Estado de Mapeo

✅ Matched: El artículo fue identificado correctamente y emparejado con un modelo canónico. Se mostrará en vivo cuando esté in_stock.
⚠️ Ambiguous: Nuestro algoritmo encontró varias coincidencias posibles (ej. no pudo distinguir entre versiones de 12GB y 16GB por un título impreciso). Requiere corrección manual.
🔍 Review: La oferta fue marcada para revisión manual (ej. precio un 40% inferior a la media de mercado). Retenida hasta su comprobación.
❌ Rejected: La oferta no puede importarse (ej. categoría no admitida o combo).

Códigos de Diagnóstico

NON_COMPONENT_ACCESSORY: El artículo es una caja de PC, bloque de agua o soporte. (Ignorado de forma segura por el importador).
PRICE_ANOMALY: El precio está fuera de los rangos normales de hardware.
ERR_NO_IDENTIFIER: El título es impreciso y no se proporcionó GTIN ni MPN.
COMBO_OR_BUNDLE: El producto contiene varios componentes (rechazado por el filtro isComboListing).

5. Cómo Enviar Correcciones de Mapeo

Si un artículo fue marcado como Ambiguous o asignado al modelo incorrecto:

Abre el informe CSV en Excel o Google Sheets.
Añade una columna llamada Correction.
Introduce el nombre canónico exacto del componente o su URL en The Comparator (ej. https://thecomparator.tech/gpu/rtx-4070-super/).
Envía el CSV anotado a retailers@thecomparator.tech con el asunto Correcciones de Mapeo - [Nombre de tu Tienda].

Nuestro equipo aplica tus correcciones en un plazo de 24 horas, actualizando cpu_corrections.json o mobo_sata_corrections.json en el pipeline.

6. Notificación de Ofertas Incorrectas en Vivo

Si una oferta activa muestra un precio erróneo o enlaza a una página equivocada:

Comprueba tu feed de origen para asegurarte de que el SKU y el precio son correctos.
Envía un correo a retailers@thecomparator.tech con el asunto: URGENTE: Desajuste de Precio en Vivo - [Nombre de tu Tienda].
Incluye el SKU, la URL activa errónea y el enlace correcto de la página de destino.
Las incidencias urgentes se procesan en un plazo máximo de 4 horas.

Prepara tu feed de productos

Mon, 01 Jan 0001 00:00:00 +0000

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.

Método de Envío	¿Compatible?	Formato	Autenticación	Tamaño Máximo	Frecuencia de Actualización	Notificación de Errores
URL Pública de Feed	Sí (Preferido)	CSV / JSON / XML	HTTP Basic Auth o Ninguna	50 MB	Programada (Diaria/Horaria)	Informe de Mapeo por Email
XML Google Merchant	Sí	RSS 2.0 XML	Ninguna	50 MB	Programada	Informe de Mapeo por Email
Red de Afiliación	Sí	Feed de Red	Autenticación de Red	Según la Red	Diaria	Informe de Mapeo por Email
API Autoservicio	Planificada	REST / Webhooks	Bearer Token	N/A	Tiempo Real	Respuesta de API

Nota

Nota Operativa: Si tu feed requiere autenticación o autorización de IP, incluye los detalles en tu solicitud en .

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.

Campo	Estado Obligatorio	Tipo de Dato	Ejemplo	Regla de Validación	Uso Principal
`id`	Obligatorio	String	`GPU-4070S-01`	No vacío, único por artículo, máx. 64 caracteres	Seguimiento de SKU e historial de precios
`title`	Obligatorio	String	`ASUS TUF Gaming GeForce RTX 4070 Ti SUPER OC 16GB`	Debe contener marca y modelo de hardware	Mapeo de modelo y visualización en interfaz
`link`	Obligatorio	URL	`https://example.com/gpu-4070`	URL HTTP/HTTPS válida, accesible sin inicio de sesión	Redirección de compradores a la compra
`price`	Obligatorio	Decimal	`599.99`	Número positivo, 2 decimales	Cálculo de valor y visualización
`currency`	Obligatorio	String	`USD`	Debe ser `USD` (mercado estadounidense activo)	Normalización de precios
`availability`	Obligatorio	String	`in_stock`	Debe coincidir con los estados de stock aceptados	Filtrado de ofertas activas
`condition`	Obligatorio	String	`New`	`New`, `Refurbished` o `Used`	Agrupación en el Motor de Valor
`brand`	Obligatorio	String	`ASUS`	Nombre de fabricante no vacío	Identificación por Hardware Fingerprinting
`gtin`	Condicionalmente Obligatorio	String	`4711387450889`	Dígitos válidos EAN/UPC (12-14 dígitos)	Emparejamiento exacto de producto
`mpn`	Condicionalmente Obligatorio	String	`90YV0J80-M0NA00`	Número de pieza exacto del fabricante	Emparejamiento exacto de producto
`image_link`	Recomendado	URL	`https://example.com/img.jpg`	URL de imagen directa válida (HTTPS)	Elementos visuales de respaldo
`shipping`	Opcional	Decimal	`9.99`	Decimal no negativo	Costo Total de Propiedad (TCO)

Importante

Requisito de Identificadores: Debes proporcionar un gtin o un mpn válido (o ambos) para un emparejamiento fiable. Los feeds basados únicamente en títulos tienen una tasa de rechazo un 35% mayor por ambigüedad.

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:

Valor en el Feed	Estado Interno Normalizado	¿Se Publica en el Sitio?	Notas
`in_stock`, `available`, `instock`	`in_stock`	Sí	Visible en la tabla de comparación activa.
`out_of_stock`, `sold_out`, `unavailable`	`out_of_stock`	No	Oculto de la vista por defecto (archivado).
`preorder`, `backorder`	`preorder`	No	Pausado temporalmente hasta la llegada de stock.

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.

Advertencia

No etiquetes artículos reacondicionados o usados como New. El etiquetado incorrecto conlleva la suspensión permanente de la tienda.

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

Código de Error	Descripción del Problema	Ejemplo Incorrecto	Ejemplo Corregido	¿Bloqueante?
`ERR_MISSING_ID`	El campo SKU está vacío	`""`	`"GPU-4070-01"`	🔴 Sí
`ERR_INVALID_PRICE`	Símbolo de moneda en el precio	`"$599.99"`	`599.99`	🔴 Sí
`ERR_UNSUPPORTED_CURRENCY`	La moneda no es USD	`"EUR"`	`"USD"`	🔴 Sí
`ERR_AMBIGUOUS_TITLE`	El título carece de datos del modelo	`"Tarjeta NVIDIA RTX"`	`"ASUS RTX 4070 SUPER 12GB"`	🔴 Sí
`ERR_COMBO_REJECTED`	Combo de componentes detectado	`"Combo Ryzen 7 + B650"`	Excluir del feed	🔴 Sí
`WARN_MISSING_GTIN`	Sin GTIN ni MPN proporcionado	`gtin: ""`	`gtin: "4711387450889"`	🟡 No

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:

📄
📄
📄

Puedes validar tus feeds de muestra localmente ejecutando:

node scripts/test_sample_feeds.js

Academia de Tiendas | PC Part Comparator

Gestiona tu feed y resultados de mapeo

Gestiona tu feed y resultados de mapeo

1. Resumen del Flujo Operativo

2. Interfaz de Integración y Capturas

Interfaz de Solicitud de Tienda (/retailers/apply/)

Referencia de Requisitos del Feed (/retailers/feed-requirements/)

3. Interpretación del Informe de Mapeo (Formato CSV)

Estructura del Informe de Mapeo CSV

4. Significado de Estados y Códigos de Diagnóstico

Definiciones de Estado de Mapeo

Códigos de Diagnóstico

5. Cómo Enviar Correcciones de Mapeo

6. Notificación de Ofertas Incorrectas en Vivo

Prepara tu feed de productos

Prepara tu feed de productos

1. Qué es un feed de productos

2. Métodos de envío compatibles

3. Referencia exacta de campos

4. Reglas para IDs de producto estables

5. Títulos de productos de hardware

GPU (Tarjetas Gráficas)

CPU (Procesadores)

SSD (Discos de Estado Sólido)

RAM (Memoria)

Placas Base

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

7. Precio y moneda

8. Mapeo de disponibilidad

9. Estándares de condición

10. Requisitos de URLs de producto

11. Requisitos de URLs de imágenes

12. Variantes, kits y paquetes

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

14. Etapas del proceso de validación

15. Solución de errores comunes

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

17. Archivos de ejemplo listos para usar

Interfaz de Solicitud de Tienda (`/retailers/apply/`)

Referencia de Requisitos del Feed (`/retailers/feed-requirements/`)