Wybór API generowania PDF wygląda prosto tylko do momentu, gdy zaczynasz porównanie. Na rynku jest około 40 dostawców, strony marketingowe brzmią podobnie, a realne kompromisy poznasz dopiero po kilku tysiącach dokumentów w produkcji.

To lista kontrolna, którą możesz zabrać na ocenę dostawców — neutralna wobec sprzedawców, oparta na faktycznych incydentach, które zespoły spotykają przy zakupach i pośmiertnych analizach problemów. Osiem pytań; jeśli nie dostajesz jasnej odpowiedzi na każde z nich, nie masz jeszcze wystarczających danych do wyboru.

1. Jaki jest format wejściowy — HTML, JSON czy DSL szablonów?

To najważniejsze pytanie. Odpowiedź określa, co zespół będzie pisał — i co będzie debugował o 2:00 w nocy.

HTML/CSS (Puppeteer, DocRaptor, Prince): znane, niemal nieskończenie elastyczne, kosztowne w czasie wykonania, trudne do ułożenia w deterministyczny wynik.
JSON / dane strukturalne (gPdf): tanie w renderowaniu, bajtowo identyczne, wymagają napisania małego mapera z modelu danych do modelu dokumentu.
DSL szablonów (PDFKit, ReportLab, Apache PDFBox): pełna kontrola i pełna odpowiedzialność — samodzielnie piszesz paginację, układ i fallback fontów.

Nie ma jednej złej odpowiedzi. Jest zła odpowiedź dla Twojego zespołu. Zapytaj inżynierów, w którym modelu woleliby debugować trzygodzinny błąd paginacji.

2. Jaka jest latencja cold start — i czy jest przewidywalna?

Niektóre silniki renderowania startują w mikrosekundach: wszystko, co jest WASM albo natywnym binarium. Inne startują w sekundach: rozwiązania oparte na Chromium. Różnica jest niewidoczna do pierwszego skoku ruchu.

O co pytać dostawcę:

“Jaka jest Wasza latencja p99 dla pierwszego żądania do zimnego workera?”
“Po jakim czasie od ostatniego żądania worker znów staje się zimny?”
“Czy publikujecie stronę statusu z danymi o cold start?”

Jeśli nie potrafią odpowiedzieć na pierwsze pytanie liczbą, załóż, że wynik jest słaby.

3. Jak modelowany jest koszt pojedynczego renderowania?

Trzy warianty, w kolejności, w jakiej najczęściej zaskakują zespoły:

Cena za stronę (Anvil za 0,10 USD/PDF, DocRaptor za 89 USD/100 000): przewidywalna, łatwa do budżetowania, droga w skali.
Progi subskrypcyjne z nadwyżką (gPdf za 5-12 USD/mies. + 0,00005 USD za stronę nadwyżki): tanie przy dowolnym wolumenie, trudniejsze do prognozowania dla użycia, którego jeszcze nie testowałeś.
Cena oparta na compute (self-hosted Puppeteer na Lambda): bezpośrednio ponosisz rachunek za compute, w tym cold start i pamięć Chromium.

Policz RZECZYWISTY rachunek na trzech poziomach ruchu: obecnym, 5× i 50× przed podpisaniem umowy. Kształt krzywej kosztu jest ważniejszy niż liczba na stronie z cennikiem.

4. Czy wynik jest deterministyczny?

Determinizm — ten sam input → te same bajty — brzmi akademicko do momentu, gdy go potrzebujesz.

Potrzebujesz go, gdy:

porównujesz PDF w CI, aby wykrywać niezamierzone zmiany szablonu,
przechowujesz dokumenty na potrzeby e-faktur albo prawa podatkowego: PDF, który zapisujesz, i PDF renderowany ponownie muszą się zgadzać,
haszujesz PDF dla integralności archiwum,
wersjonujesz wyrenderowany wynik do przeglądu prawnego.

Silniki oparte na przeglądarce (Puppeteer, wszystko na Chromium) NIE są deterministyczne między wersjami poprawek. Natywne silniki binarne (Prince, gPdf) zwykle są. Zapytaj wprost: “Czy bajty wyjściowe zmienią się, gdy opublikujecie aktualizację silnika renderowania?”.

5. Jak silnik obsługuje fonty, szczególnie CJK i RTL?

To pytanie kosztowało w świecie PDF więcej karier niż jakiekolwiek inne.

Tryb awarii jest powtarzalny: startujesz na rynku macierzystym, fonty działają. Sześć miesięcy później wchodzisz na rynek z pismem, dla którego silnik nie ma glifów. PDF zaczyna emitować pola ▢▢▢▢. Klient eskaluje. Zespół spędza dwa sprinty na dodawaniu fontów do Dockerfile.

Pytania do zadania:

“Które systemy pisma są wbudowane bez dodatkowej konfiguracji? Latin, CJK, Cyrillic, Devanagari, Arabic, Hebrew?”
“Co dzieje się przy nieznanym glifie — fallback czy tofu?”
“Czy mogę dodać własne fonty w czasie żądania, czy muszę wdrożyć je wcześniej?”
“Czy obsługujecie skład tekstu RTL?”

Dobra odpowiedź: “Osadzamy NotoSans CJK i zestaw fallbacków Noto; nieznane glify przechodzą do Noto Symbols”. Zła odpowiedź: “Tak, obsługujemy fonty”.

6. Jakie profile zgodności są obsługiwane?

Jeśli Twoja firma kiedykolwiek może:

wystawiać faktury w UE (Factur-X / ZUGFeRD / EN 16931, obowiązkowe w DE/FR/IT/PL do 2026 r.),
archiwizować dokumenty według reguł retencji SOX, HIPAA albo GDPR (PDF/A),
przekazywać dokumentację medyczną (PDF/A-3 z dołączonym XML),
osadzać podpisy cyfrowe (PAdES),

…zapytaj, które profile zgodności silnik renderowania obsługuje natywnie. Zła odpowiedź brzmi: “możesz potem uruchomić inne narzędzie do konwersji”. To wielostopniowy pipeline, za który od teraz odpowiadasz.

Dobre odpowiedzi zwykle wyglądają jak pojedyncza flaga — na przykład gPdf przyjmuje settings.profile: "pdfa-3b" oraz blok settings.e_invoice z standard: "factur_x" i osadzonym CII XML. Funkcja wbudowana oznacza znacznie mniej pracy operacyjnej niż dokładanie jej po renderowaniu.

7. Czy renderowanie jest bezstanowe? Gdzie trafiają dokumenty po renderowaniu?

To dwa powiązane pytania.

Renderowanie bezstanowe oznacza, że żądanie przychodzi, PDF jest emitowany, nic nie jest zapisywane. Trwałość obsługujesz samodzielnie: S3, własna baza albo inny magazyn. Tego chcesz przy obciążeniach mocno regulowanych — silnik renderowania nigdy nie staje się depozytariuszem Twoich danych.

Renderowanie stanowe oznacza, że dostawca zapisuje PDF, często na własnym CDN, i daje Ci podpisany URL. Wygodne przy luźniejszych procesach, na przykład “wyślij klientowi link”, problematyczne przy procesach regulowanych, bo trzeci podmiot ma kopię każdego dokumentu, który kiedykolwiek wyrenderowałeś.

Zapytaj:

“Czy renderowanie jest bezstanowe domyślnie?”
“Gdzie geograficznie dokument jest przechowywany, jeśli go przechowujecie?”
“Jak długo jest retencjonowany?”
“Czy mogę dostać pisemną gwarancję bezstanowego renderowania do przeglądu zgodności?”

Jeśli odpowiedź jest mglista, zespół prywatności albo prawny zrobi z tego problem za 9 miesięcy.

8. Co dzieje się, gdy silnik renderowania zawiedzie — i jak się o tym dowiaduję?

Każdy silnik renderowania czasem zawodzi. Pytania brzmią:

Jak awaria wychodzi na powierzchnię? 500 ze stack trace? 4xx ze strukturalnym błędem? Pusty PDF?
Jaka jest polityka ponawiania? Czy jest idempotentna? Czy płacisz za nieudane renderowania?
Jaką telemetrię daje dostawca? Strona statusu? Webhooki dla incydentów? Dashboardy p50/p99 według regionu?
Czy istnieje sonda syntetyczna — czy dostawca monitoruje własny publiczny punkt końcowy, czy czeka, aż Ty zgłosisz ticket?

Szybki test: odwiedź stronę statusu dostawcy teraz. Jeśli nie istnieje, nie jest real-time albo pokazuje “all systems operational” bez szczegółów, taki poziom transparentności niezawodności dostaniesz po zakupie.

(Dla odniesienia: gPdf publikuje /status z danymi sond syntetycznych i Cloudflare Analytics z ostatnich 7 dni).

Jak gPdf wypada w tych ośmiu pytaniach

Ponieważ to nasz blog i możesz podejrzewać, że dobraliśmy pytania pod siebie, poniżej uczciwa karta wyników:

#	Pytanie	Odpowiedź gPdf
1	Format wejściowy	JSON `DocumentRequest` (dane strukturalne)
2	Cold start	5-20 ms (izolat V8, bez przeglądarki)
3	Model kosztu	0/5/8/12 USD miesięcznie; 0,00005 USD za stronę nadwyżki
4	Determinizm	Bajtowo identyczny wynik, gwarantowany w tej samej wersji silnika
5	Fonty	Osadzone NotoSans CJK + fallback Latin
6	Zgodność	PDF/A-1b/2b/3b/4 + wbudowany załącznik Factur-X / ZUGFeRD
7	Bezstanowość	Tak, kontraktowo — bez przechowywania dokumentów gdziekolwiek
8	Awaria i widoczność	Publiczna strona statusu z trendem 7-dniowym; strukturalne 4xx/5xx; idempotencja

Gdzie przegrywamy: Q1, jeśli wejściem jest naprawdę HTML, którego nie możesz zrefaktoryzować, na przykład raporty generowane przez użytkowników albo stare szablony. Wtedy DocRaptor albo Prince są właściwą odpowiedzią.

TL;DR

Nie pytaj “które API PDF jest najlepsze”. Zadaj osiem pytań, oceń odpowiedzi i wybierz dostawcę, który pasuje do faktycznego obciążenia. Zespół, który przegrał zakup na rzecz trochę tańszego rywala, a dziewięć miesięcy później został zaskoczony pytaniem #5, powie Ci to samo.

Jeśli Twoje obciążenie pasuje do tego, jak zbudowano gPdf, Playground pozwala ocenić to w 30 sekund. Jeśli nie pasuje, bez problemu wskażemy właściwe narzędzie — zwykle DocRaptor dla problemów w kształcie HTML, Prince dla self-hostingu albo Puppeteer, gdy wejście to naprawdę dowolne strony webowe.