API da URL a PDF#

L'endpoint POST /v1/convert/url-to-pdf converte qualsiasi URL pubblicamente accessibile in un documento PDF ad alta fedeltà. Supporta il rendering continuo a pagina singola o l'output paginato con dimensioni di pagina personalizzate, oltre alla gestione del lazy loading, alla chiusura dei banner cookie, all'HTTP Basic Auth, all'iniezione di cookie e agli header personalizzati. Esegui le conversioni in modo sincrono per ottenere un URL di download presigned o i byte grezzi del PDF, oppure usa la modalità asincrona per convertire in batch più URL con notifiche webhook ed email.

Endpoint#

POST /v1/convert/url-to-pdf

Content-Type: application/json

Autenticazione#

Questo endpoint supporta l'autenticazione sia con chiave privata che con chiave pubblica.

Chiave privata#

Includi la tua chiave segreta nell'header X-API-Key. Usala per le chiamate server-to-server, dove la chiave non viene mai esposta al client.

X-API-Key: sk_your_private_key

Chiave pubblica con JWT#

Per l'uso lato client, genera prima un token JWT usando la tua chiave pubblica, poi passalo come token Bearer.

Passo 1 -- Ottieni un token:

POST /v1/auth/token
X-API-Key: pk_your_public_key

Passo 2 -- Usa il token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Parametri della richiesta#

Parametri di primo livello#

Parametri del browser e del rendering#

Autenticazione e richieste personalizzate#

Opzioni PDF#

Passa questi parametri all'interno di un oggetto pdf_options nel corpo della richiesta.

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

Variabili template per header/footer: {{page}}, {{total_pages}}, {{date}}, {{title}}, {{url}}

Schema dell'oggetto cookie#

Ogni elemento dell'array cookies deve seguire questa struttura:

Risposta#

Sincrona con download diretto (direct_download=true)#

Chiave privata -- restituisce i byte grezzi del PDF:

HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="example_20260404_123456789.pdf"
X-Object-Key: env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf
X-File-Size: 123456
X-Conversion-Time: 12.5
X-Filename: example_20260404_123456789.pdf

(binary PDF data)

Chiave pubblica -- restituisce JSON con un URL presigned:

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 12.5,
    "job_id": "client-provided-id"
}

Sincrona senza download diretto (direct_download=false)#

Disponibile solo con chiavi private.

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 12.5
}

Modalità asincrona#

Restituisce immediatamente un batch_id per il polling.

HTTP 202 Accepted

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 5,
    "output_format": "individual"
}

Quando output_format=true (raggruppamento ZIP):

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 5,
    "output_format": "zip"
}

Polling dello stato del job (solo chiavi pubbliche)#

L'endpoint di polling dello stato è progettato per il recupero da timeout con chiave pubblica. Quando una conversione sincrona richiede più tempo del timeout del reverse proxy (in genere 60s), il client può recuperare il risultato eseguendo il polling con il job_id fornito nella richiesta originale.

GET /v1/convert/status/{job_id}
Authorization: Bearer <jwt_token>

Polling dello stato batch (solo chiavi private)#

Per i job batch asincroni, esegui il polling dell'endpoint di stato batch con il batch_id restituito nella risposta 202.

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

Risposta:

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 5,
    "completed": 3,
    "failed": 1,
    "in_progress": 1,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 102400,
            "duration": "2.34"
        },
        {
            "source_url": "https://example.com/page2",
            "status": "Failed",
            "download_url": null,
            "output_file_size": null,
            "duration": "0.87"
        },
        {
            "source_url": "https://example.com/page3",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}

Valori di stato del batch:

Quando output_mode è "zip", viene fornito un unico zip_download_url invece dei valori download_url per singolo elemento.

Payload del callback webhook#

Quando viene fornito un callback_url, EnConvert invia una richiesta POST a quell'URL al completamento.

Job con singolo URL:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "gcs_uri": "object_key",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456
}

Job batch:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "total_tasks": 10,
    "successful_tasks": 8,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/page1", "status": "success", "filename": "page1.pdf"},
        {"url": "https://example.com/page2", "status": "failed", "filename": null}
    ]
}

Funzionalità#

Modalità Clear Capture#

EnConvert gestisce automaticamente gli ostacoli più comuni delle pagine web per produrre PDF puliti:

• Banner di consenso cookie -- Chiude automaticamente i banner di OneTrust, Cookiebot, Didomi, Usercentrics e implementazioni generiche. Opera sia sulla pagina principale che sugli iframe. Usa una strategia "prima chiudi, poi accetta".
• Chiusura di modali e popup -- Chiude gli overlay usando più strategie: tasto Escape, pulsanti di chiusura ARIA, pulsanti di chiusura basati su classe e pulsanti di dialogo basati su ruolo.
• Rivelazione delle animazioni da scroll -- Forza la visibilità degli elementi nascosti da librerie di animazione attivate dallo scroll, tra cui WOW.js, AOS, ScrollReveal e GSAP ScrollTrigger.
• Pulizia dei dropdown -- Chiude tutti i dropdown aperti e converte gli elementi pulsante di navigazione in veri link di ancoraggio, in modo che restino cliccabili nel PDF.

Dimensionamento e dimensioni della pagina#

• Modalità a pagina singola (predefinita): l'intera pagina web viene renderizzata come un'unica pagina PDF continua. L'altezza viene calcolata dinamicamente in base al contenuto effettivo tramite l'attraversamento del DOM.
• Modalità paginata (single_page=false): l'output usa page_size, orientation e margins configurati. Supporta 18 dimensioni con nome, da A0 a Ledger, oppure dimensioni personalizzate in millimetri.

HTTP Basic Auth#

Passa auth con username e password per convertire pagine protette da HTTP Basic Authentication. Le credenziali vengono inviate come credenziali HTTP con ogni richiesta alla pagina di destinazione.

{
    "url": "https://staging.example.com/report",
    "auth": {
        "username": "admin",
        "password": "secret"
    }
}

Iniezione di cookie#

Inietta fino a 50 cookie prima del caricamento della pagina. Utile per convertire pagine che richiedono una sessione attiva o preferenze utente specifiche.

{
    "url": "https://example.com/dashboard",
    "cookies": [
        {"name": "session_id", "value": "abc123", "domain": "example.com"},
        {"name": "locale", "value": "en-US", "domain": "example.com"}
    ]
}

Header personalizzati#

Invia fino a 20 header HTTP personalizzati con ogni richiesta alla pagina di destinazione. Utile per passare token API, user agent personalizzati o altri metadati della richiesta.

{
    "url": "https://example.com/report",
    "headers": {
        "X-Custom-Token": "my-token-value",
        "Accept-Language": "en-US"
    }
}

Caricamento differito delle immagini#

Quando load_media ed enable_scroll sono abilitati (entrambi predefiniti a true), il convertitore:

1. Scorre l'intera pagina lentamente (120px ogni 90ms) per attivare i loader a caricamento differito basati su IntersectionObserver
2. Attende che tutti gli elementi <img> generino il proprio evento onload (timeout di 5 secondi per immagine)
3. Attende 500ms per la stabilizzazione del layout dopo il caricamento di tutte le immagini

Imposta load_media=false per una conversione più veloce se la fedeltà dei contenuti multimediali non è critica -- il convertitore userà uno scroll rapido (300px ogni 30ms) e aggiungerà stili segnaposto per le immagini non caricate.

Gestione dell'header sticky#

Quando handle_sticky_header è abilitato (predefinito true), il convertitore rileva gli elementi posizionati come fixed e sticky che sembrano essere header (usando tag semantici, ruoli ARIA e pattern comuni nei nomi delle classi), quindi scorre in cima alla pagina prima della cattura in modo che l'header venga renderizzato correttamente all'inizio del PDF.

Header e footer#

Aggiungi header e footer ripetuti in modalità paginata con contenuto HTML e variabili template:

{
    "url": "https://example.com/report",
    "single_page": false,
    "pdf_options": {
        "page_size": "A4",
        "header": {
            "content": "<div style='font-size:10px;text-align:center;width:100%'>Confidential Report</div>",
            "height": 15
        },
        "footer": {
            "content": "<div style='font-size:9px;text-align:center;width:100%'>Page {{page}} of {{total_pages}}</div>",
            "height": 10
        }
    }
}

Output in scala di grigi#

Imposta pdf_options.grayscale su true per convertire il PDF finale in scala di grigi tramite post-elaborazione con Ghostscript.

Funzionalità di rendering aggiuntive#

• Normalizzazione delle unità di viewport -- Converte le unità CSS vh, svh, lvh, dvh in valori fissi in pixel per evitare problemi di layout nel rendering di stampa.
• Modalità stealth -- Usa il mascheramento del fingerprint del browser per evitare il rilevamento dei bot su pagine protette.
• Intercettazione dei popup -- Chiude automaticamente eventuali nuove schede del browser o popup attivati dalla pagina.
• Bypass CSP -- Gestisce le restrizioni di Content Security Policy e Trusted Types che altrimenti bloccherebbero la conversione.

Limitazioni per piano di abbonamento#

Modalità asincrona#

La modalità asincrona è utile per conversioni di lunga durata o quando si convertono più URL.

Come funziona#

1. Invia una richiesta con async_mode=true (oppure passa più URL, che abilita automaticamente la modalità asincrona).
2. L'API restituisce immediatamente HTTP 202 con un batch_id e un url_count.
3. Ogni URL viene convertito in background, caricato nello storage e monitorato individualmente.
4. Monitora il completamento tramite notifica email o callback webhook.

Notifica email#

Per impostazione predefinita, al termine del job asincrono viene inviata un'email di completamento all'indirizzo email del proprietario del progetto. Puoi sovrascriverlo con notification_email:

{
    "url": ["https://example.com/page1", "https://example.com/page2"],
    "async_mode": true,
    "notification_email": "[email protected]"
}

Callback webhook#

Fornisci un callback_url nella richiesta per ricevere una notifica POST automatica al completamento del job:

{
    "url": ["https://example.com/page1", "https://example.com/page2"],
    "async_mode": true,
    "callback_url": "https://your-server.com/webhook/enconvert"
}

Il webhook viene inviato con un timeout di 30 secondi e considera HTTP 200, 201, 202 e 204 come consegna riuscita.

Elaborazione batch e di massa#

Converti più URL in un'unica richiesta. Richiede la modalità asincrona e una chiave privata.

Output individuale (predefinito)#

Ogni URL produce un file PDF separato:

{
    "url": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ],
    "async_mode": true
}

Output in bundle ZIP#

Raggruppa tutti i PDF in un unico archivio ZIP:

{
    "url": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ],
    "async_mode": true,
    "output_format": true,
    "output_filename": "monthly-reports"
}

Il file ZIP viene nominato {output_filename}_{timestamp}.zip oppure batch_{timestamp}.zip se non viene fornito un nome personalizzato.

Esempi di codice#

Python (chiave privata)#

import requests

response = requests.post(
    "https://api.enconvert.com/v1/convert/url-to-pdf",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "single_page": True,
        "pdf_options": {
            "page_size": "A4",
            "margins": {"top": 15, "bottom": 15, "left": 10, "right": 10}
        }
    }
)

data = response.json()
print(data["presigned_url"])

PHP (chiave privata)#

$ch = curl_init("https://api.enconvert.com/v1/convert/url-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",
        "single_page" => true,
        "pdf_options" => [
            "page_size" => "A4",
            "margins" => ["top" => 15, "bottom" => 15, "left" => 10, "right" => 10]
        ]
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data["presigned_url"];

Node.js (chiave privata)#

const response = await fetch("https://api.enconvert.com/v1/convert/url-to-pdf", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com",
        single_page: true,
        pdf_options: {
            page_size: "A4",
            margins: { top: 15, bottom: 15, left: 10, right: 10 }
        }
    })
});

const data = await response.json();
console.log(data.presigned_url);

Go (chiave privata)#

package main

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

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "url":         "https://example.com",
        "single_page": true,
        "pdf_options": map[string]interface{}{
            "page_size": "A4",
            "margins":   map[string]int{"top": 15, "bottom": 15, "left": 10, "right": 10},
        },
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/url-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))
}

JavaScript -- Browser (chiave pubblica)#

// Step 1: Get a JWT token
const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
    method: "POST",
    headers: { "X-API-Key": "pk_your_public_key" }
});
const { token } = await tokenRes.json();

// Step 2: Convert URL to PDF
const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-pdf", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({
        url: "https://example.com"
    })
});

const data = await convertRes.json();
// Open the PDF in a new tab
window.open(data.presigned_url, "_blank");

React (chiave pubblica)#

import { useState } from "react";

function UrlToPdf() {
    const [loading, setLoading] = useState(false);
    const [pdfUrl, setPdfUrl] = useState(null);

    async function convertUrl() {
        setLoading(true);
        try {
            // Get JWT token
            const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
                method: "POST",
                headers: { "X-API-Key": "pk_your_public_key" }
            });
            const { token } = await tokenRes.json();

            // Convert
            const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-pdf", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    "Authorization": `Bearer ${token}`
                },
                body: JSON.stringify({ url: "https://example.com" })
            });

            const data = await convertRes.json();
            setPdfUrl(data.presigned_url);
        } finally {
            setLoading(false);
        }
    }

    return (
        <div>
            <button onClick={convertUrl} disabled={loading}>
                {loading ? "Converting..." : "Convert to PDF"}
            </button>
            {pdfUrl && <a href={pdfUrl} target="_blank" rel="noreferrer">Download PDF</a>}
        </div>
    );
}

export default UrlToPdf;

Risposte di errore#

Limiti#

Domande frequenti#

Come converto una pagina web in PDF con un'API REST?#

Invia una richiesta POST a /v1/convert/url-to-pdf con un corpo JSON contenente l'url da convertire, autenticandoti con la tua chiave privata nell'header X-API-Key (oppure con un token Bearer JWT ottenuto da una chiave pubblica). La risposta sincrona restituisce un presigned_url per scaricare il PDF, oppure i byte grezzi del PDF quando direct_download=true.

Posso convertire più URL in PDF in un'unica richiesta API?#

Sì. Passa un array di URL nel parametro url con async_mode=true (è richiesta una chiave privata); l'API restituisce HTTP 202 con un batch_id che interroghi tramite GET /v1/convert/batch/{batch_id}. Imposta output_format=true per raggruppare tutti i PDF in un unico archivio ZIP.

Come catturo un'intera pagina web come un'unica pagina PDF continua?#

La modalità a pagina singola è quella predefinita (single_page=true): l'intera pagina viene renderizzata come un'unica pagina PDF continua, la cui altezza è calcolata in base al contenuto effettivo. Imposta single_page=false per un output paginato con page_size, orientation, margins e header/footer opzionali tramite pdf_options.

Perché il mio PDF mostra banner cookie o immagini mancanti?#

La chiusura dei banner cookie (handle_cookies) e la gestione del lazy-load (enable_scroll, load_media, wait_for_images) sono tutte predefinite a true e coprono OneTrust, Cookiebot, Didomi, Usercentrics e i banner generici. Se imposti load_media=false, la conversione è più veloce ma i contenuti multimediali possono apparire come segnaposto.

Posso convertire in PDF una pagina protetta da login?#

Sì. Usa il parametro auth per l'HTTP Basic Auth, inietta fino a 50 cookie di sessione con cookies, oppure invia fino a 20 header HTTP personalizzati con headers. Queste opzioni richiedono l'accesso a basic auth nel tuo piano, e auth non può essere combinato con un header personalizzato Authorization.