Integrazioni#

La stessa API, raggiungibile dagli strumenti che usi già. Un server MCP porta EnConvert dentro un agente di coding, un nodo n8n dentro un 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 una quinta superficie senza una pagina propria: i web widget, trattati qui sotto, che sono 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.

Per rimuovere il branding, abbandona il piano gratuito Founding. Qualsiasi piano a pagamento lo nasconde.

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. Se vuoi che sia un assistente AI a fare il lavoro, installa il server MCP. 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.