Vai al contenuto
Torna al blog
TutorialPubblicato il 21 giugno 20265 min di lettura

Validare una fattura Peppol in Node.js in 5 minuti

Un tutorial passo passo: valida una fattura UBL / Peppol BIS / EN 16931 in Node.js rispetto a XSD e Schematron usando il pacchetto npm gratuito peppol-validator — senza Java.

Le fatture Peppol ed EN 16931 sono XML rigoroso: un file che "sembra a posto" può comunque fallire le regole che un'autorità fiscale o la rete Peppol applicano. In questo tutorial ne validiamo una in Node.js in circa cinque minuti, usando il pacchetto open source gratuito peppol-validator — senza Java né JVM.

Cosa ti serve

  • Node.js 18 o più recente.
  • Un file XML di fattura (UBL Invoice o CreditNote) — chiamiamolo invoice.xml.
  • Circa cinque minuti.

Passo 1 — Installare il pacchetto

npm install peppol-validator

Passo 2 — Verificare la struttura (XSD)

Per prima cosa, valida l'XML rispetto allo schema UBL 2.1. Gli schemi OASIS sono inclusi, quindi non serve alcuna configurazione — l'elemento radice viene rilevato automaticamente.

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 ti dice se la struttura è corretta; result.errors elenca gli eventuali problemi con i numeri di riga. Questo individua all'istante i documenti malformati.

Passo 3 — Aggiungere le regole di business (Schematron)

L'XSD verifica solo la forma. Le vere regole EN 16931 e Peppol — i totali devono quadrare, le categorie IVA devono essere coerenti, i campi obbligatori devono essere presenti — vivono nello Schematron. Quei set di regole non sono inclusi (appartengono a OpenPEPPOL e agli altri enti), quindi scarichi una volta il .sch ufficiale e lo compili con lo strumento incluso:

# 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

Ora esegui XSD e regole di business insieme in un'unica chiamata:

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);
}

Passo 4 — Leggere il risultato

  • report.valid — esito complessivo (XSD e Schematron combinati).
  • report.xsd.errors — problemi strutturali.
  • report.schematron.errors — violazioni delle regole di business, ciascuna con un ID regola (ad es. BR-CO-10) e un messaggio leggibile.
  • report.schematron.warnings — problemi non fatali che potresti comunque voler correggere.

Ecco fatto

In poche righe hai sia la validazione strutturale sia quella delle regole di business per Peppol BIS, EN 16931 o XRechnung — eseguibile ovunque giri Node, senza Java. Punta a un diverso set di regole compilato per validare altri profili o i documenti di approvvigionamento.

Ottieni peppol-validator su npm

Dove si inserisce MyInvoice

peppol-validator verifica i documenti. Se devi anche generarli — trasformare CSV, Excel, UBL, EDIFACT o i dati del tuo ERP in una fattura EN 16931 conforme — è esattamente ciò che fa MyInvoice: convertire, validare e restituire un documento pronto per l'invio tramite un'unica API.