PDF oluşturma API’si seçmek başlangıçta kolay görünür. Piyasada yaklaşık 40 satıcı vardır, pazarlama sayfaları birbirine benzer ve gerçek trade-off’ları ancak üretimde birkaç bin belge oluşturduktan sonra öğrenirsiniz.

Bu kontrol listesini satıcı değerlendirmesine götürebilirsiniz: satıcıdan bağımsızdır ve ekiplerin satın alma sürecinde ya da post-mortem’lerde gerçekten yaşadığı olaylardan çıkarılmıştır. Sekiz soru var; sekizinin tamamına net cevap alamıyorsanız seçim yapmak için yeterli bilginiz yoktur.

1. Girdi formatınız ne: HTML, JSON veya template DSL?

Tek başına en önemli soru budur. Cevap, ekibinizin ne yazacağını ve sabah 02:00’de neyi debug edeceğini belirler.

HTML/CSS (Puppeteer, DocRaptor, Prince): tanıdık, sonsuz esnek, runtime’da pahalı, deterministik yapmak zor.
JSON / yapılandırılmış veri (gPdf): render maliyeti düşük, byte-identical, veri modelinizden belge modeline küçük bir mapper yazmayı gerektirir.
Template DSL (PDFKit, ReportLab, Apache PDFBox): tam kontrol, tam sorumluluk; pagination, layout ve font fallback’i kendiniz yazarsınız.

Yanlış bir evrensel cevap yoktur. Ekibiniz için yanlış cevap vardır. Mühendislerinize üç saatlik bir pagination bug’ını hangi modelde debug etmeyi tercih edeceklerini sorun.

2. Cold-start latency nedir ve öngörülebilir mi?

Bazı renderer’lar microsecond içinde açılır (WASM veya native binary olan her şey). Bazıları saniyeler sürer (Chromium tabanlı olanlar). Fark, trafik spike’ı gelene kadar görünmez.

Satıcıya şunları sorun:

“Cold worker’a gelen ilk request için p99 latency’niz nedir?”
“Son request’imden ne kadar sonra worker tekrar ‘cold’ olur?”
“Cold-start verisi içeren bir status page yayınlıyor musunuz?”

İlk soruya sayıyla cevap veremiyorlarsa kötü olduğunu varsayın.

3. Render başına maliyet nasıl modelleniyor?

Sizi en sık ısıran sırayla üç model:

Sayfa başı fiyatlandırma (Anvil’de $0.10/PDF, DocRaptor'da$ 89/100K): öngörülebilir, bütçelemesi kolay, ölçekte pahalı.
Aşım ücretli abonelik katmanları (gPdf’te $5-12/ay + aşımda$ 0,00005/sayfa): her hacimde ucuz, ancak hiç test etmediğiniz kullanım için tahmin yapmak daha zordur.
Compute tabanlı fiyatlandırma (self-hosted Puppeteer on Lambda): cold-start’lar ve Chromium belleği dahil compute faturasını doğrudan siz yersiniz.

İmzadan önce gerçek faturanızı üç trafik düzeyinde hesaplayın: bugünkü hacim, 5× ve 50×. Maliyet eğrisinin şekli, başlıktaki rakamdan daha önemlidir.

4. Çıktı deterministik mi?

Determinizm, yani aynı girdi -> aynı bytes, ihtiyaç duyana kadar akademik görünür.

Şu durumlarda gerekir:

CI’da istenmeyen template değişikliklerini yakalamak için PDF diff yaparsınız.
e-invoice / vergi hukuku kapsamında belge saklarsınız; sakladığınız PDF ile yeniden render ettiğiniz PDF eşleşmelidir.
Arşiv bütünlüğü için PDF hash’i alırsınız.
Hukuk incelemesi için render edilmiş çıktıyı version-control altında tutarsınız.

Browser tabanlı renderer’lar (Puppeteer, Chromium kullanan her şey) patch sürümleri arasında deterministik DEĞİLDİR. Native binary renderer’lar (Prince, gPdf) genelde öyledir. Açıkça sorun: “Bir renderer update yayınlarsanız çıktı bytes değişir mi?”

5. Renderer fontları, özellikle CJK ve RTL’i nasıl ele alıyor?

PDF dünyasında kariyerlere en çok mal olan soru budur.

Failure mode tutarlıdır: kendi pazarınızda launch edersiniz, fontlar sorunsuzdur. Altı ay sonra renderer’ınızda glyph bulunmayan bir script kullanan pazara açılırsınız. PDF ▢▢▢▢ kutuları üretmeye başlar. Müşteri escalates. Ekibiniz iki sprint boyunca Dockerfile’a font ekler.

Sorulacak sorular:

“Hangi script’ler ek config olmadan bundled geliyor? (Latin, CJK, Cyrillic, Devanagari, Arabic, Hebrew?)”
“Bilinmeyen glyph ile karşılaşınca ne olur: fallback mi, tofu mu?”
“Request zamanında custom font ekleyebilir miyim, yoksa önceden deploy etmem mi gerekir?”
“RTL text shaping destekliyor musunuz?”

İyi cevap: “NotoSans CJK ve Noto fallback set’i embed ediyoruz; bilinmeyen glyph’ler Noto Symbols’a düşer.” Kötü cevap: “Evet, font destekliyoruz.”

6. Hangi compliance profilleri destekleniyor?

İşiniz ileride muhtemelen şunlardan birini yapacaksa:

AB’de invoice kesmek (Factur-X / ZUGFeRD / EN 16931, 2026’ya kadar DE/FR/IT/PL’de zorunlu)
SOX, HIPAA veya GDPR retention kuralları altında belge arşivlemek (PDF/A)
Medical record göndermek (XML attachment içeren PDF/A-3)
Digital signature embed etmek (PAdES)

…o zaman renderer’ın hangi compliance profillerini native desteklediğini sorun. Kötü cevap: “Sonradan dönüştürmek için başka bir tool çalıştırabilirsiniz.” Bu, artık sizin sahip olduğunuz çok adımlı bir pipeline demektir.

İyi cevaplar genelde tek flag gibi görünür; örneğin gPdf settings.profile: "pdfa-3b" ve standard: "factur_x" içeren embedded CII XML’li bir settings.e_invoice block alır. Built-in olmak, bolt-on’a göre dramatik biçimde daha az ops yüküdür.

7. Rendering stateless mi? Belgelerim render sonrası nereye gidiyor?

İki bağlantılı soru.

Stateless rendering, request gelir, PDF çıkar, hiçbir şey saklanmaz demektir. Persistence’ı siz yönetirsiniz (S3, kendi DB’niz, ne kullanıyorsanız). Compliance yoğun iş yükleri için istediğiniz model budur; renderer verinizin custodian’ı olmaz.

Stateful rendering, satıcının PDF’i saklaması (çoğu zaman kendi CDN’inde) ve size signed URL vermesi demektir. Casual workflow’lar için kullanışlıdır (örneğin “müşteriye link gönder”), ancak regulated workflow’lar için problemlidir: artık her render ettiğiniz belgenin bir kopyasına sahip üçüncü taraf vardır.

Sorun:

“Rendering default olarak stateless mı?”
“Eğer saklıyorsanız belge coğrafi olarak nerede saklanıyor?”
“Ne kadar süre tutuluyor?”
“Compliance review için stateless rendering garantisini yazılı alabilir miyim?”

Cevap belirsizse privacy/legal ekibiniz bunu 9 ay sonra issue yapacaktır.

8. Renderer fail ederse ne olur ve bunu nasıl öğrenirim?

Her renderer bazen fail eder. Sorular şunlardır:

Failure nasıl yüzeye çıkar? Stack trace içeren 500 mü? Structured error içeren 4xx mi? Boş PDF mi?
Retry policy nedir? Idempotent mi? Failed render için ücret alınır mı?
Satıcı hangi instrumentation’ı sağlar? Status page? Incident webhook’ları? Region bazında p50/p99 dashboard’ları?
Synthetic probe var mı? Satıcı public endpoint’e karşı kendi monitoring’ini çalıştırıyor mu, yoksa ticket açmanızı mı bekliyor?

Hızlı test: satıcının status page’ini şu anda ziyaret edin. Yoksa, real-time değilse veya detay vermeden “all systems operational” diyorsa, satın alma sonrası alacağınız reliability transparency seviyesi budur.

(Referans için: gPdf /status sayfasında trailing 7 gün için synthetic probe verisi + Cloudflare Analytics yayınlar.)

Sekiz soruda gPdf’in durumu

Bu bizim blog’umuz olduğu ve soruları kendimize göre eğdiğimizden şüpheleneceğiniz için dürüst scorecard:

#	Soru	gPdf yanıtı
1	Girdi formatı	JSON `DocumentRequest` (structured data)
2	Cold start	5-20 ms (V8 isolate, browser yok)
3	Maliyet modeli	Ayda $0/$ 5/ $8/$ 12; aşımda $0,00005/sayfa
4	Determinizm	Byte-identical, aynı engine version içinde garantili
5	Fontlar	NotoSans CJK + Latin fallback embedded
6	Compliance	PDF/A-1b/2b/3b/4 + built-in Factur-X / ZUGFeRD attachment
7	Stateless	Evet, contractually; hiçbir yerde document storage yok
8	Failure & visibility	7 günlük trend içeren public status page; structured 4xx/5xx; idempotent

Kaybettiğimiz yer: Q1. Input’unuz gerçekten refactor edemeyeceğiniz HTML ise (örneğin user-generated reports, legacy templates), doğru cevap DocRaptor veya Prince’tir.

TL;DR

“En iyi PDF API hangisi?” diye sormayın. Sekiz soruyu sorun, cevapları puanlayın ve gerçek iş yükünüze uyan satıcıyı seçin. Dokuz ay sonra #5 numaralı soruyla gafil avlandığı için biraz daha ucuz rakibe procurement kaybeden ekip de size aynı şeyi söyleyecektir.

Workload’unuz gPdf’in inşa edildiği modele uyuyorsa, Playground değerlendirme için 30 saniye sürer. Uymuyorsa sizi memnuniyetle doğru araca yönlendiririz: HTML-shaped problemler için genellikle DocRaptor, self-hosted için Prince veya input’unuz gerçekten rastgele web sayfalarıysa Puppeteer.