Zgodność z ZUGFeRD / Factur-X: osadzony profil faktury EN 16931

W skrócie

Oświadczenie o granicach odpowiedzialności. NextPDF tworzy osadzony profil XML; o ważności fiskalnej i prawnej decyduje organ przyjmujący, a nie biblioteka.

ZUGFeRD / Factur-X to faktura hybrydowa: czytelny dla człowieka plik PDF (archiwizacyjne podłoże PDF/A-3) z osadzonym, czytelnym maszynowo dokumentem XML Cross-Industry-Invoice (CII), zgodnym z semantycznym modelem danych EN 16931. NextPDF Core dostarcza kontrakt osadzający (NextPDF\Contracts\EInvoice); konkretny silnik Factur-X 1.08 jest dostępny w pakiecie Premium nextpdf/pro. Biblioteka tworzy osadzony dokument XML oraz strukturę załącznika PDF/A-3. O ważności fiskalnej decyduje walidator EN 16931 / Schematron albo organ podatkowy przyjmujący fakturę.

Instalacja

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

Core dostarcza EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface oraz ValidationResult w NextPDF\Contracts\EInvoice. Docblock interfejsu wskazuje to wprost: warstwa Pro (silnik przepisujący bajty Factur-X 1.08) oraz warstwa Enterprise (kreator zarządzany przez PDF/A) implementują ten kontrakt. Sam Core nie osadza faktur. Definiuje kontrakt byte-in/byte-out spełniany przez te warstwy.

Przegląd koncepcyjny

NextPDF\Contracts\EInvoice\ProfileType to dyskryminator zgodności z EN 16931: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Jego metoda isEn16931Conformant() koduje regułę wynikającą bezpośrednio z normy EN 16931-1. Profile MINIMUM i BASIC_WL nie są zgodne z EN 16931 (nie spełniają liczności identyfikatora specyfikacji BT-24 ani wymogu dotyczącego pozycji wiersza). Profile BASIC, EN16931, EXTENDED, XRECHNUNG są zgodne z EN 16931.

Kontrakt komponentu osadzającego (EmbedderInterface) wymaga, aby implementacja:

parsowała dostarczony dokument XML CII za pomocą XmlGuard (z ochroną przed XXE);
wstrzykiwała schemat rozszerzenia XMP Factur-X dla zadeklarowanego profilu;
dołączała dokument XML jako osadzony plik z prawidłową wartością AFRelationship (Data / Alternative), tak aby archiwizacyjne podłoże PDF/A-3 niosło ten plik (§6.7.5 — wymagania dotyczące osadzonych plików, klucze F/UF).

NextPDF generuje tę strukturę. Nie poświadcza przy tym, że faktura jest ważna fiskalnie. To rozstrzygnięcie podejmuje organ przyjmujący na podstawie reguł biznesowych EN 16931 §7 oraz ewentualnego krajowego CIUS.

Powierzchnia API

Symbol	Działanie
`Contracts\EInvoice\EmbedderInterface`	Kontrakt byte-in/byte-out; implementują go Pro/Enterprise.
`Contracts\EInvoice\ProfileType` (typ wyliczeniowy)	Dyskryminator profilu EN 16931.
`ProfileType::isEn16931Conformant(): bool`	False dla MINIMUM/BASIC_WL; true dla BASIC/EN16931/EXTENDED/XRECHNUNG.
`Contracts\EInvoice\ValidatorInterface`	Kontrakt walidacji zwracający `ValidationResult` z naruszeniami reguł.

Przykład kodu — szybki start

<?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";

Przykład kodu — produkcja

Potok produkcyjny (warstwa Pro) osadza dokument XML CII w bazowym pliku PDF/A-3. Następnie uruchamia walidator Schematron EN 16931 albo przekazuje plik do organu przyjmującego i traktuje uzyskany raport jako bramkę walidacyjną. NextPDF generuje osadzony dokument XML i załącznik PDF/A-3; o ważności fiskalnej decyduje walidator lub organ. Sam Core nie może uruchomić tego potoku. Silnik osadzający wymaga pakietu nextpdf/pro.

Przypadki brzegowe i pułapki

Core zawiera tylko kontrakty. Bez nextpdf/pro nie istnieje konkretny komponent osadzający. Kod wywołujący musi zależeć od interfejsu i w razie braku implementacji Pro obsłużyć degradację w sposób jednoznaczny.
MINIMUM / BASIC_WL nie są EN 16931. isEn16931Conformant() zwraca dla nich false; gdy ich używasz, nie przedstawiaj faktury jako EN 16931.
Podłoże PDF/A-3. Osadzony dokument XML znajduje się w archiwizacyjnym kontenerze PDF/A-3; klucze osadzonego pliku F/UF (PDF/A §6.7.5) muszą być obecne.
XML jest parsowany w sposób bezpieczny względem XXE. Kontrakt wymaga parsowania przez XmlGuard; własny komponent osadzający nie może wprowadzać punktu podatnego na XXE.
Ważność nie jest werdyktem biblioteki. Wytworzenie poprawnego strukturalnie pliku Factur-X nie oznacza, że organ podatkowy go zaakceptuje.

Wydajność

Osadzanie przepisuje plik PDF, aby dodać załącznik XML oraz schemat rozszerzenia XMP. Budżet dla typowej faktury to czas zegarowy ≤ 1500 ms i szczytowe zużycie pamięci ≤ 128 MB.

Uwagi dotyczące bezpieczeństwa

Osadzony dokument XML jest parsowany w sposób bezpieczny względem XXE za pomocą XmlGuard. Dokument XML faktury zawiera dane handlowe umożliwiające identyfikację osób (PII), w tym strony i kwoty. Jest osadzony, a nie zaszyfrowany. Za poufność faktury odpowiada integrator.

Rezydencja danych i środki ograniczające ryzyko PII

Dokument XML faktury zawiera dane PII stron oraz dane finansowe. Osadzanie odbywa się w obrębie procesu; podczas osadzania żadne dane nie opuszczają procesu. Przesyłanie do organu przyjmującego pozostaje poza zakresem, a za rezydencję danych w tym obszarze odpowiada integrator.

Bezpieczna telemetria i czyszczenie dzienników

Nigdy nie zapisuj w dziennikach dokumentu XML CII ani bajtów osadzonego pliku PDF – zawierają one dane PII z faktury. Zapisuj tylko nazwę profilu oraz werdykt strukturalny.

Model zagrożeń

Plik Factur-X nie zapewnia kontroli dostępu. Osadzony dokument XML może odczytać każdy, kto dysponuje tym plikiem. Hybryda gwarantuje maszynową czytelność faktury, a nie jej poufność ani akceptację fiskalną.

Zachowanie w trybie FIPS

Osadzanie nie wykonuje żadnych operacji kryptograficznych. Podpisana faktura Factur-X to odrębny obszar receptury podpisu i dziedziczy jej postawę FIPS. Ta strona nie formułuje żadnych twierdzeń dotyczących podpisywania.

Zgodność

Twierdzenie	Specyfikacja	Klauzula
Faktura EN 16931 zawiera terminy biznesowe semantycznego modelu danych.	EN 16931-1	§6.4
Zgodność z EN 16931 określają liczności reguł biznesowych, które musi spełniać faktura zgodna z normą.	EN 16931-1	§7
Profil EN 16931 Factur-X wymaga zgodności z regułami biznesowymi CII-XML.	Factur-X 1.08	Profil EN 16931
Profil EN 16931 Factur-X określa wymaganą treść faktury.	Factur-X 1.08	Profil EN 16931
Factur-X to hybryda: czytelny maszynowo dokument XML osadzony obok pliku PDF czytelnego dla człowieka.	Factur-X 1.08	Basic
Osadzony dokument XML znajduje się w archiwizacyjnym podłożu PDF/A (klucze osadzonego pliku F/UF).	ISO 19005-4	§6.7.5

Cytowania są wskaźnikami clause-id + reference_id prowadzącymi do korpusu weryfikacyjnego. Żaden tekst normy nie jest powielany; klauzule są streszczone własnymi słowami zespołu NextPDF.