API e-fakturowania: XRechnung, ZUGFeRD, Factur-X, Peppol BIS, FA(3)

KRONENWERK nie ma osobnego punktu końcowego „generowania e-faktury”. Ustrukturyzowane e-faktury są tworzone i walidowane w chwili wystawienia faktury w produkcie, w formacie wymaganym przez kraj sprzedawcy: XRechnung lub ZUGFeRD w Niemczech, Factur-X we Francji, Peppol BIS Billing 3.0 UBL w Belgii, XML FA(3) w Polsce. Państwa integracja tworzy szkic za pomocą POST /invoices/drafts i otrzymuje invoice.issued, gdy zwalidowany dokument istnieje. Niezależnie od tego bezpłatny, anonimowy walidator pod adresem POST /api/v1/meta/pruefen sprawdza dowolny plik według reguł danego kraju i niczego nie zapisuje.

Jak formaty ustrukturyzowane powstają ze szkicu

Szkic zawiera fakty: sprzedawcę, nabywcę, pozycje, daty, walutę. Gdy osoba go wystawia, moduł krajowy podmiotu prawnego sprzedawcy przekształca te fakty w dokument oczekiwany przez dany kraj i waliduje wynik, zanim numer faktury zostanie zużyty. Te same fakty tworzą PDF dla czytelnika i plik ustrukturyzowany dla maszyny; która składnia ustrukturyzowana i który profil zostaną użyte, zależy od kraju i ustawień firmy.

1. Wynik weryfikacji podatkowej jest obliczany na podstawie faktów (kraj sprzedawcy i nabywcy, przedsiębiorca czy konsument, rodzaj świadczenia), a numer VAT nabywcy jest sprawdzany w VIES. Wynik „wymaga decyzji” zatrzymuje wystawienie do czasu decyzji osoby.
2. Moduł krajowy renderuje dokument ustrukturyzowany — UBL, CII, PDF/A-3 z osadzonym CII lub XML FA(3).
3. Dokument jest walidowany według reguł publikowanych przez dany kraj. Dokument niemiecki przechodzi przez reguły Schematron KoSIT i jest krzyżowo sprawdzany biblioteką Mustang; uruchomione walidatory są zapisywane razem z wynikiem.
4. Dopiero po pomyślnej walidacji numer zostaje zużyty, wiersz archiwum zamrożony, a invoice.issued zakolejkowane do Państwa punktu końcowego webhooka.

Dlatego API zatrzymuje się na szkicu. Dokument, który nie przechodzi walidacji, to dokument, który musi poprawić człowiek, a pola decydujące o formacie są ustawieniami podmiotu prawnego, a nie parametrami żądania. Uzasadnienie przedstawiono na stronie API faktur.

Zachowanie przy wystawianiu w zależności od kraju

XRechnung, ZUGFeRD, Factur-X i Peppol BIS są implementacjami europejskiego modelu semantycznego EN 16931; ZUGFeRD i Factur-X to technicznie ten sam standard hybrydowy, publikowany wspólnie przez FeRD i FNFE-MPE. FA(3) jest własnym schematem Polski i nie jest składnią EN 16931. Formaty porównano na stronie formaty e-faktur; niemiecki wybór wyjaśniono na stronie XRechnung a ZUGFeRD.

Co API udostępnia w zakresie e-faktur

Mniej, niż można by oczekiwać, a lista jest dokładna.

• POST /invoices/drafts rozpoczyna szkic, który stanie się dokumentem ustrukturyzowanym. Przyjmuje wyłącznie customerId.
• GET /invoices i GET /invoices/{number} zwracają zamrożone dane wystawionej faktury: number, documentType, buyer, currency, issuedOn, dueOn, deliveredOn, net, tax, gross, outstanding, paymentState, overdue, cancelled, creditNote, paidOn, recordedAt.
• Webhook invoice.issued informuje, że istnieje już zwalidowany dokument, podając invoiceId, number, documentType, buyerName, issueDate, dueDate, currency, netMinor, taxMinor, grossMinor, amountDueMinor oraz paymentState.

Nieudostępniane i nieosiągalne w żadnym zakresie uprawnień: sam plik XML lub PDF, raport walidacji wystawionej faktury, uzasadnienie wyniku weryfikacji podatkowej, stan przesyłania Peppol lub KSeF oraz jakikolwiek punkt końcowy, który wystawia, wysyła lub anuluje. Pliki pobiera się w produkcie; przesyłanie konfiguruje się i obserwuje tam. To, czy przyszła wersja API doda pobieranie plików, nie jest tu obiecywane.

Bezpłatny walidator: POST /api/v1/meta/pruefen

Walidator sprawdza jeden plik według reguł jednego kraju i odpowiada ustrukturyzowanym werdyktem. Nie wymaga konta ani klucza API i niczego nie zachowuje — ani pliku, ani skrótu, ani wiersza w bazie. Istnieje, ponieważ każde niemieckie przedsiębiorstwo musi od 1 stycznia 2025 r. przyjmować ustrukturyzowane e-faktury, a większość nie ma jak sprawdzić, czy ta, która właśnie przyszła, jest poprawna; pobieranie opłaty za tę kontrolę byłoby pobieraniem opłaty za samą zgodność z prawem. Wersja przeglądarkowa znajduje się na stronie sprawdź e-fakturę.

Żądanie to multipart/form-data z dwiema częściami: datei (plik) i land (kod ISO kraju, którego reguły mają zastosowanie: DE, FR, BE, PL, CA lub US). Kraj jest wymagany. Wcześniej domyślnie były to Niemcy, a belgijska faktura sprawdzona według niemieckich reguł otrzymuje pewną siebie odpowiedź, która jest z całą pewnością błędna.

curl -X POST https://kronenwerk.org/api/v1/meta/pruefen \
  -F "datei=@rechnung.xml" \
  -F "land=DE"

{
  "istERechnung": true,
  "lesbar": true,
  "gueltig": false,
  "format": "XRechnung (UBL)",
  "profil": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
  "zusammenfassung": "…",
  "lieferant": "Beispiel GmbH",
  "nummer": "2026-0041",
  "rechnungsdatum": "2026-08-28",
  "waehrung": "EUR",
  "nettoMinor": 89000,
  "steuerMinor": 16910,
  "bruttoMinor": 105910,
  "fehler": [
    { "schwere": "…", "quelle": "…", "regel": "BR-DE-15", "ort": "…", "meldung": "…" }
  ],
  "hinweise": [],
  "leseprobleme": [],
  "validatoren": ["KoSIT validationtool …", "…"]
}

Trzy wartości logiczne odpowiadają na trzy różne pytania. istERechnung: czy to w ogóle ustrukturyzowana e-faktura, a nie zwykły PDF lub obraz. lesbar: czy dokument dało się wczytać jako fakturę. gueltig: czy spełnia reguły danego kraju. Zwykły PDF to istERechnung: false, a nie błąd. fehler i hinweise to listy ustaleń, każde z wagą, walidatorem, który je zgłosił, identyfikatorem reguły, lokalizacją i komunikatem. leseprobleme wymienia problemy z wyodrębnianiem, validatoren — walidatory, które faktycznie się uruchomiły, aby częściowa kontrola była widoczna jako częściowa. Sumy są obecne tylko wtedy, gdy dokument się bilansuje; dokument, który się nie bilansuje, jest już ustaleniem, a brak sumy jest lepszy niż zgadywanie. Wartości format, profil i zusammenfassung zależą od pliku i powyżej są poglądowe.

Ograniczenia walidatora

• Pliki większe niż 25 MB są odrzucane z kodem 413, zanim zostanie sparsowany choć jeden bajt. Prawdziwa e-faktura z osadzonym XML ma kilkaset kilobajtów.
• Żądania są limitowane per adres klienta: pula 5 kontroli, uzupełniana o jedną kontrolę co 60 sekund. Po jej wyczerpaniu odpowiedzią jest 429 z nagłówkiem Retry-After i treścią JSON informującą, jak długo czekać. Walidator jest narzędziem dla ludzi i okazjonalnych skryptów, a nie usługą masowej walidacji.
• Nic nie jest zapisywane, więc nie ma historii ani linku, do którego można wrócić. Jeśli odpowiedź jest Państwu potrzebna, należy ją zachować.
• Walidator waliduje; nie rozstrzyga kwestii prawnych. To, czy dokument, który przeszedł kontrolę, jest również prawidłową fakturą dla celów VAT w Państwa sytuacji, wymaga potwierdzenia przez specjalistę.

Odbiór faktur ustrukturyzowanych

Te same czytniki, które stoją za walidatorem, są używane wewnątrz produktu: przychodzące dokumenty XRechnung, ZUGFeRD/Factur-X i UBL są wczytywane jako faktury zakupu z dostawcą, numerem, datą i sumami, a wynik ich walidacji jest zapisywany razem z fakturą zakupu. Ta ścieżka przychodząca nie jest dziś udostępniona w publicznym API; faktury zakupu zarejestrowane w produkcie są raportowane na zewnątrz przez webhook purchase.recorded z polami purchaseId, kind, documentNumber, supplierName, supplierId, documentDate, dueDate, currency, netMinor, taxMinor i grossMinor. Niemieckie obowiązki odbioru wyjaśniono na stronie odbiór e-faktur w Niemczech.

Jak KRONENWERK to obsługuje

OBSŁUGIWANE Z OGRANICZENIAMI Generowanie i walidacja XRechnung, ZUGFeRD, Factur-X, Peppol BIS UBL i FA(3) przy wystawianiu są częścią produktu (e-fakturowanie). Udziałem API w tym procesie są szkic, odczyt zwrotny i webhook, w planie Enterprise (cennik). Walidator jest bezpłatny dla wszystkich. Ograniczenia dotyczą transportu: wysyłanie i odbieranie przez Peppol odbywa się za pośrednictwem akredytowanego dostawcy punktu dostępowego (Storecove) po podłączeniu firmy w Ustawienia → Dostarczanie — KRONENWERK sam nie jest punktem dostępowym Peppol; francuskie przesyłanie przez plateforme agréée jest planowane z użyciem funkcji zatwierdzonej platformy Storecove i nie jest jeszcze gotowe produkcyjnie; polski moduł KSeF 2.0 nie był używany wobec produkcyjnego KSeF. Każdy z tych tematów ma własną stronę: integracja Peppol, integracja KSeF oraz przewodnik po formatach dla programistów EN 16931 dla programistów.