SDI / Fatturazione Elettronica

Il modulo SDI / Fatturazione Elettronica di NOX Enterprise Suite gestisce l'intero ciclo di vita della fattura elettronica: dalla generazione del file XML FatturaPA a partire dal modello Documento, fino alla trasmissione al Sistema di Interscambio e alla ricezione delle notifiche di esito.

Il flusso operativo si articola in tre fasi principali:

1. Generazione XML: un adapter converte i dati del Documento (fattura, nota di credito, ecc.) nel tracciato XML conforme alle specifiche FatturaPA v1.2.2. La generazione puo avvenire singolarmente dal documento o in modalita batch per piu documenti contemporaneamente.
2. Trasmissione al SDI: il file XML viene firmato digitalmente (se configurato) e trasmesso al Sistema di Interscambio tramite i canali previsti. Il sistema traccia lo stato di ogni trasmissione.
3. Gestione notifiche: il modulo riceve e processa le notifiche restituite dal SDI (ricevuta di consegna, notifica di scarto, esito committente, ecc.), aggiornando automaticamente lo stato della trasmissione.

Il tracciato FatturaPA prevede due formati distinti, identificati dal codice nel campo FormatoTrasmissione:

Per generare il file XML FatturaPA da un singolo documento:

1. Aprire il Documento (fattura, nota di credito, ecc.) dalla lista documenti o dalla scheda dettaglio.
2. Verificare che tutti i dati obbligatori siano compilati: dati cedente/prestatore, dati cessionario/committente, righe documento con natura IVA, condizioni di pagamento.
3. Premere il pulsante XML SDI presente nella toolbar del documento.
4. Il sistema genera il file XML tramite l'adapter Documento → FatturaPA, applicando automaticamente il formato corretto (FPR12 o FPA12) in base al tipo di cessionario.
5. Viene visualizzata un'anteprima del file XML con evidenza dei principali campi mappati. Verificare la correttezza dei dati.
6. Premere Conferma e Invia per trasmettere il file al SDI oppure Salva come bozza per salvarlo nello stato DA_INVIARE.

La generazione batch consente di elaborare in un solo passaggio tutte le fatture emesse che non sono ancora state archiviate in SDI. L'operazione si svolge direttamente dalla pagina Archivio SDI.

Come attivarla

1. Accedere al menu Fatturazione → Archivio SDI.
2. Nella barra dei filtri (sopra la lista delle trasmissioni) cliccare il pulsante ⚡ Genera da fatture.
3. Si apre un pannello con l'elenco automatico di tutte le fatture emesse non ancora elaborate per il SDI: il sistema filtra autonomamente i documenti con tipo TD01…TD28 in stato definitivo (EMESSO, CONFERMATO, INVIATO, PAGATO) che non possiedono ancora un record in Archivio SDI.
4. Selezionare le fatture desiderate con le checkbox a sinistra di ogni riga, oppure usare la checkbox di intestazione per selezionare tutto l'elenco.
5. Premere ⚡ Genera N XML (dove N è il numero di fatture selezionate) per avviare la generazione.
6. Al termine appare un riepilogo con: file XML generati, fatture già esistenti saltate (idempotenza), eventuali errori con documento di origine. Il pannello si chiude automaticamente e la tabella dell'archivio si aggiorna.

Colonne mostrate nel pannello di selezione

Endpoint backend

• GET /api/sdi/emesse/_/da-elaborare — lista delle fatture senza record SDI (LEFT JOIN nullo su fatture_sdi.documentoId). Il prefisso _/ evita la collisione con la rotta /emesse/:id.
• POST /api/sdi/emesse/_/batch-genera con body { documentoIds:[id1,id2,…] } — genera in sequenza riusando internamente il flusso genera-da-documento, con gestione individuale degli errori e skip idempotente se il record SDI esiste già

L'Archivio SDI (menu Fatturazione → SDI → Archivio) presenta la lista completa di tutte le trasmissioni effettuate, con strumenti di consultazione e monitoraggio.

Statistiche riepilogative

In testa alla pagina vengono visualizzate le statistiche aggregate:

Filtri disponibili

Ogni trasmissione al Sistema di Interscambio attraversa una sequenza di stati che ne descrivono il ciclo di vita. Di seguito la tabella completa degli stati e le transizioni possibili:

Il Sistema di Interscambio comunica l'esito delle trasmissioni tramite notifiche codificate. Il modulo riceve e processa automaticamente le seguenti tipologie:

L'adapter converte il modello Documento di NOX nella struttura XML FatturaPA conforme al tracciato v1.2.2. Di seguito la mappatura dei principali blocchi:

Aggiornamento del modulo SDI con nuove funzionalità di gestione massiva e fix del generatore XML.

Selezione multipla con checkbox

Nella lista Archivio SDI è disponibile una colonna checkbox per la selezione multipla dei record. Quando sono selezionati uno o più record compare una barra azioni bulk in alto con le operazioni disponibili:

• Cambia stato → applica il nuovo stato a tutte le fatture selezionate
• Rigenera XML → rigenera in massa
• Esporta → esporta XML e ricevute

Eliminazione (cestino) record SDI

Ogni record SDI presenta un'icona cestino. L'icona è sempre visibile ma è attiva solo per i record in stato ANNULLATA; negli altri stati è disabilitata a tutela della tracciabilità fiscale.

Modifica manuale del Progressivo Invio

Accanto al valore Progressivo Invio compare un'icona ✎ che permette di modificare manualmente il contatore. Utile per allineamenti in fase di migrazione o quando il contatore SDI remoto e quello locale vanno disallineati.

Data visualizzata in lista SDI (fix 24 aprile 2026)

La colonna Data nella lista SDI mostra la data del documento fiscale (campo dataDocumento), non la data di generazione del record SDI. Prima del fix, i record generati in massa (es. tutti insieme dopo una migrazione) apparivano tutti con la stessa data di creazione, nascondendo la data fiscale reale.

Univocità del Progressivo Invio (fix aprile 2026)

Dal 24 aprile 2026 il campo progressivoInvio ha un constraint UNIQUE a livello database su tutti i workspace. Il calcolo del prossimo progressivo si basa ora sul valore massimo del progressivoInvio esistente (non sull'id record), eliminando un bug che poteva generare duplicati dopo cancellazioni di record SDI pregressi.

Sincronizzazione cross-workspace

Quando si genera un XML in un workspace per cui è configurato un syncTargetWorkspaceId (vedi Utenti → Database di Lavoro), il record SDI e il file XML vengono replicati automaticamente sul workspace target. Rimpiazza gli hardcoded precedenti (“provatest” / “studio”) con una configurazione per workspace.

Fix del generatore XML FatturaPA

Il file backend utils/fatturaXml.js è stato corretto in più punti per allinearsi al tracciato XSD ufficiale:

Dalla versione 2.1.1 NOX supporta la trasmissione diretta dei file XML FatturaPA al Sistema di Interscambio, senza passaggio manuale attraverso il portale Fatture e Corrispettivi. Sono disponibili tre modalità configurabili per workspace.

10.1 Configurazione intermediario

La configurazione si effettua in Parametri → Fatturazione-Cassa ⚡SDI → sezione ⚡ Trasmissione Sistema di Interscambio (SDI).

10.2 Modalità PEC (Aruba PEC esempio)

Se si utilizza una casella Aruba PEC, i parametri SMTP tipici sono:

Per altri gestori PEC (Legalmail, Namirial, ecc.) consultare la documentazione del provider. I limiti di invio della casella PEC vanno rispettati: la PEC e sconsigliata per volumi massivi (> 50 fatture/giorno).

10.3 Modalità Aruba API — Produzione

Per il canale Aruba Fatturazione Elettronica API servono credenziali rilasciate da Aruba al momento dell'attivazione del servizio (non coincidono con le credenziali della PEC). Endpoint tipico di produzione:

• URL: https://ws.fatturazioneelettronica.aruba.it
• Username / Password: forniti nel pannello Aruba

10.4 Modalità Aruba API — Demo (test)

Aruba mette a disposizione un ambiente di collaudo gratuito per testare l'integrazione senza inviare fatture reali al SDI. I passi per registrarsi e testare sono:

1. Registrarsi sul portale demo.fatturazioneelettronica.aruba.it con un indirizzo email valido; si ottengono username e password di test.
2. In NOX selezionare modalità Aruba API e inserire come URL: https://demows.fatturazioneelettronica.aruba.it
3. Inserire le credenziali demo ricevute via email.
4. Salvare la configurazione e provare a trasmettere una fattura di test dalla lista SDI.
5. Le fatture trasmesse sono visibili nel pannello web Aruba Demo sotto Gestione Documenti → Inviati, dove si possono verificare lo stato e i messaggi di risposta.

10.5 Pulsante ⚡ di trasmissione

Nell'Archivio SDI, per ogni record in stato DA_INVIARE compare il pulsante ⚡ (fulmine) nella riga. Premendolo:

1. Il sistema legge la configurazione corrente (sdiConfig) del workspace.
2. A seconda della modalità attiva, il file XML viene:
   • Manuale: scaricato sul PC dell'operatore (non cambia stato)
   • PEC: allegato a un messaggio PEC inviato a sdi01@pec.fatturapa.it via nodemailer
   • Aruba API: caricato sul web service REST con autenticazione Basic
3. Se la trasmissione riesce, lo stato del record passa automaticamente da DA_INVIARE a IN_ATTESA.
4. Se la trasmissione fallisce (es. credenziali errate, rete, 5xx), il record resta in DA_INVIARE e l'errore viene mostrato in popup + scritto nel log trasmissione.

10.6 Riepilogo stati

10.7 Password Toggle

Tutte le caselle password della sezione (PEC e Aruba) e della configurazione SMTP email sono dotate dell'icona 👁 per mostrare il carattere in chiaro durante l'inserimento. L'icona agisce solo sul rendering del campo: il valore salvato resta nascosto di default e viene sempre trasmesso su connessione HTTPS.

Dalla versione 2.1.2, il menu Modalità trasmissione in Parametri → Fatturazione-Cassa ⚡SDI → ⚡ Trasmissione Sistema di Interscambio (SDI) offre 11 opzioni totali: le 3 già presenti in v2.1.1 (Manuale, PEC, Aruba) e 8 nuovi intermediari aggiunti in questa release.

11.1 Riepilogo delle 11 modalità

11.2 Fatture in Cloud (TeamSystem)

Autenticazione: OAuth2 refresh-token. Durante l'invio NOX scambia il refresh-token con un access-token temporaneo e lo utilizza per tentare l'upload dell'XML.

Credenziali richieste:

• clientId — ID applicazione (ottenuto dal portale sviluppatori TeamSystem)
• clientSecret — segreto applicazione
• companyId — ID azienda su Fatture in Cloud
• refreshToken — token di refresh a lunga durata ottenuto tramite flusso OAuth2

11.3 Agyo Digital Hub (TeamSystem)

Autenticazione: OAuth2 client_credentials grant type. NOX ottiene un access-token via /auth/token e lo utilizza come Bearer per POST /v1/documents.

Credenziali richieste: clientId, clientSecret, vatId (P.IVA dell'azienda).

Esempio URL: https://services.agyo.io/v1/documents

11.4 Zucchetti Digital Hub

Autenticazione: header X-API-Key con chiave fornita da Zucchetti.

Endpoint configurabile: il campo endpoint è personalizzabile per puntare ad ambienti diversi (produzione, staging). NOX chiama POST {endpoint}/invoices/send.

Credenziali richieste: apiKey, endpoint.

Esempio endpoint test: https://api.zucchetti-digital-hub.com

11.5 FattureWeb (Wolters Kluwer)

Autenticazione: header Authorization: ApiKey {apiKey}. Upload dell'XML tramite multipart/form-data.

Selezione ambiente: il campo environment accetta test o production; NOX commuta automaticamente l'URL base.

Credenziali richieste: apiKey, companyCode, environment.

Esempio URL di test: https://test.fattureweb.wolterskluwer.it/api

Esempio URL produzione: https://fattureweb.wolterskluwer.it/api

11.6 Fatturapa.it

Autenticazione: Bearer token Authorization: Bearer {apiKey}. Upload XML tramite POST /v2/invoices.

Credenziali richieste: email (account Fatturapa.it), apiKey.

Esempio URL: https://www.fatturapa.it/api/v2/invoices

11.7 Intermediari con requisiti speciali (stub)

Tre intermediari sono presenti in elenco ma ritornano 501 Not Implemented con un messaggio esplicativo: richiedono setup aggiuntivo non disponibile nella versione corrente.

11.8 Come scegliere l'intermediario giusto

11.9 Validazione credenziali ed errori

• Errore 400: credenziali mancanti o incomplete (il sistema verifica i campi obbligatori prima di contattare il provider).
• Errore 401/403: credenziali errate o scadute (apiKey revocata, refreshToken scaduto, password cambiata).
• Errore 502: il provider ha restituito un errore. Il body della risposta del provider è incluso nel messaggio per facilitare il debug.
• Errore 501: intermediario non implementato (Infocert / Sistema Impresa / AdE diretti) o funzionalità non disponibile (Fatture in Cloud upload XML).

Se fatturi o ricevi fatture da clienti/fornitori con P.IVA in altri paesi UE, devi presentare all'Agenzia Entrate gli elenchi Intrastat e, per operazioni esterne UE, l'Esterometro.

Intrastat UE — Cessioni (INTRA-1bis) e Acquisti (INTRA-2bis)

1. Apri il menu utente in alto a destra → Fatturazione avanzata
2. Nella sidebar scegli “Intrastat UE”
3. Imposta l'anno di riferimento
4. Clicca Genera CSV INTRA-1bis/2bis

Il file CSV contiene, per ciascun paese UE, l'elenco dei soggetti con P.IVA + il totale fatture/imponibile/IVA. Le ultime 4 colonne (Nomenclatura combinata, Natura transazione, Condizioni consegna, Modo trasporto) sono da compilare dal commercialista.

Esterometro — Comunicazione operazioni transfrontaliere

1. Stessa pagina, sezione “Esterometro”
2. Scegli anno + trimestre (Q1-Q4)
3. Clicca Genera XML

Il file XML elenca separatamente Cessioni e Acquisti verso controparti con P.IVA non italiana. È pensato come riepilogo per controlli interni o per export al commercialista.

Scadenze

• Intrastat mensile: entro il giorno 25 del mese successivo
• Intrastat trimestrale: entro il 25 del mese successivo al trimestre (es. Q1 → 25 aprile)
• Esterometro: entro la fine del mese successivo al trimestre

Ogni transizione di stato di una fattura emessa è tracciata nella tabella log_modifiche_fattura_sdi.

Stati gestiti

PENDENTE → IN_ATTESA → INVIATA → (ACCETTATA | SCARTATA) → CONSERVATA

Ogni cambio registra: stato vecchio, stato nuovo, operatore, timestamp, eventuale messaggio di errore SDI come motivazione.

Endpoint: GET /api/sdi/emesse/:id/audit-log.

Ogni evento di interscambio con il Sistema di Interscambio è registrato in log_trasmissioni_sdi.

Eventi tracciati

Dati conservati

• identificativo_sdi: ID assegnato da AdE
• hash_xml: SHA-256 del file XML trasmesso
• xml_size: dimensione in byte
• ricevuta_xml: XML ricevuta grezza conservata per analisi forense
• operatore: utente che ha eseguito / ricevuto

Endpoint: GET /api/sdi/emesse/:id/trasmissioni.

Endpoint GET /api/sdi/emesse/:id/timeline restituisce la vista unificata: modifiche + trasmissioni ordinate cronologicamente (descendente).

Utile per ricostruire la catena completa «fattura → invio SdI → notifica AdE → esito» in caso di contestazione o verifica fiscale.

L'XML FatturaPA originale è conservato anche dopo invio. L'hash SHA-256 permette di verificare a posteriori se il file sul disco coincide con quanto trasmesso.

• Nome file generato per convenzione (provv. AdE 30/04/2018)
• Progressivo univoco per trasmissione, mai riutilizzabile
• Hash calcolato al momento della prima trasmissione
• Confronto con file attuale rileva alterazioni accidentali o deliberate

Le fatture elettroniche devono essere conservate per 10 anni (art. 2220 c.c. + art. 39 DPR 633/72).

La conservazione a norma AgID richiede conservatore accreditato esterno. Il modulo conservazione interno è placeholder.

In attesa dell'integrazione conservatore AgID:

• Gli XML restano nel filesystem backend del server
• Backup giornaliero del DB include i riferimenti
• Log trasmissioni conservato per ricostruire lo stato

La transizione dello stato di una fattura SDI è validata server-side da una matrice fissa che impedisce retrocessioni incoerenti con la posizione fiscale e con la logica del Sistema di Interscambio.

Matrice applicata

Comportamento in caso di transizione non ammessa

• Il server risponde HTTP 409 Conflict con messaggio esplicativo
• Il body della response contiene il campo ammesse con l'elenco delle transizioni lecite da quello stato
• Esempio: { error: "Transizione non consentita: ACCETTATA → IN_ATTESA. Stati ammessi: (stato finale). SUPERADMIN può forzare con flag forza:true.", ammesse: [] }

Forzatura transizione (override)

Solo un utente SUPERADMIN può forzare una transizione non ammessa aggiungendo "forza": true nel body del PATCH. La forzatura viene registrata separatamente nell'audit log come campo = "stato_forzato" con motivazione automatica.

Riferimento normativo

• Provv. AdE 30/04/2018 — Specifiche tecniche fatturazione elettronica v1.7.1
• Art. 1 comma 909 L. 205/2017 — Obbligo fatturazione elettronica
• Documentazione tecnica SdI — Cicli di vita fatture e notifiche

Parsing XML FatturaElettronica robusto

Il parsing del XML ricevuto da SDI è ora eseguito tramite la libreria xml2js (aggiunta come dipendenza backend). Gestisce correttamente namespaces, attributi, linee singole o array, riepiloghi IVA multipli.

• POST /api/fatturazione/sdi-passive/:id/parse-xml [ADMIN] — estrae DettaglioLinee, DatiRiepilogo, dati cedente; popola fattura_passiva_righe
• Ritorna: righeEstratte, riepilogoIva[] (aliquota + natura + imponibile + imposta + esigibilità), intestazioneFornitore

Contabilizzazione automatica fatture passive

Vedi manuale Contabilità § Contabilizzazione automatica. Pattern reverse charge per TD17/TD18/TD19 con doppia annotazione IVA credito/debito.

Esterometro — XML reale

Generazione del file XML "Dati fatture transfrontaliere" v3.0 (schema Agenzia Entrate) a partire dai documenti TD17/TD18/TD19 del trimestre.

• POST /api/fatturazione/esterometro-xml/genera/:periodo [ADMIN] (es. 2026-Q1) — produce XML con sezioni DTE (cessioni) e DTR (acquisti), salva file in /app/xml-generati/, aggiorna esterometro_comunicazioni.stato = INVIATO
• GET /api/fatturazione/esterometro-xml/download/:id — scarica il file XML generato
• Archivio centralizzato: xml_generati_archivio con path, SHA-256, contenuto inline se < 500KB

Intrastat — dichiarazioni cessioni / acquisti UE

Gestione dichiarazioni intra-comunitarie con tabelle intrastat_dichiarazioni (UNIQUE periodo + tipo) e intrastat_righe. Generazione XML secondo schemi ministeriali (INTRA-1bis per cessioni, INTRA-2bis per acquisti).

• GET/POST /api/fatturazione/intrastat/dichiarazioni — CRUD dichiarazioni con periodicità MENSILE / TRIMESTRALE
• POST /api/fatturazione/intrastat/righe/:dichiarazioneId [ADMIN] — inserisce riga con: paese ISO, PIVA controparte, codice NC8, valore statistico, massa netta kg, natura transazione (A-P tabella Dogana), condizioni consegna (INCOTERMS: EXW, FOB, CIF, DAP…), modo trasporto (1-5), paese origine
• POST /api/fatturazione/intrastat/genera-xml/:dichiarazioneId [ADMIN] — produce XML e setta stato PRESENTATA, data_presentazione = oggi

Archivio XML centralizzato

Tabella xml_generati_archivio raccoglie tutti gli XML generati (Esterometro, Intrastat, Autofattura). Ogni record ha hash SHA-256 per verifica integrità.

• GET /api/fatturazione/archivio-xml?tipo=ESTEROMETRO&periodo=2026-Q1 — lista filtrata

Le fatture devono essere trasmesse al Sistema di Interscambio entro 12 giorni dalla data documento (Art. 21 DPR 633/72, vigente dal 1° luglio 2019).

Dove si vede l'avviso

NOX ti avvisa in 3 punti diversi:

1. Dashboard: tra le notifiche compare un banner rosso critico se ci sono fatture DA_INVIARE oltre i 12 giorni. Cliccando si va in /sdi filtrato per DA_INVIARE.
2. Pagina /sdi (Archivio Emesse): in cima alla lista appare un banner riepilogo a 3 livelli con il conteggio aggregato delle fatture in vista del termine.
3. Riga tabella: per ogni fattura DA_INVIARE in vista del termine appare un badge pulsante con i giorni rimanenti (o di ritardo). Stesso badge nel modal «Genera XML da fatture».

Soglie di urgenza

• 🚨 SCADUTO (rosso): oltre 12 giorni dalla data documento — trasmetti subito
• ⚠️ Imminente (arancione): 2 giorni o meno residui
• ⏳ Attenzione (giallo): 5 giorni o meno residui

Le soglie sono visibili e configurabili in archivio-sdi.component.ts (costante TERMINE_SDI_GG).