Zwaliduj fakturę Peppol w Node.js w 5 minut
Poradnik krok po kroku: zwaliduj fakturę UBL / Peppol BIS / EN 16931 w Node.js względem XSD i Schematron za pomocą darmowego pakietu npm peppol-validator — bez Javy.
Faktury Peppol i EN 16931 to rygorystyczny XML: plik, który „wygląda dobrze", może i tak nie przejść reguł egzekwowanych przez organ podatkowy lub sieć Peppol. W tym poradniku walidujemy taką fakturę w Node.js w około pięć minut, używając darmowego, otwartoźródłowego pakietu peppol-validator — całkowicie bez Javy ani JVM.
Czego potrzebujesz
- Node.js 18 lub nowszy.
- Plik XML faktury (UBL Invoice lub CreditNote) — nazwijmy go invoice.xml.
- Około pięciu minut.
Krok 1 — Zainstaluj pakiet
npm install peppol-validatorKrok 2 — Sprawdź strukturę (XSD)
Najpierw zwaliduj XML względem schematu UBL 2.1. Schematy OASIS są dołączone, więc nie wymaga to żadnej konfiguracji — element główny jest wykrywany automatycznie.
import { readFileSync } from 'node:fs';
import { validateXsd } from 'peppol-validator';
const xml = readFileSync('./invoice.xml', 'utf-8');
const result = validateXsd(xml);
console.log(result.root, result.valid); // e.g. "Invoice" true
if (!result.valid) console.error(result.errors);result.valid mówi, czy struktura jest poprawna; result.errors wymienia ewentualne problemy z numerami linii. To natychmiast wychwytuje uszkodzone dokumenty.
Krok 3 — Dodaj reguły biznesowe (Schematron)
XSD sprawdza tylko formę. Właściwe reguły EN 16931 i Peppol — sumy muszą się zgadzać, kategorie VAT muszą być spójne, pola obowiązkowe muszą być obecne — żyją w Schematronie. Te zestawy reguł nie są dołączone (należą do OpenPEPPOL i innych organów), więc pobierasz oficjalny plik .sch raz i kompilujesz go dołączonym narzędziem:
# Download the official Peppol BIS Schematron (.sch) from docs.peppol.eu, then:
npx peppol-validator-compile PEPPOL-EN16931-UBL.sch ./artefacts/PEPPOL-EN16931-UBL.sef.jsonTeraz uruchom XSD i reguły biznesowe razem w jednym wywołaniu:
import { readFileSync } from 'node:fs';
import { validate, resolveSef } from 'peppol-validator';
const xml = readFileSync('./invoice.xml', 'utf-8');
const sef = resolveSef('peppol-bis-3', './artefacts');
const report = await validate(xml, { sef });
console.log('valid:', report.valid);
for (const e of report.schematron?.errors ?? []) {
console.log(e.id + ': ' + e.message);
}Krok 4 — Odczytaj wynik
- report.valid — ogólny wynik zaliczenia/niezaliczenia (XSD i Schematron łącznie).
- report.xsd.errors — problemy strukturalne.
- report.schematron.errors — naruszenia reguł biznesowych, każde z identyfikatorem reguły (np. BR-CO-10) i czytelnym komunikatem.
- report.schematron.warnings — niekrytyczne problemy, które i tak warto naprawić.
To wszystko
W kilku linijkach masz zarówno walidację strukturalną, jak i reguł biznesowych dla Peppol BIS, EN 16931 lub XRechnung — działającą wszędzie tam, gdzie działa Node, bez Javy. Wskaż inny skompilowany zestaw reguł, aby walidować inne profile lub dokumenty zakupowe.
Pobierz peppol-validator z npmGdzie pojawia się MyInvoice
peppol-validator sprawdza dokumenty. Jeśli musisz je również generować — przekształcać CSV, Excel, UBL, EDIFACT lub dane z ERP w zgodną fakturę EN 16931 — to właśnie robi MyInvoice: konwertuje, waliduje i zwraca gotowy do wysłania dokument przez jedno API.