ZUGFeRD / Factur-X 準拠: EN 16931 請求書プロファイルの埋め込み

概要

適用範囲に関する注記。 NextPDF は埋め込み XML プロファイルを生成します。財務的および法的な有効性は受領機関が判断するものであり、ライブラリが判断するものではありません。

ZUGFeRD / Factur-X はハイブリッド請求書です。人間が読める PDF（PDF/A-3 アーカイブ基盤）に、EN 16931 のセマンティックデータモデルに従った機械可読の Cross-Industry-Invoice（CII）XML を埋め込んだ形式です。NextPDF Core は埋め込みコントラクト（NextPDF\Contracts\EInvoice）を提供します。具体的な Factur-X 1.08 エンジンは、Premium の nextpdf/pro パッケージで提供されます。ライブラリは、埋め込み XML と PDF/A-3 の添付ファイル構造を生成します。財務的な有効性は、EN 16931 / Schematron バリデーター、または受領側の税務当局が判断します。

インストール

composer require nextpdf/core:^3   # EInvoice contracts only
composer require nextpdf/pro       # Factur-X 1.08 embedder engine

Core は EmbedderInterface、ProfileInterface、ProfileType、ValidatorInterface、および ValidationResult を NextPDF\Contracts\EInvoice で提供します。インターフェイスの docblock に明記されているとおり、Pro ティア（Factur-X 1.08 バイト書き換えエンジン）と Enterprise ティア（PDF/A マネージドビルダー）がこのコントラクトを実装します。Core 単体では請求書を埋め込みません。各ティアが満たすべき byte-in/byte-out コントラクトを定義するだけです。

概念の概要

NextPDF\Contracts\EInvoice\ProfileType は EN 16931 準拠性を表す判別子で、値は MINIMUM、BASIC_WL、BASIC、EN16931、EXTENDED、XRECHNUNG です。その isEn16931Conformant() は、EN 16931-1 のルールを直接表現しています。MINIMUM と BASIC_WL は EN 16931 に準拠していません（BT-24 の仕様識別子のカーディナリティと明細行の要件を満たさないためです）。BASIC、EN16931、EXTENDED、XRECHNUNG は EN 16931 に準拠しています。

埋め込みツール（EmbedderInterface）は、次の処理をコントラクトとして規定します。

指定された CII XML を XmlGuard 経由で XXE セーフに解析する。
宣言されたプロファイル向けの Factur-X XMP 拡張スキーマを注入する。
正しい AFRelationship（Data / Alternative）を付けて XML を埋め込みファイルとして添付し、PDF/A-3 アーカイブ基盤（§6.7.5 の埋め込みファイル要件 — F/UF キー）上で保持できるようにする。

NextPDF はこの構造を生成します。請求書が財務的に有効であることを主張するものではありません。その判断は、EN 16931 §7 のビジネスルールおよび各国の CIUS に照らして、受領機関が行います。

API サーフェス

シンボル	効果
`Contracts\EInvoice\EmbedderInterface`	byte-in/byte-out コントラクト。Pro/Enterprise による実装。
`Contracts\EInvoice\ProfileType`（enum）	EN 16931 プロファイルの判別子。
`ProfileType::isEn16931Conformant(): bool`	MINIMUM/BASIC_WL では false、BASIC/EN16931/EXTENDED/XRECHNUNG では true。
`Contracts\EInvoice\ValidatorInterface`	ルール違反の `ValidationResult` を返す検証コントラクト。

コードサンプル — クイックスタート

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ProfileType;

// Core: choose and check the profile before delegating embedding to Pro.
$profile = ProfileType::EN16931;

if (!$profile->isEn16931Conformant()) {
    fwrite(STDERR, "Profile {$profile->value} is not EN 16931 conformant.\n");
    exit(1);
}

// The concrete embedder is provided by nextpdf/pro:
//   $embedder = /* the Factur-X embedder from nextpdf/pro; see the Premium docs */;
//   $pdfWithInvoice = $embedder->embed($basePdfBytes, $ciiXml, $options);
echo "Profile {$profile->value} selected (embedding requires nextpdf/pro).\n";

コードサンプル — 本番環境

本番パイプライン（Pro ティア）では、CII XML を PDF/A-3 ベースに埋め込みます。続いて、EN 16931 の Schematron バリデーターを実行します（または受領機関に送信します）。そのレポートをゲートとして扱います。NextPDF は埋め込み XML と PDF/A-3 の添付ファイルを生成します。財務的な有効性は validator/authority が判断します。Core 単体ではこのパイプラインを実行できません。埋め込みエンジンには nextpdf/pro が必要です。

エッジケースと注意点

Core が提供するのはコントラクトのみです。 nextpdf/pro がなければ、具体的な埋め込みツールは存在しません。呼び出し側のコードはインターフェイスに依存し、Pro の実装がない場合には明示的にデグレードする必要があります。
MINIMUM / BASIC_WL は EN 16931 ではありません。 これらに対して isEn16931Conformant() は false を返します。これらを使用する場合でも、EN 16931 請求書であると表明しないでください。
PDF/A-3 基盤。 埋め込み XML は PDF/A-3 アーカイブコンテナーに格納されます。埋め込みファイルの F/UF キー（PDF/A §6.7.5）が存在していなければなりません。
XML は XXE セーフに解析されます。 コントラクトは XmlGuard による解析を要求します。カスタムの埋め込みツールは XXE シンクを持ち込んではなりません。
有効性はライブラリの判定ではありません。 構造的に正しい Factur-X ファイルを生成しても、税務当局による受理を表明するものではありません。

パフォーマンス

埋め込み処理では、XML 添付ファイルと XMP 拡張スキーマを追加するために PDF を書き換えます。標準的な請求書の場合、ウォール時間 ≤ 1500 ms、ピーク ≤ 128 MB を予算としています。

セキュリティに関する注意事項

埋め込み XML は XmlGuard 経由で XXE セーフに解析されます。請求書 XML は、その性質上、商取引上の PII（当事者、金額）を含みます。これは暗号化されているわけではなく、単に埋め込まれているだけです。請求書の機密性はインテグレーターの責任です。

データ所在地と PII の緩和策

請求書 XML は、当事者および財務上の PII を保持します。埋め込みはプロセス内で行われます。埋め込み中にデータがプロセス外に出ることはありません。受領機関への送信はスコープ外であり、インテグレーターがデータ所在地について責任を負います。

安全なテレメトリとログのスクラビング

CII XML や埋め込み PDF のバイトをログに記録してはなりません。これらには請求書の PII が含まれます。ログに記録するのは、プロファイル名と構造上の判定のみにしてください。

脅威モデル

Factur-X ファイルにはアクセス制御がありません。埋め込み XML は、そのファイルを持つ誰もが読み取れます。ハイブリッドが保証するのは請求書の機械可読性であり、機密性や財務上の受理ではありません。

FIPS モードの動作

埋め込み処理は暗号化を行いません。署名付き Factur-X 請求書は別の署名レシピで扱う問題であり、そのレシピの FIPS 体制を継承します。本ページは署名に関する主張を行いません。

準拠

主張	仕様	条項
EN 16931 請求書における、セマンティックデータモデルのビジネス用語の保持	EN 16931-1	§6.4
準拠した請求書が満たすべきビジネスルールのカーディナリティによる、EN 16931 準拠の規定	EN 16931-1	§7
Factur-X の EN 16931 プロファイルにおける、CII-XML のビジネスルール準拠要件	Factur-X 1.08	EN 16931 プロファイル
Factur-X の EN 16931 プロファイルにおける、必須の請求書コンテンツ要件	Factur-X 1.08	EN 16931 プロファイル
Factur-X のハイブリッド性と、人間が読める PDF に併存する機械可読 XML の埋め込み	Factur-X 1.08	Basic プロファイル
PDF/A アーカイブ基盤（埋め込みファイルの F/UF キー）に格納される埋め込み XML	ISO 19005-4	§6.7.5

引用は、検証コーパスを指す clause-id + reference_id のポインターです。規格テキストは転載していません。条項は NextPDF 独自の言葉で要約しています。