Batch-PDF-Generierung API für Queues und Jobs
Erzeugen Sie viele PDFs über queue-sichere JSON Render- oder Template Render-Workflows, während Ihr System Chunking, Retries, Idempotenz und Speicherung verantwortet.
/api/v1/template-render Rendern Sie viele PDFs aus einer Queue oder einem geplanten Job, indem Sie Arbeit in sichere Requests aufteilen, jedes Dokument oder Template-data-Element an gPdf senden und das zurückgegebene PDF in Ihrem eigenen System speichern oder ausliefern.
Wann diese API passt
- Sie müssen Rechnungen, Kontoauszüge, Labels oder Berichte in einem geplanten oder eventgetriebenen Batch erzeugen.
- Sie haben eine stabile Vorlage und können mehrere data-Elemente innerhalb der Endpunktlimits senden.
- Sie benötigen queue-freundliches Rendering, ohne Browser-Worker zu betreiben.
- Sie können Deduplizierung, Retries und Ausgabespeicherung selbst verantworten.
Was sie nicht ersetzt
- Sie benötigen gPdf als Ihren Batch-Scheduler, Ihre Queue, Ihr Speichersystem oder Ihr Idempotenz-Ledger.
- Sie benötigen veröffentlichte Rate-Limit-Header oder einen serverseitigen Idempotency-Key-Vertrag.
- Sie benötigen einen unbegrenzten Request, der jedes Dokument einer Kampagne rendert.
Welchen Endpoint aufrufen
/api/v1/template-render
Template Render ist der Standardpfad für diesen Workflow.
/api/v1/pdf/render
Nutzen Sie dies, wenn der Workflow den zugehörigen API-Pfad, einen Template-Vertrag oder eine Capability-Abfrage braucht.
Minimaler Request
POST /api/v1/template-render - kleiner Batch mit zwei Rechnungs-data-Elementen.
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
Was gPdf übernimmt
- PDF-Rendering für jeden JSON Render- oder Template Render-Request.
- Template Render-data-Arrays innerhalb dokumentierter öffentlicher Limits.
- Schnelle zustandslose Render-Antworten, die für Queue-Worker geeignet sind.
- Gemeinsames Request-ID- und Fehler-Envelope-Verhalten.
Was Ihr System verantwortet
- Queue-Design, Chunking, Nebenläufigkeit, Retries, Deduplizierung und Ausgabespeicherung.
- Auswahl von Geschäftsobjekten, Template-Wahl und Zustellungsworkflow.
- Backoff-Policy, Alerting und Wiederherstellung nach Teilausfall.
Produktions-Checkliste
- Chunking so planen, dass jeder Request innerhalb dokumentierter Item- und Payload-Limits bleibt.
- Pro Request ein X-Request-Id erzeugen und Ihrer Job-ID zuordnen.
- Nur Netzwerk- oder 5xx-Fehler mit begrenztem exponentiellem Backoff erneut versuchen.
- 4xx-Validierungsfehler nicht erneut senden, ohne den Payload zu ändern.
- Ausgabe-PDFs oder Quelldaten gemäß Ihrer Aufbewahrungsrichtlinie speichern.
Aussagegrenzen
- gPdf ist die Render API, nicht die Queue- oder Storage-Schicht.
- Die öffentliche API veröffentlicht heute keine Rate-Limit-Header oder serverseitigen Idempotency Keys.
- Ihr System muss Retries sicher machen.
Batch-Generierung ist ein Integrationsmuster
Batch-PDF-Generierung ist kein separater Endpunkt. Sie beschreibt, wie Ihre Queue die öffentlichen Render APIs nutzt. Halten Sie Jobs klein, beobachtbar und retry-sicher.
Für wiederholte Layouts bietet Template Render meistens den saubersten Vertrag. Für programmatische Dokumente mit individuellen Layouts bleibt JSON Render verfügbar.
FAQ
- Stellt gPdf eine Batch-Job-API bereit?
- Es gibt keinen separaten Batch-Scheduler. Nutzen Sie JSON Render oder Template Render aus Ihrer eigenen Queue oder Ihrem eigenen Worker-System.
- Kann Template Render mehrere data-Elemente akzeptieren?
- Ja, innerhalb der öffentlichen Endpunktlimits. Teilen Sie größere Jobs auf mehrere Requests auf.
- Wer verantwortet Retries?
- Ihr System verantwortet Retries, Backoff, Deduplizierung und Idempotenz. gPdf spiegelt Request IDs für Nachvollziehbarkeit zurück.
- Kann ich viele verschiedene Layouts in einem Request rendern?
- Nutzen Sie getrennte Requests, wenn Layouts oder template_id-Werte unterschiedlich sind. Halten Sie jeden Request einfach und nachvollziehbar.