API пакетного створення PDF для черг і задач
Генеруйте багато PDF через безпечні для черги процеси JSON Render або Template Render, поки ваша система відповідає за розбиття роботи, повторні спроби, ідемпотентність і зберігання.
/api/v1/template-render Рендерити багато PDF із черги або планової задачі: розбивати роботу на безпечні запити, надсилати кожен документ або елемент template data в gPdf і зберігати чи доставляти повернений PDF у власній системі.
Коли використовувати цю API
- Потрібно генерувати рахунки, виписки, етикетки або звіти у плановому чи подієвому пакеті.
- Є стабільний шаблон, і ви можете надсилати кілька елементів data у межах лімітів маршруту API.
- Потрібен дружній до черг рендеринг без запуску браузерних worker.
- Ви можете самі відповідати за дедуплікацію, retry і зберігання результату.
Що вона не замінює
- Потрібно, щоб gPdf був вашим планувальником batch-задач, чергою, системою зберігання або ledger ідемпотентності.
- Потрібні опубліковані rate-limit headers або серверний контракт idempotency-key.
- Потрібен один необмежений запит для рендерингу всіх документів кампанії.
Який шлях API викликати
/api/v1/template-render
Template Render — типовий шлях для цього сценарію.
/api/v1/pdf/render
Використовуйте, коли сценарію потрібен пов’язаний API-шлях, контракт шаблону або перевірка можливостей.
Мінімальний запит
POST /api/v1/template-render - невеликий batch із двома елементами invoice data.
{
"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-рендеринг для кожного запиту JSON Render або Template Render.
- Масиви data у Template Render у межах задокументованих публічних лімітів.
- Швидкі stateless-відповіді рендера, придатні для обробника черги.
- Спільну поведінку request ID і конверта помилок.
Що контролює ваша система
- Дизайн черги, розбиття роботи, паралельність, повторні спроби, дедуплікацію й зберігання результатів.
- Вибір бізнес-об’єктів, шаблону й процес доставки.
- Політику backoff, алерти та відновлення після часткового збою.
Чеклист для робочого запуску
- Розбивайте роботу так, щоб кожен запит залишався в межах задокументованих лімітів елементів і тіла запиту.
- Генеруйте один X-Request-Id на запит і зіставляйте його з вашим job ID.
- Повторюйте лише мережеві або 5xx збої з обмеженим експоненційним backoff.
- Не повторюйте 4xx validation failures без зміни тіла запиту.
- Зберігайте PDF-результати або вихідні дані відповідно до вашої політики зберігання.
Межі заявлених можливостей
- gPdf — це render API, а не шар черги або зберігання.
- Публічний API сьогодні не публікує rate-limit headers або серверні idempotency keys.
- Ваша система має зробити retry безпечними.
Batch generation — це інтеграційний патерн
Пакетне створення PDF не є окремим маршрутом API. Це спосіб, у який ваша черга використовує публічні render API. Тримайте задачі невеликими, спостережуваними й безпечними для повторних спроб.
Для повторюваних макетів Template Render зазвичай дає найчистіший контракт. Для програмних документів із власними макетами залишається доступним JSON Render.
FAQ
- Чи надає gPdf batch job API?
- Окремий batch scheduler не виставлено. Використовуйте JSON Render або Template Render із власної черги чи worker-системи.
- Чи може Template Render приймати кілька елементів data?
- Так, у межах публічних лімітів маршруту API. Більші задачі розбивайте на окремі запити.
- Хто відповідає за retry?
- Ваша система відповідає за повторні спроби, backoff, дедуплікацію та ідемпотентність. gPdf повертає request ID для трасування.
- Чи можна рендерити багато різних макетів в одному запиті?
- Використовуйте окремі запити, коли макети або template ID відрізняються. Тримайте кожен запит простим і трасованим.