Guide

XML Builder

Costruzione fatture elettroniche con API fluent

XML Builder

Costruisci fatture elettroniche FatturaPA con un'API fluent type-safe.

Setup

import { FatturaBuilder, FatturaSerializer, FatturaValidator } from '@fatturazione-elettronica-aruba/xml-builder';

Costruzione Fattura

API Fluent

const fattura = FatturaBuilder.create()
  .setTrasmissioneB2B({
    idPaese: 'IT',
    idCodice: '01234567890',
    progressivoInvio: '00001',
    codiceDestinatario: 'ABC1234',
  })
  .setCedentePrestatore({
    datiAnagrafici: {
      idFiscaleIVA: { idPaese: 'IT', idCodice: '01234567890' },
      anagrafica: { denominazione: 'Azienda SRL' },
      regimeFiscale: 'RF01',
    },
    sede: {
      indirizzo: 'Via Roma 1',
      cap: '00100',
      comune: 'Roma',
      provincia: 'RM',
      nazione: 'IT',
    },
  })
  .setCessionarioCommittente({
    datiAnagrafici: {
      idFiscaleIVA: { idPaese: 'IT', idCodice: '09876543210' },
      anagrafica: { denominazione: 'Cliente SPA' },
    },
    sede: {
      indirizzo: 'Via Milano 10',
      cap: '20100',
      comune: 'Milano',
      provincia: 'MI',
      nazione: 'IT',
    },
  })
  .setDatiGenerali({
    datiGeneraliDocumento: {
      tipoDocumento: 'TD01',
      divisa: 'EUR',
      data: '2024-01-15',
      numero: '1',
    },
  })
  .setDatiBeniServizi({
    dettaglioLinee: [
      {
        numeroLinea: 1,
        descrizione: 'Servizio di consulenza',
        quantita: 10,
        unitaMisura: 'ore',
        prezzoUnitario: 100.0,
        prezzoTotale: 1000.0,
        aliquotaIVA: 22.0,
      },
    ],
    datiRiepilogo: [
      {
        aliquotaIVA: 22.0,
        imponibileImporto: 1000.0,
        imposta: 220.0,
        esigibilitaIVA: 'I',
      },
    ],
  })
  .build();

Fattura PA

Per fatture alla Pubblica Amministrazione:

const fattura = FatturaBuilder.create()
  .setTrasmissionePA({
    idPaese: 'IT',
    idCodice: '01234567890',
    progressivoInvio: '00001',
    codiceDestinatario: 'ABCDEF', // Codice IPA 6 caratteri
  })
  // ... resto della fattura
  .build();

Dati Pagamento

const fattura = FatturaBuilder.create()
  // ... dati fattura
  .addDatiPagamento({
    condizioniPagamento: 'TP02', // Pagamento completo
    dettaglioPagamento: [
      {
        modalitaPagamento: 'MP05', // Bonifico
        importoPagamento: 1220.0,
        iban: 'IT60X0542811101000000123456',
        dataScadenzaPagamento: '2024-02-15',
      },
    ],
  })
  .build();

Fatture Lotto (Multiple Bodies)

const fattura = FatturaBuilder.create()
  .setTrasmissioneB2B({ /* ... */ })
  .setCedentePrestatore({ /* ... */ })
  .setCessionarioCommittente({ /* ... */ })
  // Prima fattura
  .setDatiGenerali({ datiGeneraliDocumento: { numero: '1', /* ... */ } })
  .setDatiBeniServizi({ /* ... */ })
  .newBody() // Inizia nuova fattura nel lotto
  // Seconda fattura
  .setDatiGenerali({ datiGeneraliDocumento: { numero: '2', /* ... */ } })
  .setDatiBeniServizi({ /* ... */ })
  .build();

// fattura.fatturaElettronicaBody.length === 2

Validazione

import { FatturaValidator, validateFattura } from '@fatturazione-elettronica-aruba/xml-builder';

// Metodo 1: Istanza
const validator = new FatturaValidator({ strict: true });
const result = validator.validate(fattura);

// Metodo 2: Helper
const result = validateFattura(fattura, { validateTotals: true });

if (!result.valid) {
  console.log('Errori:', result.errors);
  console.log('Warning:', result.warnings);
}

Opzioni Validazione

const result = validateFattura(fattura, {
  validateTotals: true,       // Verifica totali
  validateCodiceFiscale: true, // Verifica CF
  validatePartitaIVA: true,   // Verifica P.IVA
  validateDates: true,        // Verifica date
  strict: false,              // Warning come errori
});

Serializzazione XML

import { FatturaSerializer } from '@fatturazione-elettronica-aruba/xml-builder';

const serializer = new FatturaSerializer({
  includeSchemaLocation: true,
});

const xml = serializer.serialize(fattura);

console.log(xml);
// <?xml version="1.0" encoding="UTF-8"?>
// <p:FatturaElettronica xmlns:p="..." versione="FPR12">
//   ...
// </p:FatturaElettronica>

Invio Fattura

Per inviare la fattura, usa il modulo invoices:

import { ArubaClient } from '@fatturazione-elettronica-aruba/core';
import { InvoicesClient } from '@fatturazione-elettronica-aruba/invoices';
import { FatturaBuilder, FatturaSerializer, validateFattura } from '@fatturazione-elettronica-aruba/xml-builder';

// 1. Setup client
const client = new ArubaClient({ environment: 'demo' });
await client.auth.signin('username', 'password');
const invoices = new InvoicesClient(client.http);

// 2. Costruisci fattura
const fattura = FatturaBuilder.create()
  .setTrasmissioneB2B({ /* ... */ })
  .setCedentePrestatore({ /* ... */ })
  .setCessionarioCommittente({ /* ... */ })
  .setDatiGenerali({ /* ... */ })
  .setDatiBeniServizi({ /* ... */ })
  .build();

// 3. Valida (opzionale)
const validation = validateFattura(fattura);
if (!validation.valid) {
  throw new Error(`Fattura non valida: ${JSON.stringify(validation.errors)}`);
}

// 4. Serializza in XML
const serializer = new FatturaSerializer();
const xml = serializer.serialize(fattura);

// 5. Codifica in Base64
const base64 = Buffer.from(xml, 'utf-8').toString('base64');

// 6. Invia
const result = await invoices.upload({
  dataFile: base64,
  dryRun: false, // true per solo validazione
});

console.log('Fattura inviata:', result.uploadFileName);

Tipi Documento

CodiceDescrizione
TD01Fattura
TD02Acconto/Anticipo su fattura
TD03Acconto/Anticipo su parcella
TD04Nota di credito
TD05Nota di debito
TD06Parcella
TD16Integrazione fattura reverse charge interno
TD17Integrazione/autofattura acquisto servizi estero
TD24Fattura differita
TD25Fattura differita (triangolazione)
TD26Cessione beni ammortizzabili

Regimi Fiscali

CodiceDescrizione
RF01Ordinario
RF02Contribuenti minimi
RF04Agricoltura
RF19Forfettario