Rendu en file d’attente

Quand utiliser la file

Le point de terminaison direct répond lorsque le document est prêt, ce qui est le plus simple tant que l’appelant peut attendre. Utilisez la file pour les documents longs, les lots ou une requête web qui ne doit pas rester ouverte : la réponse revient immédiatement avec queueId et le traitement continue en arrière-plan.

Mettez la requête en file d’attente pour les documents longs et les traitements par lots. La réponse est immédiate et vous suivez la tâche via son statusUrl.

Ordre de la file

La priorité dans la file dépend de votre offre et ne crée pas de file distincte : une tâche est traitée comme si elle était arrivée plus tôt, proportionnellement à sa priorité. Deux conséquences en découlent : une tâche prioritaire dépasse une tâche mise en file au même instant, et aucune tâche ne reste indéfiniment en attente. L’attente maximale est calculable ; avec les valeurs actuelles, une tâche Free attend au plus 54 minutes et une tâche Max n’attend pas.

curl -X POST https://api.pdfgine.com/api/v1/documents/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateCode": "invoice", "format": "pdf", "data": { } }'

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "queued",
  "statusUrl": "/api/v1/async-jobs/queue_ea464b42...",
  "documentId": null,
  "createdAt": "2026-08-28T13:23:45+00:00"
}

curl https://api.pdfgine.com/api/v1/async-jobs/queue_ea464b42... \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Ajoutez webhookUrl à la requête pour recevoir une notification signée à la fin de la tâche, sans avoir à interroger son état.

À quoi ressemble une tâche terminée

Lisez la tâche via son statusUrl. Pendant son exécution, status vaut queued ou running ; une fois terminée, documentId et result sont renseignés.

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "succeeded",
  "attemptCount": 1,
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "result": {
    "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
    "pageCount": 12
  },
  "failureCode": null,
  "createdAt": "2026-08-28T13:23:45+00:00",
  "completedAt": "2026-08-28T13:23:52+00:00"
}

Une tâche en échec répond avec status failed et un failureCode indiquant la raison ; ces mêmes codes figurent sur la page des erreurs.

Les problèmes les plus courants

• La file répond 202 avec queueId et sans document. documentId reste null jusqu’à la fin de la tâche ; le lire immédiatement et considérer null comme un échec est l’erreur la plus courante.
• Interroger chaque seconde gaspille votre limite de débit. Espacez les interrogations de quelques secondes, ou envoyez webhookUrl et n’interrogez plus.
• status failed indique une tâche terminée, pas en attente. Lisez failureCode et corrigez l’entrée ; la tâche ne redémarrera pas d’elle-même.
• Une notification webhook est signée. Vérifiez la signature avant de lui faire confiance, comme expliqué sur la page des webhooks, et répondez 2xx ; sinon elle sera envoyée à nouveau.
• Un document en file coûte autant de pages qu’un document direct. La file change le moment du traitement, pas son coût.