Enterprise edycja

Invoice — szczegółowa referencja

W skrócie

Moduł Invoice ma trzy niezależne powierzchnie: osadzanie, walidację oraz wykonywanie reguł Schematron. ZugferdEmbedder i PeppolEmbedder dołączają dostarczony przez wywołującego XML faktury do nośnika PDF/A-4f lub PDF/A-3b i zwracają ustrukturyzowany wynik. InvoiceXmlValidator wykonuje strukturalną kontrolę wstępną EN 16931 z wybieralną wagą COMPAT lub STRICT. SchematronValidator wykonuje w procesie wstępnie skompilowane pakiety reguł Schematron i parsuje ustalenia SVRL. NextPDF nie generuje XML faktury; wywołujący dostarcza ładunek i jest jego właścicielem.

Dostępność i licencjonowanie

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

Niuans zależny od poziomu: wykrywanie i walidacja e-faktur to powierzchnia poziomu Pro (moduł Pro Compliance). Osadzanie hybrydowych faktur, profil XRechnung CIUS oraz silnik Schematron działający w procesie są dostępne wyłącznie w Enterprise. Poza granicą pakietu nextpdf/enterprise nie istnieje osobny kod funkcji dla poszczególnych możliwości.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Symbol	Parametry	Domyślne zachowanie	Zwraca	Rzuca lub kończy się niepowodzeniem	Uwagi
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Osadza XML CII profilu BASIC: kontrola XmlGuard, walidacja strukturalna, wstrzyknięcie schematu XMP, załącznik	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Szybka ścieżka; zalecany punkt startowy
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	Ten sam potok w profilu MINIMUM	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Szybka ścieżka
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Wejście budowniczego; odrzuca pusty XML	`self`	`InvalidArgumentException`	Konfiguracja przez `withoutValidation()`, `withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Nadpisuje domyślną relację `/Alternative`; bramkowane przez regulamin plików powiązanych	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` odrzucane dla faktur
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Końcowe wywołanie budowniczego: XmlGuard, opcjonalna walidacja, kontrola nośnika, XMP, załączenie	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Niepowodzenie walidacji nazywa pierwszy błąd
`ZugferdProfile` (enum)	—	Przypadki MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG dołącza `xrechnung.xml`; profile CII dołączają `factur-x.xml`
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Rejestruje opis RDF Factur-X oraz wpis schematu rozszerzenia PDF/A	`XmpMetadata`	Brak	Wywoływane przez `embed()`; można też użyć bezpośrednio
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Osadza XML faktury lub noty kredytowej Peppol BIS 3.0 UBL	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Domyślne nazwy plików `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Wejście budowniczego; odrzuca pusty XML lub nazwę pliku	`self`	`InvalidArgumentException`	Konfiguracja przez `withFilename()`, `withDescription()`, `withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Kontrola XmlGuard, kontrola nośnika, brama regulaminu, załączenie	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Ponowna kontrola regulaminu świadoma nośnika w czasie osadzania
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	Strukturalna kontrola wstępna EN 16931; domyślnie waga COMPAT	`InvoiceValidationResult`	Nie rzuca; niepowodzenia pojawiają się jako ustalenia błędów	Tryb rozstrzyga argument, następnie środowisko, następnie COMPAT
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	Kontrola elementu głównego i przestrzeni nazw dla ładunków CII	`bool`	Nie rzuca; zwraca `false`	Tania sonda wykrywająca
`InvoiceValidatorMode` (enum)	—	`COMPAT` (domyślny) utrzymuje ustalenia BT-24 przy ostrzeżeniu; `STRICT` podnosi je do błędu	—	—	`fromEnvironment()` wraca do COMPAT przy nieustawionych lub nierozpoznanych wartościach
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Niezmienne agregaty: `isValid`, `getErrors()`, `getWarnings()`; poziom, kod, komunikat na ustalenie	—	—	`InvoiceValidationResult::fail()` opakowuje pojedynczy błąd
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Wykonuje wstępnie skompilowany XSLT Schematron; parsuje SVRL do ustaleń	`SchematronResult`	`InvalidArgumentException` dla brakującego lub nieczytelnego XSLT; niepowodzenia silnika zwracają wynik błędu	Czas zmierzony w `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Adapter międzypoziomowy; mapuje ustalenia błędów na obiekty kontraktu `RuleViolation`	`list<RuleViolation>`	Jak `validate()`	Ustalenia poziomu info są pomijane
`SchematronResult` / `SchematronFinding`	—	Werdykt, ustalenia, czas trwania; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()` oznacza niepowodzenia silnika jako nieważne
`SchematronCacheInterface`	—	Kontrakt pamięci podręcznej z wykrywaniem manipulacji: `getVerified()`, `set()`, `computeKey()`	—	—	Zawodzi bezpiecznie przy niezgodności skrótu
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	Pamięć podręczna plików weryfikowana SHA-256 z zapisami atomowej zmiany nazwy	—	`InvalidArgumentException`, `SchematronCacheException`	Katalog musi istnieć lub być możliwy do utworzenia oraz zapisywalny
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	Przypięcia pakietów reguł zablokowane SHA-256: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` przy zniekształconym JSON blokady	Puste lub zniekształcone skróty zawodzą bezpiecznie
`InvoiceContractValidator`	`?SemanticValidator`	Adapter międzypoziomowy `ValidatorInterface`; kontrola strukturalna plus głębokie reguły semantyczne EN 16931	`ContractResult`	Zawodzi bezpiecznie; błędy silnika pojawiają się jako ustalenia błędów	Wiązany na ścieżkach frameworka, gdy zainstalowano `nextpdf/premium`
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Adapter międzypoziomowy `EmbedderInterface`; osadzanie bajty-wejście / bajty-wyjście	`string` (bajty PDF)	Propaguje niepowodzenia delegata	Deleguje do silnika przepisywania bajtów poziomu Pro
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Taksonomia niepowodzeń modułu	—	—	Wszystkie rozszerzają `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

Kontrakt zachowania

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. Obsługuje dwa nośniki: PDF/A-4f (ISO 19005-4:2020), preferowany nowoczesny nośnik, oraz PDF/A-3b (ISO 19005-3:2012) dla wstecznej kompatybilności. embed() zawsze najpierw wykonuje kontrolę bezpieczeństwa XmlGuard, następnie walidację strukturalną, chyba że ustawiono withoutValidation(), następnie weryfikuje, że nośnik obsługuje pliki osadzone, wstrzykuje deklarację schematu rozszerzenia XMP przez ZugferdXmpSchema i dołącza XML jako plik powiązany. Relacja załącznika domyślnie przyjmuje rekomendację regulaminu /Alternative; nadpisania przechodzą przez ten sam regulamin, który egzekwuje zestaw relacji ISO 32000-2:2020 §14.13 oraz podzbiór faktur EN 16931. PeppolEmbedder wykonuje operację równoważną dla dostarczonego przez wywołującego XML faktury lub noty kredytowej Peppol BIS Billing 3.0 UBL 2.1. Żaden z osadzaczy nie generuje XML faktury.

Walidacja. InvoiceXmlValidator sprawdza XML CII względem strukturalnych oczekiwań EN 16931: element główny, wymagane sekcje, krotność nagłówka, pozycje wierszy tam, gdzie wymaga tego profil, oraz identyfikator specyfikacji BT-24 nakazany regułą biznesową BR-1. InvoiceValidatorMode wybiera wagę. COMPAT (domyślny) raportuje brakujący lub niezgodny BT-24 jako ostrzeżenie, aby logiczna brama ważności nie uległa regresji. STRICT czyni z obu twardy błąd, a także sprawdza spójność profilu względem zadeklarowanego ZugferdProfile, odzwierciedlając semantykę zewnętrznych walidatorów KoSIT / Mustang. Tryb jest rozstrzygany w kolejności: jawny argument, następnie nadpisanie środowiskowe INVOICE_VALIDATOR_MODE, następnie COMPAT. Wyniki to ustrukturyzowane obiekty InvoiceValidationResult / InvoiceValidationFinding; walidator zwraca ustalenia, zamiast rzucać.

Schematron. SchematronValidator wykonuje wstępnie skompilowane zestawy reguł Schematron — reguły CEN EN 16931 .sch skompilowane do XSLT w czasie kompilacji — przy użyciu procesora XSLT PHP działającego w procesie. Parsuje raport SVRL do obiektów SchematronFinding / SchematronResult: nieudane asercje stają się ustaleniami błędów, udane raporty stają się ustaleniami info. Opcjonalna pamięć podręczna (SchematronCacheInterface, z implementacją plikową opartą na atomowej zmianie nazwy) serwuje zweryfikowane bajty arkusza stylów kluczowane skrótem treści oraz wersją kompilatora. VersionPinRegistry przypina każdy zewnętrzny pakiet reguł do wersji zablokowanej SHA-256 i zawodzi bezpiecznie przy dryfie lub zniekształconych skrótach.

Ten moduł wytwarza i sprawdza ustrukturyzowane dane faktury. Nie twierdzi, że jakikolwiek dokument jest prawnie zgodną fakturą, że jest zatwierdzony przez organ podatkowy ani że jego przyjęcie przez jakikolwiek organ jest gwarantowane. Walidator sprawdza wyłącznie model semantyczny EN 16931 oraz kontener ZUGFeRD / Factur-X / UBL; wyklucza rozszerzenia krajowe (na przykład włoskie SDI, francuskie Chorus Pro, niemiecki transport XRechnung). Jak stwierdza EN 16931-1, za spełnienie reguł odpowiedniego ustawodawstwa odpowiada wystawca faktury; nie jest to walidator organu podatkowego. Obsługa standardu nie jest zgodnością z nim.

Przypadki brzegowe i tryby awarii

Pusty XML zawodzi szybko: budowniczowie rzucają InvalidArgumentException; InvoiceXmlValidator::validate() zwraca wynik nieudany.
XmlGuard odrzuca deklaracje DOCTYPE, rozwijanie encji, nadmiarowe ładunki oraz znaki sterujące. Osadzacze przedstawiają to jako ZugferdEmbeddingException lub PeppolEmbeddingException z zachowaną przyczyną.
withoutValidation() i withoutSanitization() nigdy nie omijają kontroli bezpieczeństwa XmlGuard. Pominąć można wyłącznie strukturalne kontrole terminów biznesowych.
Nośnik bez obsługi plików osadzonych (jakikolwiek inny niż PDF/A-4f lub PDF/A-3b) zgłasza InvalidArgumentException z nazwami akceptowanych wersji.
Niedozwolona wartość AFRelationship jest odrzucana na granicy budowniczego; ponowna kontrola regulaminu świadoma nośnika przebiega jeszcze raz wewnątrz embed().
COMPAT utrzymuje brakujący BT-24 przy wadze ostrzeżenia; STRICT czyni brakujące oraz niezgodne z profilem wartości BT-24 twardymi błędami.
SchematronValidator rzuca wyłącznie dla brakującej lub nieczytelnej ścieżki XSLT. Niepowodzenia transformacji lub parsowania SVRL zwracają SchematronResult::error() z isValid równym false.
Wpis pamięci podręcznej, którego przechowywane bajty nie przejdą weryfikacji skrótu, jest usuwany, a arkusz stylów jest ponownie odczytywany z dysku; zatrute bajty nigdy nie są zwracane.
Procesor XSLT działa z zablokowanym wczytywaniem zasobów plikowych i sieciowych oraz nigdy nie rejestruje funkcji PHP; document(), xsl:include, xsl:import oraz result-document nie mogą wczytywać zasobów.
VersionPinRegistry odrzuca puste lub zniekształcone skróty SHA-256 podczas wczytywania i regeneracji; verifyArtefact() zwraca false zamiast przepuszczać nieweryfikowalne przypięcie.
Ten moduł nie wykonuje żadnego podpisywania kryptograficznego; zachowanie w trybie FIPS jest tutaj poza zakresem (zobacz moduł Signature).

Zgodność

Zachowanie	Odniesienie	Status
Podstawowy model semantyczny faktury	EN 16931-1:2026 §4	Zbudowane względem; wystawca pozostaje odpowiedzialny
Identyfikator specyfikacji (BT-24)	EN 16931-1:2026 BR-1	Ostrzeżenie w COMPAT, błąd w STRICT
Powiązanie składni UN/CEFACT CII	CEN/TS 16931-3-3:2020	Osadzanie obsługiwane
Powią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
Wartości relacji pliku powiązanego	ISO 32000-2:2020 §14.13	Bramkowane regulaminem
Parsowanie raportu Schematron / SVRL	ISO/IEC 19757-3	Zbudowane względem (oparte na produkcie; standard nieobecny w korpusie cytowań)

Zbudowane względem, a nie certyfikacja ani zatwierdzenie organu podatkowego. NextPDF nie posiada certyfikatu dla żadnego z tych standardów. NextPDF wytwarza ustrukturyzowane faktury zgodne z modelem danych EN 16931 i raportuje ustalenia reguł; nie wytwarza prawnie zgodnych faktur, nie dostarcza wyniku zatwierdzonego przez organ podatkowy ani nie gwarantuje przyjęcia. Skonsultuj się z własnymi doradcami podatkowymi i prawnymi.

Uwagi programistyczne

Silnik Schematron wymaga rozszerzenia PHP ext-xsl; jego udostępnienie i włączenie należy do odpowiedzialności operatora.
Przetwarzanie odbywa się w procesie i lokalnie. Podczas osadzania ani walidacji nie występują wychodzące wywołania sieciowe. Krajowy transport e-fakturowania, platformy rozliczeniowe oraz systemy archiwalne są zewnętrzne wobec tego modułu.
Pakiety reguł są kompilowane z .sch do XSLT w czasie kompilacji; środowisko uruchomieniowe wykonuje wyłącznie wstępnie skompilowane arkusze stylów.
Klucze pamięci podręcznej uwzględniają sól wersji kompilatora (obecnie nextpdf-schxslt-1.0); jej podbicie unieważnia wdrożone pamięci podręczne bez kroku czyszczenia.
Przypięcia pakietów reguł znajdują się w pliku blokady enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); CI weryfikuje wdrożone artefakty względem przypiętych skrótów.
Wywołujący międzypoziomowo używają InvoiceContractValidator oraz ZugferdContractEmbedder; wywołujący natywni dla poziomu Enterprise używają ZugferdEmbedder oraz InvoiceXmlValidator bezpośrednio.

Granica publikacji

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

Zobacz też

Możliwość Invoice — odpowiednik tej referencji na poziomie możliwości.
Pro Compliance — wykrywanie/walidacja na poziomie Pro.
Document E-Filing
Przegląd Enterprise