Enterprise エディション

Invoice — 詳細リファレンス

概要

Invoice モジュールには、埋め込み、検証、Schematron ルール実行という 3 つの独立したサーフェスがあります。ZugferdEmbedder と PeppolEmbedder は、呼び出し側が提供したインボイス XML を PDF/A-4f または PDF/A-3b キャリアに添付し、構造化された結果を返します。InvoiceXmlValidator は、選択可能な COMPAT または STRICT の深刻度で EN 16931 の構造プリフライトを実行します。SchematronValidator は、事前コンパイル済みの Schematron ルールパックをインプロセスで実行し、SVRL 検出結果を解析します。NextPDF はインボイス XML を生成しません。呼び出し側がペイロードを提供して所有します。

提供状況とライセンス

この機能は NextPDF Enterprise（nextpdf/enterprise）に含まれ、Enterprise ティアのライセンスエンベロープで有効化されます。その権利のないデプロイメントでは、この機能のクラスはロードされません。エディションを比較してライセンスを取得。

ティアごとのニュアンス。e-invoice の検出と検証は Pro ティアのサーフェス（Pro Compliance モジュール）です。ハイブリッドインボイスの埋め込み、XRechnung CIUS プロファイル、およびインプロセスの Schematron エンジンは Enterprise 専用です。nextpdf/enterprise パッケージの境界を超えた、機能ごとの個別の機能コードはありません。

パブリック API サーフェス

composer require nextpdf/enterprise:^3

シンボル	パラメーター	デフォルトの挙動	戻り値	スロー/失敗	備考
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	BASIC プロファイルの CII XML を埋め込む。XmlGuard パス、構造検証、XMP スキーマ注入、添付	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	クイックパス。推奨される起点
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	MINIMUM プロファイルで同じパイプライン	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	クイックパス
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	ビルダーのエントリー。空の XML を拒否	`self`	`InvalidArgumentException`	`withoutValidation()`、`withDescription()` で構成
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	デフォルトの `/Alternative` 関係をオーバーライド。関連ファイルのルールブックによってゲートされる	`self`	`InvalidArgumentException`	インボイスでは `Schema`、`EncryptedPayload`、`FormData` を拒否
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	ビルダーの終端呼び出し。XmlGuard、任意の検証、キャリアチェック、XMP、添付	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	検証の失敗は最初のエラーを示す
`ZugferdProfile`（enum）	—	ケース MINIMUM、BASIC_WL、BASIC、EN16931、EXTENDED、XRECHNUNG	—	—	XRECHNUNG は `xrechnung.xml` を添付。CII プロファイルは `factur-x.xml` を添付
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Factur-X の RDF 記述と PDF/A 拡張スキーマエントリーを登録	`XmpMetadata`	なし	`embed()` から呼ばれる。直接も使用可能
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Peppol BIS 3.0 UBL のインボイスまたはクレジットノート XML を埋め込む	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	デフォルトのファイル名 `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	ビルダーのエントリー。空の XML またはファイル名を拒否	`self`	`InvalidArgumentException`	`withFilename()`、`withDescription()`、`withoutSanitization()` で構成
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	XmlGuard パス、キャリアチェック、ルールブックのゲート、添付	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	埋め込み時にキャリアを考慮したルールブックの再チェック
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	EN 16931 の構造プリフライト。デフォルトは COMPAT 深刻度	`InvoiceValidationResult`	スローしない。失敗はエラー検出結果として表面化	モードは引数、次に環境、次に COMPAT の順で解決
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	CII ペイロードのルート要素と名前空間のチェック	`bool`	スローしない。`false` を返す	低コストの検出プローブ
`InvoiceValidatorMode`（enum）	—	`COMPAT`（デフォルト）は BT-24 の検出結果を警告に保つ。`STRICT` はそれをエラーに昇格	—	—	`fromEnvironment()` は未設定または認識できない値の場合 COMPAT にフォールバック
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	イミュータブルな集約。`isValid`、`getErrors()`、`getWarnings()`。検出結果ごとにレベル、コード、メッセージ	—	—	`InvoiceValidationResult::fail()` は単一のエラーをラップ
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	事前コンパイル済みの Schematron XSLT を実行。SVRL を検出結果に解析	`SchematronResult`	欠落または読み取り不能な XSLT の場合 `InvalidArgumentException`。エンジンの失敗はエラー結果を返す	タイミングは `durationMs` に記録
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	ティア横断アダプター。エラー検出結果をコントラクトの `RuleViolation` オブジェクトにマッピング	`list<RuleViolation>`	`validate()` と同じ	情報レベルの検出結果はスキップ
`SchematronResult` / `SchematronFinding`	—	判定、検出結果、所要時間。`getFailedAssertions()`、`getSuccessfulReports()`	—	—	`SchematronResult::error()` はエンジンの失敗を無効としてマーク
`SchematronCacheInterface`	—	改ざん検出キャッシュのコントラクト。`getVerified()`、`set()`、`computeKey()`	—	—	ダイジェスト不一致時はフェイルクローズ
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	アトミックリネーム書き込みを伴う SHA-256 検証済みファイルキャッシュ	—	`InvalidArgumentException`, `SchematronCacheException`	ディレクトリは存在するか作成可能で、かつ書き込み可能であること
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	SHA-256 でロックされたルールパックのピン。`loadFromLockFile()`、`get()`、`verifyArtefact()`、`regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`、不正な形式のロック JSON では `JsonException`	空または不正な形式のダイジェストはフェイルクローズ
`InvoiceContractValidator`	`?SemanticValidator`	ティア横断の `ValidatorInterface` アダプター。構造プリフライトに加え EN 16931 の深いセマンティックルール	`ContractResult`	フェイルクローズ。エンジンのエラーはエラー検出結果として表面化	`nextpdf/premium` がインストールされている場合、フレームワークのパスでバインドされる
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	ティア横断の `EmbedderInterface` アダプター。バイト入力/バイト出力の埋め込み	`string`（PDF バイト列）	デリゲートの失敗を伝播	Pro ティアのバイト書き換えエンジンに委譲
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	モジュールの失敗の分類	—	—	すべて `RuntimeException` を継承

public static function basic(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $xmlData,
): ZugferdEmbedResult

public function embed(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
): ZugferdEmbedResult

public static function invoice(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $ublXml,
): PeppolEmbedResult

public static function validate(
    string $xmlData,
    ZugferdProfile $profile,
    ?InvoiceValidatorMode $mode = null,
): InvoiceValidationResult

public function validate(string $xsltPath, string $xmlData): SchematronResult

挙動コントラクト

埋め込み。 ZugferdEmbedder は、呼び出し側が提供した ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII XML ペイロードを PDF/A キャリアに添付します。2 つのキャリアをサポートします。推奨されるモダンなキャリアである PDF/A-4f（ISO 19005-4:2020）と、後方互換性のための PDF/A-3b（ISO 19005-3:2012）です。embed() は常に最初に XmlGuard セキュリティパスを実行し、次に withoutValidation() が設定されていない限り構造検証を行い、次にキャリアが埋め込みファイルをサポートすることを検証し、ZugferdXmpSchema を介して XMP 拡張スキーマ宣言を注入し、関連ファイルとして XML を添付します。添付の関係はデフォルトでルールブックの推奨値 /Alternative になります。オーバーライドは同じルールブックを経由し、そのルールブックが ISO 32000-2:2020 §14.13 の関係集合と EN 16931 のインボイスサブセットを強制します。PeppolEmbedder は、呼び出し側が提供した Peppol BIS Billing 3.0 UBL 2.1 のインボイスまたはクレジットノート XML に対して同等の処理を実行します。どちらの埋め込みツールもインボイス XML を生成しません。

検証。 InvoiceXmlValidator は、CII XML を EN 16931 の構造的な期待値に照らしてチェックします。ルート要素、必須セクション、ヘッダーのカーディナリティ、プロファイルが要求する場合の明細項目、そしてビジネスルール BR-1 が義務付ける BT-24 仕様識別子です。InvoiceValidatorMode が深刻度を選択します。COMPAT（デフォルト）は、BT-24 の欠落や不一致を警告として報告し、ブール値の有効性ゲートが後退しないようにします。STRICT は、その両方をハードエラーにし、さらに宣言された ZugferdProfile に照らしてプロファイルの一貫性を主張し、外部の KoSIT / Mustang バリデーターのセマンティクスを反映します。モードは、明示的な引数、次に INVOICE_VALIDATOR_MODE 環境オーバーライド、次に COMPAT の順で解決されます。結果は構造化された InvoiceValidationResult / InvoiceValidationFinding オブジェクトです。バリデーターはスローするのではなく検出結果を返します。

Schematron。 SchematronValidator は、事前コンパイル済みの Schematron ルールセット — ビルド時に XSLT へコンパイルされた CEN EN 16931 .sch ルール — を、インプロセスの PHP XSLT プロセッサーを使って実行します。SVRL レポートを SchematronFinding / SchematronResult オブジェクトに解析します。失敗したアサーションはエラー検出結果に、成功したレポートは情報検出結果になります。任意のキャッシュ（SchematronCacheInterface、アトミックリネームのファイル実装を伴う）が、コンテンツダイジェストとコンパイラバージョンをキーとして、検証済みのスタイルシートバイト列を提供します。VersionPinRegistry は、すべての外部ルールパックを SHA-256 でロックされたバージョンに固定し、ドリフトや不正な形式のダイジェスト時にフェイルクローズします。

このモジュールは、構造化されたインボイスデータを生成してチェックします。いかなるドキュメントが法的に準拠したインボイスであること、税務当局に承認されていること、またはいかなる当局による受理が保証されることを主張するものでは ありません。バリデーターは、EN 16931 のセマンティックモデルと ZUGFeRD / Factur-X / UBL コンテナのみをチェックし、国別拡張（例: イタリアの SDI、フランスの Chorus Pro、ドイツの XRechnung トランスポート）を除外します。EN 16931-1 が述べているとおり、関連法規のルールを満たす責任はインボイス発行者にあります。これは税務当局のバリデーターではありません。ある標準をサポートしていることは、その標準への適合ではありません。

エッジケースと失敗モード

空の XML は即座に失敗します。ビルダーは InvalidArgumentException をスローし、InvoiceXmlValidator::validate() は失敗結果を返します。
XmlGuard は DOCTYPE 宣言、エンティティ展開、サイズ超過ペイロード、制御文字を拒否します。埋め込みツールはこれを ZugferdEmbeddingException または PeppolEmbeddingException として、原因を保持したまま表面化します。
withoutValidation() と withoutSanitization() は XmlGuard セキュリティパスを決してバイパスしません。スキップできるのは構造的なビジネスターム検査のみです。
埋め込みファイルをサポートしないキャリア（PDF/A-4f または PDF/A-3b 以外のもの）は、許容されるバージョンを示す InvalidArgumentException を発生させます。
許可されていない AFRelationship の値は、ビルダーの境界で拒否されます。embed() の内部でキャリアを考慮したルールブックの再チェックが再度実行されます。
COMPAT は BT-24 の欠落を警告の深刻度に保ちます。STRICT は、欠落した BT-24 とプロファイル不一致の BT-24 の値をハードエラーにします。
SchematronValidator は、欠落または読み取り不能な XSLT パスの場合にのみスローします。変換または SVRL 解析の失敗は、isValid が false の SchematronResult::error() を返します。
保存されたバイト列がダイジェスト検証に失敗したキャッシュエントリーは追い出され、スタイルシートはディスクから再読み込みされます。汚染されたバイト列が返されることは決してありません。
XSLT プロセッサーは、ファイルおよびネットワークリソースの読み込みをブロックした状態で実行され、PHP 関数を登録することは決してありません。document()、xsl:include、xsl:import、result-document はリソースを読み込めません。
VersionPinRegistry は、取り込み時および再生成時に、空または不正な形式の SHA-256 ダイジェストを拒否します。verifyArtefact() は、検証できないピンを通過させるのではなく false を返します。
このモジュールは暗号署名を一切実行しません。FIPS モードの挙動はここでの対象外です（Signature モジュールを参照）。

適合性

挙動	参照	ステータス
コアインボイスのセマンティックモデル	EN 16931-1:2026 §4	合わせて構築。発行者が引き続き責任を負う
仕様識別子（BT-24）	EN 16931-1:2026 BR-1	COMPAT では警告、STRICT ではエラー
UN/CEFACT CII 構文バインディング	CEN/TS 16931-3-3:2020	埋め込みをサポート
UBL 2.1 構文バインディング	CEN/TS 16931-3-2:2020	埋め込みをサポート
PDF/A-3 関連ファイル	ISO 19005-3:2012 §6.7.8	キャリアをサポート
PDF/A-4f 埋め込みファイル	ISO 19005-4:2020 Annex A	キャリアをサポート
関連ファイルの関係値	ISO 32000-2:2020 §14.13	ルールブックでゲート
Schematron / SVRL レポートの解析	ISO/IEC 19757-3	合わせて構築（製品準拠。標準は引用コーパスに含まれない）

合わせて構築されたものであり、認証または税務当局の承認ではありません。NextPDF はこれらの標準のいずれについても認証を保持していません。NextPDF は、EN 16931 データモデルに準拠した構造化インボイスを生成し、ルールの検出結果を報告します。法的に準拠したインボイスを生成したり、税務当局に承認された出力を提供したり、受理を保証したりすることはありません。税務および法務の助言者にご相談ください。

開発上の注意

Schematron エンジンには ext-xsl PHP 拡張機能が必要です。これをプロビジョニングして有効化することはオペレーターの責任です。
処理はインプロセスかつローカルです。埋め込みや検証の間にアウトバウンドのネットワーク呼び出しは発生しません。国別の電子インボイストランスポート、クリアランスプラットフォーム、およびアーカイブシステムは、このモジュールの外部にあります。
ルールパックはビルド時に .sch から XSLT へコンパイルされます。ランタイムは事前コンパイル済みのスタイルシートのみを実行します。
キャッシュキーはコンパイラバージョンのソルト（現在は nextpdf-schxslt-1.0）を織り込みます。これをバンプすると、パージ手順なしでデプロイ済みのキャッシュが無効化されます。
ルールパックのピンは、ロックファイル enterprise/config/invoice-versions.lock（VersionPinRegistry::DEFAULT_LOCK_PATH）に存在します。CI はデプロイ済みのアーティファクトを固定されたダイジェストに照らして検証します。
ティア横断の呼び出し側は InvoiceContractValidator と ZugferdContractEmbedder を使用します。ティアネイティブな Enterprise の呼び出し側は ZugferdEmbedder と InvoiceXmlValidator を直接使用します。

公開範囲

このページは、外部から観測可能な挙動とサポートされるパブリック API サーフェスのみを記載しています。内部名前空間パス、ヘルパークラス、メカニズムのテーブル、ランブックのファイル名、チケットのプレフィックスは対象外です。