---
id: "US-SCR-001"
title: "Scraping de propiedades desde Inmuebles24"
type: "User Story"
epic: "IAI-007"
status: "Draft"
story_points: 13
priority: "Alta"
project: "inmobiliaria-analytics"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---

# US-SCR-001: Scraping de propiedades desde Inmuebles24

---

## User Story

**Como** administrador del sistema
**Quiero** que el sistema extraiga automaticamente propiedades de Inmuebles24
**Para** tener datos actualizados del mercado inmobiliario mexicano

---

## Descripcion

Implementar un scraper robusto que extraiga listados de propiedades del portal Inmuebles24, manejando la proteccion de Cloudflare y respetando las politicas de rate limiting para evitar bloqueos.

---

## Criterios de Aceptacion

### Funcionales

- [ ] El scraper puede navegar y extraer listados de propiedades
- [ ] Extrae todos los campos requeridos (precio, ubicacion, caracteristicas)
- [ ] Maneja paginacion hasta el limite configurado
- [ ] Almacena datos raw en formato JSON

### Tecnicos

- [ ] Usa Playwright con stealth mode
- [ ] Rotacion de proxies residenciales
- [ ] Delay configurable entre requests (2-5s base)
- [ ] Manejo de reintentos con backoff exponencial

### Anti-detection

- [ ] Simula comportamiento humano (scroll, delays)
- [ ] User-Agent rotativo y realista
- [ ] Maneja desafios de Cloudflare Turnstile
- [ ] Respeta robots.txt (paginas 1-5 inicialmente)

---

## Campos a Extraer

```yaml
Requeridos:
  - source_id: ID interno de Inmuebles24
  - source_url: URL de la propiedad
  - title: Titulo del anuncio
  - price: Precio (numerico)
  - currency: MXN/USD
  - property_type: casa/departamento/terreno/etc
  - transaction_type: venta/renta
  - bedrooms: Recamaras
  - bathrooms: Banos
  - construction_m2: Metros construidos
  - land_m2: Metros de terreno
  - address: Direccion
  - neighborhood: Colonia
  - city: Ciudad
  - state: Estado
  - description: Descripcion completa

Opcionales:
  - parking_spaces: Estacionamientos
  - age_years: Antiguedad
  - amenities: Lista de amenidades
  - images: URLs de imagenes
  - latitude: Coordenada
  - longitude: Coordenada
```

---

## Tareas Tecnicas

| # | Tarea | Estimacion |
|---|-------|------------|
| 1 | Setup Playwright + stealth plugins | 2h |
| 2 | Implementar navegacion de listados | 4h |
| 3 | Parser de detalle de propiedad | 4h |
| 4 | Integracion con proxy pool | 3h |
| 5 | Rate limiting y delays | 2h |
| 6 | Manejo de errores y reintentos | 3h |
| 7 | Storage de raw data (S3/local) | 2h |
| 8 | Tests unitarios y de integracion | 4h |

**Total estimado:** 24h (~3 dias)

---

## Configuracion

```yaml
scraper_config:
  source: inmuebles24
  base_url: https://www.inmuebles24.com

  targets:
    cities:
      - guadalajara
      - monterrey
      - ciudad-de-mexico
    property_types:
      - casas
      - departamentos

  limits:
    max_pages_per_city: 5
    max_properties_per_run: 500
    delay_ms:
      min: 2000
      max: 5000

  proxy:
    type: residential
    rotate_every: session

  retry:
    max_attempts: 3
    backoff_multiplier: 2
```

---

## Notas de Implementacion

1. **Selectores**: Usar selectores CSS robustos, evitar XPath fragiles
2. **Cloudflare**: Esperar carga completa antes de extraer
3. **CAPTCHA**: Si aparece frecuentemente, activar solver externo
4. **Logs**: Logging detallado para debugging

---

## Definition of Done

- [ ] Codigo implementado y revisado
- [ ] Tests pasan (unit + integracion)
- [ ] Scraper extrae 500+ propiedades sin bloqueos
- [ ] Documentacion actualizada
- [ ] Metricas de exito > 80%

---

## Dependencias

- Proxy pool configurado (US-SCR-000)
- Redis para Bull Queue
- Storage S3/local para raw data

---

## Riesgos

| Riesgo | Mitigacion |
|--------|------------|
| Cambios en HTML | Alertas + selectores flexibles |
| Rate limit | Delay adaptativo |
| IP ban | Pool de proxies amplio |

---

**Asignado a:** -
**Sprint:** -
**Fecha limite:** -