---
seo_title: Integrazioni: MCP, n8n, CLI, SDK e widget | EnConvert
meta_desc: Raggiungi l'API EnConvert dagli strumenti che usi già: server MCP per agenti di coding, nodo n8n, CLI da terminale, dieci SDK e widget web integrabili.
keywords: integrazioni enconvert, server mcp conversione file, nodo n8n conversione file, cli conversione file da terminale, sdk conversione file, integrare widget convertitore file sul sito, widget conversione file iframe, shortcode convertitore file wordpress, widget url in pdf da integrare
---

# 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.

| Superficie | Pacchetto | Quando usarla |
|---------|---------|-------------|
| [Impostazione MCP](/it/docs/guides/integrations/mcp-setup.md) | `@enconvert/mcp` | Un agente di coding come Claude Code, Cursor, Windsurf o Claude Desktop deve chiamare l'API da solo, in chat, senza che tu scriva HTTP. |
| [n8n](/it/docs/guides/integrations/n8n.md) | `@enconvert/n8n-nodes-enconvert` | Stai costruendo un workflow n8n e vuoi conversioni, scraping e crawling come un nodo che emette dati binari veri. |
| [CLI](/it/docs/guides/integrations/cli.md) | `@enconvert/cli` | Vuoi convertire file o estrarre dati web da un terminale o da uno script di shell, con output `--json` e codici di uscita stabili. |
| [SDK](/it/docs/guides/integrations/sdks.md) | dieci client di linguaggio | Stai scrivendo codice applicativo e vuoi metodi tipizzati con autocompletamento nell'editor invece di HTTP scritto a mano. |

Esiste una quinta superficie senza una pagina propria: i [web widget](#web-widgets), trattati qui sotto, che sono l'unica con cui i tuoi utenti finali interagiscono direttamente.

Se stai ancora decidendo, [REST, MCP e CLI](/it/docs/concepts/rest-mcp-and-cli.md) mette a confronto le superfici di accesso fianco a fianco, e [Autenticazione](/it/docs/authentication.md) spiega di quale tipo di chiave ha bisogno ciascuna.

---

## Web widget {: #web-widgets }

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](/it/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/it/docs/endpoints/convert/web-pages/url-to-screenshot.md)
- Basati su file: tutti gli endpoint di [formato dati](/it/docs/endpoints/convert/data-formats.md), [documento in PDF](/it/docs/endpoints/convert/documents.md) e [conversione di immagini](/it/docs/endpoints/convert/images.md)

### 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:

```html
<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:**

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

| Campo | Descrizione |
|-------|-------------|
| `endpoint` | L'endpoint di conversione che questo widget è configurato a usare. |
| `input_type` | `"url"` per gli endpoint basati su URL, `"file"` per gli endpoint di caricamento file. |
| `allowed_domains` | Domini autorizzati a integrare questo widget. Supporta le wildcard. |
| `turnstile_site_key` | Site key di Cloudflare Turnstile per la verifica anti-bot. |
| `widget_branding` | Se il badge "Powered by EnConvert" viene mostrato. Determinato dal piano di abbonamento. |

#### 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:**

```json
{
    "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:**

```json
{
    "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:

```json
{
    "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](/it/docs/concepts/signed-urls.md) 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:

| Piano | Branding |
|------|----------|
| Founding (gratuito) | Mostrato |
| Indie, Studio, Production, Enterprise | Nascosto |

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:

| Operazione | Endpoint | Descrizione |
|-----------|----------|-------------|
| Create | `POST /widgets` | Crea un widget e genera automaticamente una chiave API pubblica interna. |
| List | `GET /widgets?project_id={id}` | Elenca tutti i widget attivi di un progetto. |
| Get | `GET /widgets/{id}` | Recupera i dettagli di un singolo widget. |
| Update | `PATCH /widgets/{id}` | Aggiorna nome, endpoint o chiave API del widget. |
| Delete | `DELETE /widgets/{id}` | Elimina il widget in soft-delete (imposta `active=false`). |

<div class="alert alert-info">
<strong>Host diverso:</strong> queste route di gestione risiedono sul backend EnConvert che serve la dashboard, non su <code>api.enconvert.com</code>. Le route di conversione e di autenticazione dei widget sotto <code>/v1/</code> sono il gateway.
</div>

### Riferimento del Codice di Embed

#### HTML Standard

```html
<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:

| Parametro | Variabile CSS | Descrizione |
|-----------|-------------|-------------|
| `bg` | `--w-bg` | Colore di sfondo del widget |
| `text` | `--w-text` | Colore del testo |
| `btn-bg` | `--w-btn-bg` | Colore di sfondo del pulsante |
| `btn-text` | `--w-btn-text` | Colore del testo del pulsante |
| `border` | `--w-border` | Colore del bordo |
| `radius` | `--w-radius` | Raggio del bordo |
| `input-bg` | `--w-input-bg` | Sfondo del campo di input |
| `result-bg` | `--w-result-bg` | Sfondo dell'area del risultato |
| `error` | `--w-error` | Colore del testo di errore |
| `font` | `--w-font` | Famiglia di caratteri |
| `padding` | `--w-padding` | Padding del widget |
| `max-width` | `--w-max-width` | Larghezza massima del widget |

### Comunicazione con l'Iframe

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

| Tipo di Evento | Dati | Descrizione |
|-----------|------|-------------|
| `Enconvert:ready` | nessuno | Il widget è stato caricato ed è pronto. |
| `Enconvert:resize` | `{ height: number }` | L'altezza del contenuto del widget è cambiata. Usalo per ridimensionare l'iframe. |
| `Enconvert:conversion:complete` | `{ url: string, filename?: string }` | Conversione completata. `url` è l'URL di download presigned. |
| `Enconvert:conversion:error` | `{ error: string }` | Conversione fallita. |

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

#### Esempio: Ascolto degli Eventi

```javascript
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

| Livello | Protezione |
|-------|-----------|
| **Whitelisting dei domini** | Il widget funziona solo sui domini elencati. Supporta corrispondenze esatte e sottodomini con wildcard. Validazione lato server all'emissione del token. |
| **Verifica Turnstile** | Ogni richiesta iniziale di token richiede una risposta valida alla challenge Cloudflare Turnstile. |
| **Restrizione dell'endpoint** | Ogni widget è bloccato su un singolo endpoint di conversione tramite `allowed_endpoints` nel JWT. |
| **Scadenza del token** | Il JWT scade dopo 1 ora. Il refresh token scade dopo 7 giorni. Entrambi vengono ruotati al refresh. |
| **Sicurezza del refresh token** | Cookie httpOnly con `Secure` e `SameSite=none`, inaccessibile a JavaScript, inviato solo su HTTPS. |
| **Protezione CORS** | L'API gateway valida l'origin dell'iframe del widget a ogni richiesta. |
| **CSP frame-ancestors** | Gli endpoint di configurazione e token del widget impostano header `frame-ancestors` che limitano quali domini possono integrare l'iframe. |
| **Nessuna chiave esposta** | Il codice di embed contiene solo l'ID del widget. La chiave API interna non è mai visibile. |

<div class="alert alert-warning">
<strong>Non mettere mai una chiave privata in una pagina.</strong> I widget esistono proprio perché il traffico del browser giri su una chiave pubblica limitata e un JWT di breve durata. Una chiave privata <code>sk_</code> inviata da un browser viene rifiutata a vista con HTTP 403. Vedi <a href="/it/docs/authentication#public-keys-and-jwt">Chiavi pubbliche e JWT</a>.
</div>

---

## 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](/it/docs/guides/integrations/sdks.md) per il tuo linguaggio. Se automatizzi senza scrivere codice, usa [n8n](/it/docs/guides/integrations/n8n.md). Se vuoi che sia un assistente AI a fare il lavoro, installa il [server MCP](/it/docs/guides/integrations/mcp-setup.md). Se vuoi soltanto che siano i tuoi visitatori a convertire i file, usa un [web widget](#web-widgets).

### 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](/it/docs/reference/rate-limits.md).