API de Capturas de Pantalla de Sitios Web#

El endpoint POST /v1/convert/website-to-screenshot descubre cada página de un sitio web (mediante análisis de sitemap o un rastreo completo en anchura), captura una captura de pantalla PNG de página completa de cada página, y agrupa los resultados en un único archivo ZIP. Los trabajos siempre se ejecutan de forma asíncrona: la API devuelve HTTP 202 con un batch_id de inmediato, la finalización se señala mediante sondeo del estado del batch, un callback de webhook, o una notificación por correo electrónico, y la respuesta del estado del batch incluye una URL de descarga prefirmada para el ZIP terminado. Requiere un plan de pago y una clave de API privada.

Endpoint#

POST /v1/convert/website-to-screenshot

Content-Type: application/json

Formato de salida: Archivo ZIP que contiene una captura de pantalla PNG por cada página descubierta.

Modo: Siempre asíncrono. Devuelve HTTP 202 de inmediato.

Autenticación#

Este endpoint requiere una clave de API privada. Las claves públicas no son compatibles con la captura de sitios web.

X-API-Key: sk_your_private_key

Parámetros de la solicitud#

Parámetros de descubrimiento del sitio web#

Parámetros de notificación#

Parámetros del navegador y renderizado#

Estos ajustes se aplican a la captura de cada página individual dentro del sitio web.

Autenticación y solicitudes personalizadas#

Modos de rastreo#

"auto" (predeterminado)#

Usa el modo de rastreo más alto que permite tu plan. Si tu plan admite rastreo completo, ejecuta un rastreo completo. Si tu plan solo admite sitemap, ejecuta descubrimiento por sitemap.

"sitemap"#

Descubre páginas analizando el sitemap.xml del sitio web:

1. Obtiene {base_url}/sitemap.xml (tiempo límite de 30 segundos)
2. Si el elemento raíz es <sitemapindex>, obtiene recursivamente cada sitemap hijo
3. Extrae todas las entradas <url><loc> de los elementos <urlset>
4. Devuelve la lista completa de URLs descubiertas

Devuelve un error si falta el sitemap, si devuelve un estado distinto de 200, si contiene XML inválido, o si no tiene URLs.

"full"#

Realiza un rastreo exhaustivo en dos fases:

Fase 1 -- Descubrimiento de semillas:

1. Analiza robots.txt en busca de directivas de sitemap y reglas de rastreo
2. Verifica rutas estándar de sitemap (/sitemap.xml, /wp-sitemap.xml, /sitemap_index.xml, etc.)
3. Descubre feeds RSS/Atom a partir de etiquetas <link> y rutas de feed comunes
4. Extrae URLs semilla de todas las fuentes descubiertas

Fase 2 -- Rastreo de enlaces en anchura:

1. Comienza desde la URL base más todas las URLs semilla
2. Visita cada página y encola los enlaces del mismo dominio
3. Aplica include_patterns y exclude_patterns para filtrar enlaces
4. Respeta las reglas de robots.txt
5. Detecta y evita trampas de URL infinitas (páginas de calendario, filtros facetados, etc.)
6. Deduplica URLs normalizando el esquema, el host, los parámetros de consulta, y eliminando parámetros de seguimiento (utm_*, fbclid, gclid, etc.)

Patrones de exclusión predeterminados (cuando no se proporciona exclude_patterns):

• Recursos estáticos: *.pdf, *.zip, *.jpg, *.png, *.gif, *.svg, *.css, *.js, *.xml, *.json, *.mp4, *.webm, *.woff, *.woff2
• Rutas protegidas: /login, /admin, /cart, /checkout
• Paginación profunda: URLs con parámetros page= que superan los 3 dígitos

Respuesta#

202 Accepted (inmediato)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 42,
    "total_discovered": 42,
    "discovery_method": "sitemap",
    "output_format": "zip"
}

Sondeo del estado del batch#

Consulta con el batch_id de la respuesta 202:

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_your_private_key

Devuelve el estado agregado, los estados por URL, y una URL de descarga prefirmada para el ZIP cuando finaliza. Consulta Sondeo del estado del batch para ver el esquema completo de la respuesta.

Payload del callback de webhook#

Cuando se proporciona callback_url, EnConvert envía una solicitud POST al finalizar:

{
    "job_id": "batch-uuid",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-screenshot/website_20260405_123456789.zip",
    "filename": "website_20260405_123456789.zip",
    "file_size": 12345678,
    "total_tasks": 42,
    "successful_tasks": 40,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/", "status": "success", "filename": "example_20260405_001.png"},
        {"url": "https://example.com/about", "status": "success", "filename": "example_20260405_002.png"},
        {"url": "https://example.com/broken", "status": "failed", "error": "Timeout"}
    ]
}

Notificación por correo electrónico#

Se envía un correo de finalización a notification_email (o al correo del propietario del proyecto por defecto) cuando el trabajo termina, independientemente de si tuvo éxito o falló.

Restricciones por plan de suscripción#

Ejemplos de código#

Python (clave privada)#

import requests
import time

# Start the website capture
response = requests.post(
    "https://api.enconvert.com/v1/convert/website-to-screenshot",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "crawl_mode": "sitemap",
        "output_filename": "example-screenshots",
        "viewport_width": 1440,
        "viewport_height": 900
    }
)

data = response.json()
print(f"Batch ID: {data['batch_id']}")
print(f"Pages found: {data['url_count']}")

# Poll for completion
batch_id = data["batch_id"]
while True:
    status = requests.get(
        f"https://api.enconvert.com/v1/convert/batch/{batch_id}",
        headers={"X-API-Key": "sk_your_private_key"}
    ).json()

    print(f"Status: {status['status']} ({status['completed']}/{status['total']})")

    if status["status"] in ("completed", "partial", "failed"):
        if status.get("zip_download_url"):
            print(f"Download: {status['zip_download_url']}")
        break

    time.sleep(5)

PHP (clave privada)#

$ch = curl_init("https://api.enconvert.com/v1/convert/website-to-screenshot");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-Key: sk_your_private_key"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "crawl_mode" => "sitemap",
        "output_filename" => "example-screenshots",
        "viewport_width" => 1440,
        "viewport_height" => 900
    ])
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Batch ID: " . $response["batch_id"] . "\n";
echo "Pages found: " . $response["url_count"] . "\n";

Node.js (clave privada)#

const response = await fetch("https://api.enconvert.com/v1/convert/website-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com",
        crawl_mode: "sitemap",
        output_filename: "example-screenshots",
        viewport_width: 1440,
        viewport_height: 900
    })
});

const data = await response.json();
console.log(`Batch ID: ${data.batch_id}`);
console.log(`Pages found: ${data.url_count}`);

// Poll for completion
const poll = async () => {
    const status = await fetch(
        `https://api.enconvert.com/v1/convert/batch/${data.batch_id}`,
        { headers: { "X-API-Key": "sk_your_private_key" } }
    ).then(r => r.json());

    console.log(`Status: ${status.status} (${status.completed}/${status.total})`);

    if (["completed", "partial", "failed"].includes(status.status)) {
        if (status.zip_download_url) console.log(`Download: ${status.zip_download_url}`);
        return;
    }
    setTimeout(poll, 5000);
};
poll();

Go (clave privada)#

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "url":             "https://example.com",
        "crawl_mode":      "sitemap",
        "output_filename": "example-screenshots",
        "viewport_width":  1440,
        "viewport_height": 900,
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/website-to-screenshot", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "sk_your_private_key")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

Con callback de webhook#

{
    "url": "https://example.com",
    "crawl_mode": "full",
    "callback_url": "https://your-server.com/webhook/enconvert",
    "output_filename": "example-full-site-screenshots",
    "include_patterns": [".*\\/blog\\/.*", ".*\\/docs\\/.*"]
}

Con autenticación (sitio protegido con contraseña)#

{
    "url": "https://staging.example.com",
    "crawl_mode": "sitemap",
    "auth": {
        "username": "admin",
        "password": "staging-password"
    },
    "cookies": [
        {"name": "session_token", "value": "abc123", "domain": "staging.example.com"}
    ]
}

Respuestas de error#

Límites#

Preguntas frecuentes#

¿Cómo capturo cada página de un sitio web con una API?#

Envía una solicitud POST a /v1/convert/website-to-screenshot con la url base del sitio y tu clave privada en el encabezado X-API-Key. La API descubre cada página (sitemap o rastreo completo), captura un PNG de página completa de cada una, las agrupa en un archivo ZIP, y devuelve HTTP 202 con un batch_id que puedes sondear para obtener el enlace de descarga.

¿Puedo controlar el tamaño o el formato de las capturas de pantalla?#

El ancho de la captura coincide con viewport_width (predeterminado 1920), y viewport_height se usa como referencia de renderizado. Cada página siempre se captura como un único PNG de página completa. Los parámetros single_page y pdf_options no se aplican a las capturas de pantalla.

¿Cómo descargo las capturas de pantalla cuando el trabajo finaliza?#

Sondea GET /v1/convert/batch/{batch_id} con tu clave privada para obtener el estado agregado, los estados por URL, y una URL de descarga prefirmada del ZIP, o pasa un callback_url para recibir un POST de webhook al finalizar. También se envía un correo de finalización a notification_email (o al propietario del proyecto por defecto).

¿Puedo capturar un sitio protegido con contraseña o en staging?#

Sí, en planes con acceso a autenticación básica: pasa auth con username y password para aplicar HTTP Basic Auth a cada página, inyecta hasta 50 cookies de sesión, o envía hasta 20 headers personalizados.

¿Por qué el endpoint de captura de pantalla de sitios web devuelve 403 Forbidden?#

Las causas más comunes: la captura de sitios web no está disponible en el plan Founding, crawl_mode: "full" requiere Studio o superior, el número de páginas descubiertas supera el límite de tamaño de batch de tu plan, o una función solicitada (webhook, autenticación básica) no está incluida en tu plan.