wallabicher/platforms

Plataformas de Monitoreo

Este directorio contiene las implementaciones de las diferentes plataformas de marketplace que el monitor puede usar.

Estructura

• base_platform.py: Clase abstracta que define la interfaz común para todas las plataformas
• platform_factory.py: Factory para crear instancias de plataformas dinámicamente
• wallapop_platform.py: Implementación para Wallapop
• vinted_platform_template.py: Plantilla de ejemplo para añadir nuevas plataformas

Cómo añadir una nueva plataforma

1. Crear la clase de la plataforma

Crea un nuevo archivo <platform_name>_platform.py que herede de BasePlatform:

from platforms.base_platform import BasePlatform
from models.article import Article
import requests
import logging

class MiPlataformaPlatform(BasePlatform):
    def __init__(self, item_monitor):
        super().__init__(item_monitor)
        self.logger = logging.getLogger(__name__)
    
    def get_platform_name(self):
        return "mi_plataforma"
    
    def create_url(self):
        # Construye la URL de búsqueda usando self._item_monitor
        url = f"https://api.miplataforma.com/search?q={self._item_monitor.get_search_query()}"
        
        # Añade parámetros opcionales según la configuración
        if self._item_monitor.get_min_price() != 0:
            url += f"&min_price={self._item_monitor.get_min_price()}"
        
        return url
    
    def fetch_articles(self):
        # Obtiene artículos desde la API
        url = self.create_url()
        headers = self.get_request_headers()
        
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        
        data = response.json()
        return self.parse_response(data)
    
    def parse_response(self, response_data):
        # Parsea la respuesta y crea objetos Article
        articles = []
        for item in response_data['items']:
            article = Article(
                id=item['id'],
                title=item['title'],
                description=item['description'],
                price=item['price'],
                currency=item['currency'],
                location=item['location'],
                allows_shipping=item['shipping'],
                url=item['url'],
                images=item['images'][:3],
                modified_at=item['date'],
                platform=self.get_platform_name()
            )
            articles.append(article)
        
        return articles

2. Registrar la plataforma en el Factory

Edita platform_factory.py y añade tu plataforma al diccionario _platforms:

from platforms.mi_plataforma_platform import MiPlataformaPlatform

class PlatformFactory:
    _platforms = {
        'wallapop': WallapopPlatform,
        'mi_plataforma': MiPlataformaPlatform,  # <-- Añade aquí
    }

3. Configurar workers.json

Añade el campo platform a tus items en workers.json:

{
  "items": [
    {
      "name": "Mi búsqueda",
      "platform": "mi_plataforma",
      "search_query": "gameboy",
      "min_price": 10,
      "max_price": 100,
      ...
    }
  ]
}

Parámetros disponibles en ItemMonitor

Tu plataforma puede usar los siguientes parámetros de configuración:

• get_name(): Nombre del monitor
• get_search_query(): Términos de búsqueda
• get_latitude() / get_longitude(): Coordenadas geográficas
• get_max_distance(): Distancia máxima en km
• get_condition(): Estado del artículo
• get_min_price() / get_max_price(): Rango de precios
• get_title_exclude(): Palabras a excluir del título
• get_description_exclude(): Palabras a excluir de la descripción
• get_title_must_include(): Palabras requeridas en el título
• get_description_must_include(): Palabras requeridas en la descripción
• get_title_first_word_exclude(): Primera palabra del título a excluir
• get_check_every(): Intervalo de verificación en segundos
• get_thread_id(): ID del hilo de Telegram

Nota: Los filtros de título y descripción son aplicados automáticamente por el Worker, no necesitas implementarlos en tu plataforma.

Modelo Article

Todas las plataformas deben devolver objetos Article con los siguientes campos:

• id: Identificador único del artículo en la plataforma
• title: Título del artículo
• description: Descripción (se trunca a 500 caracteres)
• price: Precio numérico
• currency: Código de moneda (EUR, USD, etc.)
• location: Ubicación del vendedor
• allows_shipping: Boolean indicando si permite envíos
• url: URL del artículo
• images: Lista de URLs de imágenes (máximo 3)
• modified_at: Fecha de modificación (string "YYYY-MM-DD HH:MM:SS")
• platform: Nombre de la plataforma

Lógica común del Worker

El Worker maneja automáticamente:

• ✅ Filtrado por palabras excluidas en título/descripción
• ✅ Filtrado por palabras requeridas en título/descripción
• ✅ Filtrado por primera palabra del título
• ✅ Deduplicación de artículos
• ✅ Envío de notificaciones a Telegram
• ✅ Gestión de errores y reintentos
• ✅ Logging y estadísticas

Tu plataforma solo debe encargarse de:

• 🔧 Construir la URL de búsqueda específica de la plataforma
• 🔧 Hacer la petición HTTP con los headers apropiados
• 🔧 Parsear la respuesta y convertirla a objetos Article