Novedad en ScrapeUnblocker: interactúa con una página y luego extráela

ScrapeUnblocker es nuestra API de web scraping: le das una URL y te devuelve el HTML completamente renderizado de esa página, superando por el camino las protecciones anti-bot. Hoy añadimos una nueva capacidad. Antes de entregarte el HTML, ScrapeUnblocker ya puede interactuar con la página.

Eso significa que puedes alcanzar los datos que solo aparecen tras una acción: escribir una consulta y ejecutar una búsqueda, pulsar un botón de “cargar más”, elegir un país o una moneda en un desplegable o avanzar por un formulario de varios pasos, y recibir el HTML al que llegó la página una vez ejecutadas esas acciones. Una función complementaria lista todos los elementos interactivos de una página, para que sepas exactamente sobre qué hacer clic, dónde escribir o qué seleccionar. Este artículo cubre ambas y cómo usarlas juntas.

Cómo usarlo

Ambas funciones son simples parámetros de consulta sobre la misma petición de descarga de página que ya haces (el endpoint getPageSource). No hay una URL nueva, ni un plan nuevo, ni un navegador que ejecutar de tu lado.

• list_elements=true devuelve un mapa JSON de los elementos interactivos de la página en lugar del HTML.
• steps=[...] recibe un array JSON de acciones que se ejecutan tras cargar la página, y devuelve el HTML al que llegó.

Casi siempre los usarás en ese orden: list_elements para encontrar los selectores, steps para actuar sobre ellos.

Descubre los elementos de una página

Antes de poder actuar sobre una página, necesitas saber qué contiene. Pon list_elements=true y, en lugar de HTML en bruto, recibes una lista JSON compacta de aquello sobre lo que puedes actuar: botones, campos de entrada, áreas de texto, selects, enlaces y formularios. Cada uno llega con un selector listo para usar, además de su texto, nombre, placeholder y rol cuando existen.

curl -X POST -G "https://api.scrapeunblocker.com/getPageSource" \
  --data-urlencode "url=https://www.example.com/search" \
  --data-urlencode "list_elements=true" \
  -H "X-ScrapeUnblocker-Key: YOUR_API_KEY"

La respuesta tiene este aspecto:

{
  "url": "https://www.example.com/search",
  "count": 12,
  "elements": [
    {
      "tag": "input",
      "selector": "#searchInput",
      "type": "text",
      "name": "q",
      "placeholder": "Search products",
      "text": "Search products"
    },
    {
      "tag": "button",
      "selector": "button.search-submit",
      "text": "Search"
    },
    {
      "tag": "select",
      "selector": "select[name=\"country\"]",
      "name": "country",
      "text": "Country"
    }
  ]
}

Como la página se mide después de que un navegador real la renderiza e hidrata, ves los controles que un usuario ve de verdad, no solo lo que hay en el marcado en bruto. Los selectores se eligen para ser estables: primero un #id real, luego un name, después una clase y por último una ruta posicional corta, de modo que puedes colocar cualquiera de ellos directamente en un paso.

Actúa sobre la página con steps

Una vez que conoces los selectores, adjuntas steps: un array JSON de acciones que se ejecutan en orden después de que la página carga. Cuando los pasos terminan, recibes de vuelta el HTML resultante, exactamente como si hubieras hecho tú mismo los clics y las pulsaciones.

Aquí tienes un flujo de búsqueda: escribe una consulta en la caja, pulsa Enter y espera a que aparezcan los resultados antes de capturar el HTML.

curl -X POST -G "https://api.scrapeunblocker.com/getPageSource" \
  --data-urlencode "url=https://www.example.com/search" \
  --data-urlencode 'steps=[
    {"action":"type","selector":"#searchInput","value":"bmw"},
    {"action":"press_key","value":"Enter"},
    {"action":"wait_for","selector":".results"}
  ]' \
  -H "X-ScrapeUnblocker-Key: YOUR_API_KEY"

La respuesta es el HTML completamente renderizado de la página de resultados. El mismo patrón gestiona un botón de “cargar más” (haz clic, espera nuevas filas), un desplegable de filtro (selecciona una opción, espera a que la lista se actualice) o un flujo de dos campos de tipo iniciar sesión y ver.

Algunas cosas que conviene saber:

• La escritura es como la humana. La acción type introduce el texto carácter a carácter con un ritmo natural, en lugar de pegarlo de golpe, así que los formularios que vigilan pulsaciones reales se comportan con normalidad.
• Se ejecuta una vez. Una petición con steps puede enviar un formulario o cambiar el estado, así que se ejecuta una sola vez y no se reintenta por detrás. Pide exactamente la secuencia que quieras.
• Hay un presupuesto de tiempo. Toda la secuencia comparte un presupuesto de acción acotado de unos 30 segundos, más que suficiente para una búsqueda o un par de clics. Usa wait_for sobre el elemento que realmente necesitas en lugar de un wait fijo largo.

Las acciones que puedes ejecutar

Cada paso es un objeto con una action y, según la acción, un selector y un value. Las acciones disponibles son:

• wait_for - espera hasta que sea visible un elemento que coincida con selector.
• wait_for_text - espera hasta que aparezca en la página un texto concreto (value es el texto).
• wait - una pausa fija, con value en milisegundos.
• click - haz clic en el elemento de selector.
• type - escribe value en el campo de selector, carácter a carácter.
• select - elige una opción de un <select> por su valor.
• press_key - pulsa una tecla como Enter, Tab o Escape.
• scroll - desplaza la página, con value puesto en "bottom" o una cantidad de píxeles, que es como se dispara el contenido que se carga al hacer scroll.

Los selectores son CSS por defecto. Si lo prefieres, un paso puede llevar "selector_type": "xPath" para apuntar a un elemento por XPath.

Cuando un paso falla, sigues recibiendo la página

Si un paso no puede completarse (un selector nunca coincide, o un elemento nunca aparece a tiempo), la API no se limita a devolver un error y tirar el trabajo. Responde con HTTP 422 y un cuerpo JSON que indica exactamente qué paso falló y por qué, e incluye el HTML de la página en el estado al que llegó.

{
  "error": "step_failed",
  "step_index": 2,
  "action": "wait_for",
  "reason": "Timeout 8000ms exceeded.",
  "selector": ".results",
  "html": "<!doctype html>..."
}

Ese step_index te dice que el tercer paso (contando desde cero) es el que hay que corregir, y el html te deja ver qué hizo realmente la página: quizá el contenedor de resultados tiene una clase distinta de la que esperabas. Un payload de steps mal formado, como una acción desconocida o un selector ausente, se detecta aún antes y devuelve un 422 antes de que arranque ningún navegador, así que nunca gastas una petición en una errata.

Cuándo resulta útil

Siempre que los datos que quieres no estén en el primer renderizado, sino a una o dos interacciones de distancia:

• Resultados de búsqueda detrás de un formulario. Escribe una consulta, envíala y extrae la página de resultados en lugar de adivinar una URL de búsqueda.
• Listados paginados o de scroll infinito. Pulsa “cargar más” o desplázate hasta el final, espera a las nuevas filas y captura una página más completa.
• Selectores de país, moneda o idioma. Elige la opción que necesitas para que los precios y el contenido que extraes coincidan con el mercado que te importa.
• Flujos de varios pasos. Rellena un campo, pasa al siguiente, envía, y lee la página a la que llegas.
• Agentes de IA que primero deben entender una página. Un agente puede listar los elementos, decidir qué hacer y luego actuar, sin selectores codificados a mano.

Descubre y luego actúa: el ciclo completo

Las dos funciones están diseñadas para trabajar en pareja, y es aquí donde brillan para los agentes de IA y la automatización. Un agente que llega a una página desconocida no puede adivinar los selectores de forma fiable. Así que hace lo que hace una persona: mira primero.

1. Llama a list_elements=true para obtener los controles de la página y sus selectores.
2. Decide qué hacer (qué campo rellenar, qué botón pulsar) a partir de esa lista.
3. Construye un array steps contra esos selectores exactos.
4. Llama al endpoint con los pasos y lee el HTML resultante.

Como el primer paso devuelve selectores reales y estables en lugar de una captura de pantalla que el modelo tenga que interpretar, el plan que el agente construye en el paso tres suele funcionar a la primera. Y como cada llamada ya se ejecuta detrás del mismo manejo anti-bot que el resto de ScrapeUnblocker, el agente nunca tiene que pensar en bloqueos, rotación de IP ni renderizado: simplemente descubre la página y actúa sobre ella.

Ambas funciones ya están disponibles. Consulta la referencia completa de parámetros y más ejemplos en la documentación de integración en docs.scrapeunblocker.com, o revisa los planes en scrapeunblocker.com/pricing.