Quels sont les statuts possibles d’un document PDFMonkey ?

Les documents passent par cinq statuts : draft (créé mais non mis en file d’attente), pending (en attente de traitement), generating (en cours de rendu), success (le fichier est prêt à télécharger) et failure (une erreur s’est produite lors de la génération).

Peut-on ignorer le statut draft lors de la génération d’un document PDFMonkey ?

Oui. Définissez le statut sur pending lors de la création du document via l’API pour lancer immédiatement la génération. C’est le schéma le plus courant pour les intégrations API.

Que se passe-t-il quand un document PDFMonkey échoue ?

Le document passe au statut failure avec un champ failure_cause décrivant l’erreur. Vous pouvez inspecter l’erreur, corriger le modèle ou les données, puis relancer en remettant le statut sur pending.

Statuts des documents et cycle de vie

Chaque document dans PDFMonkey passe par une série de statuts au fil de sa progression, de la création jusqu’au PDF final. Comprendre ce cycle de vie vous aide à construire des intégrations fiables et à résoudre les problèmes de génération.

Vue d’ensemble des statuts

Statut	Signification	Ce que vous pouvez faire
`draft`	Créé mais pas encore mis en file d’attente	Modifier le payload, prévisualiser, supprimer
`pending`	En file d’attente, en attente d’un worker	Attendre — le traitement démarre automatiquement
`generating`	Activement transformé en PDF	Attendre — le worker traite le document
`success`	Le PDF est prêt	Télécharger, partager, intégrer une prévisualisation
`failure`	Une erreur s’est produite pendant la génération	Examiner l’erreur, corriger le problème, réessayer

stateDiagram-v2
    [*] --> draft: Création via API ou tableau de bord
    draft --> pending: Génération demandée
    pending --> generating: Pris en charge par un worker
    generating --> success: PDF prêt
    generating --> failure: Erreur survenue
    failure --> pending: Nouvelle tentative

Brouillon (Draft)

Un document commence au statut draft lorsque vous le créez, que ce soit via l’API ou le Dashboard. C’est le statut par défaut — si vous ne définissez pas "status": "pending" dans votre appel API, le document reste dans cet état.

Ce que vous pouvez faire :

Modifier les données dynamiques (payload) du document
Prévisualiser le document via le champ preview_url (voir Intégrer une prévisualisation de document)
Supprimer le document

Transition sortante : Demandez la génération en appelant l’API avec "status": "pending" ou en cliquant sur Generate dans le Dashboard. Le document passe au statut pending.

Vous pouvez passer l’étape du brouillon. Définissez "status": "pending" dès la création du document pour lancer immédiatement la génération — c’est l’approche la plus courante pour les intégrations API.

En attente (Pending)

Un document au statut pending est en file d’attente et attend d’être pris en charge par un worker de génération.

Ce que cela signifie : La demande de génération a été acceptée mais le traitement n’a pas encore commencé. En conditions normales, les documents quittent ce statut en quelques secondes.

Transition sortante : Un worker prend en charge le document et le fait passer au statut generating. Cela se produit automatiquement — aucune action n’est requise de votre côté.

Définir "status": "pending" déclenche une vérification du quota. Si votre compte a dépassé son quota mensuel de documents, l’API rejette la requête avec une erreur de validation. Consultez Nos offres pour les détails des quotas.

En cours de génération (Generating)

Un document au statut generating est activement traité. Le template est rendu avec le payload du document puis converti en PDF (ou en image, selon le format de sortie du template).

Ce que cela signifie : Le worker construit le document. Cela prend généralement quelques secondes, mais les templates complexes avec de nombreuses pages ou des ressources lourdes peuvent prendre plus de temps.

Transition sortante : Le document passe au statut success ou failure selon le résultat.

Succès (Success)

Un document au statut success a été généré et son PDF est disponible au téléchargement.

Ce que vous pouvez faire :

Télécharger le PDF via le champ download_url — il s’agit d’une URL signée temporaire valide pendant 1 heure, renouvelée à chaque appel API (voir L’URL de téléchargement)
Partager le document via son public_share_link si activé (voir Liens de partage)
Recevoir une notification webhook lorsque la génération est terminée

Le download_url expire après 1 heure. Récupérez le document à nouveau depuis l’API pour obtenir une URL fraîche. Consultez L’URL de téléchargement pour plus de détails.

Échec (Failure)

Un document au statut failure a rencontré une erreur pendant la génération. Le champ failure_cause dans la réponse de l’API contient une description lisible de l’erreur. Le champ generation_logs fournit des détails supplémentaires pour le débogage.

Causes fréquentes :

Erreurs de syntaxe dans le template (Liquid, HTML ou la CSS)
Données dynamiques invalides ou manquantes
Échec du chargement de ressources (URLs d’images cassées, ressources externes inaccessibles)
Timeout dû à une complexité excessive du template

Ce que vous pouvez faire :

Examiner les champs failure_cause et generation_logs pour comprendre l’erreur
Corriger le problème sous-jacent dans le template ou le payload
Relancer la génération en remettant le statut du document à "pending" via l’API

Transition sortante : Lorsque vous demandez une nouvelle tentative, le document repasse au statut pending et traverse à nouveau le cycle de génération.

Réagir aux changements de statut

Vous n’avez pas besoin de faire des appels en boucle à l’API pour savoir quand un document est prêt. Configurez un endpoint webhook pour recevoir une notification lorsque la génération réussit ou échoue. C’est l’approche recommandée pour les intégrations en production.

Si vous préférez un flux synchrone, utilisez l’endpoint /api/v1/documents/sync pour attendre le résultat en une seule requête. Consultez Génération synchrone pour les détails et les limitations.

Pages associées

L’URL de téléchargement — fonctionnement des liens de téléchargement temporaires
Webhooks — recevoir des notifications lors des changements de statut
Référence API Documents — documentation complète des endpoints et des champs
Dépannage : l’URL de téléchargement est vide — raisons courantes pour lesquelles download_url est null
Dépannage : l’URL de téléchargement retourne une erreur 403 — comment gérer les URLs expirées

Questions fréquentes

Quels sont les statuts possibles d’un document PDFMonkey ?: Les documents passent par cinq statuts : draft (créé mais non mis en file d’attente), pending (en attente de traitement), generating (en cours de rendu), success (le fichier est prêt à télécharger) et failure (une erreur s’est produite lors de la génération).
Peut-on ignorer le statut draft lors de la génération d’un document PDFMonkey ?: Oui. Définissez le statut sur pending lors de la création du document via l’API pour lancer immédiatement la génération. C’est le schéma le plus courant pour les intégrations API.
Que se passe-t-il quand un document PDFMonkey échoue ?: Le document passe au statut failure avec un champ failure_cause décrivant l’erreur. Vous pouvez inspecter l’erreur, corriger le modèle ou les données, puis relancer en remettant le statut sur pending.