Wallabicher 🛎️

Automatiza tus búsquedas en marketplaces (Wallapop, Vinted, etc.) y recibe notificaciones instantáneas en Telegram cuando aparezcan nuevos artículos! Wallabicher monitoriza múltiples plataformas según tus parámetros personalizados, analiza novedades y te avisa en tiempo real a tu canal o chat de Telegram.

Índice

• Instalación
• Configuración
• Uso
• Nuevas Funcionalidades
• Arquitectura Multi-Plataforma
• Añadir Nuevas Plataformas

Instalación 🔧

1. Instala las dependencias necesarias:

   pip3 install -r requirements.txt
   

2. Configura los archivos de configuración:

   Opción A - Automática (recomendado):

   python setup_config.py
   

   Este script creará automáticamente config.yaml y workers.json desde los archivos de muestra si no existen.

   Opción B - Manual:

   cp config.sample.yaml config.yaml
   cp workers.sample.json workers.json
   

3. Edita config.yaml con tus credenciales de Telegram:

   telegram_channel: "@Tu_Canal_Telegram"
   telegram_token: "Tu_Token_De_Telegram"
   

4. Personaliza workers.json con tus búsquedas deseadas (ver sección Configuración)

Configuración 🛠️

Crea un archivo args.json con los parámetros de búsqueda. Wallabicher permite definir múltiples búsquedas y personalizar criterios para filtrar exactamente lo que quieres recibir.

Parámetros:

Parámetro	Descripción	Ejemplo	Obligatorio
platform	Plataforma a monitorizar: wallapop, vinted, etc. (por defecto: wallapop)	"wallapop"	No
search_query	Término de búsqueda principal; solo se mostrarán artículos con este texto en el título.	"laptop"	Sí
min_price	Precio mínimo del artículo.	100	Sí
max_price	Precio máximo del artículo.	500	Sí
latitude	Latitud para filtrar por distancia respecto a una ubicación.	40.4165	No
longitude	Longitud para filtrar por distancia respecto a una ubicación.	-3.70256	No
max_distance	Rango máximo en metros desde la latitud/longitud especificadas. Usa 0 para ilimitado.	10000	No
condition	Estado del artículo: all, new, as_good_as_new, good, fair, has_given_it_all.	"good"	No
title_exclude	Lista de palabras: si alguna está en el título, se descarta el anuncio.	["estropeado", "partes"]	No
description_exclude	Lista de palabras: si alguna aparece en la descripción, se descarta el anuncio.	["dañado"]	No
title_must_include	Palabras requeridas en el título: si no aparece alguna, se descarta.	["Intel", "i5"]	No
description_must_include	Palabras requeridas en la descripción: si no aparece alguna, se descarta.	["funciona"]	No
title_first_word_exclude	Lista de palabras: si el primer término del título coincide, se descarta. (Nuevo)	["Reacondicionado"]	No
check_every	Cada cuántos segundos se actualiza la búsqueda (por defecto, 30s si no se especifica).	15	No
thread_id	ID del tema/hilo de Telegram donde se enviarán los mensajes. Si no se especifica, se envía al tema general. (Nuevo)	2	No

Consulta el archivo de ejemplo args.json para ver cómo estructurarlo.

Nuevas Funcionalidades 🌟

• Filtrado más avanzado: ahora puedes filtrar artículos por el primer término del título.
• Multiples criterios combinados para ignorar anuncios indeseados o exigir palabras clave.
• Recibes una galería de imágenes en cada notificación, no solo una imagen.
• El código es más modular y fácil de personalizar para diferentes búsquedas simultáneas.

Sistema de Favoritos ⭐

• Botones interactivos: Cada artículo incluye un botón "⭐ Añadir a favoritos" para guardar rápidamente los que te interesan.
• Comando /favs: Escribe /favs en tu chat de Telegram para ver todos tus artículos favoritos guardados.
• Gestión completa: Puedes añadir y eliminar artículos de favoritos con un solo clic.
• Persistencia: Todos tus favoritos se guardan en favorites.json y persisten entre reinicios.
• Enlaces directos: Cada favorito incluye un enlace directo al mensaje original en Telegram.

Soporte para Temas de Telegram 📌

Wallabicher ahora soporta grupos de Telegram con temas (topics/hilos). Puedes organizar tus notificaciones enviando cada búsqueda a su tema correspondiente:

• Configuración por worker: Añade el parámetro thread_id a cada búsqueda en workers.json con el ID del tema donde quieres recibir las notificaciones.
• Tema general: Si un worker no tiene especificado el thread_id, los mensajes se enviarán al tema general del grupo.
• Cómo obtener el thread_id:
  1. En tu grupo de Telegram, haz clic en el tema donde quieres enviar notificaciones
  2. Copia el enlace del tema (tiene el formato: https://t.me/c/XXXXX/THREAD_ID)
  3. El número después de la última barra es el thread_id

Ejemplo en workers.json:

{
  "name": "Nintendo 64",
  "platform": "wallapop",
  "search_query": "nintendo 64",
  "thread_id": 6
}

Arquitectura Multi-Plataforma 🏗️

Wallabicher ahora soporta múltiples plataformas de marketplace mediante una arquitectura desacoplada y extensible:

Plataformas Soportadas

• ✅ Wallapop - Totalmente funcional
• ✅ Vinted - Implementado (ver nota sobre limitaciones)
• 🚧 Buyee - Por implementar
• 🚧 Tu plataforma - ¡Fácil de añadir!

Características de la Arquitectura

• Desacoplada: La lógica de filtrado es común para todas las plataformas
• Extensible: Añade nuevas plataformas sin modificar el código existente
• Modular: Cada plataforma implementa solo su lógica específica
• Factory Pattern: Instanciación dinámica de plataformas

Estructura del Proyecto

wallamonitor/
├── platforms/              # Implementaciones de plataformas
│   ├── base_platform.py    # Clase abstracta base
│   ├── platform_factory.py # Factory para crear plataformas
│   ├── wallapop_platform.py # Implementación de Wallapop
│   ├── vinted_platform_template.py # Plantilla para Vinted
│   └── README.md           # Documentación de plataformas
├── models/                 # Modelos de datos genéricos
│   └── article.py          # Modelo Article (común a todas las plataformas)
├── managers/               # Gestores de lógica de negocio
│   ├── worker.py           # Worker con filtros comunes
│   ├── queue_manager.py    # Gestión de cola de notificaciones
│   └── telegram_manager.py # Gestión de Telegram
└── datalayer/              # Capa de datos
    ├── item_monitor.py     # Configuración de monitoreo
    └── general_monitor.py  # Configuración global

Añadir Nuevas Plataformas 🔧

Para añadir una nueva plataforma de marketplace:

1. Crea tu clase de plataforma heredando de BasePlatform:

   from platforms.base_platform import BasePlatform
   from models.article import Article
   
   class MiPlataformaPlatform(BasePlatform):
       def get_platform_name(self):
           return "mi_plataforma"
   
       def create_url(self):
           # Construir URL de búsqueda
           pass
   
       def fetch_articles(self):
           # Obtener artículos
           pass
   
       def parse_response(self, data):
           # Parsear respuesta a objetos Article
           pass
   

2. Registra la plataforma en platform_factory.py:

   from platforms.mi_plataforma_platform import MiPlataformaPlatform
   
   _platforms = {
       'wallapop': WallapopPlatform,
       'mi_plataforma': MiPlataformaPlatform,
   }
   

3. Configura workers.json con tu nueva plataforma:

   {
     "name": "Mi búsqueda",
     "platform": "mi_plataforma",
     "search_query": "gameboy",
     ...
   }
   

Consulta platforms/README.md y platforms/vinted_platform_template.py para más detalles y ejemplos completos.

Uso de Vinted

Vinted está implementado y funcional, pero puede experimentar bloqueos debido a protecciones anti-bot:

{
  "name": "Gameboy Vinted",
  "platform": "vinted",
  "country": "es",
  "search_query": "gameboy",
  "min_price": 15,
  "max_price": 120,
  "check_every": 180
}

Países soportados: es, fr, de, it, pl, cz, lt, uk, us, nl, be, at

Importante: Usa check_every de 120-300 segundos para evitar bloqueos. Ver VINTED_NOTES.md para más detalles y alternativas.

Uso 🚀

1. Asegúrate de completar tu archivo workers.json con los parámetros deseados para tus búsquedas.

2. Ejecuta Wallabicher:

   python3 wallamonitor.py
   

El bot revisará Wallapop periódicamente (configurable, por defecto cada 30s) y enviará notificaciones a tu canal o chat de Telegram siempre que aparezcan artículos nuevos que encajen con tus filtros.