Batch PDF generation API для queues и jobs
Генерируйте много PDF через queue-safe workflows JSON Render или Template Render, пока ваша система отвечает за chunking, retries, idempotency и storage.
/api/v1/template-render Рендерить много PDF из queue или scheduled job, разбивая работу на safe requests, отправляя каждый document или template data item в gPdf и сохраняя или доставляя returned PDF в вашей системе.
Когда использовать эту API
- Нужно генерировать invoices, statements, labels или reports в scheduled или event-driven batch.
- У вас стабильный template и можно отправлять multiple data items в пределах endpoint limits.
- Нужен queue-friendly rendering без browser workers.
- Вы готовы владеть deduplication, retries и output storage.
Что она не заменяет
- Нужно, чтобы gPdf был вашим batch scheduler, queue, storage system или idempotency ledger.
- Нужны published rate-limit headers или server-side idempotency-key contract.
- Нужен один unbounded request, который рендерит все documents в campaign.
Какой endpoint вызывать
/api/v1/template-render
Template Render — путь по умолчанию для этого сценария.
/api/v1/pdf/render
Используйте, когда сценарию нужен связанный API-путь, контракт шаблона или проверка возможностей.
Минимальный запрос
POST /api/v1/template-render - небольшой batch с двумя invoice data items.
{
"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": []
}
]
}
Что выполняет gPdf
- PDF rendering для каждого JSON Render или Template Render request.
- Template Render data arrays в documented public limits.
- Быстрые stateless render responses, подходящие для queue workers.
- Общее поведение request ID и error envelope.
Что контролирует ваша система
- Queue design, chunking, concurrency, retries, deduplication и output storage.
- Business object selection, template choice и delivery workflow.
- Backoff policy, alerting и recovery после partial failure.
Production-чеклист
- Дробите работу так, чтобы каждый request оставался в documented item и payload limits.
- Генерируйте один X-Request-Id на request и связывайте его с вашим job ID.
- Повторяйте только network или 5xx failures с bounded exponential backoff.
- Не retry 4xx validation failures без изменения payload.
- Храните output PDFs или source data согласно вашей retention policy.
Границы заявлений
- gPdf — render API, а не queue или storage layer.
- Публичный API сегодня не публикует rate-limit headers или server-side idempotency keys.
- Ваша система должна делать retries безопасными.
Batch generation — это integration pattern
Batch PDF generation не является отдельным endpoint. Это способ, которым ваша queue использует public render APIs. Держите jobs небольшими, наблюдаемыми и retry-safe.
Для повторяемых layouts Template Render обычно дает самый чистый contract. Для programmatic documents с custom layouts остается доступен JSON Render.
FAQ
- Предоставляет ли gPdf batch job API?
- Отдельный batch scheduler не exposed. Используйте JSON Render или Template Render из вашей queue или worker system.
- Может ли Template Render принимать несколько data items?
- Да, в пределах public endpoint limits. Более крупные jobs разбивайте по requests.
- Кто отвечает за retries?
- Ваша система отвечает за retries, backoff, deduplication и idempotency. gPdf echoes request IDs для traceability.
- Можно ли рендерить много разных layouts в одном request?
- Используйте отдельные requests, когда layouts или template IDs различаются. Каждый request должен оставаться простым и traceable.