Соответствие ZUGFeRD / Factur-X: встроенный профиль счёта EN 16931

Кратко

Заявление о границах ответственности. NextPDF формирует встроенный XML указанного профиля; фискальную и юридическую действительность определяет принимающий орган, а не библиотека.

ZUGFeRD / Factur-X — это гибридный счёт: читаемый человеком PDF (на архивной основе PDF/A-3) со встроенным машиночитаемым XML формата Cross-Industry-Invoice (CII), который соответствует семантической модели данных EN 16931. 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) обязывает:

разобрать переданный XML формата CII через XmlGuard (с защитой от XXE);
внедрить схему расширения XMP Factur-X для заявленного профиля;
прикрепить XML как встроенный файл с корректным AFRelationship (Data / Alternative), чтобы XML входил в архивный субстрат PDF/A-3 (требования к встроенным файлам §6.7.5 — ключи F/UF).

NextPDF формирует эту структуру. NextPDF не утверждает, что счёт фискально действителен. Это решение принимает принимающий орган на основании бизнес-правил EN 16931 §7 и любых национальных CIUS.

Поверхность API

Символ	Назначение
`Contracts\EInvoice\EmbedderInterface`	Контракт byte-in/byte-out; его реализуют Pro/Enterprise.
`Contracts\EInvoice\ProfileType` (enum)	Дискриминатор профиля EN 16931.
`ProfileType::isEn16931Conformant(): bool`	False для MINIMUM/BASIC_WL; true для BASIC/EN16931/EXTENDED/XRECHNUNG.
`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) XML формата CII встраивается в основу PDF/A-3. Затем запускается валидатор Schematron для EN 16931 либо данные передаются принимающему органу, а его отчёт используется как контрольный шлюз. NextPDF формирует встроенный XML и вложение PDF/A-3; фискальную действительность определяет валидатор или орган. 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. Контракт требует разбирать XML через XmlGuard; собственная реализация встраивания не должна вводить уязвимость XXE.
Библиотека не выносит вердикт о действительности. Создание структурно корректного файла Factur-X не означает, что налоговый орган его примет.

Производительность

Встраивание перезаписывает PDF, чтобы добавить вложение XML и схему расширения XMP. Бюджет для типичного счёта: общее время ≤ 1500 ms, пик памяти ≤ 128 MB.

Замечания по безопасности

Встроенный XML разбирается защищённо от XXE через XmlGuard. XML счёта содержит коммерческие персональные данные (PII), включая стороны и суммы. Он встроен, а не зашифрован. За конфиденциальность счёта отвечает интегратор.

Размещение данных и меры по защите PII

XML счёта содержит персональные данные о сторонах и финансах. Встраивание выполняется внутри процесса; во время встраивания данные не покидают процесс. Передача принимающему органу выходит за рамки этой страницы и относится к ответственности интегратора за размещение данных.

Безопасная телеметрия и очистка журналов

Никогда не записывайте в журнал XML формата CII или байты PDF со встроенным XML — они содержат персональные данные счёта. Записывайте в журнал только имя профиля и структурный вердикт.

Модель угроз

В файле Factur-X нет контроля доступа. Встроенный XML может прочитать любой, у кого есть файл. Гибрид гарантирует машиночитаемость счёта, но не его конфиденциальность и не его фискальное принятие.

Поведение в режиме FIPS

Встраивание не выполняет криптографических операций. Подписанный счёт Factur-X — отдельная тема рецепта подписи, и он наследует состояние FIPS этого рецепта. Эта страница не делает заявлений о подписании.