Выбор API для генерации PDF кажется простым только до начала работы. На рынке десятки поставщиков, маркетинг звучит одинаково, а настоящие компромиссы видны лишь после тысяч документов в продакшене.

Этот чеклист можно использовать при оценке поставщиков. Он не привязан к конкретному вендору и основан на реальных инцидентах закупки, эксплуатации и post-mortem. Если нет ясных ответов на все восемь вопросов, информации для выбора недостаточно.

1. Какой формат входа: HTML, JSON или шаблонный DSL?

Это главный вопрос. Он определяет, что ваша команда будет писать и что будет отлаживать в два часа ночи.

HTML/CSS (Puppeteer, DocRaptor, Prince): знакомо, очень гибко, дорого в runtime и сложно сделать детерминированным.
JSON / структурированные данные (gPdf): дешево рендерить, одинаковые байты на выходе, но нужен mapper из бизнес-модели в модель документа.
Template DSL (PDFKit, ReportLab, Apache PDFBox): полный контроль и полная ответственность за пагинацию, layout и fallback шрифтов.

Правильного ответа для всех нет. Есть неправильный ответ для вашей команды. Спросите инженеров, где они предпочли бы искать трехчасовой баг пагинации.

2. Какова cold-start latency и предсказуема ли она?

Некоторые рендереры стартуют за микросекунды, особенно WASM и native binary. Chromium-based решения могут занимать секунды. Разница проявляется на пиках трафика.

Спросите:

“Какой p99 у первого запроса на холодный worker?”
“Через сколько после последнего запроса worker снова становится cold?”
“Публикуете ли вы cold-start data на status page?”

Если нет численного ответа, считайте это плохим знаком.

3. Как считается стоимость одного render?

Три модели чаще всего кусаются:

Цена за страницу: предсказуемо, просто бюджетировать, дорого на масштабе.
Подписка с overage: дешево при многих объемах, но надо хорошо оценивать usage.
Compute-based pricing: вы напрямую платите за Lambda, контейнеры, память Chromium и cold starts.

Посчитайте счет при текущем трафике, 5x и 50x. Форма кривой важнее рекламной цены.

4. Детерминирован ли результат?

Одинаковый input должен давать одинаковые bytes. Это нужно для PDF diff в CI, налогового хранения, архивных hash и юридического review.

Browser-based рендереры обычно не детерминированы между версиями Chromium. Native renderers чаще лучше. Спросите прямо: “Изменятся ли мои bytes после обновления движка?”

5. Как обрабатываются шрифты, CJK и RTL?

Шрифты часто становятся production-инцидентом. В домашнем рынке все хорошо, потом появляется новый script и PDF показывает □□□□.

Спросите, какие scripts встроены без настройки, что будет с неизвестным glyph, можно ли передать custom fonts в запросе, и поддерживается ли RTL shaping. Хороший ответ говорит о NotoSans CJK и понятном fallback.

6. Какие compliance profiles поддерживаются?

Если возможны счета в ЕС, архивирование PDF/A, XML-вложения или цифровые подписи, спрашивайте native support. “Потом конвертируйте другой утилитой” означает pipeline, который теперь обслуживаете вы.

Хороший ответ похож на флаг: { profile: "PDF/A-3b" } или { einvoice: { format: "factur-x", xml: "..." } }.

7. Rendering stateless? Куда попадают документы?

Stateless rendering принимает запрос, возвращает PDF и ничего не хранит. Вы сами управляете persistence. Это лучший вариант для regulated workloads.

Stateful rendering сохраняет PDF у поставщика и возвращает signed URL. Удобно, но третья сторона получает копию каждого документа.

Спросите, где хранится файл, как долго и можно ли получить письменную гарантию stateless rendering.

8. Что происходит при сбое?

Любой renderer иногда падает. Важно, как именно.

Структурированный 4xx/5xx или пустой PDF?
Retry idempotent?
Берется ли плата за failed render?
Есть ли status page, webhooks, p50/p99 по регионам?
Запускает ли vendor synthetic probes?

Откройте status page прямо сейчас. Если там нет деталей, такой будет и прозрачность после покупки.

Ответы gPdf

#	Вопрос	Ответ gPdf
1	Input	JSON `DocumentRequest`
2	Cold start	5-20 ms, V8 isolate, без браузера
3	Cost	$0/$5/$8/$12 в месяц; $0.00005/page overage
4	Determinism	Byte-identical в рамках одной версии движка
5	Fonts	NotoSans CJK + Latin fallback встроены
6	Compliance	PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD
7	Stateless	Да, без хранения документов
8	Failure	Public status page, structured errors, idempotent

Где gPdf не лучший выбор: если input действительно HTML и его нельзя менять, лучше подойдут DocRaptor или Prince.

Итог

Не спрашивайте “какой PDF API лучший”. Задайте эти восемь вопросов, оцените ответы и выберите поставщика под свою реальную нагрузку. Для счетов, чеков и структурированных документов gPdf можно быстро проверить в Playground.