Integrationen#

Dieselbe API, erreichbar aus den Tools, die du ohnehin nutzt. Ein MCP-Server bringt EnConvert in einen Coding-Agenten, ein ClawHub-Skill in OpenClaw, ein n8n Node und eine Zapier-Integration in deine Automatisierungen, ein Dify-Plugin in deine Agenten und Workflows, 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 achte 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.

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 oder Zapier. Baust du einen Agenten oder einen Workflow in Dify, installiere das Dify-Plugin. Soll ein KI-Assistent die Arbeit machen, installiere den MCP-Server, oder den ClawHub-Skill, wenn du OpenClaw betreibst. 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.