構造化ドキュメント生成向け JSON-to-PDF API
ページ、座標、テキスト、表、バーコード、メタデータ、PDF/A 設定を含む、構造化された JSON DocumentRequest のリクエストデータを PDF に変換します。
/api/v1/pdf/render 構造化されたアプリケーションデータを、ブラウザを動かさず、HTML/CSS を送らず、顧客ファイルを保存せずに、再現性のある PDF ドキュメントへ変換します。自社システムはページ、要素、座標、settings、業務コンテンツを送り、gPdf は application/pdf レスポンスを返します。
この API が合う場合
- バックエンドにすでに構造化データがあり、PDF レスポンスが必要な場合。
- HTML レイアウトではなく、ページ、座標、要素、バーコード、settings を明示して扱いたい場合。
- 請求書、ラベル、レポート、明細書、生成された文書一式など、再現性のある出力が必要な場合。
- 本番環境にトークンを入れる前に、Playground でリクエストデータをテストしたい場合。
置き換えないもの
- 任意の HTMLからPDF 変換が必要な場合。gPdf はブラウザ DOM ではなく DocumentRequest JSON を使います。
- 安定した template_id のインターフェイスが必要な場合。レイアウトを公開したあとは Template Render を使います。
- Factur-X または ZUGFeRD の電子請求書パッケージングが必要な場合。E-Invoice Render エンドポイントを使います。
呼び出す endpoint
/api/v1/pdf/render
JSON Render がこのワークフローの標準パスです。
/api/v1/template-render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/pdf/render - 1ページの JSON DocumentRequest。
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Hello from gPdf",
"style": {
"font_size": 18,
"font_family": "NotoSans-Regular"
}
}
]
}
]
}
gPdf が担当すること
- ページと要素からの DocumentRequest レンダリング。
- テキスト、表、画像、ベクターバーコード、線、図形、透かし、メタデータ、PDF/A 設定。
- Latin、CJK、絵文字対応、その他の対応スクリプトのフォント埋め込みとフォールバック。
- バイナリ PDF レスポンス。失敗時は共通の gPdf エラーコードエンベロープを返します。
自社システムが担当すること
- 業務データ、フィールドマッピング、文書上の意味づけ。
- リクエスト ID、リトライと冪等性の戦略、ファイル名、レスポンス受領後の保存。
- レンダリング前の税務、請求書、配送業者、コンプライアンス、顧客固有のルール。
本番前チェックリスト
- トレーサビリティのために X-Request-Id を生成して渡す。
- 本番トラフィックを流す前に、OpenAPI またはドキュメントに対して送信データを検証する。
- API ベース URL を設定可能にし、bearer token はソースコードの外に保管する。
- 出力を inline モードにするか attachment モードにするかを決める。
- 重要なレイアウトには golden-PDF テストを追加し、テンプレートやデータの変更が見えるようにする。
対応範囲の境界
- これは HTMLからPDF ではなく、Chromium を動かしません。
- API は記述されたドキュメントをレンダリングします。データから法的・業務的な意味を推定することはありません。
- 繰り返し使うレイアウトでは、通常 Template Render のほうが適切な公開インターフェイスです。
JSON Render ワークフローの位置づけ
JSON Render は、公開されているレンダリング経路の中で最も低レベルなものです。アプリケーションは、ページサイズ、要素、座標、スタイル、メタデータ、出力モード、任意の PDF/A 設定といったドキュメント構造を直接送ります。ドキュメントレイアウトをコードで生成する場合や、チームが PDF をピクセル単位で制御したい場合に適したレイヤーです。
API のインターフェイスは明示的です。システムがテキスト要素を送れば、gPdf はテキスト要素をレンダリングします。バーコード要素を送れば、gPdf はバーコードをベクター PDF コンテンツとして描画します。gPdf はリクエストデータから業務上の意図を読み取らず、請求書番号、配送業者の追跡値、税フィールドが正しいかどうかを判断しません。
いつ Template Render に切り替えるか
同じレイアウトを複数のシステムで繰り返し使うなら、それをテンプレートとして公開し、POST /api/v1/template-render を template_id と data[] で呼び出します。これにより、各呼び出し側がレイアウトを管理する必要がなくなり、ERP、OMS、WMS、SaaS バックエンドに安定したフィールドインターフェイスを提供できます。
レイアウトの作成、一度きりのドキュメント、プログラムで生成するドキュメントには JSON Render を使います。レイアウトが固定され、リクエストごとに変わるのが業務データだけになったら Template Render を使います。
本番での形
本番では、PDF リクエストを他の重要な API 呼び出しと同じように扱います。リクエスト ID を含め、タイムアウトを設定し、リトライを冪等にし、レスポンスのメタデータをログに記録し、保持が必要な場合のみ返ってきた PDF を自社システムに保存します。gPdf のレンダリングパスは、標準的なレンダリングレスポンスのあとはステートレスです。
FAQ
- これは HTMLからPDF API ですか？
- いいえ。gPdf はページ、要素、座標、settings を持つ構造化 JSON DocumentRequest を受け取ります。ブラウザを動かしたり、任意の HTML/CSS を実行したりはしません。
- 最初にどのエンドポイントを呼ぶべきですか？
- レイアウトを直接制御したいときは POST /api/v1/pdf/render から始めます。レイアウトを安定した template_id のインターフェイスにすべき段階になったら POST /api/v1/template-render へ移ります。
- API は PDF を直接返しますか？
- はい。レンダリングが成功すると application/pdf を返します。エラーは API-XXX コードと req_id を含む共通 JSON エラーエンベロープを使います。
- 統合を作らずにテストできますか？
- gPdf Playground で JSON リクエストデータを対話的にテストしてから、同じ DocumentRequest の形をバックエンドクライアントへ移します。