PDF生成APIの選定は、始めるまでは簡単に見えます。市場には多くのベンダーがあり、マーケティングページはどれも似ています。本当の違いは、本番で数千件のドキュメントを処理してから見えてきます。
これはベンダー評価にそのまま使えるチェックリストです。特定ベンダーに寄せたものではなく、調達や障害後の振り返りで実際に起きる問題から作っています。8つの質問すべてに明確な答えがなければ、まだ選ぶには早いです。
1. 入力形式はHTML、JSON、テンプレートDSLのどれか
最重要の質問です。チームが何を書くのか、そして深夜に何をデバッグするのかが決まります。
- HTML/CSS (Puppeteer, DocRaptor, Prince): 慣れていて柔軟だが、実行コストが高く、決定的な出力にしづらい。
- JSON / 構造化データ (gPdf): レンダリングが安く、byte-identicalだが、業務データから文書モデルへのmapperが必要。
- テンプレートDSL (PDFKit, ReportLab, Apache PDFBox): 完全な制御と引き換えに、ページング、レイアウト、フォントfallbackも自分で持つ。
全員に正しい答えはありません。チームに合わない答えはあります。3時間かかるpagination bugをどのモデルで直したいか、エンジニアに聞いてください。
2. Cold start latencyはいくつで、予測可能か
WASMやnative binaryはマイクロ秒単位で起動することがあります。一方、Chromiumベースは秒単位になることがあります。トラフィックが跳ねるまで差は見えにくいです。
質問すべきこと:
- cold workerへの最初のrequestのp99は?
- 最後のrequestから何分で再びcoldになる?
- cold-start dataをstatus pageに出している?
数字で答えられないなら、悪い前提で見積もるべきです。
3. Render単位のコストはどう計算されるか
よく問題になるモデルは3つです。
- ページ単価: 予測しやすいが、規模が増えると高い。
- サブスクリプション + 超過課金: 多くの量で安いが、利用量の見積もりが必要。
- Compute課金: Lambda、コンテナ、Chromiumのメモリ、cold startのコストを直接払う。
現在、5倍、50倍のトラフィックで請求額を計算してください。見出しの価格よりコスト曲線が重要です。
4. 出力はdeterministicか
同じinputから同じbytesが出るか、という話です。CIでPDF diffをする、税務保存をする、archive hashを取る、法務レビュー用に出力をversion-controlする場合に必要です。
ブラウザベースのrendererはChromiumのpatch versionをまたぐとdeterministicではないことが多いです。native rendererの方が有利です。更新時にbytesが変わるかを明確に聞きましょう。
5. Fonts、CJK、RTLをどう扱うか
PDFで最もよく事故になる領域の一つです。国内では問題なくても、CJK、Devanagari、Arabicなどが必要になると□□□□が出ることがあります。
どのscriptが追加設定なしで入っているか、未知のglyphはfallbackするか、request単位でcustom fontを渡せるか、RTL shapingがあるかを確認してください。良い答えはNotoSans CJKやfallback setを具体的に説明します。
6. どのcompliance profilesをサポートするか
EU invoice、PDF/A archive、XML添付、digital signatureが将来あり得るなら、native supportを確認してください。「後で別ツールで変換できます」は、壊れやすいpipelineを自分で持つという意味です。
良い答えは{ profile: "PDF/A-3b" }や{ einvoice: { format: "factur-x", xml: "..." } }のように見えます。
7. Renderingはstatelessか。文書はどこへ行くか
Stateless renderingはrequestを受け、PDFを返し、何も保存しません。保存はS3やDBなど自分で管理します。規制の強いworkloadでは望ましい形です。
Stateful renderingはvendorがPDFを保存し、signed URLを返します。便利ですが、第三者が全documentのcopyを持つことになります。保存場所、保持期間、stateless保証を確認しましょう。
8. 失敗時に何が起きるか
どのrendererも失敗します。重要なのは見え方です。structured 4xx/5xxか、空PDFか。retryはidempotentか。失敗renderに課金されるか。status page、webhook、region別p50/p99、synthetic probeがあるかを確認します。
gPdfの回答
| # | 質問 | gPdfの回答 |
|---|---|---|
| 1 | 入力 | JSON DocumentRequest |
| 2 | Cold start | 5-20 ms、V8 isolate、ブラウザなし |
| 3 | コスト | 月額$0/$5/$8/$12、超過$0.00005/page |
| 4 | Determinism | 同じengine versionでbyte-identical |
| 5 | Fonts | NotoSans CJK + Latin fallback内蔵 |
| 6 | Compliance | PDF/A-1b/2b/3b/4 + Factur-X / ZUGFeRD |
| 7 | Stateless | はい、document storageなし |
| 8 | Failure | public status page、structured errors、idempotent |
gPdfが負ける場面もあります。入力が本当にHTMLで、作り直せないならDocRaptorやPrinceの方が合います。
まとめ
「最高のPDF API」を探すのではなく、この8つの質問で評価してください。請求書、領収書、ラベル、構造化documentが中心なら、PlaygroundでgPdfをすぐ試せます。