API Documentation

API di Conversione Batch File#

L'API batch di EnConvert converte più URL in un'unica richiesta: passa un array di URL a /v1/convert/url-to-pdf o /v1/convert/url-to-screenshot e ricevi una risposta HTTP 202 con un batch_id. Ogni URL viene convertito in modo asincrono in background e i risultati vengono consegnati come URL di download presigned, uno per file oppure raggruppati in un unico archivio ZIP. Tieni traccia dell'avanzamento facendo polling su GET /v1/convert/batch/{batch_id}, oppure ricevi una notifica via webhook callback o email al completamento.

Solo chiavi private: L'elaborazione batch è disponibile solo autenticandoti con una chiave API privata (X-API-Key: sk_...). Le chiavi pubbliche sono limitate a richieste sincrone su singolo URL.

How It Works#

  1. Invia una richiesta con un array di URL nel parametro url a /v1/convert/url-to-pdf oppure a /v1/convert/url-to-screenshot.
  2. L'API convalida il batch rispetto ai limiti del tuo piano e restituisce HTTP 202 con un batch_id.
  3. Ogni URL viene convertito in background e addebita una op. Il numero totale del batch viene verificato in anticipo rispetto alla quota mensile di ops rimanente, prima che inizi qualsiasi elaborazione.
  4. Tieni traccia dell'avanzamento tramite GET /v1/convert/batch/{batch_id}, oppure ricevi un webhook callback o una notifica email al completamento.
  5. Scarica i risultati tramite URL presigned nella risposta di stato del batch.

Output Modes#

Modalità Individuale (Predefinita)#

Ogni URL produce un file separato. Ogni file riceve il proprio URL di download presigned nella risposta di stato del batch.

Richiesta:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ]
  }'

Risposta (HTTP 202 Accepted):

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 3,
    "output_format": "individual"
}
Nota: Quando passi più URL, async_mode viene impostato automaticamente su true, indipendentemente dal fatto che tu lo includa esplicitamente nella richiesta.

Modalità Bundle ZIP#

Imposta output_format su true per ricevere tutti i file convertiti raggruppati in un unico archivio ZIP. Richiede un piano con accesso all'output ZIP.

Richiesta:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ],
    "output_format": true,
    "output_filename": "monthly-reports"
  }'

Risposta (HTTP 202 Accepted):

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

In modalità ZIP, tutti gli URL vengono elaborati in sequenza e i risultati riusciti vengono raggruppati in un unico archivio ZIP denominato {output_filename}_{timestamp}.zip (oppure batch_{timestamp}.zip se non viene fornito un nome personalizzato).

Parametri Batch#

Parametro Tipo Predefinito Descrizione Limitazione per Piano
url string[] (obbligatorio) Array di URL da convertire. --
output_format boolean false Imposta su true per raggruppare tutti i risultati in un archivio ZIP. Richiede più URL. Richiede accesso all'output ZIP
output_filename string Generato automaticamente Nome file personalizzato per l'output. In modalità ZIP, assegna il nome all'archivio ZIP. --
async_mode boolean true (implicito) Sempre true per il batch. Abilitato automaticamente quando vengono forniti più URL. Richiede accesso asincrono
notification_email string Email del proprietario del progetto Indirizzo email da notificare al completamento. Se omesso, viene usata di default l'email del proprietario del progetto. --
callback_url string null URL webhook su cui ricevere una POST al completamento. Richiede accesso webhook
direct_download -- -- Non supportato per il batch. Restituisce un errore 400 se impostato con più URL. --

Parametri di Browser e Rendering#

Queste impostazioni si applicano a ogni URL del batch:

Parametro Tipo Predefinito Descrizione
viewport_width integer 1920 Larghezza del viewport del browser in pixel.
viewport_height integer 1080 Altezza del viewport del browser in pixel.
single_page boolean true Esegue il rendering come pagina unica continua (solo url-to-pdf).
load_media boolean true Attende il caricamento di immagini e media.
enable_scroll boolean true Scorre le pagine per attivare i contenuti a caricamento differito (lazy-loaded).
handle_sticky_header boolean true Rileva e gestisce le intestazioni sticky/fisse.
handle_cookies boolean true Chiude automaticamente i banner di consenso cookie.
wait_for_images boolean true Attende il completamento del caricamento di tutte le immagini.

Autenticazione e Richieste Personalizzate#

Si applicano a ogni URL del batch. Richiedono un piano con accesso all'autenticazione basic.

Parametro Tipo Predefinito Descrizione
auth object null Credenziali HTTP Basic Auth: {"username": "...", "password": "..."}.
cookies array null Array di oggetti cookie iniettati prima di ogni caricamento pagina. Massimo 50.
headers object null Header HTTP personalizzati inviati con ogni richiesta. Massimo 20.

Opzioni PDF (solo url-to-pdf)#

Passa un oggetto pdf_options per controllare la formattazione dell'output PDF per ogni pagina del batch:

Parametro Tipo Predefinito Descrizione
page_size string "A4" Formato pagina denominato.
orientation string "portrait" "portrait" oppure "landscape".
margins object {"top": 10, "bottom": 10, "left": 10, "right": 10} Margini in mm.
grayscale boolean false Output in scala di grigi tramite Ghostscript.

Polling dello Stato del Batch#

Usa l'endpoint di stato del batch per controllare l'avanzamento e recuperare gli URL di download.

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

Sostituisci {batch_id} con il batch_id restituito dalla richiesta iniziale.

Stato di Elaborazione#

Mentre le conversioni sono ancora in corso:

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 3,
    "completed": 1,
    "failed": 0,
    "in_progress": 2,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        },
        {
            "source_url": "https://example.com/page-3",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}

Stato Completato#

Quando tutti gli URL sono stati convertiti con successo:

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "in_progress": 0,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 210944,
            "duration": "4.55"
        },
        {
            "source_url": "https://example.com/page-3",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 97280,
            "duration": "2.87"
        }
    ]
}

Stato Parziale#

Quando tutti gli URL hanno terminato ma alcuni sono falliti:

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "partial",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "in_progress": 0,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 210944,
            "duration": "4.55"
        },
        {
            "source_url": "https://invalid-url.example",
            "status": "Failed",
            "download_url": null,
            "output_file_size": null,
            "duration": "0.87"
        }
    ]
}

Modalità ZIP Completata#

In modalità ZIP, viene fornito un singolo zip_download_url per l'intero archivio:

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "in_progress": 0,
    "output_mode": "zip",
    "zip_download_url": "https://spaces.example.com/...",
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 210944,
            "duration": "4.55"
        },
        {
            "source_url": "https://example.com/page-3",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 97280,
            "duration": "2.87"
        }
    ]
}

Valori di Stato del Batch#

Stato Significato
processing Almeno un URL è ancora in fase di conversione.
completed Tutti gli URL sono stati convertiti con successo.
partial Tutti gli URL hanno terminato, ma alcuni sono falliti.
failed Tutti gli URL sono falliti.

Webhook Callback#

Fornisci un callback_url nella richiesta per ricevere una notifica POST automatica al completamento. Il webhook viene inviato con Content-Type: application/json e un timeout di 30 secondi. Non viene effettuato alcun retry in caso di fallimento della consegna.

Callback in Modalità Individuale#

In modalità individuale, viene inviata una POST webhook separata per ogni URL man mano che si completa:

{
    "job_id": "12345",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/page1_20260405_123456789.pdf",
    "filename": "page1_20260405_123456789.pdf",
    "file_size": 184320
}

Callback in Modalità ZIP#

In modalità ZIP, viene inviata una singola POST webhook quando l'intero batch si completa:

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip",
    "filename": "batch_20260405_123456789.zip",
    "file_size": 456789,
    "total_tasks": 3,
    "successful_tasks": 2,
    "failed_tasks": 1,
    "tasks": [
        {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"},
        {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"},
        {"url": "https://invalid.example", "status": "failed", "error": "Page load timeout"}
    ]
}
Differenza nel comportamento delle notifiche: In modalità individuale, ricevi N POST webhook separate (una per URL) e N email separate. In modalità ZIP, ricevi una POST webhook e una email per l'intero batch. Tienine conto quando progetti il tuo gestore webhook.

Notifiche Email#

Un'email di completamento viene inviata a notification_email quando il batch termina. Se non viene fornito alcun notification_email, l'email viene inviata di default all'email del proprietario del progetto.

L'email include:

  • Stato del job (success/failed) con un banner colorato
  • Batch ID
  • Per i job batch: una tabella con l'elenco di ogni URL, il relativo stato e il nome del file di output
  • Un link per scaricare i risultati dalla dashboard

Limitazioni per Piano di Abbonamento#

Funzionalità Founding Indie Studio Enterprise
Elaborazione batch No Sì Sì Sì
Modalità asincrona No Sì Sì Sì
Raggruppamento output ZIP No No Sì Sì
Webhook callback No No Sì Sì
HTTP Basic Auth / Cookie / Header No Sì Sì Sì
Limite dimensione batch 0 In base al piano In base al piano Illimitato
Conversioni mensili 100 In base al piano In base al piano Illimitato

Esempi di Codice#

Python -- Modalità Individuale con Polling#

import requests
import time

# Submit batch
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/page-1",
            "https://example.com/page-2",
            "https://example.com/page-3"
        ]
    }
)

data = response.json()
batch_id = data["batch_id"]
print(f"Batch started: {batch_id} ({data['url_count']} URLs)")

# Poll for completion
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"):
        for item in status["items"]:
            if item["download_url"]:
                print(f"  {item['source_url']} -> {item['download_url']}")
        break

    time.sleep(5)

Python -- Modalità ZIP con Webhook#

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/page-1",
            "https://example.com/page-2",
            "https://example.com/page-3"
        ],
        "output_format": True,
        "output_filename": "monthly-reports",
        "callback_url": "https://your-server.com/webhook/enconvert",
        "pdf_options": {
            "page_size": "A4",
            "orientation": "portrait"
        }
    }
)

data = response.json()
print(f"Batch started: {data['batch_id']}")
print(f"URLs: {data['url_count']}, Format: {data['output_format']}")
# Results will be delivered to your webhook URL

Node.js -- Screenshot in Batch#

const response = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: [
            "https://example.com/page-1",
            "https://example.com/page-2",
            "https://example.com/page-3"
        ],
        output_format: true,
        output_filename: "screenshots-bundle"
    })
});

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

Risposte di Errore#

Stato Condizione
400 Bad Request url è vuoto o mancante
400 Bad Request output_format=true con un singolo URL (richiede più URL)
400 Bad Request direct_download=true con più URL (non supportato)
400 Bad Request direct_download=true con async_mode=true
400 Bad Request Chiave pubblica che tenta più URL
402 Payment Required Il batch supererebbe la quota mensile di ops rimanente
402 Payment Required Limite di storage raggiunto
403 Forbidden Elaborazione asincrona non disponibile sul piano attuale
403 Forbidden Elaborazione batch non disponibile (limite batch pari a 0)
403 Forbidden La dimensione del batch supera il limite del piano
403 Forbidden Output ZIP non disponibile sul piano attuale
403 Forbidden Webhook callback non disponibili sul piano attuale
404 Not Found Batch non trovato (batch_id errato o progetto errato)

Limiti#

Limite Valore
Dimensione batch Dipende dal piano (Founding: disabilitato)
Conversioni mensili Dipende dal piano (l'intero batch viene verificato in anticipo)
Timeout di consegna webhook 30 secondi (nessun retry)
Numero massimo di cookie per richiesta 50
Numero massimo di header personalizzati per richiesta 20
Conservazione dei file Dipende dal piano

Domande frequenti#

Come converto più URL in PDF con un'unica richiesta API?#

Invia una POST a /v1/convert/url-to-pdf con un array di URL nel parametro url, autenticandoti con una chiave API privata (sk_...). L'API risponde con HTTP 202 e un batch_id, e ogni URL viene convertito in background.

Posso ottenere tutti i risultati della conversione batch in un unico file ZIP?#

Sì. Imposta output_format su true per raggruppare tutti i risultati riusciti in un unico archivio ZIP denominato {output_filename}_{timestamp}.zip (oppure batch_{timestamp}.zip se non viene fornito un nome personalizzato). L'output ZIP richiede un piano con accesso all'output ZIP (Studio, Production o Enterprise) e più URL nella richiesta.

Come controllo lo stato di un job di conversione batch?#

Effettua il polling di GET /v1/convert/batch/{batch_id} con la tua chiave API privata. La risposta indica processing, completed, partial, oppure failed, insieme agli elementi per singolo URL contenenti download_url, output_file_size e duration.

Perché la mia richiesta batch restituisce 403 Forbidden?#

Un 403 Forbidden indica che è stata raggiunta una limitazione del piano: l'elaborazione asincrona non è disponibile sul tuo piano, l'elaborazione batch è disabilitata (limite batch pari a 0), la dimensione del batch supera il limite del tuo piano, oppure una funzionalità limitata come l'output ZIP o i webhook callback non è inclusa nel tuo piano.

Posso usare l'elaborazione batch con una chiave API pubblica?#

No. L'elaborazione batch richiede una chiave API privata (sk_...). Le chiavi pubbliche sono limitate a richieste sincrone su singolo URL, e l'invio di più URL con una chiave pubblica restituisce 400 Bad Request.

← Webhooks Integrations →