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.

Es gibt eine fünfte Oberfläche ohne eigene Seite: Web-Widgets, weiter unten behandelt, die einzige, die deine Endnutzer direkt anfassen.

Wenn du noch unentschieden bist: REST, MCP und CLI vergleicht die Zugangsoberflächen nebeneinander, und Authentifizierung erklärt, welchen Key-Typ jede davon braucht.

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, url-to-screenshot
• Datei-basiert: Alle Endpunkte für Datenformate, Dokument zu PDF und Bildkonvertierung

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:

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

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

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:

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

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

{
    "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.

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:

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:

Embed-Code-Referenz#

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

Iframe-Kommunikation#

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

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

Beispiel: Auf Events lauschen#

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#

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 für deine Sprache an. Automatisierst du ohne Code, nimm n8n. Soll ein KI-Assistent die Arbeit machen, installiere den MCP-Server. Willst du nur, dass deine eigenen Besucher Dateien konvertieren, nimm ein Web-Widget.

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.