Faktury i fakturowanie elektroniczne

SpecSpec: EN 16931-1:2026, BT-24EN 16931-1:2026 BT-24SpecSpec: Factur-X 1.08Factur-X 1.08SpecSpec: ISO 32000-2:2020, §14.13ISO 32000-2:2020 §14.13

W skrócie

Nowoczesna faktura łączy w jednym pliku dwa dokumenty: stronę czytelną dla człowieka oraz odczytywalny maszynowo ładunek XML analizowany przez system podatkowy. Ta strona prowadzi przez scenariusz faktury hybrydowej od obowiązku po wynik: czego wymagają ZUGFeRD i Factur-X, jak NextPDF dołącza i sprawdza ustrukturyzowany ładunek oraz gdzie zgodność przestaje być zadaniem silnika, a staje się odpowiedzialnością wystawcy.

Dlaczego to ważne

Kilka jurysdykcji wymaga już ustrukturyzowanych faktur w rozliczeniach między przedsiębiorstwami (B2B) lub między przedsiębiorstwem a administracją (B2G). Pułapka polega na tym, że faktura hybrydowa może wyglądać idealnie na ekranie, a mimo to zostać odrzucona. Odrzucany jest osadzony XML, nie piksele. Jeśli w ustrukturyzowanym ładunku brakuje identyfikatora specyfikacji, deklaruje on niewłaściwy profil albo jest dołączony z niewłaściwą relacją, platforma odbiorcza go odrzuci. Po stronie wystawcy niepowodzenie często pozostaje niezauważone i ujawnia się kilka dni później, blokując przy tym płatność.

Poprawne zrobienie tego raz, w warstwie tworzącej plik, jest znacznie tańsze niż odkrywanie problemu osobno przy każdej rozliczanej fakturze.

Wersja skrócona

• Zgodna faktura hybrydowa to nośnik PDF/A ze zgodnym ładunkiem XML osadzonym jako plik powiązany. Metadane nośnika muszą deklarować profil.
• Pole, które najczęściej decyduje o akceptacji, to BT-24, identyfikator specyfikacji. Norma EN 16931, a konkretnie reguła biznesowa BR-1, wymaga, aby zawierała go każda faktura. Jego wartością jest URN wskazujący dokładny profil — na przykład w profilu EN 16931 (COMFORT) jest to urn:cen.eu:en16931:2017.
• Zadaniem NextPDF jest osadzanie i walidacja strukturalna XML dostarczonego przez wywołującego. Silnik nie tworzy treści faktury i nie jest walidatorem organu podatkowego.
• Za poprawność prawną i podatkową nadal odpowiada wystawca. Pomyślny wynik walidacji jest jednym z elementów tej decyzji, a nie certyfikatem.

Jak podchodzi do tego NextPDF

NextPDF traktuje ustrukturyzowaną fakturę jako kontrakt obejmujący wiele warstw, a nie pojedynczą funkcję. Silnik podstawowy definiuje interfejsy — moduł osadzający, deskryptor profilu, walidator — a warstwa Premium dostarcza implementacje. Ten podział jest celowy. Publiczny interfejs jest zamrożony w warstwie podstawowej, więc miejsca wywołań i testy odwołują się do profilu i wyniku w ten sam sposób, niezależnie od warstwy, która za nimi stoi.

Przepływ ma cztery etapy, a ich kolejność ma znaczenie, ponieważ każdy etap zależy od poprzedniego.

1. Author the invoice XMLYou (or your ERP) produce a UN/CEFACT CII or Peppol UBL payload. NextPDF never synthesizes invoice content.
2. Produce the PDF/A carrierA PDF/A-3 or PDF/A-4f document is the human-readable face and the conformant container the standard requires.
3. Embed the payloadThe embedder attaches the XML as an associated file with the correct AFRelationship, and injects the Factur-X XMP profile declaration.
4. Validate, then shipA structural pass checks the root, the required sections, and BT-24 against the declared profile before the file leaves your system.

Kompleksowy scenariusz hybrydowej e-faktury: ty tworzysz XML i odpowiadasz za jego poprawność prawną; NextPDF go przenosi i sprawdza strukturalnie; platforma odbiorcza podejmuje ostateczną decyzję o akceptacji.

Kontrakt modułu osadzającego działa na zasadzie bajty na wejściu, bajty na wyjściu: na wejściu trafiają nośnik PDF/A i ładunek XML, a na wyjściu powstają bajty hybrydowego PDF. Zanim cokolwiek zostanie dołączone, XML jest analizowany przez zabezpieczoną warstwę, która odrzuca DOCTYPE, ogranicza rozmiar wejścia i odmawia przyjęcia znaków sterujących zabronionych w XML 1.0. Z założenia eliminuje to ataki XML External Entity oraz Billion Laughs, ponieważ XML faktury często pochodzi spoza granicy zaufania systemu.

Deskryptor profilu odpowiada na cztery pytania, które zadaje dalsza część systemu: kanoniczny URN profilu, wartość BT-24 do zadeklarowania, stabilna nazwa do dzienników oraz neutralny względem warstwy wyróżnik, dzięki któremu testy parytetu mogą grupować wyniki. Deskryptor jawnie wskazuje braki. Profil ZUGFeRD MINIMUM nie zawiera identyfikatora specyfikacji BT-24, a deskryptor zwraca dla niego null zamiast go sztucznie tworzyć. To również powód, dla którego MINIMUM i BASIC WL nie są zgodne z EN 16931. Silnik odwzorowuje rzeczywistość krotności, zamiast ją ukrywać.

Human-factors note:Human-factors note

Walidator ma dwa tryby, a domyślny jest zachowawczy. W trybie domyślnym brakujące BT-24 jest zgłaszane jako ostrzeżenie, aby istniejący potok oparty na wartości logicznej nie uległ niezauważalnej regresji. Tryb ścisły traktuje to samo wykrycie jako twardy błąd, zgodnie z semantyką zewnętrznych walidatorów. Tryb jest świadomym wyborem dokonywanym przy każdym wywołaniu. Silnik nie wybiera za ciebie nastawienia do ryzyka; informuje, które nastawienie jest aktywne, zamiast zostawiać to domysłom.

Praktyczny przykład

Poniższy szkic ilustruje punkt integracji, a nie integrację gotową do skopiowania. Konstrukcja nośnika i moduł osadzający pochodzą z warstwy Premium, a XML pozostaje po stronie wywołującego.

<?php

declare(strict_types=1);

use NextPDF\Contracts\EInvoice\ProfileType;
use NextPDF\Contracts\EInvoice\ValidatorContext;
use NextPDF\Contracts\EInvoice\ValidatorInterface;
use NextPDF\Contracts\EInvoice\EmbedderInterface;
use NextPDF\Contracts\EInvoice\EmbedderOptions;
use Psr\Log\LoggerInterface;

/**
 * Validate first, embed second, never ship an invalid payload.
 *
 * @param non-empty-string $carrierPdf  PDF/A-3 or PDF/A-4f carrier bytes
 * @param non-empty-string $ciiXml      Caller-authored UN/CEFACT CII XML
 *
 * @return non-empty-string Hybrid invoice bytes, ready to deliver
 */
function buildHybridInvoice(
    ValidatorInterface $validator,
    EmbedderInterface $embedder,
    LoggerInterface $logger,
    string $carrierPdf,
    string $ciiXml,
): string {
    // STRICT mode: a missing BT-24 is a hard error, not a warning.
    $context = new ValidatorContext(
        profile: ProfileType::EN16931,
        strictMode: true,
    );

    $result = $validator->validate($ciiXml, $context);

    if (!$result->isValid) {
        foreach ($result->getErrors() as $finding) {
            $logger->error('invoice.structural_finding', [
                'message' => $finding->message,
            ]);
        }

        // A failed structural check is your signal to stop, not to ship.
        throw new \RuntimeException('Invoice XML failed structural validation.');
    }

    $options = new EmbedderOptions(profile: ProfileType::EN16931);

    return $embedder->embed($carrierPdf, $ciiXml, $options);
}

Krytyczna jest kolejność. Walidacja jest tania w porównaniu z odrzuconą fakturą i opóźnioną płatnością, więc uruchamia się ją, zanim ładunek w ogóle zostanie dołączony.

Częste nieporozumienie

Najkosztowniejsze nieporozumienie to „NextPDF sprawia, że moje faktury są zgodne.” Tak nie jest. Ta strona mówi to wprost. Silnik osadza i sprawdza strukturalnie XML, który tworzysz. Pomyślny wynik walidacji strukturalnej oznacza, że ładunek ma strukturę, której oczekuje EN 16931, i deklaruje profil, którego żądasz. Nie oznacza to jednak, że faktura spełnia wymogi prawne, została zatwierdzona przez organ podatkowy ani że ma gwarancję przyjęcia przez jakąkolwiek platformę rozliczeniową. Rozszerzenia krajowe i transporty rozliczeniowe są poza zakresem na poziomie silnika. Jak ujmuje to sama EN 16931-1, model rdzeniowy zawiera informacje potrzebne do wspierania zgodności. Za spełnienie odpowiednich przepisów odpowiada wystawca.

Druga, mniej oczywista pułapka: obsługa normy nie jest zgodnością z nią. Zgodność jest właściwością ostatecznego pliku w zestawieniu z walidatorem, a nie właściwością biblioteki, która go utworzyła.

Ograniczenia i granice

• NextPDF nie tworzy ani nie poprawia treści faktury. Wywołujący dostarcza prawidłowy XML i pozostaje wystawcą faktury. Brak wykryć nie czyni niezgodnego ładunku zgodnym.
• Osadzanie danych strukturalnych i walidacja Schematron to możliwości warstwy Premium. Warstwa podstawowa definiuje kontrakty; implementacje wymagają pakietu komercyjnego. Zobacz granicę poniżej.
• Walidator sprawdza wyłącznie model semantyczny EN 16931 oraz kontener ZUGFeRD / Factur-X / UBL. Nie jest walidatorem organu podatkowego. Transporty SDI, Chorus Pro i XRechnung są poza zakresem na poziomie transportu.
• Profile MINIMUM i BASIC WL nie są zgodne z EN 16931 i nie zawierają identyfikatora specyfikacji BT-24 — z założenia; odzwierciedla to krotność określoną w normie, a nie ograniczenie silnika.
• Silnik Schematron wymaga ext-xsl. Zestawy reguł są kompilowane na etapie budowania. Środowisko uruchomieniowe wykonuje tylko wstępnie skompilowany XSLT, z wyłączonym ładowaniem zasobów z sieci i systemu plików.
• Ta strona opisuje zachowanie na poziomie możliwości. Nie potwierdza akceptacji przez żaden konkretny organ ani platformę.

Structured e-invoice embedding and validation — edition availability

Edition	Availability
Core	○ Warstwa podstawowa definiuje kontrakty obejmujące wiele warstw (EmbedderInterface, ProfileInterface, ValidatorInterface), ale nie dostarcza implementacji ustrukturyzowanej faktury. Zwykły nośnik PDF bez ustrukturyzowanego ładunku to wynik dostępny tylko w warstwie podstawowej.
Pro	○ Osadzanie CII Factur-X 1.08 w nośniku PDF/A oraz deskryptory profilu EN 16931 są dostępne.
Enterprise	○ Dodaje osadzanie UBL Peppol BIS 3.0, CIUS XRechnung B2G, walidację XML COMPAT/STRICT oraz wbudowany silnik reguł Schematron.

Powiązane dokumenty

• Archiwizacja i PDF/A — dlaczego nośnikiem faktury jest plik PDF/A oraz co gwarantuje dla długoterminowej czytelności.
• Przewodnik po decyzjach integracyjnych — który pakiet ekosystemu pasuje do potoku fakturowania (generowanie w kolejce, mostek frameworka lub Connect).
• Eksploatacja NextPDF w środowisku produkcyjnym — jak monitorować wykrycia i niepowodzenia walidacji, gdy faktury przechodzą przez system na dużą skalę.

Słownik pojęć

• Faktura hybrydowa — pojedynczy plik PDF, który jest jednocześnie stroną czytelną dla człowieka oraz osadzonym, odczytywalnym maszynowo ładunkiem XML faktury.
• ZUGFeRD / Factur-X — niemiecka i francuska nazwa tego samego podejścia do faktury hybrydowej: ładunek XML UN/CEFACT Cross Industry Invoice (CII) osadzony w nośniku PDF/A.
• EN 16931 — europejska norma definiująca semantyczny model danych podstawowych elementów faktury elektronicznej.
• BT-24 (identyfikator specyfikacji) — termin biznesowy EN 16931, którego wartością jest URN wskazujący dokładny profil, z którym faktura jest zgodna. Wymagany przez regułę biznesową BR-1.
• Profil — nazywany też poziomem zgodności (MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED, XRECHNUNG). Określa, które terminy biznesowe musi zawierać faktura.
• Plik powiązany — plik osadzony w PDF z zadeklarowaną relacją (AFRelationship) opisującą, jak odnosi się do widocznego dokumentu; mechanizm przenoszący XML faktury.
• Schematron — język reguł używany do wyrażania reguł biznesowych EN 16931. NextPDF uruchamia zestawy reguł CEN skompilowane do XSLT.