Guía de integración de la API de renderizado web de WebExtrator

POST https://api.acedata.cloud/webextrator/render La API de renderizado web de WebExtrator es un servicio de renderizado web basado en Chromium sin interfaz gráfica. Dada una URL, devuelve el HTML completamente renderizado (incluido el contenido inyectado por JS), texto sin formato, el título de la página y la URL final. Render es la interfaz más básica de WebExtrator. Si necesitas resultados de extracción estructurados (cuerpo de artículos, precios de productos, ingredientes de recetas …), utiliza /webextrator/extract —— ejecuta un conjunto completo de flujos de extracción tipados sobre la misma base de renderizado.

Proceso de solicitud

Para utilizar la página de servicio de WebExtrator, primero obtén tu API Token en la consola de Ace Data Cloud y guárdalo como respaldo.

Si aún no has iniciado sesión o no te has registrado, serás redirigido automáticamente a la página de inicio de sesión para invitarte a registrarte e iniciar sesión; al completarlo, volverás automáticamente a la página actual. Un solo API Token puede invocar todos los servicios de la plataforma, sin necesidad de solicitar uno por separado para cada servicio. La primera solicitud incluye crédito gratuito, que permite una experiencia gratuita; cuando el crédito sea insuficiente, puedes recargar saldo general en la consola.

📘 Documentación completa: Página de servicio de WebExtrator →

Autenticación

Todas las interfaces de WebExtrator utilizan autenticación estándar mediante Bearer Token:

Authorization: Bearer YOUR_API_KEY
Content-Type:  application/json

Parámetros de solicitud

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`url`	string	✅	—	La URL de la página que se va a renderizar; debe ser `http(s)://`.
`user_agent`	string	❌	Rotación del grupo de UA integrado	User-Agent personalizado.
`timeout`	integer	❌	`30`	Tiempo de espera de navegación única (segundos enteros positivos).
`wait_until`	enum	❌	`load`	Evento de finalización de carga: `load` / `domcontentloaded` / `networkidle` / `commit`.
`delay`	integer	❌	`0`	Segundos de espera adicionales después de que se active `wait_until` (entero no negativo) (para el renderizado secundario de SPA).
`wait_for_selector`	string	❌	—	Espera a que aparezca este selector CSS; es más estable que `networkidle`.
`block_resources`	string[]	❌	`["image","font","media"]`	Tipos de recursos bloqueados, opcionales: `image` / `font` / `media` / `stylesheet` / `xhr` / `fetch`.
`headers`	object	❌	—	Encabezados de solicitud HTTP adicionales (por ejemplo, `{"Accept-Language": "en-US"}`).
`cookies`	array	❌	—	Cookies inyectadas antes de la navegación; consulta la estructura a continuación.
`callback_url`	string	❌	—	Dirección de devolución de llamada en modo asíncrono; la plataforma hace `POST` del resultado completo a esta dirección al completar la tarea.
`bypass_cache`	boolean	❌	`false`	Omite la lectura de la caché Redis (pero aun así escribe este resultado de vuelta en la caché).
`cache_ttl_seconds`	integer	❌	`3600`	TTL de caché personalizado para esta escritura; pasar `0` indica no almacenar en caché esta respuesta.
`async`	boolean	❌	`false`	Establécelo en `true` para devolver inmediatamente `task_id`; el resultado se recupera mediante `callback_url` o la API Tasks.

El contrato de la plataforma utiliza de forma unificada snake_case. El servicio interno de renderizado admite camelCase, pero las llamadas externas siempre utilizan snake_case.

{
  "name":      "string",
  "value":     "string",
  "domain":    "string",
  "path":      "/",
  "expires":   1735689600,
  "httpOnly":  false,
  "secure":    true,
  "sameSite":  "Lax"
}

Respuesta síncrona

{
  "success": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "trace_id": "550e8400-e29b-41d4-a716-446655440001",
  "started_at": 1777717800.123,
  "finished_at": 1777717801.234,
  "elapsed": 1.111,
  "data": {
    "kind": "render",
    "url": "https://example.com",
    "finalUrl": "https://example.com/",
    "title": "Example Domain",
    "status": 200,
    "html": "<!DOCTYPE html><html>...</html>",
    "text": "Example Domain\nThis domain is for use in illustrative examples...",
    "userAgent": "Mozilla/5.0 ...",
    "elapsedMs": 1108
  }
}

Campo	Tipo	Descripción
`data.kind`	string	Fijo en `"render"`.
`data.url`	string	La URL que enviaste.
`data.finalUrl`	string	La URL final después de seguir las redirecciones.
`data.title`	string	El `document.title` después del renderizado.
`data.status`	number \| null	El código de estado HTTP de la navegación principal.
`data.html`	string	El HTML completo después del renderizado.
`data.text`	string	Instantánea de `document.body.innerText` (si necesitas un cuerpo más limpio, utiliza Extract).
`data.userAgent`	string	El UA realmente utilizado.
`data.elapsedMs`	number	Solo el tiempo de renderizado del navegador.
`data.cached`	boolean?	Es `true` cuando se alcanza la caché.
`data.cacheStoredAt`	number?	Marca de tiempo Unix en milisegundos de la primera escritura de la entrada de caché.

Respuesta asíncrona

Cuando async=true (o se proporciona callback_url), devuelve inmediatamente (HTTP 200):

{
  "success": true,
  "task_id": "550e8400-...",
  "trace_id": "6ba7b810-...",
  "started_at": 1777717800.123
}

El resultado se enviará mediante POST a callback_url (si está configurado), o se consultará activamente a través de /webextrator/tasks.

Estructura de devolución de llamada

La plataforma hace POST del envelope exactamente igual que en el modo síncrono a callback_url, con Content-Type: application/json. Devolver cualquier 2xx se considera confirmado; los 5xx se reintentarán con retroceso exponencial durante aproximadamente 5 minutos.

Respuesta de error

HTTP	`error.code`	Significado
400	`bad_request`	El cuerpo de la solicitud no pasó la validación de Zod (falta `url`, tipo incorrecto …).
401	`unauthorized`	Falta o no es válido `Authorization: Bearer …`.
402	(x402)	Saldo insuficiente en la plataforma, devuelve el envelope de requisitos de pago x402.
408	`timeout`	La navegación superó `timeout`.
429	`queue_busy`	La cola síncrona está congestionada, vuelve a intentarlo o usa `async=true`.
500	`internal_error`	Excepción no controlada del lado del servidor (bloqueo del navegador, etc.), el Worker vuelve a intentarlo automáticamente una vez.

Estructura de error:

{
  "success": false,
  "task_id": "...",
  "trace_id": "...",
  "started_at": 1777717800.123,
  "finished_at": 1777717800.135,
  "elapsed": 0.012,
  "error": { "code": "bad_request", "message": "url: Invalid url" }
}

Ejemplos

cURL

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "wait_until": "networkidle",
    "block_resources": ["image", "media", "font"]
  }'

Python (requests)

import os, requests

API_KEY = os.environ["ACEDATA_API_KEY"]

resp = requests.post(
    "https://api.acedata.cloud/webextrator/render",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "wait_until": "networkidle",
        "block_resources": ["image", "media", "font"],
    },
    timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["title"], data["status"], len(data["html"]))

Node.js (fetch)

const apiKey = process.env.ACEDATA_API_KEY;

const res = await fetch('https://api.acedata.cloud/webextrator/render', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    wait_until: 'networkidle',
    block_resources: ['image', 'media', 'font'],
  }),
});
const { data } = await res.json();
console.log(data.title, data.status, data.html.length);

Asíncrono + callback

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async": true,
    "callback_url": "https://your-app.example.com/hooks/webextrator"
  }'

Devuelve inmediatamente { "success": true, "task_id": "...", "trace_id": "...", "started_at": 1777717800.123 }； cuando la tarea se complete, la plataforma hará POST del resultado completo a tu callback_url.

Forzar la omisión de caché

curl -X POST https://api.acedata.cloud/webextrator/render \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "bypass_cache": true
  }'

Consejos y errores comunes

Es importante elegir correctamente wait_until. networkidle es el más estable pero el más lento; domcontentloaded es rápido, pero puede omitir contenido inyectado de forma asíncrona; load es adecuado para páginas estáticas tradicionales.
La clave de caché ignora async. Las solicitudes síncronas y asíncronas para la misma URL alcanzan la misma entrada de caché, por lo que cambiar libremente entre ellas no la invalidará.
La clave de caché ignora bypass_cache y cache_ttl_seconds. Estos dos son interruptores operativos, y no afectan al contenido de la respuesta.
cookies y headers segmentan la caché. Personalizar estos dos hará que falle el primer acierto con la misma combinación.
Las SPA pesadas a menudo superan los 30 segundos predeterminados. Se recomienda timeout: 60, wait_until: "domcontentloaded", delay: 4, y luego combinarlo con wait_for_selector para esperar los elementos que realmente te interesan.
block_resources es la vía más rápida para reducir la latencia. Las imágenes / fuentes / medios ya están bloqueados de forma predeterminada; si tu extracción no depende del diseño CSS, añadir stylesheet puede hacerlo aún más rápido.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Guía de integración de la API de renderizado web de WebExtrator

Proceso de solicitud

Autenticación

Parámetros de solicitud

Respuesta síncrona

Respuesta asíncrona

Estructura de devolución de llamada

Respuesta de error

Ejemplos

cURL

Python (requests)

Node.js (fetch)

Asíncrono + callback

Forzar la omisión de caché

Consejos y errores comunes

​Proceso de solicitud

​Autenticación

​Parámetros de solicitud

​Estructura de Cookie

​Respuesta síncrona

​Respuesta asíncrona

​Estructura de devolución de llamada

​Respuesta de error

​Ejemplos

​cURL

​Python (requests)

​Node.js (fetch)

​Asíncrono + callback

​Forzar la omisión de caché

​Consejos y errores comunes

Proceso de solicitud

Autenticación

Parámetros de solicitud

Estructura de Cookie

Respuesta síncrona

Respuesta asíncrona

Estructura de devolución de llamada

Respuesta de error

Ejemplos

cURL

Python (requests)

Node.js (fetch)

Asíncrono + callback

Forzar la omisión de caché

Consejos y errores comunes