Faktura

W skrócie

NextPDF Enterprise tworzy ustrukturyzowane faktury hybrydowe ZUGFeRD / Factur-X / Peppol-UBL i waliduje XML faktury wobec modelu danych EN 16931 oraz zestawów reguł Schematron. Tworzy ustrukturyzowane faktury zgodne z modelem danych zdefiniowanym w EN 16931; nie jest walidatorem organu podatkowego i nie certyfikuje żadnego dokumentu.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/enterprise:^3

Silnik Schematron korzysta z rozszerzenia PHP ext-xsl. Zainstaluj je i włącz przed uruchomieniem walidacji Schematron.

Przegląd koncepcyjny

Moduł Invoice ma trzy niezależne powierzchnie: osadzanie ustrukturyzowanej faktury, walidację XML EN 16931 oraz wykonywanie reguł Schematron.

Osadzanie. ZugferdEmbedder dołącza dostarczony przez wywołującego ładunek XML ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII do nośnika PDF/A, tworząc fakturę hybrydową. Obsługiwane są dwa formaty nośnika: PDF/A-4f (ISO 19005-4:2020), preferowany nowoczesny nośnik, oraz PDF/A-3b (ISO 19005-3:2012) dla zachowania wstecznej zgodności. ZugferdXmpSchema wstrzykuje deklarację schematu rozszerzenia XMP Factur-X, której wymaga nośnik. PeppolEmbedder pełni tę samą rolę dla dostarczonego przez wywołującego XML faktury lub noty kredytowej Peppol BIS Billing 3.0 UBL 2.1, dołączając go z poprawną relacją pliku powiązanego i typem MIME. NextPDF nie syntetyzuje XML faktury; wywołujący dostarcza prawidłowy XML i pozostaje wystawcą faktury.

Walidacja. InvoiceXmlValidator sprawdza XML faktury wobec semantycznego modelu danych EN 16931 oraz oczekiwań kontenera ZUGFeRD / Factur-X, w tym identyfikatora specyfikacji BT-24, którego wymaga reguła biznesowa BR-1 EN 16931. Działa w jednym z dwóch trybów: COMPAT (domyślny; graniczne ustalenia dotyczące liczności EN 16931 są zgłaszane jako ostrzeżenia, aby zachować wsteczną zgodność dla istniejących fixture’ów) oraz STRICT (liczność BT-24 jest błędem krytycznym, odwzorowując semantykę walidatorów zewnętrznych). Tryb można wybrać dla każdego wywołania, przez nadpisanie środowiskowe lub przez politykę zgodności.

Schematron. SchematronValidator uruchamia prekompilowane zestawy reguł Schematron (reguły CEN EN 16931 .sch skompilowane do XSLT na etapie kompilacji) wobec XML faktury, korzystając z działającego w procesie procesora PHP XSLT, i parsuje raport SVRL na ustrukturyzowane ustalenia. Wyliczenie ZugferdProfile modeluje profile zgodności — MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED oraz niemiecki XRechnung B2G CIUS nad EN 16931.

Czego ten moduł deklaruje i czego nie deklaruje

Ten moduł tworzy i sprawdza ustrukturyzowane dane faktury. Nie deklaruje, że jakikolwiek dokument jest fakturą zgodną z prawem, że jest zatwierdzony przez organ podatkowy ani że jego akceptacja przez jakikolwiek organ jest gwarantowana.

• Walidator sprawdza wyłącznie semantyczny model EN 16931 oraz kontener ZUGFeRD / Factur-X / UBL. Nie jest walidatorem organu podatkowego. Rozszerzenia krajowe i platformy rozliczeniowe — na przykład włoski SDI, francuski Chorus Pro, niemiecki transport XRechnung — są poza zakresem na poziomie transportu.
• Jak stwierdza samo EN 16931-1, podstawowy model semantyczny zawiera istotne informacje, których faktura elektroniczna potrzebuje do wsparcia zgodności prawnej i podatkowej; wystawca faktury odpowiada za spełnienie zasad właściwych przepisów. To nie jest walidator organu podatkowego.
• Wsparcie dla standardu nie jest tym samym co zgodność z nim. Skonsultuj się z doradcami podatkowymi i ds. zgodności, aby ocenić wystarczalność regulacyjną w swojej jurysdykcji.

Dlaczego działa w ten sposób

Moduł celowo nigdy nie syntetyzuje XML faktury. Osadzanie, walidacja EN 16931 oraz wykonywanie Schematron to trzy niezależne powierzchnie nad XML, który wywołujący dostarcza i którego jest właścicielem. Utrzymuje to NextPDF w roli producenta i kontrolera, nigdy wystawcy, ponieważ odpowiedzialności prawnej nie można scedować na bibliotekę. Walidacja domyślnie działa w trybie COMPAT, więc graniczne ustalenie dotyczące liczności jest ostrzeżeniem, a nie regresją. STRICT jest opcjonalny, gdy potrzebujesz semantyki walidatorów zewnętrznych. W efekcie mamy czysty podział: NextPDF zgłasza to, co obserwuje, a wystawca decyduje, czy dokument spełnia wymogi prawa. Kontekst projektowy: Faktury i e-fakturowanie.

Powierzchnia API

Klasa	Odpowiedzialność
ZugferdEmbedder	Dołącza XML ZUGFeRD / Factur-X CII do nośnika PDF/A-4f lub PDF/A-3b.
ZugferdXmpSchema	Wstrzykuje deklarację schematu rozszerzenia XMP Factur-X.
ZugferdProfile	Wyliczenie profilu zgodności (MINIMUM … EXTENDED, XRECHNUNG).
PeppolEmbedder	Dołącza XML faktury / noty kredytowej Peppol BIS 3.0 UBL do nośnika PDF/A.
InvoiceXmlValidator	Sprawdza XML wobec modelu danych EN 16931; tryb COMPAT lub STRICT.
InvoiceValidatorMode	Wyliczenie trybu walidacji: COMPAT (domyślny) lub STRICT.
SchematronValidator	Uruchamia prekompilowane zestawy reguł Schematron; parsuje ustalenia SVRL.
InvoiceValidationResult / SchematronResult	Ustrukturyzowane wyniki: profil, ustalenia, wagi.

Przykład kodu — szybki start

use NextPDF\Enterprise\Invoice\ZugferdEmbedder;
use NextPDF\Enterprise\Invoice\ZugferdProfile;

$pdf = ZugferdEmbedder::basic($pdfAManager, $fileAttachment, $ciiXml)
    ->embed(ZugferdProfile::EN16931);

Przykład kodu — użycie produkcyjne

use NextPDF\Enterprise\Invoice\InvoiceXmlValidator;
use NextPDF\Enterprise\Invoice\InvoiceValidatorMode;

$result = $validator->validate($ciiXml, InvoiceValidatorMode::STRICT);

foreach ($result->findings as $finding) {
    $logger->warning('invoice.finding', [
        'rule'     => $finding->ruleId,
        'severity' => $finding->severity->value,
    ]);
}
// A clean result is one input to your decision, not a compliance verdict.
// The invoice issuer remains responsible for relevant legislation.

Przypadki brzegowe i pułapki

• Poprawny plik PDF, który nie zawiera rozpoznawalnego ładunku faktury, daje wynik „nie jest fakturą” zamiast zgłaszać wyjątek.
• COMPAT to domyślny tryb walidacji: brak identyfikatora specyfikacji BT-24 jest zgłaszany jako ostrzeżenie, więc miejsca wywołań, które bramkują na logicznej fladze ważności, nie ulegają regresji. Użyj STRICT, aby uczynić BT-24 błędem krytycznym, zgodnym z semantyką zewnętrznych narzędzi KoSIT / Mustang.
• Wywołujący dostarcza XML faktury. NextPDF go nie generuje ani nie poprawia; pusta lista ustaleń nie czyni niezgodnego ładunku zgodnym.
• Silnik Schematron wymaga ext-xsl. Zestawy reguł są kompilowane na etapie kompilacji; środowisko uruchomieniowe wykonuje wyłącznie prekompilowany XSLT.

Wydajność

Koszt walidacji skaluje się wraz z rozmiarem osadzonego XML oraz liczbą reguł Schematron. Koszt osadzania skaluje się wraz z rozmiarem nośnika i jest zdominowany przez serializację PDF/A. Budżet wydajności strony odzwierciedla renderowanie dokumentacji, a nie przepustowość faktur.

Uwagi dotyczące bezpieczeństwa

Całe parsowanie XML przebiega przez wzmocnioną ochronę XML: rozwiązywanie zewnętrznych encji jest wyłączone (bezpieczne wobec XXE), DOCTYPE jest odrzucany, a dekompresja jest ograniczona. Procesor XSLT działa z wyłączonym ładowaniem zasobów sieciowych i systemu plików oraz nigdy nie rejestruje funkcji PHP, więc document(), xsl:include, xsl:import ani result-document nie mogą sięgnąć do sieci ani dysku. XML faktury z niezaufanych źródeł traktuj jako wrogi.

Rezydencja danych i środki ograniczające dla danych osobowych

XML faktury może zawierać dane osobowe, handlowe i finansowe. Przetwarzanie odbywa się w procesie i lokalnie; moduł nie wykonuje żadnych wychodzących połączeń sieciowych podczas osadzania ani walidacji. Zastosuj własne mechanizmy retencji i minimalizacji do wyodrębnionego XML i ustaleń.

Bezpieczna telemetria i czyszczenie logów

Ustalenia i logi walidacji mogą zawierać identyfikatory reguł i wartości znaczników. Nie zawierają pełnych ładunków faktur. Przed przekazaniem logów do współdzielonych odbiorników wyczyść lub zredaguj wartości pól, jeśli są one wrażliwe.

Zgodność

Zachowanie	Odniesienie	Status
Podstawowy model semantyczny faktury	EN 16931-1:2026 §4	Oparte na nim; wystawca odpowiada za właściwe przepisy
Identyfikator specyfikacji (BT-24)	EN 16931-1:2026 BR-1	Sprawdzane (ostrzeżenie w COMPAT, błąd w STRICT)
Wiązanie składni UN/CEFACT CII	CEN/TS 16931-3-3:2020	Osadzanie obsługiwane
Wiązanie składni UBL 2.1	CEN/TS 16931-3-2:2020	Osadzanie obsługiwane
Plik powiązany PDF/A-3	ISO 19005-3:2012 §6.7.8	Nośnik obsługiwany
Plik osadzony PDF/A-4f	ISO 19005-4:2020 Annex A	Nośnik obsługiwany

Ta tabela rejestruje specyfikacje, na których opiera się NextPDF Enterprise, oraz co sprawdza. Nie jest to oświadczenie o certyfikacji, zatwierdzeniu przez organ podatkowy ani o wystarczalności regulacyjnej. Wystawca faktury odpowiada za spełnienie zasad właściwych przepisów; to nie jest walidator organu podatkowego.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje kryptograficznego podpisywania. Podpisywanie faktury hybrydowej oraz piecza nad kluczami w trybie FIPS są tutaj poza zakresem; zobacz moduł Signature.

Model zagrożeń

Podstawowym wejściem jest niezaufany XML faktury. Środki ograniczające: parsowanie bezpieczne wobec XXE, odrzucanie DOCTYPE, ograniczona dekompresja, procesor XSLT z wyłączonym ładowaniem zasobów sieciowych i plikowych oraz brak syntezowania deklaracji — wywołujący dostarcza i jest właścicielem treści faktury.

Kontrakt zachowania

• ZugferdEmbedder / PeppolEmbedder dołączają dostarczony przez wywołującego XML faktury do nośnika PDF/A-4f lub PDF/A-3b; NextPDF nigdy nie syntetyzuje XML faktury.
• InvoiceXmlValidator działa w trybie COMPAT (domyślnym; graniczna liczność EN 16931 jest ostrzeżeniem) lub STRICT (liczność BT-24 jest błędem krytycznym).
• SchematronValidator wykonuje prekompilowane zestawy reguł przez działający w procesie procesor XSLT i parsuje ustalenia SVRL; pusta lista ustaleń nie czyni niezgodnego ładunku zgodnym.
• Całe parsowanie XML jest bezpieczne wobec XXE: rozwiązywanie zewnętrznych encji wyłączone, DOCTYPE odrzucany, dekompresja ograniczona.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie zastępcze Core

NextPDF Core nie generuje ani nie waliduje ustrukturyzowanych faktur. Wdrożenie wyłącznie z Core może utworzyć plik PDF, ale nie ma osadzania ZUGFeRD / Factur-X / Peppol, walidatora EN 16931 ani silnika Schematron.

Rozwiązanie zastępcze Pro

We wdrożeniu wyłącznie z Pro obsługiwaną powierzchnią jest wykrywanie i walidacja e-faktur na poziomie Pro dla ładunków Factur-X / ZUGFeRD. Pro nie generuje nośników hybrydowych ZUGFeRD / Factur-X ani Peppol-UBL, nie dodaje profilu XRechnung CIUS i nie uruchamia działającego w procesie silnika Schematron; konfiguracja, która żąda generowania, profilu XRechnung CIUS lub Schematron we wdrożeniu wyłącznie z Pro, nie ma komponentu Enterprise, który by ją zaspokoił. Zobacz Pro Compliance dla powierzchni wykrywania i walidacji Pro.

Uwaga o granicy Enterprise

Wewnętrzne szczegóły mechanizmów pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica wdrożenia

Silnik Schematron wymaga rozszerzenia PHP ext-xsl; jego dostarczenie i włączenie należy do operatora. Przetwarzanie odbywa się w procesie i lokalnie; moduł nie wykonuje żadnych wychodzących połączeń sieciowych podczas osadzania ani walidacji. Krajowy transport e-faktur, platformy rozliczeniowe oraz systemy archiwizacyjne są zewnętrzne wobec tego modułu i należą do operatora.

Granica zgodności prawnej

NextPDF tworzy ustrukturyzowane faktury zgodne z modelem danych zdefiniowanym w EN 16931 i zgłasza ustalenia reguł. Nie tworzy „faktur zgodnych z prawem”, nie dostarcza wyników „zatwierdzonych przez organ podatkowy” i nie gwarantuje, że jakakolwiek faktura zostanie przyjęta przez organ podatkowy, sąd czy rejestr. Wystawca faktury odpowiada za spełnienie zasad właściwych przepisów; to nie jest walidator organu podatkowego. Krajowe platformy e-fakturowania, modele rozliczeniowe, nakazy archiwizacyjne oraz wymogi dotyczące podpisu cyfrowego różnią się w zależności od jurysdykcji i należą do wystawcy. Skonsultuj się z doradcami podatkowymi i prawnymi.

Zobacz także

• Dokumentacja Invoice — dokumentacja na poziomie API dla embedderów, walidatorów i silnika Schematron.
• Pro Compliance — wykrywanie i walidacja e-faktur na poziomie Pro.
• Document E-Filing — optymalizacja dostarczania do sądu/rejestru.
• Przegląd Enterprise
• Macierz funkcji: Core vs Pro vs Enterprise