Oprogramowanie do e-faktur dla programistów: XRechnung, Factur-X, Peppol

Wygenerowanie poprawnego pliku XML zgodnego z EN 16931 to mała część e-fakturowania, a dobra biblioteka zrobi to za Państwa w tydzień. Duża część to wszystko wokół pliku: nadążanie za krajowymi zestawami reguł, które ciągle się zmieniają, walidacja względem Schematronu kraju nabywcy, wybór właściwego profilu i składni dla każdego nabywcy, transport dokumentu przez Peppol, platformę akredytowaną lub KSeF, przechowywanie faktury w postaci wystawionej przez okres retencji oraz to samo w drugą stronę dla tego, co przysyłają Państwa dostawcy. Budować należy wtedy, gdy e-fakturowanie jest Państwa produktem; kupić — lub zintegrować przez API — gdy jest Państwa obowiązkiem.

Czego naprawdę wymaga od Państwa norma

EN 16931 definiuje semantyczny model faktury oraz dwie składnie XML, które go przenoszą; każdy format krajowy w Europie Zachodniej i Środkowej jest albo ograniczonym profilem tego modelu, albo — w przypadku Polski — odrębnym schematem. Aby go wdrożyć, potrzebują Państwo modelu, powiązania ze składnią oraz nałożonych na to reguł krajowych.

Strona Komisji dotycząca pozyskania normy wymienia jej części: „semantyczny model danych (EN 16931-1: 2017)" oraz „dwie obowiązkowe składnie zgodne z normą (CEN/TS 16931-2: 2017)" są dostępne bezpłatnie za pośrednictwem krajowych jednostek normalizacyjnych, natomiast „kopie pozostałych części (3-6) normy, obejmujących powiązania składniowe, wytyczne i metodologie, są sprzedawane". Dwie składnie to UBL 2.1 (część 3-2) i UN/CEFACT CII D16B (część 3-3). Do tego dochodzą:

• Niemcy — XRechnung, krajowa specyfikacja KoSIT, z własnym Schematronem i ograniczeniami list kodów; oraz ZUGFeRD, hybrydowy PDF/A-3 z osadzonym CII. Od 2027 r. przedsiębiorstwa o obrocie powyżej 800 000 EUR „nie będą już mogły wystawiać faktur papierowych ani używać nieustrukturyzowanych formatów elektronicznych"; wszystkie przedsiębiorstwa od 2028 r.
• Francja — Factur-X, „francusko-niemiecki standard hybrydowej faktury elektronicznej (PDF dla użytkowników i dane XML do automatycznego przetwarzania)", technicznie „ten sam standard co ZUGFeRD 2.5", a także UBL i CII, wymieniane przez platformy akredytowane, które ministerstwo nazywa „obowiązkowym pośrednikiem między przedsiębiorstwami".
• Belgia — Peppol BIS Billing 3.0, CIUS normy EN 16931 w UBL 2.1; „każdy dokument zgodny z tą specyfikacją będzie zgodny z normą europejską (EN 16931)".
• Polska — FA(3), krajowy schemat XML przesyłany do KSeF, „obowiązkowy dla wszystkich przedsiębiorców" od 1 kwietnia 2026 r., z wyjątkiem najmniejszych, którzy dołączają 1 stycznia 2027 r.

Formaty są szczegółowo porównane na stronie formatów; sam model — na stronie EN 16931.

Co daje biblioteka, a czego nie

Biblioteka zamienia Państwa obiekt faktury na XML (lub hybrydowy PDF), a lepsze z nich uruchamiają także Schematron. Nie zna kraju Państwa nabywcy, Państwa rozstrzygnięcia VAT, sekwencji numeracji ani okresu retencji i niczego nigdzie nie dostarcza.

Decyzja o budowie to w istocie decyzja o wzięciu na siebie środkowych wierszy tej tabeli. Dla firmy, której produktem jest fakturowanie, to właściwy wybór. Dla SaaS lub firmy usługowej, która musi wystawić pięćdziesiąt poprawnych faktur miesięcznie w trzech krajach, to drugi produkt, o który nikt nie prosił.

Walidacja: reguły się zmieniają, a walidator nabywcy ma ostatnie słowo

Faktura jest poprawna wtedy, gdy tak orzeknie walidator odbiorcy, a odbiorcy stosują krajowe zestawy reguł. Należy walidować względem nich, a nie względem „poprawnie sformułowanego XML", i walidować ponownie po zmianie zestawu reguł — zarówno KoSIT, jak i OpenPeppol publikują zaktualizowane pakiety reguł w regularnych cyklach wydawniczych.

Narzędziem referencyjnym dla Niemiec jest walidator KoSIT, silnik open source, który „identyfikuje faktyczny format XML, waliduje plik XML (przy użyciu schematu i reguł Schematron), generuje niestandardowy raport / wyodrębnia niestandardowe dane z pliku XML, wylicza status akceptacji", sterowany konfiguracjami scenariuszy dla XRechnung i EN 16931. Działa z wiersza poleceń, osadzony w Javie lub jako demon HTTP, na licencji Apache 2.0 — co czyni go dobrym krokiem CI niezależnie od tego, czy Państwo budują, czy kupują. Peppol BIS Billing 3.0 dostarcza swój Schematron w dwóch zestawach: „reguły biznesowe transakcji Peppol" i „reguły biznesowe transakcji EN 16931"; oba muszą przejść. Formaty hybrydowe waliduje się dwukrotnie: osadzony XML względem profilu, a kontener względem PDF/A-3.

Niezależnie od wyboru warto mieć w pipeline niezależny walidator. Bezpłatne narzędzie do sprawdzania e-faktur waliduje plik względem reguł danego kraju bez jego zapisywania, co wystarcza do kontroli wyrywkowej; walidator KoSIT w CI to solidniejszy nawyk. Szczegóły na poziomie programisty — terminy biznesowe, identyfikatory reguł, częste błędy — znajdują się w przewodniku EN 16931 dla programistów.

Transport: trzy sieci, trzy różne problemy

Wytworzenie pliku to ten sam problem w każdym kraju; dostarczenie go — nie. Peppol to sieć czterech narożników, do której dołącza się przez punkt dostępowy; francuski system kieruje faktury B2B przez platformy akredytowane; polski KSeF to centralna platforma rządowa, która nadaje fakturze jej tożsamość prawną.

Peppol (Belgia oraz transgranicznie)

Nie rozmawiają Państwo z nabywcą; Państwa punkt dostępowy rozmawia z jego punktem po wyszukaniu identyfikatora uczestnika nabywcy. Zbudowanie własnego punktu dostępowego oznacza akredytację w OpenPeppol i utrzymywanie infrastruktury SMP/AS4; niemal każda firma zamiast tego zawiera umowę z dostawcą punktu dostępowego i integruje się z jego API. Zob. Peppol oraz przewodnik Peppol dla programistów.

Platformy akredytowane (Francja)

Tylko plateforme agréée może przesyłać między przedsiębiorstwami i do organu podatkowego. Dostawca oprogramowania albo sam nią zostaje — w procesie rejestracji w administracji — albo integruje się z jedną z nich. Zob. platformy akredytowane.

KSeF (Polska)

Uwierzytelniają się Państwo, otwierają sesję, przesyłają XML FA(3) i otrzymują numer KSeF oraz Urzędowe Poświadczenie Odbioru (UPO); faktura jest prawnie wystawiona z chwilą przyjęcia jej przez KSeF, a nie z chwilą wygenerowania. Platforma ma odrębne środowiska testowe i produkcyjne, a zachowanie potwierdzone w jednym nie dowodzi działania w drugim. Zob. KSeF.

Niemcy

Brak narzuconej sieci: e-mail, pobranie lub Peppol są dopuszczalnymi kanałami dla XRechnung i ZUGFeRD w B2B. Obowiązek dotyczy formatu, a nie transportu.

Archiwizacja: wystawiony plik, niezmieniony, przez lata

Fakturą, którą muszą Państwo przechowywać, jest ustrukturyzowany plik w postaci wystawionej — nie jego wizualizacja w PDF ani kopia wygenerowana ponownie z dzisiejszych danych. Przepisy UE pozostawiają formę przechowywania otwartą („przedsiębiorstwa mogą co do zasady dowolnie wybierać, gdzie i jak przechowują faktury"), ale każdy kraj ustala okres retencji i wymagania dostępu dla kontroli, a tam, gdzie faktura została wystawiona jako ustrukturyzowany XML, to właśnie XML — a nie jego wizualizacja — jest fakturą.

Dla budującego oznacza to: przechowywać dokładnie te bajty, które zostały wysłane, wraz z hashem, obok raportu walidacji oraz — dla Peppol lub KSeF — potwierdzenia transportu; nigdy nie generować ponownie; uczynić archiwum czytelnym bez Państwa aplikacji. Okresy retencji i dopuszczalne miejsce przechowywania dla Państwa podmiotu wymagają potwierdzenia przez specjalistę.

Jak KRONENWERK to obsługuje

KRONENWERK to system księgowy, który generuje i waliduje e-fakturę w chwili wystawienia, z API dla przepływów wokół niej. To kolumna „kupić / zintegrować" z powyższej tabeli, z podanymi ograniczeniami transportu. Obsługiwane z ograniczeniami

• Generowanie i walidacja przy wystawieniu. Niemcy: XRechnung i ZUGFeRD, walidowane regułami Schematron KoSIT i sprawdzane krzyżowo biblioteką Mustang. Francja: Factur-X (PDF/A-3 z osadzonym CII). Belgia: Peppol BIS Billing 3.0 UBL. Polska: XML FA(3) dla KSeF. Profil i składnia wynikają z kraju nabywcy; rozstrzygnięcie VAT i sprawdzenie w VIES odbywają się w tym samym kroku.
• Odbieranie. Przychodzące XRechnung, ZUGFeRD/Factur-X i UBL są wczytywane jako faktury zakupowe.
• Transport. Wysyłanie i odbieranie przez Peppol za pośrednictwem akredytowanego dostawcy punktu dostępowego (Storecove), po podłączeniu firmy w Ustawienia → Doręczanie — KRONENWERK sam nie jest punktem dostępowym. Obsługiwane z ograniczeniami. Przesyłanie we Francji jest planowane przez funkcję platformy akredytowanej Storecove i nie jest jeszcze gotowe produkcyjnie — KRONENWERK nie jest plateforme agréée. Jeszcze niegotowe. Moduł KSeF 2.0 (uwierzytelnianie tokenem, sesja, przesyłanie FA(3), pobieranie UPO, odbieranie) jest zbudowany i zależny od środowiska, nie był używany z produkcyjnym KSeF, a KRONENWERK nie sprzedaje obecnie subskrypcji polskim firmom. Jeszcze niegotowe w zakresie przesyłania.
• API. Państwa aplikacja tworzy klientów i projekty faktur pod adresem https://kronenwerk.org/api/extern/v1 (POST /customers, POST /invoices/drafts, z Idempotency-Key); wystawienie — krok, który nadaje numer, generuje e-fakturę i uruchamia walidację — odbywa się w produkcie po walidacji. Webhooki zgłaszają invoice.issued, invoice.paid i invoice.cancelled. Warto zacząć od szybkiego startu; perspektywa e-fakturowania jest na stronie API e-fakturowania.