Jumbo Colombia Supermarket & Retail Scraper 🛒🇨🇴

Desbloquea el catálogo completo de jumbocolombia.com (Cencosud Colombia). Obtén acceso inmediato y en tiempo real a miles de productos, precios actualizados, descuentos, marcas, código de barras (EAN-13 / GTIN) y especificaciones técnicas detalladas. Extrae datos estructurados con máxima velocidad y estabilidad.

---

🌟 Casos de Uso Principales

• 📉 Monitoreo de Precios y Competencia: Rastrea cambios de precios diarios, ofertas y descuentos.
• 🏷️ Cruce de Datos por EAN: Extracción de códigos de barras (GTIN/EAN-13) para cruce de catálogo con INVIMA y otros supermercados.
• 📊 Inteligencia de Mercado: Análisis de marcas, departamentos, categorías y disponibilidad.

---

🔍 Modo Descubrimiento (discovery_mode)

[!IMPORTANT] ¿CÓMO FUNCIONAN LOS FILTROS EN JUMBO? Cada categoría en Jumbo tiene filtros específicos (Marca, Departamento, Categoría, Rango de Precio, etc.).

Si deseas conocer exactamente qué filtros existen para una búsqueda específica (ej. query=leche), activa el Modo Descubrimiento (discovery_mode: true).

[!WARNING] ATENCIÓN SOBRE EL MODO DESCUBRIMIENTO: Este modo se utiliza SOLAMENTE para detectar e identificar la lista de filtros válidos y sus opciones disponibles para una búsqueda. EL MODO DESCUBRIMIENTO NO EXTRAE PRODUCTOS.

Una vez que identifiques la clave y el valor del filtro que te interesa (ej. brand=COLANTA o priceMin=30000), desactiva el Modo Descubrimiento (discovery_mode: false) y coloca esos valores en los campos de entrada o en Filtros Dinámicos Adicionales (custom_filters).

---

🧾 Campos estándar para comparar cadenas (nuevo)

Además de los campos de siempre, cada producto trae columnas iguales en los scrapers de Éxito, Carulla, Jumbo y Olímpica, para cruzarlos sin limpiar datos:

Campo	Qué es
Cadena	Jumbo
EAN	Código de barras (EAN/GTIN) con dígito de control verificado. Es la llave para comparar el mismo producto entre cadenas.
SKU, Referencia_Cadena	Identificadores internos de la tienda.
Precio_Lista, Precio_Venta, Descuento_Pct, En_Promocion	Precios numéricos y descuento calculado.
Promociones	Nombres de las promociones activas (cuando la tienda las publica).
Contenido_Total, Unidad_Base, Unidades_Empaque	Contenido total del empaque en g, ml o unidades (ej. bolsa x6 de 1.100 ml = 6.600 ml).
Precio_Kg_L	Precio por kilo, por litro o por unidad: compara presentaciones distintas.
Disponible, Stock_Disponible	Disponibilidad online (el stock solo es informativo por debajo de 10.000).
Vendedor, Vendido_Por_Cadena	Quién vende: la cadena o un vendedor del marketplace.
Departamento, Categoria_Nivel_2, Categoria_Nivel_3, Ruta_Categoria	Árbol de categorías de la tienda.
Imagen_URL, Fecha_Extraccion, Moneda	Imagen, fecha UTC de la lectura y moneda (COP).

🧺 Modo canasta: los mismos productos en todas las cadenas (nuevo)

Ideal para monitorear precios todos los días con la misma canasta:

{
  "eans": ["7702001029716", "7702511000045"],
  "terms": ["leche deslactosada", "café molido"],
  "max_items_per_term": 50
}

• eans: busca cada código de barras y devuelve ese producto exacto. Los que la cadena no vende quedan en el registro OUTPUT como no_encontrados.
• terms: toma los primeros max_items_per_term productos de cada búsqueda, sin repetir, con el mismo orden en todas las cadenas.
• Si usas cualquiera de los dos, el actor no hace la búsqueda normal. Corre la misma entrada en los cuatro scrapers y une los resultados por EAN.

⚙️ Parámetros de Entrada (Input)

Parámetro	Tipo	Descripción	Ejemplo
search_term	String	Palabra clave o término de búsqueda en Jumbo.	"leche"
brand	String	Selección o slug de Marca.	"COLANTA"
price	String	Rango de precio en pesos colombianos Min:Max.	"30000:50000"
max_items	Integer	Cantidad máxima de productos a extraer. Usa 0 para sin límite.	100
discovery_mode	Boolean	SOLO para detectar filtros. Si se activa, devuelve los filtros disponibles y se detiene (NO extrae productos).	false
custom_filters	String	Filtros dinámicos adicionales en formato Clave=Valor separados por coma.	"brand=COLANTA,priceMin=30000,priceMax=50000"

---

📊 Ejemplo de Resultados (Output)

{
  "ID": "206584",
  "Nombre": "Leche Entera Colanta Bolsa x6 Und x1000ml",
  "Marca": "COLANTA",
  "Precio_Original": 32600,
  "Precio_Final": 32600,
  "URL_Producto": "https://www.jumbocolombia.com/leche-entera-colanta-bolsa-x6-und-x1000ml-3509862/p",
  "Informacion_Adicional": {
    "EAN": "7702129004961",
    "Referencia": "3509862",
    "Categoria": "Leche",
    "Tipo de Producto": "Leche Entera",
    "Origen": "Nacional",
    "País de Origen": "Colombia",
    "Descripcion": "Buena fuente de proteina y calcio con un sabor inigualable. Combinala con cereales, tortas, galletas y más."
  }
}

---

🛠️ Ejecución Local

pip install -r requirements.txt
python3 -m src