Libreria JavaScript per gestire fatture elettroniche italiane (formato SDI).
Supporta i due formati ufficiali:
| Tipo | Formato |
|---|---|
'ordinaria' |
FatturaPA e FatturaPR (FPA12 / FPR12) |
'semplificata' |
FatturaSemplificata (FSM10) |
- Node.js ≥ 18
npm install github:davmapo/felkitPer abilitare la generazione PDF su Node.js, installa anche la peer dependency opzionale:
npm install puppeteerimport { FatturaElettronica } from 'felkit';import { readFile } from 'node:fs/promises';
const xml = await readFile('./fattura.xml', 'utf8');
// Pattern consigliato: rileva il tipo automaticamente via XSD
const fattura = await FatturaElettronica.from(xml);
console.log(fattura.type); // 'ordinaria' | 'semplificata'
console.log(fattura.data); // struttura JS della fattura
console.log(fattura.raw); // XML originale grezzoIn alternativa, è possibile usare il costruttore sincrono (senza rilevamento automatico):
const fattura = new FatturaElettronica(xml);
// fattura.type è null finché non si chiama detectType()
await fattura.detectType();
console.log(fattura.type);// Oggetto JavaScript (convenzione JS: JSON.stringify(fattura) funziona correttamente)
const obj = fattura.toJSON();
// Stringa JSON indentata
const json = fattura.serializeJSON();// Node.js — usa xslt-processor + il foglio ufficiale (scaricato automaticamente).
// Se la fattura contiene <?xml-stylesheet?>, viene usato il foglio della versione
// dichiarata (supporto automatico versioni precedenti al v1.4).
const html = await fattura.toHTML();
// Browser — occorre caricare il foglio XSL manualmente con fetch
// Il nome del file è quello derivato dall'URL ufficiale dell'AdE (vedi tabella in fondo)
const xslRes = await fetch('/path/to/Foglio_di_stile_fattura_ordinaria_ver1.2.3.xsl');
const xslString = await xslRes.text();
const html = fattura.toHTMLFromXSL(xslString);Richiede puppeteer installato (Node.js) oppure apre il dialogo di stampa del browser.
Usa automaticamente il foglio XSLT della versione dichiarata nella fattura (come toHTML()).
// Node.js → restituisce un Buffer
const pdfBuffer = await fattura.toPDF();
await fs.writeFile('fattura.pdf', pdfBuffer);
// Browser → apre window.print(), restituisce null
await fattura.toPDF();const result = await fattura.validate();
if (result.valid) {
console.log('Fattura conforme allo schema ufficiale');
console.log('Schema usato:', result.schema); // es. 'FatturaOrdinaria' o 'Schema_VFPR12_v1.2.1'
} else {
console.log('Errori di validazione:', result.errors);
}La libreria supporta automaticamente le versioni precedenti sia per la validazione che per il rendering:
| Operazione | Hint letto dalla fattura | Fallback |
|---|---|---|
validate() |
xsi:schemaLocation (secondo token = primo URL) |
schema v1.4 |
toHTML() / toPDF() |
<?xml-stylesheet type="text/xsl" href="..."> |
foglio v1.4 |
Se l'hint è presente e valido, la libreria scarica e cachera il file specifico in data/ al primo utilizzo. Le chiamate successive useranno il file locale. Il campo result.schema indica quale schema XSD è stato effettivamente usato.
Sicurezza: il download da hint è consentito solo da
fatturapa.gov.it(allowlist). URL di host diversi vengono ignorati e si usa il fallback v1.4.
In ambiente browser
validate()restituisce{ valid: null, errors: [...] }: la validazione XSD non è disponibile nel browser.
Costruttore sincrono. Effettua il parsing XML ma non rileva il tipo.
| Proprietà | Tipo | Descrizione |
|---|---|---|
raw |
string |
XML originale |
data |
object |
Struttura JS della fattura (output di fast-xml-parser) |
type |
string | null |
'ordinaria' / 'semplificata' / null se non ancora rilevato |
Factory statico. Equivale a new FatturaElettronica(xml) + detectType(). Uso consigliato.
| Metodo | Ritorna | Note |
|---|---|---|
toJSON() |
object |
Struttura JS della fattura (usato da JSON.stringify) |
serializeJSON() |
string |
JSON indentato della fattura |
toHTML() |
Promise<string> |
HTML via XSLT (Node); lancia errore nel browser |
toHTMLFromXSL(xslString) |
string |
HTML via XSLT già caricato — solo browser |
toPDF() |
Promise<Buffer | null> |
Buffer PDF (Node) oppure null + window.print() (browser) |
validate() |
Promise<{valid, errors, schema}> |
Valida contro XSD (versione-aware); valid: null nel browser |
detectType() |
Promise<string> |
Rileva e imposta this.type |
| Funzione | Node.js | Browser |
|---|---|---|
parseXML() |
✅ | ✅ |
toJSON() |
✅ | ✅ |
validate() / detectType() |
✅ xmllint-wasm | { valid: null } |
toHTML() |
✅ xslt-processor | ❌ usare toHTMLFromXSL() |
toHTMLFromXSL(xsl) |
❌ usare toHTML() |
✅ XSLTProcessor nativo |
toPDF() |
✅ puppeteer (peer dep) | window.print() + null |
import { readFile, writeFile } from 'node:fs/promises';
import { FatturaElettronica } from 'felkit';
const xml = await readFile('./IT01234567890_FPR01.xml', 'utf8');
const fattura = await FatturaElettronica.from(xml);
console.log('Tipo:', fattura.type);
// Validazione (rileva automaticamente la versione dello schema)
const { valid, errors, schema } = await fattura.validate();
if (!valid) {
console.warn('Attenzione, la fattura presenta errori XSD:', errors);
}
console.log('Schema usato:', schema);
// JSON
await writeFile('./fattura.json', fattura.serializeJSON());
// HTML
const html = await fattura.toHTML();
await writeFile('./fattura.html', html);
// PDF (richiede: npm install puppeteer)
const pdf = await fattura.toPDF();
await writeFile('./fattura.pdf', pdf);La libreria scarica automaticamente gli schemi XSD e i fogli XSLT ufficiali dell'Agenzia delle Entrate al primo utilizzo e li salva in cache nella cartella data/ del pacchetto installato.
Se la fattura XML dichiara esplicitamente la versione degli schemi o del foglio di stile, la libreria scarica e cacha automaticamente i file corrispondenti, senza nessuna configurazione:
- Schema XSD: attributo
xsi:schemaLocationnell'elemento radice - Foglio XSLT: processing instruction
<?xml-stylesheet type="text/xsl" href="..."?>
Sono accettati solo URL con host fatturapa.gov.it (protezione anti-SSRF).
Puoi fornire direttamente i tuoi file, copiandoli nelle cartelle cache prima che la libreria li scarichi:
| Tipo | Cartella di destinazione | Nome file atteso |
|---|---|---|
| Schema XSD fattura ordinaria | node_modules/felkit/data/schemi/ |
Schema_VFPR12_v1.2.3.xsd |
| Schema XSD fattura semplificata | node_modules/felkit/data/schemi/ |
Schema_VFSM10v_1.0.2.xsd |
| Schema XSD xmldsig | node_modules/felkit/data/schemi/ |
xmldsig-core-schema.xsd |
| Foglio XSLT fattura ordinaria | node_modules/felkit/data/style/ |
Foglio_di_stile_fattura_ordinaria_ver1.2.3.xsl |
| Foglio XSLT fattura semplificata | node_modules/felkit/data/style/ |
Foglio_di_stile_VFSM10_v1.0.2.xsl |
La libreria adotta una strategia cache-first: se il file è già presente in data/, non viene effettuato alcun download. I file manuali hanno quindi sempre la precedenza.
Tutti i file ufficiali sono disponibili su fatturapa.gov.it.
La libreria contiene URL hardcodati usati come fallback per le fatture che non dichiarano hint (xsi:schemaLocation / <?xml-stylesheet?>). Quando l'AdE pubblica una nuova versione dello standard e si vuole aggiornare il default:
| File | Costante da aggiornare |
|---|---|
| Schemi XSD principali | MAIN_SCHEMA_URLS in src/utils/schemaValidator.js |
| Schemi XSD di supporto (xmldsig ecc.) | SUPPORT_SCHEMA_URLS in src/utils/schemaValidator.js |
| Fogli XSLT | STYLE_URLS in src/transformers/toHTML.js |
Dopo aver aggiornato gli URL, elimina i file in data/schemi/ e data/style/ per forzare il re-download.
MIT