Przejdź do treści
Powrót do bloga
PoradnikOpublikowano 21 czerwca 20265 min czytania

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-validator

Krok 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.json

Teraz 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 npm

Gdzie 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.