Renderización en cola

Cuándo usar la cola

El endpoint directo responde cuando el documento está listo, la opción más sencilla mientras el cliente pueda esperar. Usa la cola si el documento es largo, si generas muchos a la vez o si el cliente es una solicitud web que no debe permanecer abierta: la respuesta llega inmediatamente con queueId y el trabajo continúa en segundo plano.

Envía la solicitud a la cola para documentos largos y trabajos masivos. La respuesta es inmediata y puedes seguir el trabajo en su statusUrl.

Orden de la cola

La prioridad de la cola procede de tu plan y no crea una cola independiente: cada trabajo se trata como si hubiera llegado antes en proporción a su prioridad. Esto tiene dos consecuencias: un trabajo de mayor prioridad adelanta a otro encolado al mismo tiempo y un trabajo en espera nunca espera indefinidamente. La espera máxima es calculable; con los valores actuales, un trabajo Free espera como máximo 54 minutos y un trabajo Max no espera.

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"

Añade webhookUrl a la solicitud y recibirás una notificación firmada al finalizar el trabajo, sin tener que consultar su estado.

Cómo es un trabajo terminado

Consulta el trabajo en statusUrl. Mientras se ejecuta, status es queued o running; cuando termina, documentId y result se rellenan.

{
  "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"
}

Un trabajo fallido responde con status failed y un failureCode que indica el motivo; los mismos códigos están en la página de errores.

Los errores más habituales

• La cola responde 202 con queueId y sin documento. documentId permanece null hasta que termina el trabajo; leerlo de inmediato y considerar null un error es el fallo más habitual.
• Consultar cada segundo desperdicia tu límite de solicitudes. Deja varios segundos entre consultas o envía webhookUrl y no consultes.
• status failed es un trabajo terminado, no pendiente. Lee failureCode y corrige la entrada; el trabajo no volverá a empezar por sí solo.
• La notificación webhook está firmada. Verifica la firma antes de confiar en ella, como explica la página de webhooks, y responde 2xx; de lo contrario, se enviará otra vez.
• Un documento en cola consume las mismas páginas que uno directo. La cola cambia cuándo se hace el trabajo, no su coste.