API Sito Web in PDF#

L'endpoint POST /v1/convert/website-to-pdf esegue il crawling di un intero sito web (tramite parsing della sitemap o un crawl completo breadth-first), converte ogni pagina rilevata in un PDF ad alta fedeltà e raggruppa i risultati in un unico archivio ZIP. I job vengono sempre eseguiti in modo asincrono: l'API restituisce HTTP 202 con un batch_id immediatamente, il completamento viene segnalato tramite polling dello stato del batch, un callback webhook o una notifica email, e la risposta dello stato del batch include un URL di download presigned per lo ZIP completato. Richiede un piano a pagamento e una chiave API privata.

Endpoint#

POST /v1/convert/website-to-pdf

Content-Type: application/json

Formato di output: archivio ZIP contenente un PDF per ogni pagina rilevata.

Modalità: Sempre asincrona. Restituisce HTTP 202 immediatamente.

Autenticazione#

Questo endpoint richiede una chiave API privata. Le chiavi pubbliche non sono supportate per la cattura di siti web.

X-API-Key: sk_your_private_key

Parametri della Richiesta#

Parametri di Scoperta del Sito Web#

Parametri di Notifica#

Parametri Browser e Rendering#

Queste impostazioni si applicano alla conversione di ogni singola pagina all'interno del sito web.

Autenticazione e Richieste Personalizzate#

Opzioni PDF#

Passa questi parametri all'interno di un oggetto pdf_options. Si applicano a ogni pagina del sito web.

Dimensioni pagina supportate: A0, A1, A2, A3, A4, A5, A6, B0, B1, B2, B3, B4, B5, Letter, Legal, Tabloid, Ledger

Modalità di Crawl#

"auto" (predefinito)#

Usa la modalità di crawl più alta consentita dal tuo piano. Se il tuo piano supporta il crawl completo, esegue un crawl completo. Se il tuo piano supporta solo la sitemap, esegue il rilevamento tramite sitemap.

"sitemap"#

Rileva le pagine effettuando il parsing del file sitemap.xml del sito web:

1. Recupera {base_url}/sitemap.xml (timeout di 30 secondi)
2. Se l'elemento radice è <sitemapindex>, recupera ricorsivamente ogni sitemap figlia
3. Estrae tutte le voci <url><loc> dagli elementi <urlset>
4. Restituisce l'elenco completo degli URL rilevati

Restituisce un errore se la sitemap è mancante, restituisce uno status diverso da 200, contiene XML non valido o non contiene URL.

"full"#

Esegue un crawl completo in due fasi:

Fase 1 -- Rilevamento dei seed:

1. Analizza robots.txt per direttive sitemap e regole di crawl
2. Controlla i percorsi sitemap standard (/sitemap.xml, /wp-sitemap.xml, /sitemap_index.xml, ecc.)
3. Rileva i feed RSS/Atom dai tag <link> e dai percorsi feed comuni
4. Estrae gli URL seed da tutte le fonti rilevate

Fase 2 -- Crawl dei link breadth-first:

1. Parte dall'URL base più tutti gli URL seed
2. Visita ogni pagina e accoda i link dello stesso dominio
3. Applica include_patterns e exclude_patterns per filtrare i link
4. Rispetta le regole di robots.txt
5. Rileva ed evita trappole URL infinite (pagine calendario, filtri sfaccettati, ecc.)
6. Deduplica gli URL normalizzando schema, host, parametri di query e rimuovendo i parametri di tracciamento (utm_*, fbclid, gclid, ecc.)

Pattern di esclusione predefiniti (quando exclude_patterns non è fornito):

• Asset statici: *.pdf, *.zip, *.jpg, *.png, *.gif, *.svg, *.css, *.js, *.xml, *.json, *.mp4, *.webm, *.woff, *.woff2
• Percorsi protetti: /login, /admin, /cart, /checkout
• Paginazione profonda: URL con parametri page= che superano 3 cifre

Risposta#

202 Accepted (immediato)#

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

Polling dello Stato del Batch#

Effettua il polling con il batch_id ricevuto nella risposta 202:

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

Restituisce lo stato aggregato, gli stati per singolo URL e un URL di download presigned per lo ZIP al completamento. Vedi Polling dello Stato del Batch per lo schema completo della risposta.

Payload del Callback Webhook#

Quando viene fornito callback_url, EnConvert invia una richiesta POST al completamento:

{
    "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"}
    ]
}

Notifica Email#

Un'email di completamento viene inviata a notification_email (o all'email del proprietario del progetto per impostazione predefinita) al termine del job, indipendentemente dal successo o dal fallimento.

Limitazioni per Piano di Abbonamento#

Esempi di Codice#

Python (Chiave Privata)#

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 (Chiave Privata)#

$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 (Chiave Privata)#

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 (Chiave Privata)#

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 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 Autenticazione (Sito Protetto da Password)#

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

Risposte di Errore#

Limiti#

Domande frequenti#

Come converto un intero sito web in PDF con un'API?#

Invia una richiesta POST a /v1/convert/website-to-pdf con l'url base del sito e la tua chiave privata nell'header X-API-Key. L'API rileva ogni pagina (sitemap o crawl completo), converte ciascuna in PDF, le raggruppa in uno ZIP e restituisce HTTP 202 con un batch_id su cui puoi effettuare il polling per ottenere il link di download.

Qual è la differenza tra la modalità sitemap e la modalità crawl completo?#

crawl_mode: "sitemap" effettua il parsing del sitemap.xml del sito (inclusi gli indici di sitemap annidati) ed è disponibile dai piani Indie in su. crawl_mode: "full" esegue un crawl in due fasi: prima il rilevamento dei seed da robots.txt, sitemap e feed RSS/Atom, poi un crawl breadth-first dei link dello stesso dominio con filtro include_patterns/exclude_patterns. Questa modalità richiede Studio o superiore. Il valore predefinito "auto" usa la modalità più alta consentita dal tuo piano.

Come faccio a sapere quando il mio job di conversione sito web in PDF è terminato?#

Effettua il polling di GET /v1/convert/batch/{batch_id} con la tua chiave privata per ottenere lo stato aggregato, gli stati per singolo URL e un URL di download ZIP presigned, oppure passa un callback_url per ricevere un POST webhook al completamento. Un'email di completamento viene inviata anche a notification_email (o al proprietario del progetto per impostazione predefinita), indipendentemente dal successo o dal fallimento.

Posso archiviare un sito protetto da password o di staging come PDF?#

Sì, sui piani con accesso basic auth: passa auth con username e password per l'HTTP Basic Auth applicata a ogni pagina, inietta fino a 50 cookies di sessione, oppure invia fino a 20 headers personalizzati.

Perché l'endpoint di conversione sito web in PDF restituisce 403 Forbidden?#

Le cause più comuni: la cattura di siti web non è disponibile sul piano Founding, crawl_mode: "full" richiede Studio o superiore, il numero di pagine rilevate supera il limite di dimensione batch del tuo piano, oppure una funzionalità richiesta (webhook, basic auth) non è inclusa nel tuo piano.