請求・財務システム向けの請求書PDF API
JSON Render または Template Render で請求データから通常の請求書PDFを生成しつつ、税務と会計のロジックは自社システム側に置いたままにします。
/api/v1/pdf/render 請求、ERP、SaaS システムの請求書データを人が読める請求書PDFに変換しつつ、採番、税計算、支払い状態、会計上の意味づけは呼び出し側システムの内側に保ちます。
この API が合う場合
- 顧客向けの通常の請求書PDF、領収書、明細書、会計エクスポートが必要な場合。
- 自社システム側で、すでに請求書番号、税計算、明細項目、支払い状態を管理している場合。
- ブラウザを動かさずに、表、合計、メタデータ、任意の PDF/A 設定がほしい場合。
- 繰り返し使う請求書レイアウトに、安定した template_id のインターフェイスが必要な場合。
置き換えないもの
- Factur-X や ZUGFeRD のような法的な電子請求書パッケージが必要な場合。E-Invoice Render を使います。
- gPdf に税計算、会計ルールの検証、支払いの消込を期待する場合。
- 構造化 JSON やテンプレートではなく、任意の HTML 請求書変換が必要な場合。
呼び出す endpoint
/api/v1/pdf/render
JSON Render がこのワークフローの標準パスです。
/api/v1/template-render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
/api/v1/e-invoice/render
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/pdf/render - 請求書のヘッダーと合計の最小例。
{
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 18, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 20,
"y": 42,
"content": "Bill to: Example Customer\nAmount due: USD 245.00",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "line",
"x1": 20,
"y1": 62,
"x2": 190,
"y2": 62
}
]
}
]
}
gPdf が担当すること
- JSON ページまたはテンプレートデータからの請求書PDFレンダリング。
- テキスト、表、合計ブロック、ページ分割、メタデータ、任意の PDF/A 出力。
- 複数システムで使われる安定した請求書レイアウト向けの Template Render。
- バイナリ PDF レスポンスと一貫した API エラーエンベロープ。
自社システムが担当すること
- 請求書番号、支払い状態、税計算、割引、クレジット、台帳上の意味。
- 顧客と発行者のデータ、明細項目のマッピング、通貨、丸めルール。
- 保持、配信、メール、支払いリンク、会計システムとの消込。
本番前チェックリスト
- 表示されるすべての請求書フィールドが、ソースの請求データに対応していることを確認する。
- 明細項目のあふれ、長い顧客名、複数ページの請求書、合計をテストする。
- そのレイアウトが JSON Render に属するか、公開テンプレートに属するかを決める。
- 通常の請求書PDF生成を、法的な電子請求書パッケージングと分けて保つ。
- リクエスト ID と出力ファイル名を、自社の請求書レコードとともに保存する。
対応範囲の境界
- 通常の請求書PDFは、法的な電子請求書要件と同じではありません。
- gPdf は請求書ドキュメントをレンダリングします。税額や会計状態を計算することはありません。
- Factur-X / ZUGFeRD の出力は POST /api/v1/e-invoice/render で扱います。
通常の請求書と電子請求書
通常の請求書PDFは、顧客が読むドキュメントです。JSON Render または Template Render から生成できます。自社システムが請求書番号、税、明細項目、通貨、支払い状態を決め、そのうえで gPdf が表示用の PDF をレンダリングします。
法的な電子請求書は別物です。Factur-X と ZUGFeRD は、人が読める PDF/A-3b の請求書と、埋め込まれた EN 16931 CII XML を組み合わせます。そのパッケージには POST /api/v1/e-invoice/render を使います。
通常は Template Render が本番向きのエンドポイント
財務チームが、すべてのサービスに請求書の座標を作り直させたいことはまずありません。一般的な運用は、請求書を一度設計してテンプレートとして公開し、呼び出し側には安定した template_id とデータスキーマを渡す形です。JSON Render は、カスタムレイアウト、社内ツール、テンプレートの試作に引き続き役立ちます。
会計ロジックは上流に保つ
gPdf は、未解決の会計判断ではなく、最終的な表示値を受け取るべきです。税、割引、丸め、支払い状態、請求書の発行可否は、レンダリング API を呼ぶ前に計算します。これにより PDF 出力は再現性を持ち、財務システムが信頼できる情報源であり続けます。
FAQ
- 請求書PDFは電子請求書と同じですか？
- いいえ。通常の請求書PDFは人が読む出力です。Factur-X や ZUGFeRD の電子請求書は、さらに EN 16931 CII XML を PDF/A-3b ラッパーの中に埋め込みます。
- 繰り返し使う請求書はどのエンドポイントを使うべきですか？
- 請求書レイアウトが安定し、呼び出し側が template_id とデータだけを送ればよいときは Template Render を使います。コード側でレイアウトを管理するときは JSON Render を使います。
- gPdf は税を計算しますか？
- いいえ。税、合計、割引、支払い状態は、レンダリングデータを送る前に自社の請求または会計システムが計算します。
- 請求書PDFで PDF/A を使えますか？
- はい。JSON Render は PDF/A 設定をサポートします。請求書を Factur-X や ZUGFeRD としてパッケージする必要がある場合は、E-Invoice Render を使います。