---
seo_title: Integrationen: MCP, n8n, CLI, SDKs und Widgets | EnConvert
meta_desc: Erreiche die EnConvert-API aus deinen gewohnten Tools: MCP-Server für Coding-Agenten, n8n Node, Terminal-CLI, zehn SDKs und einbettbare Web-Widgets.
keywords: enconvert integrationen, mcp server dateikonvertierung, n8n node dateikonvertierung, dateikonvertierung cli, dateikonvertierung sdk, datei konverter widget auf website einbetten, url zu pdf widget einbinden, wordpress dateikonverter shortcode, no-code dateikonvertierung widget
---

# Integrationen

Dieselbe API, erreichbar aus den Tools, die du ohnehin nutzt. Ein MCP-Server bringt EnConvert in einen Coding-Agenten, ein n8n Node in einen Workflow, eine CLI in dein Terminal, zehn SDKs in deinen Anwendungscode und ein Web-Widget auf deine eigene Website.

---

## Wähle deine Oberfläche

Jede Oberfläche unten ruft dieselben öffentlichen REST-Endpunkte mit demselben API-Schlüssel auf, gegen dasselbe Projekt und dasselbe monatliche Ops-Kontingent.

| Oberfläche | Paket | Wann du sie nimmst |
|---------|---------|-------------|
| [MCP-Einrichtung](/de/docs/guides/integrations/mcp-setup.md) | `@enconvert/mcp` | Ein Coding-Agent wie Claude Code, Cursor, Windsurf oder Claude Desktop soll die API selbst aufrufen, direkt im Chat, ohne dass du HTTP schreibst. |
| [n8n](/de/docs/guides/integrations/n8n.md) | `@enconvert/n8n-nodes-enconvert` | Du baust einen n8n-Workflow und willst Konvertierungen, Scraping und Crawling als Node, der echte Binary Data ausgibt. |
| [CLI](/de/docs/guides/integrations/cli.md) | `@enconvert/cli` | Du willst Dateien konvertieren oder Web-Daten holen, aus einem Terminal oder einem Shell-Skript, mit `--json`-Ausgabe und stabilen Exit-Codes. |
| [SDKs](/de/docs/guides/integrations/sdks.md) | zehn Sprach-Clients | Du schreibst Anwendungscode und willst typisierte Methoden mit Autovervollständigung im Editor statt selbst gebautem HTTP. |

Es gibt eine fünfte Oberfläche ohne eigene Seite: [Web-Widgets](#web-widgets), weiter unten behandelt, die einzige, die deine Endnutzer direkt anfassen.

Wenn du noch unentschieden bist: [REST, MCP und CLI](/de/docs/concepts/rest-mcp-and-cli.md) vergleicht die Zugangsoberflächen nebeneinander, und [Authentifizierung](/de/docs/authentication.md) erklärt, welchen Key-Typ jede davon braucht.

---

## Web-Widgets {: #web-widgets }

Web-Widgets betten URL- und Dateikonvertierung mit einem einzigen Script-Tag in jede Website ein, sodass deine Besucher eine URL zu einem PDF konvertieren, einen Screenshot erstellen oder eine hochgeladene Datei konvertieren, ohne deine Seite zu verlassen. Der Embed-Code enthält nur eine Widget-ID. Die Authentifizierung läuft im iframe über eine Cloudflare-Turnstile-Challenge und ein kurzlebiges JWT von `POST /v1/widget/{widget_id}/token`, sodass niemals ein API-Schlüssel in deinem Frontend-Code offengelegt wird.

Jedes Widget ist an einen Konvertierungs-Endpunkt und eine Liste erlaubter Domains gebunden, beides im Dashboard gesetzt. Hinter einem Widget kann jeder Konvertierungs-Endpunkt stehen:

- URL-basiert: [url-to-pdf](/de/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/de/docs/endpoints/convert/web-pages/url-to-screenshot.md)
- Datei-basiert: Alle Endpunkte für [Datenformate](/de/docs/endpoints/convert/data-formats.md), [Dokument zu PDF](/de/docs/endpoints/convert/documents.md) und [Bildkonvertierung](/de/docs/endpoints/convert/images.md)

### So funktionieren Widgets

#### Einrichtung

1. Gehe zu deinem EnConvert-**Dashboard > Widgets** und klicke auf **Create Widget**.
2. Wähle den Konvertierungs-Endpunkt aus (z. B. `/v1/convert/url-to-pdf`) und gib die Domains an, auf denen das Widget eingebettet wird. Wildcard-Subdomains werden unterstützt (z. B. `*.example.com`).
3. Für das Widget wird automatisch ein interner öffentlicher API-Schlüssel erstellt, beschränkt auf den ausgewählten Endpunkt und die erlaubten Domains. Dieser Schlüssel wird nie offengelegt.

Zwei Voraussetzungen werden gern übersehen: Deine Konto-E-Mail muss verifiziert sein, und die Liste der erlaubten Domains darf nicht leer sein. Fehlt eines von beidem, wird die Widget-Erstellung abgelehnt.

#### Einbettung

Füge das Embed-Script zu deiner Website hinzu:

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

Das Script erstellt einen sandboxed iframe, der das EnConvert-Widget lädt. Im Embed-Code erscheint kein API-Schlüssel.

#### Laufzeitablauf

1. **Widget lädt** im iframe und ruft seine Konfiguration von `GET /v1/widget/{widget_id}/config` ab.
2. **Domain-Validierung**: Das Widget prüft, ob der Origin der übergeordneten Seite mit der Liste der erlaubten Domains übereinstimmt. Unterstützt exakte Domains und Wildcard-Subdomain-Muster (`*.example.com`).
3. **Nutzer übermittelt eine URL oder Datei**: Das Widget fordert ein unsichtbares Turnstile-Challenge-Token an.
4. **Token-Austausch**: Das Widget sendet das Turnstile-Token an `POST /v1/widget/{widget_id}/token` und erhält ein JWT (1 Stunde gültig) sowie ein Refresh-Token-Cookie (7 Tage gültig).
5. **Konvertierung**: Das Widget ruft den Konvertierungs-Endpunkt mit dem JWT auf.
6. **Ergebnis**: Die API liefert eine JSON-Antwort mit einer `presigned_url`. Das Widget zeigt einen Download-Link an.
7. **Timeout-Recovery**: Überschreitet die Konvertierung die Timeout-Grenzen des Reverse-Proxys, fragt das Widget `GET /v1/convert/status/{job_id}` mit der vorab generierten Job-ID ab.

#### Automatische Token-Erneuerung

Das Widget stellt seine Funktion nie wegen abgelaufener Authentifizierung ein:

- Bei der ersten Konvertierung stellt die API sowohl ein **JWT** (1 Stunde gültig) als auch ein **Refresh-Token** (7 Tage gültig, httpOnly-Cookie) aus.
- Bei nachfolgenden Konvertierungen versucht das Widget zunächst, **das JWT zu erneuern** über `POST /v1/widget/{widget_id}/refresh` mithilfe des Refresh-Token-Cookies, ohne dass eine Turnstile-Challenge nötig ist.
- Ist das Refresh-Token selbst abgelaufen (nach 7 Tagen Inaktivität), fällt das Widget auf eine neue Turnstile-Challenge zurück.
- Das Refresh-Token wird bei jeder Erneuerung **rotiert**: Jede Erneuerung stellt ein neues 7-Tage-Cookie aus.

Das bedeutet, dass ein Widget-Besucher, der alle paar Tage konvertiert, nach der ersten Turnstile-Challenge nie wieder eine sieht.

### Widget-Endpunkte

#### Konfiguration

Ruft die Konfiguration für ein bestimmtes Widget ab. Keine Authentifizierung erforderlich.

```
GET /v1/widget/{widget_id}/config
```

**Antwort:**

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

| Feld | Beschreibung |
|-------|-------------|
| `endpoint` | Der Konvertierungs-Endpunkt, für den dieses Widget konfiguriert ist. |
| `input_type` | `"url"` für URL-basierte Endpunkte, `"file"` für Datei-Upload-Endpunkte. |
| `allowed_domains` | Domains, die berechtigt sind, dieses Widget einzubetten. Unterstützt Wildcards. |
| `turnstile_site_key` | Cloudflare-Turnstile-Site-Key zur Bot-Verifizierung. |
| `widget_branding` | Ob das „Powered by EnConvert“-Badge angezeigt wird. Wird durch den Subscription-Plan bestimmt. |

#### Token-Austausch

Tauscht ein Turnstile-Challenge-Token gegen ein JWT. Setzt ein Refresh-Token-Cookie.

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

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

**Antwort:**

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

Setzt zudem ein httpOnly-`refresh_token`-Cookie (7 Tage gültig, `Secure`, `SameSite=none`).

#### Token-Erneuerung

Erneuert ein abgelaufenes JWT mithilfe des httpOnly-Refresh-Token-Cookies. Keine Turnstile-Challenge erforderlich.

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

Kein Request-Body erforderlich. Das Refresh-Token wird automatisch aus dem Cookie gelesen.

**Antwort:**

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

Das Refresh-Token-Cookie wird bei jeder Erneuerung rotiert (neues 7-Tage-Cookie ausgestellt).

**Fehlerantworten:**
- `401`: kein Refresh-Token-Cookie vorhanden oder Refresh-Token abgelaufen
- `403`: Refresh-Token passt nicht zum Projekt des Widgets, oder Domain nicht autorisiert
- `404`: Widget nicht gefunden oder deaktiviert

### Konvertierungsantwort

Sowohl URL-basierte als auch datei-basierte Widget-Konvertierungen liefern eine konsistente JSON-Antwort mit einer presigned Download-URL:

```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"
}
```

Das Widget verwendet die `presigned_url`, um einen Download-Link anzuzeigen. Presigned URLs laufen nach 15 Minuten ab. Was dieses Zeitfenster für deine Besucher bedeutet, steht unter [Signierte URLs](/de/docs/concepts/signed-urls.md).

**Einschränkungen für Widget-Konvertierungen:**
- Nur eine einzelne URL / einzelne Datei
- Nur synchroner Modus (kein async oder Batch)
- Keine Webhook-Callbacks oder Benachrichtigungs-E-Mails
- Endpunkt beschränkt auf den für das Widget konfigurierten

### Widget-Branding

Pläne, die Widget-Branding beinhalten, zeigen unten im Widget ein kleines **„Powered by EnConvert“**-Badge an. Dies wird durch das Feld `widget_branding` im Subscription-Plan gesteuert:

| Plan | Branding |
|------|----------|
| Founding (kostenlos) | Angezeigt |
| Indie, Studio, Production, Enterprise | Ausgeblendet |

Das Branding-Badge verlinkt zu `https://www.enconvert.com` und ist dezent gestaltet: kleiner Text unterhalb des Widget-Formulars mit reduzierter Deckkraft.

Um das Branding zu entfernen, wechsle vom kostenlosen Founding-Plan weg. Jeder kostenpflichtige Plan blendet es aus.

### Widget-Verwaltung

Widgets werden über das EnConvert-Dashboard oder die Backend-API verwaltet:

| Operation | Endpunkt | Beschreibung |
|-----------|----------|-------------|
| Erstellen | `POST /widgets` | Erstellt ein Widget und generiert automatisch einen internen öffentlichen API-Schlüssel. |
| Auflisten | `GET /widgets?project_id={id}` | Listet alle aktiven Widgets für ein Projekt auf. |
| Abrufen | `GET /widgets/{id}` | Ruft die Details eines einzelnen Widgets ab. |
| Aktualisieren | `PATCH /widgets/{id}` | Aktualisiert Widget-Name, Endpunkt oder API-Schlüssel. |
| Löschen | `DELETE /widgets/{id}` | Löscht das Widget weich (setzt `active=false`). |

<div class="alert alert-info">
<strong>Anderer Host:</strong> Diese Verwaltungsrouten liegen auf dem EnConvert-Backend, das das Dashboard ausliefert, nicht auf <code>api.enconvert.com</code>. Die Konvertierungs- und Widget-Auth-Routen unter <code>/v1/</code> gehören zum Gateway.
</div>

### Embed-Code-Referenz

#### Standard-HTML

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

Das Script:
- Erstellt einen sandboxed iframe (`allow-scripts allow-same-origin allow-forms allow-popups`)
- Setzt `width: 100%`, initiale Höhe 400px, keinen Rahmen
- Aktiviert die `clipboard-write`-Berechtigung
- Verwendet Lazy Loading
- Lauscht auf `Enconvert:resize`-Nachrichten, um die Höhe automatisch anzupassen

#### WordPress-Shortcode

Wenn du das EnConvert-WordPress-Plugin verwendest, bette Widgets mit dem Shortcode ein:

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

#### Stilanpassung

Passe das Erscheinungsbild des Widgets über Query-Parameter in der Embed-Script-URL oder der iframe-Quelle an:

| Parameter | CSS-Variable | Beschreibung |
|-----------|-------------|-------------|
| `bg` | `--w-bg` | Widget-Hintergrundfarbe |
| `text` | `--w-text` | Textfarbe |
| `btn-bg` | `--w-btn-bg` | Button-Hintergrundfarbe |
| `btn-text` | `--w-btn-text` | Button-Textfarbe |
| `border` | `--w-border` | Rahmenfarbe |
| `radius` | `--w-radius` | Rahmenradius |
| `input-bg` | `--w-input-bg` | Eingabefeld-Hintergrund |
| `result-bg` | `--w-result-bg` | Ergebnisbereich-Hintergrund |
| `error` | `--w-error` | Fehlertextfarbe |
| `font` | `--w-font` | Schriftfamilie |
| `padding` | `--w-padding` | Widget-Padding |
| `max-width` | `--w-max-width` | Maximale Widget-Breite |

### Iframe-Kommunikation

Das Widget kommuniziert mit der übergeordneten Seite über `postMessage`. Lausche auf der übergeordneten Seite auf diese Events:

| Event-Typ | Daten | Beschreibung |
|-----------|------|-------------|
| `Enconvert:ready` | keine | Widget wurde geladen und ist bereit. |
| `Enconvert:resize` | `{ height: number }` | Die Inhaltshöhe des Widgets hat sich geändert. Zum Anpassen der iframe-Größe verwenden. |
| `Enconvert:conversion:complete` | `{ url: string, filename?: string }` | Konvertierung abgeschlossen. `url` ist die presigned Download-URL. |
| `Enconvert:conversion:error` | `{ error: string }` | Konvertierung fehlgeschlagen. |

Diese vier Event-Namen sind ein eingefrorener Wire-Contract. Übernimm die Groß- und Kleinschreibung exakt.

#### Beispiel: Auf Events lauschen

```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);
    }
});
```

### Sicherheit

| Ebene | Schutz |
|-------|-----------|
| **Domain-Whitelisting** | Das Widget funktioniert nur auf gelisteten Domains. Unterstützt exakte Übereinstimmungen und Wildcard-Subdomains. Serverseitige Validierung bei der Token-Ausstellung. |
| **Turnstile-Verifizierung** | Jede initiale Token-Anfrage erfordert eine gültige Cloudflare-Turnstile-Challenge-Antwort. |
| **Endpunkt-Beschränkung** | Jedes Widget ist über `allowed_endpoints` im JWT auf einen einzelnen Konvertierungs-Endpunkt festgelegt. |
| **Token-Ablauf** | Das JWT läuft nach 1 Stunde ab. Das Refresh-Token läuft nach 7 Tagen ab. Beide werden bei Erneuerung rotiert. |
| **Refresh-Token-Sicherheit** | httpOnly-Cookie mit `Secure` und `SameSite=none`, für JavaScript nicht zugänglich, wird nur über HTTPS gesendet. |
| **CORS-Schutz** | Das API-Gateway validiert bei jeder Anfrage den Origin des Widget-iframes. |
| **CSP frame-ancestors** | Widget-Konfigurations- und Token-Endpunkte setzen `frame-ancestors`-Header, die einschränken, welche Domains den iframe einbetten dürfen. |
| **Keine offengelegten Keys** | Der Embed-Code enthält nur die Widget-ID. Der interne API-Schlüssel ist nie sichtbar. |

<div class="alert alert-warning">
<strong>Niemals einen privaten Schlüssel in eine Seite schreiben.</strong> Widgets existieren, damit Browser-Traffic über einen eingeschränkten öffentlichen Schlüssel und ein kurzlebiges JWT läuft. Ein privater <code>sk_</code>-Schlüssel, der aus einem Browser gesendet wird, wird sofort mit HTTP 403 abgelehnt. Siehe <a href="/de/docs/authentication#public-keys-and-jwt">Öffentliche Schlüssel und JWT</a>.
</div>

---

## Häufig gestellte Fragen

### Wie bette ich ein Datei-Konverter-Widget auf meiner Website ein?

Erstelle ein Widget im EnConvert-Dashboard (**Dashboard > Widgets > Create Widget**), und füge dann ein Script-Tag zu deiner Seite hinzu: `<script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>`. Läuft deine Site mit WordPress, kannst du stattdessen den `[enconvert_widget id="your-widget-id"]`-Shortcode aus dem EnConvert-WordPress-Plugin verwenden.

### Muss ich einen API-Schlüssel offenlegen, um ein Konvertierungs-Widget einzubetten?

Nein. Der Embed-Code enthält nur die Widget-ID. Für jedes Widget wird automatisch ein interner öffentlicher API-Schlüssel generiert, beschränkt auf seinen konfigurierten Endpunkt und die erlaubten Domains, und er ist nie in deinem Frontend-Code sichtbar.

### Wie authentifiziert das Widget Nutzer ohne API-Schlüssel?

Das Widget fordert eine unsichtbare Cloudflare-Turnstile-Challenge an und tauscht sie bei `POST /v1/widget/{widget_id}/token` gegen ein JWT mit 1 Stunde Gültigkeit sowie ein httpOnly-Refresh-Token-Cookie mit 7 Tagen Gültigkeit. Nachfolgende Konvertierungen erneuern das JWT über `POST /v1/widget/{widget_id}/refresh` ohne neue Challenge, und das Refresh-Token wird bei jeder Erneuerung rotiert.

### Kann ich einschränken, welche Domains mein eingebettetes Widget nutzen dürfen?

Ja. Jedes Widget hat eine Liste erlaubter Domains, die exakte Domains und Wildcard-Subdomains wie `*.example.com` unterstützt, serverseitig bei der Token-Ausstellung validiert wird und über `frame-ancestors`-CSP-Header einschränkt, welche Seiten den iframe einbetten dürfen.

### Wie entferne ich das „Powered by EnConvert“-Badge vom Widget?

Das Badge wird durch das Feld `widget_branding` in deinem Subscription-Plan gesteuert. Nur der kostenlose Founding-Plan zeigt es an. Indie, Studio, Production und Enterprise blenden es alle aus, jeder kostenpflichtige Plan entfernt das Badge also.

### Mit welcher Integration fange ich an?

Schreibst du Code, fang mit einem [SDK](/de/docs/guides/integrations/sdks.md) für deine Sprache an. Automatisierst du ohne Code, nimm [n8n](/de/docs/guides/integrations/n8n.md). Soll ein KI-Assistent die Arbeit machen, installiere den [MCP-Server](/de/docs/guides/integrations/mcp-setup.md). Willst du nur, dass deine eigenen Besucher Dateien konvertieren, nimm ein [Web-Widget](#web-widgets).

### Teilen sich die Integrationen einen API-Schlüssel und ein Kontingent?

Ja. Sie alle authentifizieren sich als dasselbe Projekt, Operationen zählen also gegen ein einziges monatliches Kontingent, egal welche Oberfläche den Aufruf abgesetzt hat. Siehe [Rate-Limits und Kontingente](/de/docs/reference/rate-limits.md).