Вибір API для генерації PDF здається простим лише на початку. Постачальників багато, маркетинг звучить схоже, а справжні компроміси видно тільки після тисяч документів у production.
Цей checklist можна використовувати для оцінки vendor. Він нейтральний і базується на реальних проблемах із закупівель, експлуатації та post-mortem. Якщо немає чітких відповідей на всі вісім запитань, рішення ще передчасне.
1. Який формат входу: HTML, JSON чи template DSL?
Це головне питання. Воно визначає, що команда писатиме і що debug-итиме.
- HTML/CSS (Puppeteer, DocRaptor, Prince): знайомо, гнучко, дорого в runtime, складно зробити deterministic.
- JSON / структуровані дані (gPdf): дешево render-ити, byte-identical, але потрібен mapper до document model.
- Template DSL (PDFKit, ReportLab, Apache PDFBox): повний контроль і повна відповідальність за pagination, layout і font fallback.
Немає правильної відповіді для всіх. Є неправильна відповідь для вашої команди. Запитайте інженерів, де вони хочуть виправляти bug pagination три години.
2. Яка затримка холодного старту і чи вона передбачувана?
WASM і native binary можуть стартувати за microseconds. Chromium-based рішення можуть займати seconds. Різниця проявляється під час traffic spike.
Запитайте p99 першого request на cold worker, коли worker знову стає cold, і чи є cold-start data на status page.
3. Як рахується вартість render?
Моделі:
- Ціна за сторінку: прогнозовано, але дорого в масштабі.
- Subscription + overage: часто дешево, але треба оцінювати usage.
- Compute-based: ви платите за Lambda, containers, Chromium memory і cold start.
Порахуйте рахунок для поточного traffic, 5x і 50x. Крива вартості важливіша за headline price.
4. Чи output deterministic?
Один input має давати ті самі bytes. Це потрібно для PDF diff у CI, податкового зберігання, archive hash і legal review.
Browser-based renderers часто не deterministic між версіями Chromium. Native renderers зазвичай кращі. Запитайте, чи зміняться bytes після engine update.
5. Як обробляються fonts, CJK і RTL?
Fonts часто стають production surprise. Спочатку все працює, а після виходу на новий ринок PDF показує □□□□.
Запитайте, які scripts bundled, що буде з unknown glyph, чи можна передати custom font per request і чи є RTL shaping.
6. Які compliance profiles підтримуються?
Якщо можливі рахунки в ЄС (Factur-X / ZUGFeRD / EN 16931), архівація PDF/A, XML-вкладення або цифрові підписи, вимагайте вбудовану підтримку. “Конвертуйте потім іншим tool” означає ще один пайплайн, який доведеться підтримувати вам.
Хороші відповіді виглядають як { profile: "PDF/A-3b" } або { einvoice: { format: "factur-x", xml: "..." } }.
7. Rendering stateless? Куди йдуть документи?
Stateless rendering приймає request, повертає PDF і нічого не зберігає. Ви самі керуєте persistence. Це краще для regulated workloads.
Stateful rendering зберігає PDF у vendor і повертає signed URL. Зручно, але третя сторона має копії документів.
8. Що стається при failure?
Кожен renderer іноді падає. Перевірте structured errors, idempotent retry, оплату failed renders, status page, webhooks, p50/p99 по регіонах і synthetic probes.
Відповіді gPdf
| # | Питання | Відповідь gPdf |
|---|---|---|
| 1 | Input | JSON DocumentRequest |
| 2 | Cold start | 5-20 ms, V8 isolate, без browser |
| 3 | Cost | 0/5/8/12 на місяць; 0,00005 USD за сторінку overage |
| 4 | Determinism | Byte-identical у межах однієї engine version |
| 5 | Fonts | NotoSans CJK + Latin fallback embedded |
| 6 | Compliance | PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD |
| 7 | Stateless | Так, без document storage |
| 8 | Failure | Public status page, structured errors, idempotent |
Якщо input справді HTML і його не можна refactor, DocRaptor або Prince можуть бути кращими.
Підсумок
Не питайте “який PDF API найкращий”. Поставте ці вісім запитань і виберіть vendor під реальний workload. Для invoices, receipts і structured documents перевірте gPdf у Playground.