API de Sitio Web a PDF#

El endpoint POST /v1/convert/website-to-pdf rastrea un sitio web completo (mediante el análisis del sitemap o un rastreo completo en anchura), convierte cada página descubierta a un PDF de alta fidelidad 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 lote, un callback de webhook o una notificación por correo electrónico, y la respuesta del estado del lote 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-pdf

Content-Type: application/json

Formato de salida: Archivo ZIP que contiene un PDF 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 de navegador y renderizado#

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

Autenticación y solicitudes personalizadas#

Opciones de PDF#

Pasa estas opciones dentro de un objeto pdf_options. Se aplican a cada página del sitio web.

Tamaños de página admitidos: A0, A1, A2, A3, A4, A5, A6, B0, B1, B2, B3, B4, B5, Letter, Legal, Tabloid, Ledger

Modos de rastreo#

"auto" (predeterminado)#

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

"sitemap"#

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

1. Obtiene {base_url}/sitemap.xml (tiempo de espera 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 el sitemap no existe, devuelve un estado distinto de 200, contiene XML inválido o 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. Comprueba las 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 y 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 (inmediata)#

{
    "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 lote#

Sondea 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 se complete. Consulta Sondeo del estado del lote 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-pdf/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.pdf"},
        {"url": "https://example.com/about", "status": "success", "filename": "example_20260405_002.pdf"},
        {"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 de forma predeterminada) cuando el trabajo finaliza, independientemente del éxito o el fracaso.

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-pdf",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "crawl_mode": "sitemap",
        "output_filename": "example-website",
        "pdf_options": {
            "page_size": "A4",
            "orientation": "portrait"
        }
    }
)

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-pdf");
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-website",
        "pdf_options" => [
            "page_size" => "A4",
            "orientation" => "portrait"
        ]
    ])
]);

$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-pdf", {
    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-website",
        pdf_options: {
            page_size: "A4",
            orientation: "portrait"
        }
    })
});

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-website",
        "pdf_options": map[string]interface{}{
            "page_size":   "A4",
            "orientation": "portrait",
        },
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/website-to-pdf", 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",
    "include_patterns": [".*\\/blog\\/.*", ".*\\/docs\\/.*"],
    "pdf_options": {
        "page_size": "Letter",
        "margins": {"top": 20, "bottom": 20, "left": 15, "right": 15}
    }
}

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 convierto un sitio web completo a PDF con una API?#

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

¿Cuál es la diferencia entre el modo de rastreo por sitemap y el modo completo?#

crawl_mode: "sitemap" analiza el sitemap.xml del sitio (incluidos los índices de sitemap anidados) y está disponible en planes Indie y superiores. crawl_mode: "full" ejecuta un rastreo de dos fases: primero el descubrimiento de semillas a partir de robots.txt, sitemaps y feeds RSS/Atom, y después un rastreo de enlaces en anchura dentro del mismo dominio con filtrado mediante include_patterns/exclude_patterns. Este modo requiere el plan Studio o superior. El valor predeterminado "auto" usa el modo más alto que permite tu plan.

¿Cómo sé cuándo ha terminado mi trabajo de sitio web a PDF?#

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 de forma predeterminada) independientemente del éxito o el fracaso.

¿Puedo archivar como PDF un sitio protegido con contraseña o de 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 sitio web a PDF devuelve 403 Forbidden?#

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