Pourquoi l’URL de téléchargement PDFMonkey est-elle vide ou null ?

Dernière mise à jour le 23 mars 2026

Le champ download_url est null tant qu’un document n’a pas atteint le statut success. Cette page détaille chaque cause possible et comment y remédier.

Le statut du document est « draft »

C’est la cause la plus fréquente. Si vous ne définissez pas d’attribut status lors de la création du document, celui-ci reste en draft par défaut et aucune génération n’est lancée. Puisque le document n’est jamais généré, il n’y a pas de fichier à télécharger et download_url reste null.

Comment corriger

Définissez "status": "pending" lors de la création du document pour lancer la génération immédiatement :

{
  "document": {
    "document_template_id": "YOUR_TEMPLATE_ID",
    "status": "pending",
    "payload": {
      "name": "Jane Doe"
    }
  }
}

Vous pouvez également mettre à jour un document existant en envoyant une requête PATCH avec "status": "pending". Consultez la référence API Documents pour plus de détails.

Définir "status": "pending" dès la création est le schéma le plus courant pour les intégrations API. Cela permet de sauter l’étape « draft » et de lancer la génération en une seule requête.

Le statut du document est « pending » ou « generating »

Si vous avez défini "status": "pending" lors de la création, la génération est en file d’attente mais n’est pas encore terminée. La réponse à votre requête de création renvoie le document en statut pending ou generating ; le champ download_url est null à ce stade car le fichier n’existe pas encore.

Comment corriger

Attendez la fin de la génération avant de lire l’URL. Trois options s’offrent à vous :

ApprocheFonctionnementIdéal pour
WebhookPDFMonkey envoie un POST à votre endpoint lorsque le document atteint success ou failure.Intégrations en production
PollingRécupérez le document en boucle jusqu’à ce que status soit success ou failure.Scripts simples, prototypage
Endpoint synchronePOST /api/v1/documents/sync crée le document et attend le résultat en une seule requête (timeout de 6 minutes).Faibles volumes, workflows tolérants à la latence

Consultez Webhooks et Génération synchrone pour les instructions de configuration.

Le statut du document est « failure »

Si la génération a échoué, le statut du document est failure et download_url est null. Le champ failure_cause contient un message d’erreur lisible et generation_logs fournit des détails supplémentaires.

Comment corriger

  1. Inspectez les champs failure_cause et generation_logs dans la réponse de l’API.
  2. Corrigez le problème sous-jacent dans votre template ou votre payload.
  3. Relancez la génération en repassant le statut du document à "pending" via une requête PATCH.

Consultez Statuts et cycle de vie des documents pour les causes d’échec courantes.

Ne confondez pas download_url et preview_url

preview_url n’est pas un lien de téléchargement

Le champ preview_url affiche un aperçu visuel du document dans le navigateur. Il fonctionne même pour les brouillons et ne déclenche pas le téléchargement d’un fichier. Si vous avez besoin du fichier généré, utilisez download_url.

Un bon exemple de preview_url en action est le tableau de bord PDFMonkey : lorsque vous créez un document, le panneau d’aperçu à droite utilise preview_url pour montrer le rendu avant la génération.

Consultez Intégrer un aperçu de document pour apprendre à utiliser preview_url dans votre propre application.

Questions fréquentes

J’ai défini le statut à « pending » mais l’URL de téléchargement est toujours null.

La réponse à la requête de création renvoie le document avant la fin de la génération. Vous devez attendre que le statut atteigne success en interrogeant l’API, en utilisant un webhook ou en passant par l’endpoint synchrone.

Combien de temps dure la génération ?

La plupart des documents sont générés en quelques secondes. Les templates complexes (nombreuses pages, images lourdes, ressources externes) peuvent prendre plus de temps. L’endpoint synchrone a un timeout de 6 minutes.

Puis-je obtenir l’URL de téléchargement sans polling ?

Oui. Configurez un endpoint webhook pour recevoir une notification lorsque la génération réussit. Le payload du webhook inclut le download_url. Vous pouvez aussi utiliser l’endpoint synchrone pour attendre le résultat en une seule requête.

Questions fréquentes

Pourquoi l’URL de téléchargement PDFMonkey est-elle vide ou null ?
Le champ download_url est null tant que le document n’a pas atteint le statut "success". La cause la plus fréquente est l’oubli de passer le statut à "pending" lors de la création, ce qui laisse le document en "draft" et empêche la génération. Passez le statut à "pending", puis attendez la fin de la génération via le polling ou un webhook.
Comment obtenir une URL de téléchargement depuis PDFMonkey ?
Créez un document avec le statut "pending" pour lancer la génération. Une fois le statut à "success", le champ download_url contient une URL signée temporaire valide 1 heure. Vous pouvez interroger l’API en boucle, utiliser un webhook, ou utiliser l’endpoint synchrone /api/v1/documents/sync.
Navigation