Erstellung über die Warteschlange

Wann die Warteschlange sinnvoll ist

Der direkte Endpunkt antwortet, sobald das Dokument fertig ist. Das ist am einfachsten, solange der Aufrufer warten kann. Nutzen Sie die Warteschlange bei langen Dokumenten, vielen gleichzeitigen Erstellungen oder Webanfragen, die nicht offen bleiben dürfen: Die Antwort kommt sofort mit einer queueId, während die Arbeit im Hintergrund weiterläuft.

Stellen Sie Anfragen für lange Dokumente und Stapelaufträge in die Warteschlange. Die Antwort erfolgt sofort; Sie verfolgen den Auftrag über seine statusUrl.

Reihenfolge in der Warteschlange

Die Warteschlangenpriorität ergibt sich aus Ihrem Tarif und bedeutet keine separate Warteschlange: Ein Auftrag wird so behandelt, als wäre er entsprechend seiner Priorität früher eingegangen. Das hat zwei Folgen: Ein Auftrag mit höherer Priorität überholt einen gleichzeitig eingereihten Auftrag, und kein wartender Auftrag wartet unbegrenzt. Die maximale Wartezeit lässt sich berechnen; mit den aktuellen Werten wartet ein Free-Auftrag höchstens 54 Minuten und ein Max-Auftrag gar nicht.

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"

Fügen Sie der Anfrage eine webhookUrl hinzu, um nach Abschluss des Auftrags eine signierte Benachrichtigung zu erhalten. So ist keine regelmäßige Statusabfrage nötig.

So sieht ein abgeschlossener Auftrag aus

Lesen Sie den Auftrag über statusUrl. Während der Ausführung ist status queued oder running; nach Abschluss sind documentId und result ausgefüllt.

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

Ein fehlgeschlagener Auftrag liefert status failed und einen failureCode mit der Ursache; dieselben Codes stehen auf der Fehlerseite.

Häufige Fehler

• Die Warteschlange antwortet mit 202 und queueId, aber ohne Dokument. documentId bleibt bis zum Abschluss null. Dies sofort als Fehler zu werten ist der häufigste Fehler an dieser Stelle.
• Sekündliche Statusabfragen verschwenden Ihr Ratenlimit. Fragen Sie alle paar Sekunden ab oder senden Sie eine webhookUrl, um ganz darauf zu verzichten.
• status failed bedeutet abgeschlossen, nicht ausstehend. Lesen Sie failureCode und korrigieren Sie die Eingabe; der Auftrag startet nicht von selbst erneut.
• Webhook-Benachrichtigungen sind signiert. Prüfen Sie die Signatur vor der Verwendung — die Webhook-Seite erklärt das Vorgehen — und antworten Sie mit 2xx, sonst erfolgt eine erneute Zustellung.
• Ein Dokument aus der Warteschlange kostet genauso viele Seiten wie ein direkt erstelltes. Die Warteschlange ändert den Ausführungszeitpunkt, nicht den Preis.