API Documentation

Callback Webhook di Conversione e Notifiche Job#

EnConvert ti avvisa quando i job di conversione asincroni e batch sono completati tramite tre meccanismi indipendenti: polling su GET /v1/convert/batch/{batch_id}, callback webhook tramite il parametro callback_url e notifiche email tramite notification_email. Tutti e tre possono essere combinati in un'unica richiesta, e i file completati vengono recuperati tramite gli URL di download presenti nella risposta dello stato del batch. Questa pagina documenta i payload dei callback, i requisiti di consegna e le limitazioni di piano per ciascun metodo.

Solo chiavi private: le notifiche dei job e il polling dello stato del batch sono disponibili solo quando ti autentichi con una chiave API privata (X-API-Key: sk_...). Le chiavi pubbliche non supportano l'elaborazione asincrona o batch.

Panoramica#

Metodo Parametro / Endpoint Descrizione
Polling GET /v1/convert/batch/{batch_id} Esegui il polling per lo stato in tempo reale, i conteggi di avanzamento e gli URL di download.
Email notification_email Invia un'email di completamento con lo stato del job e un link alla dashboard.
Webhook callback_url Invia una richiesta POST con i risultati del job al tuo server.

Tutti e tre i metodi funzionano sia per i job asincroni a URL singolo sia per i job batch multi-URL sugli endpoint url-to-pdf, url-to-screenshot, website-to-pdf e website-to-screenshot.

Polling dello stato del batch#

Il modo consigliato per tracciare l'avanzamento del job. Esegui il polling dell'endpoint dello stato del batch con il batch_id restituito nella risposta 202 iniziale.

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

Risposta#

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

Valori di stato#

Stato Significato
processing Almeno un URL è ancora in fase di conversione.
completed Tutti gli URL convertiti con successo.
partial Tutti gli URL terminati, ma alcuni non sono riusciti.
failed Tutti gli URL non sono riusciti.

In modalità ZIP (output_mode: "zip"), viene fornito uno zip_download_url per l'intero archivio una volta completato. In modalità individuale, ogni elemento ha il proprio download_url.

Per i dettagli completi sullo schema della risposta, consulta Elaborazione in Batch.

Notifiche Email#

Includi il parametro notification_email nella tua richiesta per ricevere un'email quando il job viene completato. Se ometti questo parametro, l'email viene inviata per impostazione predefinita all'indirizzo email del proprietario del progetto.

Esempio#

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",
    "async_mode": true,
    "notification_email": "[email protected]"
  }'

Risposta (HTTP 202 Accepted)#

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

Contenuto dell'email#

L'email di completamento include:

  • Intestazione di stato con un banner colorato (verde per il successo, rosso per il fallimento)
  • Job ID e Batch ID (se fa parte di un batch)
  • Testo di stato (success o failed)
  • Testo statico che indirizza gli utenti a scaricare i file dalla propria dashboard
  • Tabella dei task (solo job batch in modalità ZIP) con le colonne: #, URL (troncato a 50 caratteri), stato e nome del file di output

In modalità individuale (inclusi i batch individuali multi-URL), ogni email per singolo URL contiene solo il job ID e lo stato -- nessuna tabella dei task. In modalità ZIP, la singola email del batch include la tabella completa dei task con tutti gli URL e i relativi stati.

Comportamento predefinito: se non includi notification_email nella tua richiesta, l'email di completamento viene inviata automaticamente all'indirizzo email del proprietario del progetto. Per sopprimere completamente le notifiche email, attualmente questo comportamento predefinito non può essere disabilitato.

Callback Webhook#

Includi il parametro callback_url nella tua richiesta per ricevere un POST webhook quando il job viene completato. Richiede un piano con accesso ai webhook.

Esempio#

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",
    "async_mode": true,
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Risposta (HTTP 202 Accepted)#

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

Payload del Callback per URL Singolo / Modalità Individuale#

In modalità individuale, viene inviato un POST separato per ogni URL non appena viene completato:

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

Per una conversione non riuscita:

{
    "job_id": "12345",
    "status": "failed",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000"
}

Payload del Callback in Modalità ZIP#

In modalità ZIP, viene inviato un singolo POST quando l'intero batch viene completato:

{
    "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-url.example", "status": "failed", "error": "Page load timeout"}
    ]
}
Comportamento delle notifiche individuale vs ZIP: in modalità individuale, ricevi N POST webhook separati (uno per URL) e N email separate. In modalità ZIP, ricevi un POST webhook e un'email per l'intero batch. Progetta di conseguenza il tuo gestore di webhook.

Usare Più Metodi di Notifica Insieme#

Puoi combinare polling, email e webhook nella stessa richiesta. Tutti e tre funzionano in modo indipendente.

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"
    ],
    "notification_email": "[email protected]",
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Dopo l'invio, puoi: 1. Eseguire il polling di GET /v1/convert/batch/{batch_id} per l'avanzamento in tempo reale 2. Ricevere un POST webhook al tuo callback URL quando ogni conversione termina 3. Ricevere un'email all'indirizzo specificato quando ogni conversione termina

Parametri di Notifica#

Parametro Tipo Obbligatorio Predefinito Descrizione Limitazioni di piano
notification_email string No Email del proprietario del progetto Indirizzo email che riceve le notifiche di completamento del job. --
callback_url string No -- URL che riceve un POST webhook al completamento. Richiede l'accesso ai webhook

Requisiti di Consegna del Webhook#

Requisito Dettaglio
Metodo EnConvert invia una richiesta POST con Content-Type: application/json.
Timeout Il tuo endpoint deve rispondere entro 30 secondi.
Codici di successo HTTP 200, 201, 202 o 204 sono trattati come consegna riuscita.
Tentativi Nessun tentativo in caso di fallimento. Se la consegna del webhook fallisce (risposta non riuscita o timeout), i risultati restano comunque disponibili tramite il polling dello stato del batch.
Autenticazione Non viene inviato alcun header di autenticazione. Convalida il batch_id rispetto ai tuoi record se necessario.

Limitazioni in Base al Piano di Abbonamento#

Funzionalità Founding Indie Studio Enterprise
Modalità asincrona No Sì Sì Sì
Polling dello stato del batch No Sì Sì Sì
Notifiche email No Sì Sì Sì
Callback webhook (callback_url) No No Sì Sì
Nota: le notifiche email non sono soggette a una limitazione di funzionalità separata -- sono disponibili per qualsiasi utente con chiave API privata che disponga dell'accesso asincrono. Il parametro notification_email non richiede una funzionalità di piano specifica. I callback webhook (callback_url) richiedono la funzionalità has_webhook, disponibile sui piani Studio e superiori.

Testare i Webhook#

Durante lo sviluppo, usa webhook.site per generare un callback URL temporaneo per i test:

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",
    "async_mode": true,
    "callback_url": "https://webhook.site/your-unique-id"
  }'

Visita la tua dashboard di webhook.site per ispezionare il payload esatto del callback una volta completato il job.

Domande frequenti#

Come ricevo un callback webhook quando un job di conversione file è completato?#

Includi il parametro callback_url nella tua richiesta con una chiave API privata. EnConvert invia un POST con Content-Type: application/json a quell'URL quando il job viene completato. I callback webhook richiedono un piano con accesso ai webhook (Studio, Production o Enterprise).

EnConvert ritenta le consegne webhook non riuscite?#

No. Il tuo endpoint deve rispondere entro 30 secondi con HTTP 200, 201, 202 o 204. Se la consegna fallisce, i risultati restano disponibili tramite il polling dello stato del batch su GET /v1/convert/batch/{batch_id}.

Posso usare insieme le notifiche email, webhook e polling?#

Sì. notification_email, callback_url e il polling dello stato funzionano tutti in modo indipendente e possono essere combinati nella stessa richiesta. Se notification_email viene omesso, l'email di completamento viene inviata di default all'indirizzo email del proprietario del progetto.

Perché ricevo un webhook per ogni URL invece di uno per l'intero batch?#

In modalità individuale ricevi N POST webhook separati (uno per URL) e N email separate. Per ricevere un solo webhook e una sola email per l'intero batch, usa la modalità ZIP, che invia un unico POST con total_tasks, successful_tasks, failed_tasks e un array tasks.

Come posso testare i callback webhook durante lo sviluppo?#

Usa webhook.site per generare un URL temporaneo e passalo come callback_url nella tua richiesta. La dashboard di webhook.site mostra il payload JSON esatto che EnConvert consegna quando il job viene completato.

← File Ingestion Batch Processing →