Factur-X / ZUGFeRD PDF/A-3b 向け電子請求書 API
公開 gPdf 電子請求書エンドポイントを使って、EN 16931 CII XML を埋め込んだ Factur-X と ZUGFeRD の PDF/A-3b 電子請求書を生成します。
/api/v1/e-invoice/render 人が読める請求書PDFと、呼び出し側が提供する EN 16931 CII XML を、外部の PDF/A 検証エンジンと電子請求書参照エンジンで検証できる Factur-X または ZUGFeRD の PDF/A-3b 電子請求書としてパッケージします。
この API が合う場合
- 通常の請求書PDFだけでなく、Factur-X または ZUGFeRD の出力が必要な場合。
- 自社システムが請求書向けの正しい EN 16931 CII XML を提供できる場合。
- PDF/A-3b パッケージング、添付ファイルメタデータ、電子請求書用 XMP の接続設定が必要な場合。
- 対応標準とプロファイルを公開 capabilities エンドポイントで確認したい場合。
置き換えないもの
- 通常の顧客向け請求書PDFだけが必要な場合。JSON Render または Template Render を使います。
- OpenAPI が対応標準として記載する前に、XRechnung、FatturaPA、KSeF、Peppol、ZATCA、NF-e、GST のネイティブ出力が必要な場合。
- 不完全な業務データから、法的に正しい請求書 XML を gPdf に作らせたい場合。
呼び出す endpoint
/api/v1/e-invoice/render
E-Invoice Render がこのワークフローの標準パスです。
/api/v1/e-invoice/capabilities
関連 API パス、テンプレート契約、または機能確認が必要な場合に使います。
最小リクエスト
POST /api/v1/e-invoice/render - 最小の Factur-X PDF/A-3b リクエスト。
{
"settings": {
"profile": "pdfa-3b",
"e_invoice": {
"standard": "factur_x",
"profile": "en16931",
"document_type": "invoice",
"xml": {
"format": "cii",
"encoding": "utf8",
"content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rsm:CrossIndustryInvoice>...</rsm:CrossIndustryInvoice>"
}
}
},
"pages": [
{
"size": "a4",
"elements": [
{
"type": "text",
"x": 20,
"y": 24,
"content": "Invoice INV-1007",
"style": { "font_size": 16, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf が担当すること
- POST /api/v1/e-invoice/render による Factur-X または ZUGFeRD の PDF/A-3b パッケージング。
- 呼び出し側が提供した EN 16931 CII XML を関連ファイルとして埋め込む処理。
- PDF/A-3b ラッパーのメタデータと、標準固有の電子請求書 XMP 接続設定。
- GET /api/v1/e-invoice/capabilities による対応機能の確認。
自社システムが担当すること
- 請求書の業務上の意味づけ、税務ルール、買い手/売り手識別子、EN 16931 XML の正確性。
- 受信側ワークフローに Factur-X と ZUGFeRD のどちらが適しているかの判断。
- 受信者、買掛金（AP）自動化システム、またはローカルのコンプライアンスプロセスでの外部受け入れテスト。
本番前チェックリスト
- 標準やプロファイルを前提にする前に /api/v1/e-invoice/capabilities を呼び出す。
- 埋め込む前に EN 16931 CII XML を検証する。
- 出力を /validator/ または自社の参照エンジンパイプラインに通す。
- 通常の請求書PDF生成と法的な電子請求書パッケージングをコード上で分ける。
- リクエスト ID、標準、プロファイル、XML ソースバージョン、検証証跡を記録する。
対応範囲の境界
- ネイティブの公開電子請求書出力は、EN 16931 CII XML を含む Factur-X / ZUGFeRD です。
- その他の国別電子請求書名は、OpenAPI が対応標準として記載するまでは市場文脈として扱います。
- gPdf は呼び出し側が提供した XML をパッケージします。XML の業務上の正しさは自社システムの責任です。
電子請求書パッケージのための 1 つのエンドポイント
電子請求書エンドポイントが存在するのは、このワークフローが単なる「請求書PDFのレンダリング」ではないためです。呼び出し側が提供する EN 16931 CII XML を埋め込みながら、正しい関連ファイルメタデータと標準固有の XMP を持つ PDF/A-3b ラッパーを生成する必要があります。
必要な出力が Factur-X または ZUGFeRD の場合は、POST /api/v1/e-invoice/render を呼び出します。連携側で対応標準、プロファイル、文書タイプ、XML 形式を作業送信前に確認したい場合は、GET /api/v1/e-invoice/capabilities を使います。
gPdf の外側に残るもの
XML の業務上の意味づけは引き続き自社の責任です。請求書番号が法的に有効か、税額が正しいか、買い手識別子が取引先と一致しているか、特定の受信者が業務プロセスのバリエーションを受け入れるかを、gPdf が知ることはできません。上流で XML を生成・検証してから、gPdf を PDF/A-3b のパッケージングとレンダリングに使ってください。
ロードマップ上の用語をネイティブ対応の主張に混ぜない
XRechnung、FatturaPA、KSeF、Peppol、ZATCA、NF-e、GST を市場文脈として語ることはできます。ただし、OpenAPI の capabilities 仕様に記載されていない限り、これらをネイティブの公開レンダラー出力として提示しないでください。
FAQ
- 現時点でネイティブの公開出力に対応している電子請求書標準はどれですか？
- 公開ネイティブ出力は、EN 16931 CII XML を埋め込んだ Factur-X と ZUGFeRD の PDF/A-3b です。現在の公開仕様は /api/v1/e-invoice/capabilities で確認してください。
- gPdf は EN 16931 XML を生成してくれますか？
- いいえ。XML 内容は自社システムが提供します。gPdf は必要な添付ファイルメタデータとともに、それを PDF/A-3b 電子請求書ラッパーへパッケージします。
- settings.e_invoice を JSON Render に送れますか？
- いいえ。電子請求書のパッケージングは POST /api/v1/e-invoice/render で扱います。公開ドキュメントでは settings.e_invoice は特定ルート専用とされています。
- 出力はどう検証すべきですか？
- gPdf validator または自社の参照エンジンワークフローを使って、PDF/A レイヤーと埋め込まれた電子請求書 XML レイヤーの両方を確認します。