Intégrations#

La même API, accessible depuis les outils que vous utilisez déjà. Un serveur MCP place EnConvert dans un agent de code, un nœud n8n dans un workflow, une CLI dans votre terminal, dix SDK dans le code de votre application, et un widget web sur votre propre site.

Choisissez votre surface#

Chaque surface ci-dessous appelle les mêmes endpoints REST publics avec la même clé API, sur le même projet et le même quota mensuel d'opérations.

Il existe une cinquième surface sans page dédiée : les widgets web, traités ci-dessous, la seule que vos utilisateurs finaux manipulent directement.

Si vous hésitez encore, REST, MCP et CLI compare les surfaces d'accès côte à côte, et Authentification explique quel type de clé chacune nécessite.

Widgets web#

Les widgets web intègrent la conversion d'URL et de fichiers dans n'importe quel site avec une seule balise script : vos visiteurs convertissent une URL en PDF, capturent une capture d'écran ou convertissent un fichier envoyé sans quitter votre page. Le code d'intégration ne transporte que l'ID du widget. L'authentification a lieu dans l'iframe via un défi Cloudflare Turnstile et un JWT de courte durée émis par POST /v1/widget/{widget_id}/token, si bien qu'aucune clé API n'est jamais exposée dans votre code frontend.

Chaque widget est lié à un endpoint de conversion et à une liste de domaines autorisés, tous deux définis dans le tableau de bord. N'importe quel endpoint de conversion peut alimenter un widget :

• Basés sur une URL : url-to-pdf, url-to-screenshot
• Basés sur un fichier : tous les endpoints formats de données, document vers PDF et conversion d'images

Fonctionnement des widgets#

Configuration#

1. Rendez-vous dans Dashboard > Widgets de votre compte EnConvert et cliquez sur Create Widget.
2. Sélectionnez l'endpoint de conversion (par exemple, /v1/convert/url-to-pdf) et indiquez les domaines où le widget sera intégré. Les sous-domaines génériques sont pris en charge (par exemple, *.example.com).
3. Une clé API publique interne est automatiquement créée pour le widget, restreinte à l'endpoint sélectionné et aux domaines autorisés. Cette clé n'est jamais exposée.

Deux prérequis piègent régulièrement : l'adresse e-mail de votre compte doit être vérifiée, et la liste des domaines autorisés ne peut pas être vide. La création du widget est rejetée si l'un des deux manque.

Intégration#

Ajoutez le script d'intégration à votre site :

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

Le script crée une iframe en bac à sable qui charge le widget EnConvert. Aucune clé API n'apparaît dans le code d'intégration.

Déroulement à l'exécution#

1. Chargement du widget dans l'iframe, qui récupère sa configuration depuis GET /v1/widget/{widget_id}/config.
2. Validation du domaine : le widget vérifie que l'origine de la page parente correspond à la liste des domaines autorisés. Prend en charge les domaines exacts et les motifs de sous-domaines génériques (*.example.com).
3. L'utilisateur soumet une URL ou un fichier : le widget demande un jeton de défi Turnstile invisible.
4. Échange de jeton : le widget envoie le jeton Turnstile à POST /v1/widget/{widget_id}/token et reçoit un JWT (expiration : 1 heure) ainsi qu'un cookie de jeton de rafraîchissement (expiration : 7 jours).
5. Conversion : le widget appelle l'endpoint de conversion avec le JWT.
6. Résultat : l'API renvoie une réponse JSON avec un presigned_url. Le widget affiche un lien de téléchargement.
7. Récupération après délai dépassé : si la conversion dépasse les limites de délai du reverse-proxy, le widget interroge GET /v1/convert/status/{job_id} en utilisant l'ID de tâche pré-généré.

Rafraîchissement automatique des jetons#

Le widget ne cesse jamais de fonctionner à cause d'une authentification expirée :

• Lors de la conversion initiale, l'API émet à la fois un JWT (expiration : 1 heure) et un jeton de rafraîchissement (expiration : 7 jours, cookie httpOnly).
• Lors des conversions suivantes, le widget tente d'abord de rafraîchir le JWT via POST /v1/widget/{widget_id}/refresh en utilisant le cookie de jeton de rafraîchissement, sans aucun défi Turnstile requis.
• Si le jeton de rafraîchissement lui-même a expiré (après 7 jours d'inactivité), le widget se rabat sur un nouveau défi Turnstile.
• Le jeton de rafraîchissement est renouvelé à chaque rafraîchissement : chaque rafraîchissement émet un nouveau cookie de 7 jours.

Cela signifie qu'un visiteur du widget qui effectue des conversions tous les quelques jours ne verra jamais de défi Turnstile après le premier.

Points de terminaison des widgets#

Configuration#

Récupère la configuration d'un widget spécifique. Aucune authentification requise.

GET /v1/widget/{widget_id}/config

Réponse :

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

Échange de jeton#

Échange un jeton de défi Turnstile contre un JWT. Définit un cookie de jeton de rafraîchissement.

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

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

Réponse :

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

Définit également un cookie httpOnly refresh_token (expiration : 7 jours, Secure, SameSite=none).

Rafraîchissement du jeton#

Rafraîchit un JWT expiré à l'aide du cookie httpOnly de jeton de rafraîchissement. Aucun défi Turnstile requis.

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

Aucun corps de requête nécessaire. Le jeton de rafraîchissement est lu automatiquement depuis le cookie.

Réponse :

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

Le cookie de jeton de rafraîchissement est renouvelé à chaque rafraîchissement (un nouveau cookie de 7 jours est émis).

Réponses d'erreur : - 401 : aucun cookie de jeton de rafraîchissement, ou jeton de rafraîchissement expiré - 403 : le jeton de rafraîchissement ne correspond pas au projet du widget, ou domaine non autorisé - 404 : widget introuvable ou désactivé

Réponse de conversion#

Les conversions de widget basées sur une URL comme sur un fichier renvoient une réponse JSON cohérente avec une URL de téléchargement présignée :

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

Le widget utilise le presigned_url pour afficher un lien de téléchargement. Les URL présignées expirent après 15 minutes. Voir URL signées pour comprendre ce que cette fenêtre implique pour vos visiteurs.

Restrictions de conversion du widget : - Une seule URL / un seul fichier à la fois - Mode synchrone uniquement (pas d'asynchrone ni de traitement par lot) - Aucun rappel webhook ni e-mail de notification - Endpoint limité à celui configuré pour le widget

Marque du widget#

Les forfaits incluant la marque du widget affichent un petit badge « Powered by EnConvert » en bas du widget. Ceci est contrôlé par le champ widget_branding du forfait d'abonnement :

Le badge de marque renvoie vers https://www.enconvert.com et est stylisé pour être discret : un petit texte sous le formulaire du widget avec une opacité réduite.

Pour supprimer la marque, quittez le forfait gratuit Founding. N'importe quel forfait payant la masque.

Gestion des widgets#

Les widgets sont gérés via le tableau de bord EnConvert ou l'API backend :

Référence du code d'intégration#

HTML standard#

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

Le script : - Crée une iframe en bac à sable (allow-scripts allow-same-origin allow-forms allow-popups) - Définit width: 100%, une hauteur initiale de 400px, sans bordure - Active la permission clipboard-write - Utilise le chargement différé - Écoute les messages Enconvert:resize pour ajuster automatiquement la hauteur

Shortcode WordPress#

Si vous utilisez le plugin WordPress EnConvert, intégrez les widgets à l'aide du shortcode :

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

Personnalisation du style#

Personnalisez l'apparence du widget via des paramètres de requête sur l'URL du script d'intégration ou la source de l'iframe :

Communication avec l'iframe#

Le widget communique avec la page parente via postMessage. Écoutez ces événements sur la page parente :

Ces quatre noms d'événements constituent un contrat de transport figé. Respectez exactement la casse.

Exemple : écoute des événements#

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

Sécurité#

Questions fréquentes#

Comment intégrer un widget de conversion de fichiers sur mon site ?#

Créez un widget dans le tableau de bord EnConvert (Dashboard > Widgets > Create Widget), puis ajoutez une balise script à votre page : <script src="https://enconvert.com/embed.js" data-widget-id="your-widget-id"></script>. Si votre site utilise WordPress, vous pouvez à la place utiliser le shortcode [enconvert_widget id="your-widget-id"] du plugin WordPress EnConvert.

Dois-je exposer une clé API pour intégrer un widget de conversion ?#

Non. Le code d'intégration ne contient que l'ID du widget. Une clé API publique interne est générée automatiquement pour chaque widget, restreinte à son endpoint configuré et à ses domaines autorisés, et n'est jamais visible dans votre code frontend.

Comment le widget authentifie-t-il les utilisateurs sans clé API ?#

Le widget demande un défi Cloudflare Turnstile invisible et l'échange à POST /v1/widget/{widget_id}/token contre un JWT avec une expiration d'1 heure, ainsi qu'un cookie httpOnly de jeton de rafraîchissement avec une expiration de 7 jours. Les conversions suivantes rafraîchissent le JWT via POST /v1/widget/{widget_id}/refresh sans nouveau défi, et le jeton de rafraîchissement est renouvelé à chaque rafraîchissement.

Puis-je restreindre les domaines pouvant utiliser mon widget intégré ?#

Oui. Chaque widget possède une liste de domaines autorisés qui prend en charge les domaines exacts et les sous-domaines génériques comme *.example.com, validée côté serveur lors de l'émission du jeton, avec des en-têtes CSP frame-ancestors restreignant quelles pages peuvent intégrer l'iframe.

Comment retirer le badge Powered by EnConvert du widget ?#

Le badge est contrôlé par le champ widget_branding de votre forfait d'abonnement. Seul le forfait gratuit Founding l'affiche. Indie, Studio, Production et Enterprise le masquent tous, donc n'importe quel forfait payant supprime le badge.

Par quelle intégration commencer ?#

Si vous écrivez du code, commencez par un SDK pour votre langage. Si vous automatisez sans code, utilisez n8n. Si vous voulez qu'un assistant IA fasse le travail, installez le serveur MCP. Si vous voulez simplement que vos propres visiteurs convertissent des fichiers, utilisez un widget web.

Les intégrations partagent-elles une seule clé API et un seul quota ?#

Oui. Toutes s'authentifient comme le même projet, donc les opérations sont décomptées d'un unique quota mensuel quelle que soit la surface qui a émis l'appel. Voir Limites de débit et quotas.