Renderização na fila

Quando usar a fila

O endpoint direto responde quando o documento está pronto, o mais simples quando o cliente pode esperar. Use a fila para documentos longos, muitos documentos de uma vez ou uma requisição web que não pode permanecer aberta: a resposta volta imediatamente com queueId e o trabalho continua em segundo plano.

Coloque a solicitação na fila para documentos longos e tarefas em lote. A resposta é imediata e você acompanha a tarefa em sua statusUrl.

Ordem da fila

A prioridade na fila vem do seu plano e não cria uma fila separada: uma tarefa é tratada como se tivesse chegado antes, proporcionalmente à sua prioridade. Isso tem duas consequências: uma tarefa de maior prioridade ultrapassa outra enfileirada no mesmo instante, e uma tarefa em espera nunca espera para sempre. A espera máxima pode ser calculada; com os valores atuais, uma tarefa Free espera no máximo 54 minutos e uma tarefa Max não 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"

Adicione webhookUrl à solicitação e uma notificação assinada será entregue quando a tarefa terminar, sem precisar consultar o status.

Como é uma tarefa concluída

Consulte a tarefa em statusUrl. Durante a execução, status é queued ou running; ao terminar, documentId e result são preenchidos.

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

Uma tarefa com falha retorna status failed e failureCode com o motivo; os mesmos códigos estão na página de erros.

Os problemas mais comuns

• A fila responde 202 com queueId e sem documento. documentId permanece null até a conclusão; lê-lo imediatamente e tratar null como falha é o erro mais comum.
• Consultar a cada segundo desperdiça seu limite de requisições. Consulte com alguns segundos de intervalo ou envie webhookUrl e não consulte.
• status failed é uma tarefa finalizada, não pendente. Leia failureCode e corrija a entrada; a tarefa não reiniciará sozinha.
• Uma notificação de webhook é assinada. Verifique a assinatura antes de confiar nela, conforme a página de webhooks, e responda 2xx; caso contrário, ela será entregue novamente.
• Um documento na fila custa as mesmas páginas que um direto. A fila muda quando o trabalho acontece, não o custo.