Integrazioni#

La stessa API, raggiungibile dagli strumenti che usi già. Un server MCP porta EnConvert dentro un agente di coding, una skill ClawHub dentro OpenClaw, un nodo n8n e un'integrazione Zapier dentro le tue automazioni, un plugin Dify dentro i tuoi agenti e i tuoi workflow, una CLI nel tuo terminale, dieci SDK nel codice della tua applicazione e un widget web sul tuo sito.

Scegli la tua superficie#

Ogni superficie qui sotto chiama gli stessi endpoint REST pubblici con la stessa chiave API, sullo stesso progetto e sulla stessa quota mensile di operazioni.

Esiste un'ottava superficie senza una pagina propria: i web widget, trattati qui sotto, che è l'unica con cui i tuoi utenti finali interagiscono direttamente.

Se stai ancora decidendo, REST, MCP e CLI mette a confronto le superfici di accesso fianco a fianco, e Autenticazione spiega di quale tipo di chiave ha bisogno ciascuna.

Web widget#

I web widget integrano la conversione di URL e file in qualsiasi sito web con un singolo tag script, così i tuoi visitatori convertono un URL in PDF, catturano uno screenshot o convertono un file caricato senza lasciare la tua pagina. Il codice di embed contiene soltanto un ID del widget. L'autenticazione avviene dentro l'iframe tramite una challenge Cloudflare Turnstile e un JWT di breve durata emesso da POST /v1/widget/{widget_id}/token, così nessuna chiave API viene mai esposta nel tuo codice frontend.

Ogni widget è legato a un endpoint di conversione e a un elenco di domini consentiti, entrambi impostati nella dashboard. Dietro un widget può esserci qualsiasi endpoint di conversione:

• Basati su URL: url-to-pdf, url-to-screenshot
• Basati su file: tutti gli endpoint di formato dati, documento in PDF e conversione di immagini

Come Funzionano i Widget#

Impostazione#

1. Vai alla tua Dashboard > Widgets di EnConvert e clicca Create Widget.
2. Seleziona l'endpoint di conversione (es. /v1/convert/url-to-pdf) e specifica i domini in cui il widget verrà integrato. I sottodomini con wildcard sono supportati (es. *.example.com).
3. Una chiave API pubblica interna viene creata automaticamente per il widget, limitata all'endpoint selezionato e ai domini consentiti. Questa chiave non viene mai esposta.

Due precondizioni colgono spesso di sorpresa: l'email del tuo account deve essere verificata e l'elenco dei domini consentiti non può essere vuoto. Se ne manca una, la creazione del widget viene rifiutata.

Integrazione#

Aggiungi lo script di embed al tuo sito web:

<script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>

Lo script crea un iframe sandboxed che carica il widget EnConvert. Nessuna chiave API compare nel codice di embed.

Flusso a Runtime#

1. Il widget si carica nell'iframe e recupera la sua configurazione da GET /v1/widget/{widget_id}/config.
2. Validazione del dominio: il widget verifica che l'origin della pagina genitore corrisponda all'elenco dei domini consentiti. Supporta domini esatti e pattern di sottodomini con wildcard (*.example.com).
3. L'utente invia un URL o un file: il widget richiede un token di challenge Turnstile invisibile.
4. Scambio del token: il widget invia il token Turnstile a POST /v1/widget/{widget_id}/token e riceve un JWT (scadenza 1 ora) più un cookie di refresh token (scadenza 7 giorni).
5. Conversione: il widget chiama l'endpoint di conversione con il JWT.
6. Risultato: l'API restituisce una risposta JSON con un presigned_url. Il widget mostra un link di download.
7. Recupero da timeout: se la conversione supera i limiti di timeout del reverse-proxy, il widget interroga GET /v1/convert/status/{job_id} usando il job ID pre-generato.

Refresh Automatico dei Token#

Il widget non smette mai di funzionare a causa di un'autenticazione scaduta:

• Alla conversione iniziale, l'API emette sia un JWT (scadenza 1 ora) sia un refresh token (scadenza 7 giorni, cookie httpOnly).
• Nelle conversioni successive, il widget prova prima a rinnovare il JWT tramite POST /v1/widget/{widget_id}/refresh usando il cookie di refresh token, senza alcuna challenge Turnstile richiesta.
• Se il refresh token stesso è scaduto (dopo 7 giorni di inattività), il widget ripiega su una nuova challenge Turnstile.
• Il refresh token viene ruotato a ogni refresh: ogni refresh emette un nuovo cookie da 7 giorni.

Questo significa che un visitatore del widget che converte ogni pochi giorni non vedrà mai una challenge Turnstile dopo la prima.

Endpoint dei Widget#

Configurazione#

Recupera la configurazione di uno specifico widget. Nessuna autenticazione richiesta.

GET /v1/widget/{widget_id}/config

Risposta:

{
    "endpoint": "/v1/convert/url-to-pdf",
    "input_type": "url",
    "allowed_domains": ["https://example.com", "*.example.com"],
    "turnstile_site_key": "1x00000000000000000000AA",
    "widget_branding": true
}

Scambio del Token#

Scambia un token di challenge Turnstile con un JWT. Imposta un cookie di refresh token.

POST /v1/widget/{widget_id}/token
X-Parent-Origin: https://your-website.com
Content-Type: application/json

{
    "turnstile_token": "cloudflare-challenge-response-token"
}

Risposta:

{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Imposta inoltre un cookie httpOnly refresh_token (scadenza 7 giorni, Secure, SameSite=none).

Refresh del Token#

Rinnova un JWT scaduto usando il cookie httpOnly di refresh token. Nessuna challenge Turnstile richiesta.

POST /v1/widget/{widget_id}/refresh
X-Parent-Origin: https://your-website.com

Non serve alcun corpo della richiesta. Il refresh token viene letto automaticamente dal cookie.

Risposta:

{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Il cookie di refresh token viene ruotato a ogni refresh (viene emesso un nuovo cookie da 7 giorni).

Risposte di errore: - 401: nessun cookie di refresh token o refresh token scaduto - 403: il refresh token non corrisponde al progetto del widget, oppure dominio non autorizzato - 404: widget non trovato o disattivato

Risposta di Conversione#

Sia le conversioni dei widget basate su URL sia quelle basate su file restituiscono una risposta JSON coerente con un URL di download presigned:

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf",
    "filename": "example_20260405_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 8.5,
    "job_id": "client-generated-uuid"
}

Il widget usa il presigned_url per mostrare un link di download. Gli URL presigned scadono dopo 15 minuti. Consulta URL di download firmati per capire cosa significa quella finestra per i tuoi visitatori.

Restrizioni di conversione dei widget: - Solo URL singolo / file singolo - Solo modalità sincrona (nessun async o batch) - Nessuna callback webhook o email di notifica - Endpoint limitato a quello configurato per il widget

Branding del Widget#

I piani che includono il branding del widget mostrano un piccolo badge "Powered by EnConvert" in fondo al widget. Questo è controllato dal campo widget_branding del piano di abbonamento:

Il badge di branding rimanda a https://www.enconvert.com ed è stilizzato per essere discreto: testo piccolo sotto il modulo del widget con opacità ridotta.

Gestione dei Widget#

I widget si gestiscono tramite la dashboard di EnConvert o l'API del backend:

Riferimento del Codice di Embed#

HTML Standard#

<script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>

Lo script: - Crea un iframe sandboxed (allow-scripts allow-same-origin allow-forms allow-popups) - Imposta width: 100%, altezza iniziale 400px, nessun bordo - Abilita il permesso clipboard-write - Usa il lazy loading - Ascolta i messaggi Enconvert:resize per regolare automaticamente l'altezza

Shortcode WordPress#

Se usi il plugin WordPress di EnConvert, integra i widget tramite lo shortcode:

[enconvert_widget id="your-widget-id"]

Personalizzazione dello Stile#

Personalizza l'aspetto del widget tramite parametri di query sull'URL dello script di embed o sulla sorgente dell'iframe:

Comunicazione con l'Iframe#

Il widget comunica con la pagina genitore tramite postMessage. Ascolta questi eventi nella pagina genitore:

Questi quattro nomi di evento sono un contratto wire congelato. Rispetta le maiuscole e le minuscole esattamente.

Esempio: Ascolto degli Eventi#

window.addEventListener("message", function(e) {
    if (!e.data || !e.data.type) return;

    if (e.data.type === "Enconvert:conversion:complete") {
        console.log("Conversion done:", e.data.data.url);
    }

    if (e.data.type === "Enconvert:conversion:error") {
        console.error("Conversion failed:", e.data.data.error);
    }
});

Sicurezza#

Domande frequenti#

Come integro un widget di conversione file sul mio sito web?#

Crea un widget nella dashboard di EnConvert (Dashboard > Widgets > Create Widget), poi aggiungi un tag script alla tua pagina: <script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>. Se il tuo sito usa WordPress, puoi invece usare lo shortcode [enconvert_widget id="your-widget-id"] del plugin WordPress di EnConvert.

Devo esporre una chiave API per integrare un widget di conversione?#

No. Il codice di embed contiene solo l'ID del widget. Una chiave API pubblica interna viene generata automaticamente per ogni widget, limitata all'endpoint configurato e ai domini consentiti, e non è mai visibile nel tuo codice frontend.

Come autentica gli utenti il widget senza una chiave API?#

Il widget richiede una challenge Cloudflare Turnstile invisibile e la scambia su POST /v1/widget/{widget_id}/token con un JWT con scadenza di 1 ora più un cookie httpOnly di refresh token con scadenza di 7 giorni. Le conversioni successive rinnovano il JWT tramite POST /v1/widget/{widget_id}/refresh senza nuova challenge, e il refresh token viene ruotato a ogni refresh.

Posso limitare quali domini possono usare il mio widget integrato?#

Sì. Ogni widget ha un elenco di domini consentiti che supporta domini esatti e sottodomini con wildcard come *.example.com, convalidato lato server all'emissione del token, con header CSP frame-ancestors che limitano quali pagine possono integrare l'iframe.

Come rimuovo il badge Powered by EnConvert dal widget?#

Il badge è controllato dal campo widget_branding del tuo piano di abbonamento. Solo il piano gratuito Founding lo mostra. Indie, Studio, Production ed Enterprise lo nascondono tutti, quindi qualsiasi piano a pagamento rimuove il badge.

Con quale integrazione dovrei iniziare?#

Se stai scrivendo codice, parti da un SDK per il tuo linguaggio. Se automatizzi senza scrivere codice, usa n8n o Zapier. Se stai costruendo un agente o un workflow dentro Dify, installa il plugin Dify. Se vuoi che sia un assistente AI a fare il lavoro, installa il server MCP, oppure la skill ClawHub se usi OpenClaw. Se vuoi soltanto che siano i tuoi visitatori a convertire i file, usa un web widget.

Le integrazioni condividono una sola chiave API e una sola quota?#

Sì. Tutte si autenticano come lo stesso progetto, quindi le operazioni vengono conteggiate su un'unica quota mensile indipendentemente dalla superficie che ha effettuato la chiamata. Consulta Rate limit e quote.