API Documentation

Rappels webhook de conversion et notifications de tâches#

EnConvert vous notifie lorsque les tâches de conversion asynchrones et par lot se terminent, via trois mécanismes indépendants : l'interrogation de GET /v1/convert/batch/{batch_id}, les rappels webhook via le paramètre callback_url, et les notifications par e-mail via notification_email. Les trois peuvent être combinés dans une seule requête, et les fichiers terminés sont récupérés via les URL de téléchargement présentes dans la réponse de statut du lot. Cette page documente les charges utiles de rappel, les exigences de livraison et les restrictions par forfait pour chaque méthode.

Clés privées uniquement : Les notifications de tâches et l'interrogation du statut d'un lot ne sont disponibles que lors de l'authentification avec une clé API privée (X-API-Key: sk_...). Les clés publiques ne prennent pas en charge le traitement asynchrone ou par lot.

Vue d'ensemble#

Méthode Paramètre / Endpoint Description
Polling GET /v1/convert/batch/{batch_id} Interroge le statut en temps réel, les compteurs de progression et les URL de téléchargement.
Email notification_email Envoie un e-mail de fin avec le statut de la tâche et un lien vers le tableau de bord.
Webhook callback_url Envoie une requête POST avec les résultats de la tâche vers votre serveur.

Les trois méthodes fonctionnent aussi bien pour les tâches asynchrones à URL unique que pour les tâches par lot à URL multiples, sur les endpoints url-to-pdf, url-to-screenshot, website-to-pdf et website-to-screenshot.

Interrogation du statut d'un lot#

La méthode recommandée pour suivre la progression d'une tâche. Interrogez l'endpoint de statut du lot avec le batch_id renvoyé dans la réponse initiale 202.

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_your_private_key

Réponse#

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 3,
    "completed": 1,
    "failed": 0,
    "in_progress": 2,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page-1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 184320,
            "duration": "3.12"
        },
        {
            "source_url": "https://example.com/page-2",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}

Valeurs de statut#

Statut Signification
processing Au moins une URL est encore en cours de conversion.
completed Toutes les URL ont été converties avec succès.
partial Toutes les URL sont terminées, mais certaines ont échoué.
failed Toutes les URL ont échoué.

En mode ZIP (output_mode: "zip"), un zip_download_url est fourni pour l'archive entière une fois terminée. En mode individuel, chaque élément a son propre download_url.

Pour tous les détails du schéma de réponse, consultez Traitement par lot.

Notifications par e-mail#

Incluez le paramètre notification_email dans votre requête pour recevoir un e-mail lorsque la tâche se termine. Si vous omettez ce paramètre, l'e-mail est envoyé par défaut à l'adresse e-mail du propriétaire du projet.

Exemple#

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "notification_email": "[email protected]"
  }'

Réponse (HTTP 202 Accepted)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 1,
    "output_format": "individual"
}

Contenu de l'e-mail#

L'e-mail de fin inclut :

  • En-tête de statut avec une bannière colorée (vert pour succès, rouge pour échec)
  • ID de tâche et ID de lot (si la tâche fait partie d'un lot)
  • Texte de statut (succès ou échec)
  • Texte statique dirigeant les utilisateurs vers le téléchargement des fichiers depuis leur tableau de bord
  • Tableau des tâches (uniquement pour les tâches par lot en mode ZIP) avec les colonnes : #, URL (tronquée à 50 caractères), statut, et nom de fichier de sortie

En mode individuel (y compris les lots individuels à URL multiples), chaque e-mail par URL contient uniquement l'ID de tâche et le statut -- pas de tableau des tâches. En mode ZIP, l'e-mail unique du lot inclut le tableau complet des tâches avec toutes les URL et leurs statuts.

Comportement par défaut : Si vous n'incluez pas notification_email dans votre requête, l'e-mail de fin est envoyé automatiquement à l'adresse e-mail du propriétaire du projet. Pour supprimer entièrement les notifications par e-mail, ce comportement par défaut ne peut actuellement pas être désactivé.

Rappels webhook#

Incluez le paramètre callback_url dans votre requête pour recevoir un POST webhook lorsque la tâche se termine. Nécessite un forfait avec accès aux webhooks.

Exemple#

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Réponse (HTTP 202 Accepted)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 1,
    "output_format": "individual"
}

Charge utile du rappel en mode URL unique / individuel#

En mode individuel, un POST séparé est envoyé pour chaque URL au fur et à mesure qu'elle se termine :

{
    "job_id": "12345",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/example_20260405_123456789.pdf",
    "filename": "example_20260405_123456789.pdf",
    "file_size": 184320
}

Pour une conversion échouée :

{
    "job_id": "12345",
    "status": "failed",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000"
}

Charge utile du rappel en mode ZIP#

En mode ZIP, un seul POST est envoyé lorsque le lot entier se termine :

{
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-pdf/batch_20260405_123456789.zip",
    "filename": "batch_20260405_123456789.zip",
    "file_size": 456789,
    "total_tasks": 3,
    "successful_tasks": 2,
    "failed_tasks": 1,
    "tasks": [
        {"url": "https://example.com/page-1", "status": "success", "filename": "page1.pdf"},
        {"url": "https://example.com/page-2", "status": "success", "filename": "page2.pdf"},
        {"url": "https://invalid-url.example", "status": "failed", "error": "Page load timeout"}
    ]
}
Comportement des notifications, individuel vs ZIP : En mode individuel, vous recevez N POST webhook séparés (un par URL) et N e-mails séparés. En mode ZIP, vous recevez un seul POST webhook et un seul e-mail pour le lot entier. Concevez votre gestionnaire de webhook en conséquence.

Utiliser plusieurs méthodes de notification ensemble#

Vous pouvez combiner l'interrogation, l'e-mail et le webhook dans la même requête. Les trois fonctionnent indépendamment.

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": [
      "https://example.com/page-1",
      "https://example.com/page-2"
    ],
    "notification_email": "[email protected]",
    "callback_url": "https://yourapp.com/webhooks/enconvert"
  }'

Après l'envoi, vous pouvez : 1. Interroger GET /v1/convert/batch/{batch_id} pour suivre la progression en temps réel 2. Recevoir un POST webhook à votre URL de rappel lorsque chaque conversion se termine 3. Recevoir un e-mail à l'adresse spécifiée lorsque chaque conversion se termine

Paramètres de notification#

Paramètre Type Obligatoire Par défaut Description Restriction par forfait
notification_email string Non E-mail du propriétaire du projet Adresse e-mail pour recevoir les notifications de fin de tâche. --
callback_url string Non -- URL pour recevoir un POST webhook à la fin. Nécessite l'accès aux webhooks

Exigences de livraison des webhooks#

Exigence Détail
Méthode EnConvert envoie une requête POST avec Content-Type: application/json.
Délai Votre endpoint doit répondre dans un délai de 30 secondes.
Codes de succès HTTP 200, 201, 202, ou 204 sont considérés comme une livraison réussie.
Nouvelles tentatives Aucune nouvelle tentative en cas d'échec. Si la livraison du webhook échoue (réponse d'échec ou délai dépassé), les résultats restent disponibles via l'interrogation du statut du lot.
Authentification Aucun en-tête d'authentification n'est envoyé. Validez le batch_id par rapport à vos propres enregistrements si nécessaire.

Restrictions selon le forfait d'abonnement#

Fonctionnalité Founding Indie Studio Enterprise
Mode asynchrone Non Oui Oui Oui
Interrogation du statut du lot Non Oui Oui Oui
Notifications par e-mail Non Oui Oui Oui
Rappels webhook (callback_url) Non Non Oui Oui
Remarque : Les notifications par e-mail ne sont pas soumises à une restriction de fonctionnalité distincte -- elles sont disponibles pour tout utilisateur de clé API privée ayant accès à l'asynchrone. Le paramètre notification_email ne nécessite aucune fonctionnalité de forfait spécifique. Les rappels webhook (callback_url) nécessitent la fonctionnalité has_webhook, disponible à partir des forfaits Studio.

Tester les webhooks#

Pendant le développement, utilisez webhook.site pour générer une URL de rappel temporaire à des fins de test :

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "async_mode": true,
    "callback_url": "https://webhook.site/your-unique-id"
  }'

Consultez votre tableau de bord webhook.site pour inspecter la charge utile exacte du rappel une fois la tâche terminée.

Questions fréquentes#

Comment recevoir un rappel webhook lorsqu'une tâche de conversion de fichier se termine ?#

Incluez le paramètre callback_url dans votre requête avec une clé API privée. EnConvert envoie un POST avec Content-Type: application/json à cette URL lorsque la tâche se termine. Les rappels webhook nécessitent un forfait avec accès aux webhooks (Studio, Production ou Enterprise).

EnConvert relance-t-il les livraisons de webhook échouées ?#

Non. Votre endpoint doit répondre dans un délai de 30 secondes avec HTTP 200, 201, 202, ou 204. Si la livraison échoue, les résultats restent disponibles via l'interrogation du statut du lot à GET /v1/convert/batch/{batch_id}.

Puis-je utiliser ensemble les notifications par e-mail, webhook et interrogation ?#

Oui. notification_email, callback_url et l'interrogation du statut fonctionnent tous indépendamment et peuvent être combinés dans la même requête. Si notification_email est omis, l'e-mail de fin est envoyé par défaut à l'adresse e-mail du propriétaire du projet.

Pourquoi est-ce que je reçois un webhook par URL au lieu d'un seul pour tout le lot ?#

En mode individuel, vous recevez N POST webhook séparés (un par URL) et N e-mails séparés. Pour recevoir un seul webhook et un seul e-mail pour le lot entier, utilisez le mode ZIP, qui envoie un seul POST avec total_tasks, successful_tasks, failed_tasks, et un tableau tasks.

Comment puis-je tester les rappels webhook pendant le développement ?#

Utilisez webhook.site pour générer une URL temporaire et transmettez-la comme callback_url dans votre requête. Le tableau de bord webhook.site affiche la charge utile JSON exacte qu'EnConvert livre lorsque la tâche se termine.

← File Ingestion Batch Processing →