# URL de téléchargement vide ou null : que faire ?


Le champ `download_url` est `null` tant qu’un document n’a pas atteint le [statut](../generation-de-documents/statuts-des-documents.md) `success`. Cette page détaille chaque cause possible et comment y remédier.

## Le statut du document est « draft » {#status-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 {#fix-status-draft}

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

```json
{
  "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](../api/documents.md) pour plus de détails.

> [!TIP]
> 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 » {#status-pending-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 {#fix-status-pending}

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

| Approche               | Fonctionnement                                                                                                    | Idéal pour                                        |
| :--------------------- | :---------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ |
| **Webhook**            | PDFMonkey envoie un POST à votre endpoint lorsque le document atteint `success` ou `failure`.                     | Intégrations en production                        |
| **Polling**            | Récupérez le document en boucle jusqu’à ce que `status` soit `success` ou `failure`.                              | Scripts simples, prototypage                      |
| **Endpoint synchrone** | `POST /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](../generation-de-documents/webhooks.md) et [Génération synchrone](../api/documents.md#synchronous-generation) pour les instructions de configuration.

## Le statut du document est « failure » {#status-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 {#fix-status-failure}

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](../generation-de-documents/statuts-des-documents.md#failure) pour les causes d’échec courantes.

## Ne confondez pas download_url et preview_url {#preview-url-is-not-download}

> [!WARNING]
> **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](../generation-de-documents/integrer-un-apercu.md) pour apprendre à utiliser `preview_url` dans votre propre application.


## Questions fréquentes {#faq}

**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](../api/documents.md#synchronous-generation).

**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](../generation-de-documents/webhooks.md) 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](../api/documents.md#synchronous-generation) pour attendre le résultat en une seule requête.

## Pages associées {#related-pages}

- [Statuts et cycle de vie des documents](../generation-de-documents/statuts-des-documents.md) — comprendre les statuts draft, pending, generating, success et failure
- [URL de téléchargement](../generation-de-documents/url-de-telechargement.md) — fonctionnement des URL signées temporaires et leur expiration
- [Générer des documents via l’API](../generation-de-documents/generation-pdf-via-api.md) — guide complet de création de documents via l’API
- [Webhooks](../generation-de-documents/webhooks.md) — recevoir des notifications à la fin de la génération
- [Génération synchrone](../api/documents.md#synchronous-generation) — créer un document et attendre le résultat en une requête
- [L’URL de téléchargement renvoie une erreur 403](./l-url-de-telechargement-renvoie-403.md) — comment gérer les URL expirées


## FAQ

**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.
