開発者ワークフロー
安定した文書連携インターフェイス向けのテンプレートPDF API
繰り返し使うレイアウトを一か所で管理し、ERP、OMS、WMS、SaaS の呼び出し側から再利用する場合に、安定した template_id とデータ配列から PDF をレンダリングします。
主 API Template Render
ENDPOINT
/api/v1/template-render 対象システム SaaS バックエンド / ERP 連携 / OMS / WMS / ジョブキュー
解決する業務課題
各リクエストで呼び出し側にページ、座標、レイアウト要素を記述させる代わりに、安定した template_id と業務データ配列を送って、繰り返し使う PDF をレンダリングします。
この API が合う場合
- ドキュメントレイアウトが承認済みで、複数の呼び出し側やジョブから再利用される場合。
- 呼び出し側が、座標レベルのレイアウト JSON ではなく業務データを送るべき場合。
- 請求書、梱包明細、配送ラベル、またはカスタムテンプレートの出力が必要な場合。
- 有効なテンプレートのリビジョンを、呼び出し側の外側で管理したい場合。
置き換えないもの
- まだレイアウトを設計中の場合。座標とフィールドが安定するまでは JSON Render を使います。
- 任意の HTMLからPDF 変換が必要な場合。
- CII XML を埋め込む電子請求書の PDF/A-3b パッケージングが必要な場合。
呼び出す endpoint
/api/v1/template-render
Template Render がこのワークフローの標準パスです。
/api/v1/pdf/render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/template-render - テンプレートから請求書を 1件レンダリング。
{
"template_id": "invoice",
"data": [
{
"invoice_number": "INV-2026-001",
"date_of_issue": "2026-05-29",
"date_due": "2026-06-28",
"issuer_name": "Acme Cloud Inc.",
"issuer_address": "88 Harbor Rd, Long Beach, CA",
"bill_to_name": "Receiver Inc.",
"bill_to_address": "123 Main St, Los Angeles, CA",
"subtotal": "$100.00",
"total": "$100.00",
"amount_due": "$100.00",
"items": [
{
"description": "Service A",
"qty": 1,
"unit_price": "$100.00",
"amount": "$100.00"
}
]
}
]
}
gPdf が担当すること
- 安定した template_id によるテンプレートの参照。
- 各データ項目を有効なテンプレートに対してレンダリング。
- 公開エンドポイントの上限内で、レンダリング済みページを 1つの PDF に連結。
- 共通の認証、リクエスト ID、エラーエンベロープの挙動。
自社システムが担当すること
- テンプレートの選択、フィールドマッピング、業務データ、呼び出し側の認可。
- テンプレートの公開ワークフロー、変更の周知、テストカバレッジ。
- 多数のドキュメントをレンダリングする際のチャンク分割、キューイング、リトライ。
本番前チェックリスト
- template_id は中身を解釈せず、安定した呼び出し側向け ID として扱う。
- Template Render を呼ぶ前にデータフィールドを検証する。
- 有効なテンプレートと代表的なデータに対する golden-PDF テストを維持する。
- 大きなバッチは、公開された Template Render の上限に従って分割する。
- トレーサビリティのために template_id、リクエスト ID、業務オブジェクト ID をログに記録する。
対応範囲の境界
- Template Render はそれ単体では設計ツールではありません。テンプレートはあらかじめ公開されている必要があります。
- gPdf は、テンプレートから不足している業務データを推定しません。
- Template Render は E-Invoice Render エンドポイントを置き換えるものではありません。
Template Render は本番のインターフェイス層
JSON Render は、レイアウトを設計している間に向いています。Template Render は、レイアウト仕様が固まったあとに使うレイヤーです。呼び出し側は template_id とデータを送り、有効なテンプレートがドキュメント構造を担います。
これにより呼び出し側を小さく保てるため、テンプレート変更のレビュー、テスト、ロールアウトがしやすくなります。
FAQ
- JSON Render ではなく Template Render を使うべきなのはいつですか？
- レイアウトが承認され、呼び出し側が業務データだけを送ればよくなったあとに Template Render を使います。
- template_id は安定していますか？
- はい。テンプレート API のドキュメントでは、template_id は呼び出し側に向けた安定した識別子と説明されています。
- 1つのリクエストで複数のデータ項目をレンダリングできますか？
- はい。Template Render は公開エンドポイントの上限内でデータ配列を受け取ります。
- Template Render で電子請求書を作れますか？
- いいえ。Factur-X と ZUGFeRD の PDF/A-3b パッケージングには E-Invoice Render エンドポイントを使います。