開発者ワークフロー
キューとジョブ向けのバッチPDF生成API
キュー運用に適した JSON Render または Template Render のワークフローで多数の PDF を生成し、チャンク分割、リトライ、冪等性、保存は自社システム側で担います。
主 API Template Render
ENDPOINT
/api/v1/template-render 対象システム ジョブキュー / SaaS バックエンド / ERP エクスポートサービス / 課金ワーカー
解決する業務課題
キューまたはスケジュールされたジョブから多数の PDF をレンダリングします。作業を安全なリクエスト単位に分割し、各ドキュメントまたはテンプレートのデータ項目を gPdf に送り、返ってきた PDF を自社システムで保存または配信します。
この API が合う場合
- 請求書、明細書、配送ラベル、レポートを、スケジュール実行またはイベント駆動のバッチで生成する必要がある場合。
- 安定したテンプレートがあり、エンドポイントの上限内で複数のデータ項目を送れる場合。
- ブラウザワーカーを動かさずに、キューと相性のよいレンダリングが必要な場合。
- 重複排除、リトライ、出力の保存を自社で管理できる場合。
置き換えないもの
- gPdf に、バッチスケジューラ、キュー、ストレージシステム、冪等性台帳の役割を担わせたい場合。
- 公開されたレート制限ヘッダーや、サーバー側の idempotency-key インターフェイスが必要な場合。
- キャンペーン内のすべてのドキュメントを 1回の無制限リクエストでレンダリングしたい場合。
呼び出す endpoint
/api/v1/template-render
Template Render がこのワークフローの標準パスです。
/api/v1/pdf/render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/template-render - 請求書データ 2件の小さなバッチ。
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-101",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer A",
"subtotal": "$50.00",
"total": "$50.00",
"amount_due": "$50.00",
"items": []
},
{
"invoice_number": "INV-2026-102",
"date_of_issue": "2026-05-29",
"bill_to_name": "Buyer B",
"subtotal": "$75.00",
"total": "$75.00",
"amount_due": "$75.00",
"items": []
}
]
}
gPdf が担当すること
- 各 JSON Render または Template Render リクエストの PDF レンダリング。
- 文書化された公開上限内での Template Render のデータ配列。
- キューワーカーに適した、高速でステートレスなレンダリングレスポンス。
- 共通のリクエスト ID とエラーエンベロープの挙動。
自社システムが担当すること
- キュー設計、チャンク分割、並行度、リトライ、重複排除、出力の保存。
- 業務オブジェクトの選択、テンプレートの選択、配信ワークフロー。
- バックオフ方針、アラート、部分的な失敗後のリカバリ。
本番前チェックリスト
- 各リクエストが文書化された項目数とリクエストデータの上限内に収まるよう作業をチャンク分割する。
- リクエストごとに 1つの X-Request-Id を生成し、自社のジョブ ID に対応付ける。
- ネットワークまたは 5xx の失敗のみを、上限付きの指数バックオフでリトライする。
- 送信データを変えずに 4xx の検証失敗をリトライしない。
- 出力 PDF またはソースデータを、自社の保持ポリシーに従って保存する。
対応範囲の境界
- gPdf はレンダリング API であり、キューやストレージのレイヤーではありません。
- 公開 API は現時点で、レート制限ヘッダーやサーバー側の冪等性キーを公開していません。
- リトライを安全にするのは自社システムの責任です。
バッチ生成は統合パターン
バッチPDF生成は、独立したエンドポイントではありません。自社のキューが公開レンダリング API を使う方法そのものです。ジョブは小さく、追跡・監視しやすく、安全にリトライできる形に保ちます。
繰り返し使うレイアウトには、通常 Template Render が最も明確なインターフェイスになります。カスタムレイアウトをコードで生成するドキュメントには、JSON Render が引き続き利用できます。
FAQ
- gPdf はバッチジョブ API を提供していますか？
- 専用のバッチスケジューラは公開していません。自社のキューまたはワーカーシステムから JSON Render または Template Render を使います。
- Template Render は複数のデータ項目を受け取れますか？
- はい。公開エンドポイントの上限内で受け取れます。より大きなジョブは複数のリクエストに分割します。
- リトライは誰が担当しますか？
- リトライ、バックオフ、重複排除、冪等性は自社システム側で管理します。gPdf はトレーサビリティのためにリクエスト ID をエコーします。
- 1つのリクエストで多数の異なるレイアウトをレンダリングできますか？
- レイアウトやテンプレート ID が異なる場合は、リクエストを分けます。各リクエストはシンプルで追跡可能に保ちます。