Build, validate and serialize FatturaPA electronic invoices.
Fluent builder for invoice construction.
import { FatturaBuilder } from '@fatturazione-elettronica-aruba/xml-builder';
const builder = FatturaBuilder.create();
Creates a new builder instance.
const builder = FatturaBuilder.create();
Sets the schema version (default: '1.2.2').
builder.setVersione('1.2.2');
Sets complete transmission data.
builder.setDatiTrasmissione({
idTrasmittente: { idPaese: 'IT', idCodice: '01234567890' },
progressivoInvio: '00001',
formatoTrasmissione: 'FPR12',
codiceDestinatario: 'ABC1234',
pecDestinatario?: string,
contattiTrasmittente?: { telefono?: string, email?: string },
});
Helper for B2B transmission (FPR12 format).
builder.setTrasmissioneB2B({
idPaese: string;
idCodice: string;
progressivoInvio: string;
codiceDestinatario?: string; // Default: '0000000'
pecDestinatario?: string;
});
Helper for PA transmission (FPA12 format).
builder.setTrasmissionePA({
idPaese: string;
idCodice: string;
progressivoInvio: string;
codiceDestinatario: string; // 6-char IPA code
});
Sets the seller/provider.
builder.setCedentePrestatore({
datiAnagrafici: {
idFiscaleIVA?: { idPaese: string, idCodice: string },
codiceFiscale?: string,
anagrafica: { denominazione?: string, nome?: string, cognome?: string },
regimeFiscale: RegimeFiscale,
},
sede: Indirizzo,
stabileOrganizzazione?: Indirizzo,
iscrizioneREA?: IscrizioneREA,
contatti?: Contatti,
riferimentoAmministrazione?: string,
});
Sets the buyer/customer.
builder.setCessionarioCommittente({
datiAnagrafici: {
idFiscaleIVA?: { idPaese: string, idCodice: string },
codiceFiscale?: string,
anagrafica: { denominazione?: string, nome?: string, cognome?: string },
},
sede: Indirizzo,
stabileOrganizzazione?: Indirizzo,
rappresentanteFiscale?: RappresentanteFiscale,
});
Sets general document data.
builder.setDatiGenerali({
datiGeneraliDocumento: {
tipoDocumento: TipoDocumento,
divisa: string, // E.g.: 'EUR'
data: string, // YYYY-MM-DD
numero: string,
importoTotaleDocumento?: number,
causale?: string[],
datiRitenuta?: DatiRitenuta,
datiBollo?: DatiBollo,
},
datiOrdineAcquisto?: DatiDocumentoCorrelato[],
datiContratto?: DatiDocumentoCorrelato[],
datiDDT?: DatiDDT[],
});
Sets line items and VAT summary.
builder.setDatiBeniServizi({
dettaglioLinee: [
{
numeroLinea: number,
descrizione: string,
quantita?: number,
unitaMisura?: string,
prezzoUnitario: number,
prezzoTotale: number,
aliquotaIVA: number,
natura?: Natura,
scontoMaggiorazione?: ScontoMaggiorazione[],
},
],
datiRiepilogo: [
{
aliquotaIVA: number,
imponibileImporto: number,
imposta: number,
natura?: Natura,
esigibilitaIVA?: 'I' | 'D' | 'S',
riferimentoNormativo?: string,
},
],
});
Adds a single line item. numeroLinea (incremental) and prezzoTotale
(prezzoUnitario × quantita, applying discounts) are computed if omitted.
DatiRiepilogo and ImportoTotaleDocumento are computed automatically in build().
builder.addLinea({
descrizione: string,
quantita?: number,
unitaMisura?: string,
prezzoUnitario: number,
aliquotaIVA: number,
natura?: Natura,
scontoMaggiorazione?: ScontoMaggiorazione[],
numeroLinea?: number, // optional, auto-assigned
prezzoTotale?: number, // optional, auto-computed
});
Sets all line items at once (replaces previously added lines). Same auto-computation as addLinea.
builder.setDettaglioLinee([
{ descrizione: 'Item A', quantita: 2, prezzoUnitario: 50, aliquotaIVA: 22 },
{ descrizione: 'Item B', quantita: 1, prezzoUnitario: 100, aliquotaIVA: 10 },
]);
Sets the default EsigibilitaIVA ('I' | 'D' | 'S', default 'I') applied to
the auto-computed DatiRiepilogo. Not applied to groups with a Natura.
builder.setEsigibilitaIVA('S'); // split payment
Adds payment data.
builder.addDatiPagamento({
condizioniPagamento: 'TP01' | 'TP02' | 'TP03',
dettaglioPagamento: [
{
modalitaPagamento: ModalitaPagamento,
importoPagamento: number,
dataScadenzaPagamento?: string,
iban?: string,
istitutoFinanziario?: string,
},
],
});
Finalizes current body and starts a new one (for batch invoices).
builder
.setDatiGenerali({ ... })
.setDatiBeniServizi({ ... })
.newBody()
.setDatiGenerali({ ... }) // New invoice
.setDatiBeniServizi({ ... });
Builds the electronic invoice. Repeatable: it does not mutate the builder state.
const fattura: FatturaElettronica = builder.build();
Builds and validates in one call, returning a ValidationResult.
const result = builder.validate({ strict: true });
Builds and serializes to FatturaPA XML in one call.
const xml = builder.toXml({ includeSchemaLocation: true });
Builds, validates and serializes in one call, also returning the SDI filename.
const { fattura, xml, validazione, filename } = builder.toResult({
validation?: ValidationOptions,
serializer?: FatturaSerializerOptions,
});
// filename: '<IdPaese><IdCodice>_<Progressivo>.xml'
Resets the builder to initial state.
builder.reset();
Validator for electronic invoices.
import { FatturaValidator, validateFattura } from '@fatturazione-elettronica-aruba/xml-builder';
// Instance
const validator = new FatturaValidator(options);
const result = validator.validate(fattura);
// Helper
const result = validateFattura(fattura, options);
interface ValidationOptions {
validateTotals?: boolean; // Default: true
validateCodiceFiscale?: boolean; // Default: true
validatePartitaIVA?: boolean; // Default: true
validateDates?: boolean; // Default: true
strict?: boolean; // Default: false
}
interface ValidationResult {
valid: boolean;
errors: ValidationError[];
warnings: ValidationError[];
}
interface ValidationError {
path: string;
message: string;
code: string;
}
Serializes invoices to XML.
import { FatturaSerializer } from '@fatturazione-elettronica-aruba/xml-builder';
const serializer = new FatturaSerializer({
includeSchemaLocation?: boolean, // Default: true
});
const xml = serializer.serialize(fattura);
Quantita keeps 2–8 decimals (e.g. 0.001), prices/VAT rates use 2 decimals.Pure helpers exported from the package. Useful to map domain data without re-implementing VAT/total logic or nested anagrafica objects.
Computes DatiRiepilogo (grouped by aliquotaIVA + natura) and the
importoTotaleDocumento from the line items, with correct rounding (SDI rules).
const { datiRiepilogo, importoTotaleDocumento } = calcolaRiepilogo(linee, {
esigibilitaIVA: 'I', // default; not applied to groups with a Natura
});
Computes a line's PrezzoTotale (= prezzoUnitario × quantita, applying
discounts/surcharges), rounded to 2 decimals.
calcolaPrezzoTotale(75, 40); // 3000
calcolaPrezzoTotale(100, 1, [{ tipo: 'SC', percentuale: 10 }]); // 90
toNumber coerces number | string | null | undefined to a number (DB numerics
often arrive as strings). round2 rounds to 2 decimals avoiding floating-point errors.
toNumber('12.50'); // 12.5
round2(1.005); // 1.01
Build CedentePrestatore / CessionarioCommittente from flat fields, with string
coercion and optional IdFiscaleIVA/CodiceFiscale/contacts.
const cedente = cedentePrestatore({
piva: '01234567890', codiceFiscale, denominazione: 'Azienda SRL',
regimeFiscale: 'RF01', // default 'RF01'
indirizzo, cap, comune, provincia, nazione, // nazione default 'IT'
telefono, email,
});
const cliente = cessionario({
piva, codiceFiscale, // both optional
denominazione, indirizzo, cap, comune, provincia,
});
sede builds an Indirizzo (default nazione: 'IT'); contatti builds a
Contatti block or returns undefined if all fields are empty.
Builds the SDI filename <IdPaese><IdCodice>_<Progressivo>.xml (progressivo
left-padded to 5 chars).
nomeFileSdi('IT', '01234567890', '1'); // 'IT01234567890_00001.xml'
type TipoDocumento =
| 'TD01' | 'TD02' | 'TD03' | 'TD04' | 'TD05' | 'TD06'
| 'TD07' | 'TD08' | 'TD09' | 'TD10' | 'TD11' | 'TD12'
| 'TD16' | 'TD17' | 'TD18' | 'TD19' | 'TD20' | 'TD21'
| 'TD22' | 'TD23' | 'TD24' | 'TD25' | 'TD26' | 'TD27' | 'TD28';
type RegimeFiscale =
| 'RF01' | 'RF02' | 'RF04' | 'RF05' | 'RF06' | 'RF07'
| 'RF08' | 'RF09' | 'RF10' | 'RF11' | 'RF12' | 'RF13'
| 'RF14' | 'RF15' | 'RF16' | 'RF17' | 'RF18' | 'RF19';
type Natura =
| 'N1' | 'N2' | 'N2.1' | 'N2.2'
| 'N3' | 'N3.1' | 'N3.2' | 'N3.3' | 'N3.4' | 'N3.5' | 'N3.6'
| 'N4' | 'N5' | 'N6' | 'N6.1' | 'N6.2' | 'N6.3' | 'N6.4'
| 'N6.5' | 'N6.6' | 'N6.7' | 'N6.8' | 'N6.9' | 'N7';
type ModalitaPagamento =
| 'MP01' | 'MP02' | 'MP03' | 'MP04' | 'MP05'
| 'MP06' | 'MP07' | 'MP08' | 'MP09' | 'MP10'
| 'MP11' | 'MP12' | 'MP13' | 'MP14' | 'MP15'
| 'MP16' | 'MP17' | 'MP18' | 'MP19' | 'MP20'
| 'MP21' | 'MP22' | 'MP23';
interface Indirizzo {
indirizzo: string;
numeroCivico?: string;
cap: string;
comune: string;
provincia?: string;
nazione: string;
}