Generazione in coda

Quando usare la coda

L'endpoint diretto risponde quando il documento è pronto, la soluzione più semplice se il chiamante può attendere. Usa la coda per documenti lunghi, molti documenti insieme o richieste web che non devono restare aperte: la risposta arriva subito con queueId e il lavoro prosegue in background.

Metti in coda la richiesta per documenti lunghi e processi in blocco. La risposta arriva subito e puoi seguire il processo tramite la sua statusUrl.

Ordine della coda

La priorità della coda dipende dal piano e non crea una coda separata: un processo viene trattato come se fosse arrivato prima, in proporzione alla sua priorità. Ne derivano due conseguenze: un processo con priorità maggiore supera uno messo in coda nello stesso momento e nessun processo attende all'infinito. L'attesa massima è calcolabile; con i valori attuali un processo Free attende al massimo 54 minuti e un processo Max non attende affatto.

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"

Aggiungi una webhookUrl alla richiesta per ricevere una notifica firmata al termine del processo, senza dover effettuare polling.

Com'è un processo completato

Leggi il processo dalla sua statusUrl. Durante l'esecuzione status è queued o running; al termine vengono compilati documentId e result.

{
  "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 processo non riuscito risponde con status failed e un failureCode che ne spiega il motivo; gli stessi codici sono elencati nella pagina degli errori.

Gli errori più comuni

• La coda risponde 202 con queueId e nessun documento. documentId resta null fino al termine del processo; leggerlo subito e trattare null come un errore è lo sbaglio più comune.
• Il polling ogni secondo spreca il limite di frequenza. Interroga a distanza di qualche secondo oppure invia webhookUrl ed evita del tutto il polling.
• status failed indica un processo concluso, non in attesa. Leggi failureCode e correggi l'input: il processo non riparte da solo.
• Una notifica webhook è firmata. Verifica la firma prima di fidarti, come spiega la pagina Webhook, e rispondi 2xx, altrimenti verrà inviata di nuovo.
• Un documento in coda costa le stesse pagine di uno diretto. La coda cambia quando avviene il lavoro, non quanto costa.