207 lines
12 KiB
Markdown
207 lines
12 KiB
Markdown
|
|
# 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](#instalación-)
|
|
- [Configuración](#configuración-)
|
|
- [Uso](#uso-)
|
|
- [Nuevas Funcionalidades](#nuevas-funcionalidades-)
|
|
- [Arquitectura Multi-Plataforma](#arquitectura-multi-plataforma-)
|
|
- [Añadir Nuevas Plataformas](#añadir-nuevas-plataformas-)
|
|
|
|
## Instalación 🔧
|
|
|
|
1. Instala las dependencias necesarias:
|
|
```bash
|
|
pip3 install -r requirements.txt
|
|
```
|
|
|
|
2. Configura tus credenciales de Telegram en el archivo `config.yaml`:
|
|
```yaml
|
|
telegram_channel: "@Tu_Canal_Telegram"
|
|
telegram_token: "Tu_Token_De_Telegram"
|
|
telegram_chat_id: "Tu_Chat_ID_Telegram"
|
|
```
|
|
|
|
## 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](./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**:
|
|
```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`:
|
|
```python
|
|
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`:
|
|
```python
|
|
from platforms.mi_plataforma_platform import MiPlataformaPlatform
|
|
|
|
_platforms = {
|
|
'wallapop': WallapopPlatform,
|
|
'mi_plataforma': MiPlataformaPlatform,
|
|
}
|
|
```
|
|
|
|
3. **Configura workers.json** con tu nueva plataforma:
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
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.
|
|
|