---
seo_title: Intégrations : MCP, n8n, CLI, SDK et widgets | EnConvert
meta_desc: Appelez l'API EnConvert depuis vos outils habituels : un serveur MCP pour agents de code, un nœud n8n, une CLI de terminal, dix SDK et des widgets web à intégrer.
keywords: intégrations enconvert, serveur mcp conversion de fichiers, nœud n8n conversion de fichiers, cli conversion de fichiers, sdk conversion de fichiers, intégrer un widget de conversion sur son site, widget de conversion pour site web, widget de conversion sans code, widget convertisseur en iframe, shortcode wordpress convertisseur de fichiers
---
# 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.
| Surface | Paquet | À utiliser quand |
|---------|---------|-------------|
| [Configuration MCP](/fr/docs/guides/integrations/mcp-setup.md) | `@enconvert/mcp` | Un agent de code comme Claude Code, Cursor, Windsurf ou Claude Desktop doit appeler l'API lui-même, dans le chat, sans que vous écriviez de HTTP. |
| [n8n](/fr/docs/guides/integrations/n8n.md) | `@enconvert/n8n-nodes-enconvert` | Vous construisez un workflow n8n et voulez les conversions, le scraping et le crawl sous forme de nœud qui émet de vraies données binaires. |
| [CLI](/fr/docs/guides/integrations/cli.md) | `@enconvert/cli` | Vous voulez convertir des fichiers ou récupérer des données web depuis un terminal ou un script shell, avec une sortie `--json` et des codes de sortie stables. |
| [SDK](/fr/docs/guides/integrations/sdks.md) | dix clients de langage | Vous écrivez du code applicatif et voulez des méthodes typées avec autocomplétion dans l'éditeur plutôt que du HTTP écrit à la main. |
Il existe une cinquième surface sans page dédiée : les [widgets web](#web-widgets), traités ci-dessous, la seule que vos utilisateurs finaux manipulent directement.
Si vous hésitez encore, [REST, MCP et CLI](/fr/docs/concepts/rest-mcp-and-cli.md) compare les surfaces d'accès côte à côte, et [Authentification](/fr/docs/authentication.md) explique quel type de clé chacune nécessite.
---
## Widgets web {: #web-widgets }
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](/fr/docs/endpoints/convert/web-pages/url-to-pdf.md), [url-to-screenshot](/fr/docs/endpoints/convert/web-pages/url-to-screenshot.md)
- Basés sur un fichier : tous les endpoints [formats de données](/fr/docs/endpoints/convert/data-formats.md), [document vers PDF](/fr/docs/endpoints/convert/documents.md) et [conversion d'images](/fr/docs/endpoints/convert/images.md)
### 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 :
```html
```
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 :**
```json
{
"endpoint": "/v1/convert/url-to-pdf",
"input_type": "url",
"allowed_domains": ["https://example.com", "*.example.com"],
"turnstile_site_key": "1x00000000000000000000AA",
"widget_branding": true
}
```
| Champ | Description |
|-------|-------------|
| `endpoint` | L'endpoint de conversion que ce widget est configuré pour utiliser. |
| `input_type` | `"url"` pour les endpoints basés sur une URL, `"file"` pour les endpoints d'envoi de fichier. |
| `allowed_domains` | Domaines autorisés à intégrer ce widget. Prend en charge les caractères génériques. |
| `turnstile_site_key` | Clé de site Cloudflare Turnstile pour la vérification anti-bot. |
| `widget_branding` | Indique si le badge « Powered by EnConvert » est affiché. Déterminé par le forfait d'abonnement. |
#### É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 :**
```json
{
"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 :**
```json
{
"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 :
```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"
}
```
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](/fr/docs/concepts/signed-urls.md) 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 :
| Forfait | Marque |
|------|----------|
| Founding (gratuit) | Affichée |
| Indie, Studio, Production, Enterprise | Masquée |
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 :
| Opération | Endpoint | Description |
|-----------|----------|-------------|
| Créer | `POST /widgets` | Crée un widget et génère automatiquement une clé API publique interne. |
| Lister | `GET /widgets?project_id={id}` | Liste tous les widgets actifs d'un projet. |
| Récupérer | `GET /widgets/{id}` | Récupère les détails d'un widget unique. |
| Mettre à jour | `PATCH /widgets/{id}` | Met à jour le nom, l'endpoint ou la clé API du widget. |
| Supprimer | `DELETE /widgets/{id}` | Supprime logiquement le widget (définit `active=false`). |
Hôte différent : ces routes de gestion se trouvent sur le backend EnConvert qui sert le tableau de bord, pas sur api.enconvert.com. Les routes de conversion et d'authentification des widgets sous /v1/ sont celles de la gateway.
### Référence du code d'intégration
#### HTML standard
```html
```
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 :
| Paramètre | Variable CSS | Description |
|-----------|-------------|-------------|
| `bg` | `--w-bg` | Couleur de fond du widget |
| `text` | `--w-text` | Couleur du texte |
| `btn-bg` | `--w-btn-bg` | Couleur de fond du bouton |
| `btn-text` | `--w-btn-text` | Couleur du texte du bouton |
| `border` | `--w-border` | Couleur de la bordure |
| `radius` | `--w-radius` | Rayon de la bordure |
| `input-bg` | `--w-input-bg` | Fond du champ de saisie |
| `result-bg` | `--w-result-bg` | Fond de la zone de résultat |
| `error` | `--w-error` | Couleur du texte d'erreur |
| `font` | `--w-font` | Famille de police |
| `padding` | `--w-padding` | Padding du widget |
| `max-width` | `--w-max-width` | Largeur maximale du widget |
### Communication avec l'iframe
Le widget communique avec la page parente via `postMessage`. Écoutez ces événements sur la page parente :
| Type d'événement | Données | Description |
|-----------|------|-------------|
| `Enconvert:ready` | aucune | Le widget a été chargé et est prêt. |
| `Enconvert:resize` | `{ height: number }` | La hauteur du contenu du widget a changé. Utilisez ceci pour redimensionner l'iframe. |
| `Enconvert:conversion:complete` | `{ url: string, filename?: string }` | Conversion terminée. `url` est l'URL de téléchargement présignée. |
| `Enconvert:conversion:error` | `{ error: string }` | La conversion a échoué. |
Ces quatre noms d'événements constituent un contrat de transport figé. Respectez exactement la casse.
#### Exemple : écoute des événements
```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);
}
});
```
### Sécurité
| Couche | Protection |
|-------|-----------|
| **Liste blanche de domaines** | Le widget ne fonctionne que sur les domaines listés. Prend en charge les correspondances exactes et les sous-domaines génériques. Validation côté serveur lors de l'émission du jeton. |
| **Vérification Turnstile** | Chaque requête initiale de jeton nécessite une réponse valide au défi Cloudflare Turnstile. |
| **Restriction d'endpoint** | Chaque widget est verrouillé sur un seul endpoint de conversion via `allowed_endpoints` dans le JWT. |
| **Expiration des jetons** | Le JWT expire après 1 heure. Le jeton de rafraîchissement expire après 7 jours. Les deux font l'objet d'un renouvellement lors du rafraîchissement. |
| **Sécurité du jeton de rafraîchissement** | Cookie httpOnly avec `Secure` et `SameSite=none`, inaccessible en JavaScript, envoyé uniquement via HTTPS. |
| **Protection CORS** | L'API gateway valide l'origine de l'iframe du widget à chaque requête. |
| **CSP frame-ancestors** | Les endpoints de configuration et de jeton du widget définissent des en-têtes `frame-ancestors` restreignant quels domaines peuvent intégrer l'iframe. |
| **Aucune clé exposée** | Le code d'intégration ne contient que l'ID du widget. La clé API interne n'est jamais visible. |
Ne placez jamais de clé privée dans une page. Les widgets existent précisément pour que le trafic navigateur s'appuie sur une clé publique restreinte et un JWT de courte durée. Une clé privée
sk_ envoyée depuis un navigateur est rejetée d'emblée avec un HTTP 403. Voir
Clés publiques et JWT.
---
## 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 : ``. 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](/fr/docs/guides/integrations/sdks.md) pour votre langage. Si vous automatisez sans code, utilisez [n8n](/fr/docs/guides/integrations/n8n.md). Si vous voulez qu'un assistant IA fasse le travail, installez le [serveur MCP](/fr/docs/guides/integrations/mcp-setup.md). Si vous voulez simplement que vos propres visiteurs convertissent des fichiers, utilisez un [widget web](#web-widgets).
### 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](/fr/docs/reference/rate-limits.md).