gPdf
リリース · minor

v2026.06 2026年6月: 電子インボイスのオブジェクト配信 — ジョブとアーティファクト

E-Invoice Render に delivery.mode = object を追加しました。レンダリング呼び出しが JSON のジョブ記述子を返し、認証付きエンドポイントでジョブをポーリングして、PDF、埋め込み XML、検証レポート、元のリクエストをアーティファクトとしてダウンロードできます。

by gPdf Engineering
主な内容
  • GET /api/v1/e-invoice/jobs/{job_id} — オブジェクト配信ジョブの認証付き参照。アーティファクトごとの利用可否と有効期限を含みます。
  • GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact} — pdf / xml / report / request の各アーティファクトのバイト列をダウンロードします。
  • POST /api/v1/e-invoice/render の delivery.mode = object は、インライン PDF バイト列の代わりに JSON のジョブ記述子を返します。既定値は引き続き inline_pdf です。

変更点

  • added GET /api/v1/e-invoice/jobs/{job_id} がジョブ記述子を返します。内容は status (pending | completed | failed)、データレジデンシー、作成/有効期限のタイムスタンプ、検証状態、およびアーティファクトごとの利用可否、content type、サイズ、期限付きダウンロード URL です。認証には、ジョブを作成したのと同じ Bearer token を使用します。
  • added GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact} が、pdf、xml、report (report.enabled = true の場合のみ)、request (retention.store_request = true の場合のみ) の生のアーティファクトバイト列をストリーミングします。
  • added settings.e_invoice.delivery: mode (inline_pdf | object) がレスポンスの形を選択します。url_ttl_seconds (範囲 1..900、既定値 300) はアーティファクトのダウンロード URL の有効時間を制限します。
  • added settings.e_invoice.retention: ttl_hours (範囲 1..23、既定値 23) は object モードのアーティファクトとジョブメタデータの保持期間を制限します。store_request を有効にすると、元のリクエストボディもアーティファクトとして保存されます。
  • added settings.e_invoice.data_residency: auto はインボイスの国から eu / global を解決します。eu と global はレジデンシープロファイルを強制します。strict は、解決できない国をフォールバックにせず API-002 エラーにします。

新機能

POST /api/v1/e-invoice/render が2つの配信モードに対応しました。既定の delivery.mode = inline_pdf は、これまでとまったく同じように PDF/A-3b のバイト列をインラインで返します。delivery.mode = object を設定すると、代わりに JSON のジョブ記述子を返し、レンダリング出力を個別にダウンロードできるアーティファクトとして保存します。PDF と一緒に埋め込み XML や検証レポートが必要なパイプライン、あるいは出力を別のシステムに引き渡すパイプライン向けです。

エンドポイントファミリー

エンドポイント 認証 用途
POST /api/v1/e-invoice/render 必須 レンダリング。インライン PDF またはジョブ記述子を返します。
GET /api/v1/e-invoice/jobs/{job_id} 必須 object モードのジョブをポーリングします。
GET /api/v1/e-invoice/jobs/{job_id}/artifacts/{artifact} 必須 ジョブのアーティファクトをダウンロードします。
GET /api/v1/e-invoice/capabilities 不要 静的な capability レジストリ (配信モードとレジデンシーモードを公開)。

ジョブの参照とアーティファクトのダウンロードは、ジョブを作成したのと同じ Bearer token で認証します。

アーティファクト

{artifact} は次のいずれかです。

  • pdf — 署名済みの PDF/A-3b 文書
  • xml — 埋め込みの CII XML
  • report — 検証レポート (report.enabled = true の場合のみ)
  • request — 元のリクエストボディ (retention.store_request = true の場合のみ)

ジョブ記述子には、アーティファクトごとに available、content_type、bytes、expires_at_ms、ダウンロード URL が列挙されます。ダウンロード URL 自体にも有効期限があり、同じ Bearer token で取得します。

有効期間の制御

  • delivery.url_ttl_seconds (範囲 1..900、既定値 300) は、アーティファクトのダウンロード URL が有効な時間を制限します。
  • retention.ttl_hours (範囲 1..23、既定値 23) は、アーティファクトとジョブメタデータ自体の保持期間を制限します。経過後は、アーティファクトのダウンロードは 404 を返し、ジョブの参照はメタデータのみを返します。

データレジデンシー

settings.e_invoice.data_residency は、object モードのアーティファクトを保存する場所を選択します。auto はインボイスの国から eu / global を解決します (例: DE → eu、US → global)。eu と global はプロファイルを強制します。strict = true は、解決できない国をフォールバックにせず、明示的な API-002 エラーにします。

互換性

オブジェクト配信はオプトインです。delivery を省略した request、または delivery.mode = inline_pdf を設定した request は、これまでとまったく同じように動作します。インライン PDF を返し、ジョブは作成されず、何も保存されません。

2つのエンドツーエンド検証フローを含む完全な契約については、E-invoice API リファレンス を参照してください。