¿Qué es Valkoru Scraper?

Inicio rápido

Para empezar a extraer datos en menos de un minuto:

1. Crea una cuenta gratuita en /app/register
2. Ve a /app/extractor
3. Pega la URL del sitio que quieres scrapear
4. Haz clic en Extraer Datos
5. Descarga los resultados en CSV o JSON

Primera extracción

Al abrir el extractor verás una barra de URL. Pega la dirección del listado que quieres extraer. Por ejemplo:

https://www.mercadolibre.cl/laptops

Valkoru Scraper detectará automáticamente qué tipo de datos hay en la página. Si quieres más control, abre las Opciones avanzadas.

Tipos de URL que funcionan bien

• Listados de productos (/categoria, /busqueda)
• Resultados de búsqueda de propiedades
• Listados de empleos con múltiples ofertas por página
• Directorios y catálogos públicos

Opciones avanzadas

Despliega las opciones avanzadas para personalizar la extracción:

Categoría

Ayuda al modelo a entender qué tipo de datos buscar. Las opciones son:

• Auto-detectar — el modelo infiere la categoría (recomendado)
• E-commerce — productos, precios, ratings, stock
• Inmobiliarias — propiedades, precios, m², ubicaciones
• Empleos — cargos, empresas, salarios, modalidad
• General — para cualquier otro tipo de contenido

Instrucciones

Campo de texto libre donde puedes indicarle al modelo qué extraer con precisión:

"Solo extrae productos con precio menor a $50.000"
"Extrae solo propiedades de 3 dormitorios o más"
"Ignora los avisos destacados, solo empleos orgánicos"

Extracción multi-página

Por defecto Valkoru Scraper extrae solo la primera página. Con el campo Páginas puedes indicar cuántas páginas de paginación quieres recorrer automáticamente.

El sistema detecta el botón "Siguiente" o el link de paginación y lo navega automáticamente hasta completar el número de páginas indicado o hasta que no haya más páginas.

Descargar datos

Al terminar la extracción puedes descargar los resultados en dos formatos:

• JSON — útil para procesar con Python, Node.js o cualquier lenguaje de programación
• CSV — abre directamente en Excel, Google Sheets o Numbers

También puedes descargar extracciones anteriores desde Mi Cuenta.

Categorías disponibles

Límites por plan

¿Necesitas más extracciones? Ver planes.

Visión general

La API REST de Valkoru Scraper te permite ejecutar extracciones directamente desde tu código, sin necesidad de usar el extractor web. Está disponible en los planes Pro y Enterprise.

Base URL de todos los endpoints:

https://tu-dominio/api

Todas las respuestas usan Content-Type: application/json y codificación UTF-8.

Autenticación

La API acepta dos métodos de autenticación. Usa el que más se adapte a tu integración:

1. API Key (recomendado para integraciones)

Genera tu clave desde /app/api-key (requiere plan Pro o Enterprise). Incluye la clave en el header X-API-Key:

# Todas las peticiones deben incluir este header
X-API-Key: sk-tu-clave-aqui

Ejemplo con curl:

curl -X POST https://tu-dominio/api/scrape \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk-tu-clave-aqui" \
  -d '{"url": "https://ejemplo.com", "category": "ecommerce"}'

2. Bearer Token (JWT)

Obtén un token con POST /api/auth/login y úsalo en el header Authorization:

# Paso 1: Obtener token
curl -X POST https://tu-dominio/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "tu@email.com", "password": "tucontraseña"}'

# Respuesta:
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "user": {"id": 1, "email": "tu@email.com", "plan": "pro"}
}

# Paso 2: Usar el token
curl -X POST https://tu-dominio/api/scrape \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGc..." \
  -d '{"url": "https://ejemplo.com"}'

POST /api/scrape

Endpoint principal. Recibe una URL, ejecuta la extracción con IA y retorna los datos estructurados.

Body (JSON)

Respuesta exitosa (200)

{
  "success": true,
  "data": [
    {
      "titulo": "MacBook Pro 14\"",
      "precio": "$1.299.990",
      "marca": "Apple",
      "rating": "4.8"
    }
  ],
  "metadata": {
    "job_id": 42,
    "url": "https://www.mercadolibre.cl/laptops",
    "pages_scraped": 3,
    "total_items": 48,
    "method": "hard_gpt",
    "cost": 0.0142,
    "extraction_time": 8.3
  }
}

Ejemplo en Python

import requests

API_KEY = "sk-tu-clave-aqui"
BASE_URL = "https://tu-dominio"

response = requests.post(
    f"{BASE_URL}/api/scrape",
    headers={"X-API-Key": API_KEY},
    json={
        "url": "https://www.mercadolibre.cl/laptops",
        "category": "ecommerce",
        "max_pages": 5,
        "instructions": "Solo productos con precio menor a $500.000"
    }
)

result = response.json()
print(f"Extraídos: {len(result['data'])} items")
print(f"Páginas: {result['metadata']['pages_scraped']}")
print(f"Costo: ${result['metadata']['cost']:.4f} USD")

Ejemplo en Node.js

const response = await fetch("https://tu-dominio/api/scrape", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "sk-tu-clave-aqui"
  },
  body: JSON.stringify({
    url: "https://www.portalinmobiliario.com/arriendo/departamento/las-condes",
    category: "real_estate",
    max_pages: 3
  })
});

const { data, metadata } = await response.json();
console.log(`${data.length} propiedades extraídas de ${metadata.pages_scraped} páginas`);

GET /api/jobs

Lista todas las extracciones del usuario autenticado, ordenadas de más reciente a más antigua.

Parámetros de query

# Listar las últimas 20 extracciones
curl https://tu-dominio/api/jobs \
  -H "X-API-Key: sk-tu-clave-aqui"

# Respuesta:
{
  "total": 87,
  "page": 1,
  "limit": 20,
  "jobs": [
    {
      "id": 42,
      "url": "https://www.mercadolibre.cl/laptops",
      "category": "ecommerce",
      "pages_scraped": 3,
      "total_items": 48,
      "cost": 0.0142,
      "status": "done",
      "created_at": "2025-06-10T14:32:00"
    }
  ]
}

GET /api/jobs/{id}

Obtiene los datos completos de una extracción específica. Los datos se almacenan comprimidos en el servidor durante el ciclo de vida de tu cuenta.

# Obtener datos del job 42
curl https://tu-dominio/api/jobs/42 \
  -H "X-API-Key: sk-tu-clave-aqui"

# Respuesta:
{
  "data": [
    {"titulo": "MacBook Pro 14\"", "precio": "$1.299.990", ...},
    ...
  ],
  "metadata": {
    "job_id": 42,
    "url": "https://www.mercadolibre.cl/laptops",
    "total_items": 48,
    "pages_scraped": 3,
    "cost": 0.0142,
    "created_at": "2025-06-10T14:32:00"
  }
}

Script de descarga automática en Python

import requests, json

API_KEY = "sk-tu-clave-aqui"
BASE_URL = "https://tu-dominio"
headers  = {"X-API-Key": API_KEY}

# 1. Listar todos los jobs
jobs_resp = requests.get(f"{BASE_URL}/api/jobs?limit=100", headers=headers)
jobs = jobs_resp.json()["jobs"]

# 2. Descargar datos de cada job
for job in jobs:
    data_resp = requests.get(f"{BASE_URL}/api/jobs/{job['id']}", headers=headers)
    data = data_resp.json()["data"]
    filename = f"job_{job['id']}.json"
    with open(filename, "w", encoding="utf-8") as f:
        json.dump(data, f, ensure_ascii=False, indent=2)
    print(f"✅ {filename} — {len(data)} items")

Errores

Todos los errores siguen el formato estándar de FastAPI:

{
  "detail": "Descripción del error"
}

Acceso a la API por plan

Las extracciones vía API descuentan del mismo cupo mensual que el extractor web.