Enterprise редакция

Invoice — глубокий справочник

Кратко

Модуль Invoice имеет три независимые поверхности: встраивание, проверка и выполнение правил Schematron. ZugferdEmbedder и PeppolEmbedder присоединяют предоставленный вызывающим XML счёта к носителю PDF/A-4f или PDF/A-3b и возвращают структурированный результат. InvoiceXmlValidator выполняет структурный предварительный контроль EN 16931 с выбираемой серьёзностью COMPAT или STRICT. SchematronValidator выполняет предварительно скомпилированные наборы правил Schematron внутри процесса и разбирает находки SVRL. NextPDF не генерирует XML счёта; вызывающий предоставляет и владеет полезной нагрузкой.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без такого права не загружает классы этой возможности. Сравните редакции и получите лицензию.

Нюанс по уровням: обнаружение и проверка электронных счетов — это поверхность уровня Pro (модуль Pro Compliance). Встраивание гибридных счетов, профиль XRechnung CIUS и внутрипроцессный движок Schematron доступны только в Enterprise. Отдельного кода возможности на каждую функцию сверх границы пакета nextpdf/enterprise не существует.

Публичная поверхность API

composer require nextpdf/enterprise:^3

Символ	Параметры	Поведение по умолчанию	Возвращает	Выбрасывает или завершается с	Примечания
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Встраивает CII XML профиля BASIC: проход 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`	Регистрирует RDF-описание Factur-X и запись расширения схемы PDF/A	`XmpMetadata`	Нет	Вызывается `embed()`; также применимо напрямую
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Встраивает XML счёта или кредит-ноты Peppol BIS 3.0 UBL	`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`	`InvalidArgumentException` при отсутствующем или нечитаемом XSLT; сбои движка возвращают результат ошибки	Замер времени фиксируется в `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Межуровневый адаптер; сопоставляет находки ошибок с объектами контракта `RuleViolation`	`list<RuleViolation>`	То же, что `validate()`	Находки уровня info пропускаются
`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`, `JsonException` при некорректном lock JSON	Пустые или некорректные дайджесты отказывают закрыто
`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 присоединяет предоставленную вызывающим полезную нагрузку XML в формате ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII к носителю PDF/A. Он поддерживает два носителя: PDF/A-4f (ISO 19005-4:2020), предпочтительный современный носитель, и PDF/A-3b (ISO 19005-3:2012) для обратной совместимости. embed() всегда сначала выполняет проход безопасности XmlGuard, затем структурную проверку, если не был задан withoutValidation(), затем убеждается, что носитель поддерживает встроенные файлы, внедряет объявление расширения схемы XMP через ZugferdXmpSchema и присоединяет XML как присоединённый файл. Связь присоединения по умолчанию — рекомендация свода правил /Alternative; переопределения проходят через тот же свод правил, который обеспечивает набор связей ISO 32000-2:2020 §14.13 и подмножество для счетов EN 16931. PeppolEmbedder выполняет эквивалент для предоставленного вызывающим XML счёта или кредит-ноты Peppol BIS Billing 3.0 UBL 2.1. Ни один из встраивателей не генерирует XML счёта.

Проверка. InvoiceXmlValidator проверяет CII XML на соответствие структурным ожиданиям EN 16931: корневой элемент, обязательные разделы, кардинальность заголовка, строки позиций там, где их требует профиль, и идентификатор спецификации BT-24, предписанный бизнес-правилом BR-1. InvoiceValidatorMode выбирает серьёзность. COMPAT (по умолчанию) сообщает об отсутствующем или несовпадающем BT-24 как о предупреждении, чтобы булев гейт валидности не регрессировал. STRICT делает и то и другое жёсткой ошибкой, а также утверждает согласованность профиля с объявленным ZugferdProfile, зеркаля семантику внешних валидаторов KoSIT / Mustang. Режим разрешается в порядке: явный аргумент, затем переопределение окружения INVOICE_VALIDATOR_MODE, затем COMPAT. Результаты — структурированные объекты InvoiceValidationResult / InvoiceValidationFinding; валидатор возвращает находки, а не выбрасывает исключение.

Schematron. SchematronValidator выполняет предварительно скомпилированные наборы правил Schematron — правила CEN EN 16931 .sch, скомпилированные в XSLT во время сборки, — с помощью внутрипроцессного процессора XSLT в PHP. Он разбирает отчёт SVRL в объекты SchematronFinding / SchematronResult: невыполненные утверждения становятся находками ошибок, успешные отчёты становятся находками info. Необязательный кэш (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 жёсткими ошибками.
SchematronValidator выбрасывает исключение только при отсутствующем или нечитаемом пути XSLT. Сбои преобразования или разбора SVRL возвращают SchematronResult::error() с isValid равным false.
Запись кэша, чьи сохранённые байты не проходят проверку дайджеста, вытесняется, а стилевая таблица перечитывается с диска; отравленные байты никогда не возвращаются.
Процессор XSLT работает с заблокированной загрузкой файловых и сетевых ресурсов и никогда не регистрирует функции PHP; document(), xsl:include, xsl:import и result-document не могут загружать ресурсы.
VersionPinRegistry отклоняет пустые или некорректные дайджесты SHA-256 при загрузке и при регенерации; verifyArtefact() возвращает false, а не пропускает непроверяемую фиксацию.
Этот модуль не выполняет криптографического подписания; поведение в режиме FIPS вне области действия здесь (см. модуль Signature).

Соответствие

Поведение	Ссылка	Статус
Семантическая модель счёта Core	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 требует расширения PHP ext-xsl; его предоставление и включение — ответственность оператора.
Обработка выполняется внутри процесса и локально. Исходящих сетевых вызовов во время встраивания или проверки не происходит. Национальный транспорт электронных счетов, платформы клиринга и архивные системы внешние по отношению к этому модулю.
Наборы правил компилируются из .sch в XSLT во время сборки; среда выполнения выполняет только предварительно скомпилированные стилевые таблицы.
Ключи кэша включают соль версии компилятора (в настоящее время nextpdf-schxslt-1.0); её изменение инвалидирует развёрнутые кэши без шага очистки.
Фиксации наборов правил хранятся в lock-файле по пути enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); CI проверяет развёрнутые артефакты на соответствие зафиксированным дайджестам.
Межуровневые вызывающие используют InvoiceContractValidator и ZugferdContractEmbedder; вызывающие, нативные для уровня Enterprise, используют ZugferdEmbedder и InvoiceXmlValidator напрямую.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов руководств по эксплуатации и префиксы тикетов вне области действия.

См. также

Возможность Invoice — аналог по возможности для этого справочника.
Pro Compliance — обнаружение/проверка уровня Pro.
Document E-Filing
Обзор Enterprise