Modulo Scadenzario

Il modulo Scadenzario gestisce il ciclo di vita delle scadenze di pagamento generate dai documenti fiscali (fatture di vendita e acquisto). Le scadenze vengono create automaticamente in base alle condizioni di pagamento associate al documento e al soggetto.

Ogni scadenza (rata) possiede una data di scadenza, un importo e uno stato che evolve nel tempo: Aperta, Pagata o Scaduta. Il sistema aggiorna lo stato automaticamente confrontando la data di scadenza con la data corrente.

All'interno di ogni documento fiscale (fattura, nota di credito) e presente la tab Scadenzario che mostra il piano rate generato automaticamente.

🔄 Rigenerazione automatica al cambio condizioni

Le scadenze si rigenerano automaticamente in due momenti:

• Al cambio delle condizioni di pagamento (debounced 300ms)
• Dopo ogni salvataggio del documento (cambi righe/totale → rate aggiornate, debounced 400ms)

Salvaguardia: la rigenerazione automatica non parte se ci sono rate già PAGATA, per non perdere il pagato. In quel caso interviene il banner di disallineamento descritto sotto, che ti permette di scegliere consapevolmente come procedere.

⚠ Banner disallineamento con 3 azioni

Aprendo la sezione Scadenze di un documento, se il totale rate non corrisponde al totale documento appare un banner ambrato in cima alla sezione con:

• Totale documento, totale rate, differenza, eventuali spese escluse
• Avviso esplicito se ci sono rate già PAGATA (richiede attenzione)

Tre pulsanti per scegliere come risolvere:

• 🔄 Rigenera tutto (rosso) — elimina tutte le rate e ricalcola sul totale documento corrente. Se ci sono rate PAGATA chiede conferma esplicita prima di procedere.
• 🗛 Rata di pareggio (X €) (blu) — aggiunge una nuova rata della differenza, lasciando intatte le rate esistenti. Chiede solo la data scadenza (default oggi+30gg).
• ❌ Ignora (grigio) — chiude il banner senza modifiche.

La scelta giusta dipende dal contesto: se il pagato registrato è corretto e bisogna addebitare la differenza al cliente → Rata di pareggio. Se il documento è stato modificato dopo l'incasso e il pagato va riazzerato → Rigenera tutto.

Le condizioni di pagamento determinano come l'importo del documento viene suddiviso in rate. Si configurano in Impostazioni → Condizioni di pagamento.

1. Accedere a Impostazioni → Condizioni di pagamento e premere + Nuova condizione.
2. Inserire un codice e una descrizione (es. “30/60 DFFM”).
3. Selezionare il tipo pagamento predefinito (bonifico, RiBa, cambiale, contanti, ecc.).
4. Definire le righe rate: per ciascuna rata specificare i giorni dalla data documento (o da fine mese), la percentuale dell'importo totale e il tipo pagamento specifico se diverso dal predefinito.
5. Salvare la condizione. Sara selezionabile nei documenti e nelle schede soggetto.

La vista principale del modulo presenta l'elenco di tutte le scadenze con filtri avanzati per una gestione efficace.

1. Accedere al menu Contabilita → Scadenzario per visualizzare la lista completa delle scadenze.
2. Utilizzare i filtri per stato: Aperta, Pagata, Scaduta oppure Tutte.
3. Filtrare per periodo: selezionare un intervallo di date scadenza (da/a).
4. Filtrare per soggetto: cercare per nome, ragione sociale o codice fiscale.
5. Fare clic su una scadenza per aprire il dettaglio e accedere alle azioni di registrazione pagamento.

💰 Importi in formato italiano (1.234,00)

Tutti gli importi nello scadenzario — sia nelle righe sia nei totali — sono visualizzati ed editati in formato italiano: punto come separatore di migliaia e virgola come separatore decimale. Es. 2.886,15 € invece di 2886.15 €.

Anche i campi editabili (importo rata in modifica inline) sono in formato italiano: alla scrittura il parser riconosce «1.234,56», «1234,56» e «1234.56». Al blur viene riformattato.

La registrazione del pagamento aggiorna lo stato della scadenza e alimenta la situazione finanziaria del soggetto.

Pagamento totale

1. Dalla lista scadenze o dalla tab Scadenzario del documento, selezionare la rata da incassare.
2. Premere il pulsante Registra pagamento.
3. Verificare l'importo (precompilato con il saldo residuo) e la data di pagamento.
4. Confermare. Lo stato della rata passa a Pagata.

Pagamento parziale

1. Nella finestra di registrazione, modificare l'importo inserendo un valore inferiore al saldo residuo.
2. Confermare il pagamento parziale. Il sistema registra l'acconto e aggiorna il saldo residuo della rata.
3. La rata resta in stato Aperta (o Scaduta) fino al saldo completo.

Ogni riga nella lista scadenze mostra i seguenti pulsanti nella colonna Azioni:

La dashboard principale di NOX Enterprise Suite include la stat card Scadenze aperte che fornisce una visione immediata della situazione finanziaria.

Ai sensi del D.Lgs. 231/2002, in caso di ritardo nel pagamento di transazioni commerciali tra imprese (o tra imprese e PA), il creditore ha diritto agli interessi moratori calcolati automaticamente dal sistema.

Il sistema calcola gli interessi moratori sulle scadenze con stato Scaduta e li rende disponibili per l'eventuale addebito al debitore tramite nota di debito.

Lo scadenzario supporta la selezione multipla per l'invio massivo di solleciti di pagamento.

1. Utilizzare le checkbox a sinistra di ogni riga per selezionare le scadenze da sollecitare.
2. La checkbox nell'header seleziona/deseleziona tutte le scadenze visibili.
3. Una barra scura appare in alto con il conteggio e il bottone Invia Solleciti.
4. Il sistema invia un'email di sollecito a ogni soggetto che ha un indirizzo email o PEC.
5. L'email include: numero documento, importo, data scadenza e una richiesta di pagamento.
6. Al termine viene mostrato il riepilogo: N solleciti inviati, N errori.

Sollecito singolo: è anche possibile inviare un sollecito per una singola scadenza tramite il bottone dedicato nella riga.

L'aging report (invecchiamento crediti) classifica le scadenze scadute per fasce temporali. È visibile in due punti:

L'aging viene calcolato automaticamente dai dati delle scadenze aperte, senza chiamate API aggiuntive.

Lo scadenzario supporta l'incasso parziale: una scadenza può essere saldata gradualmente senza doverla chiudere interamente.

1. Nella riga della scadenza, premere il bottone Registra incasso.
2. Inserire l'importo parziale ricevuto, la data di pagamento e la modalità di incasso.
3. Il sistema aggiorna il campo importoPagato e calcola il residuo.
4. La scadenza resta in stato ATTESA fino al saldo completo.
5. Quando l'importo pagato raggiunge l'importo totale, la scadenza passa a PAGATA.

I dati dello scadenzario alimentano la sezione Situazione Finanziaria nella dashboard principale:

Le scadenze possono essere esportate tramite Impostazioni → Import / Export → Scadenzario.

1. Selezionare il modulo Scadenzario.
2. Premere Configura Campi per selezionare i campi da esportare (data scadenza, importo, soggetto, stato, numero documento, ecc.).
3. I campi vengono caricati dal database con tutti i campi disponibili.
4. Esportare in CSV o Excel.

Aggiornamento strutturale del modulo Scadenzario con tracciamento modifiche, cestino compliance-safe e operazioni massive. Il design rispetta le implicazioni contabili: le scadenze pagate non possono essere cancellate per non falsificare il registro incassi.

Soft-delete limitato alle scadenze ATTESA

L'eliminazione di una scadenza segue regole differenti in base allo stato:

• ATTESA: eliminazione = soft-delete (la scadenza va nel cestino, e ripristinabile).
• SCADUTA / PAGATA / ANNULLATA: eliminazione non consentita (errore 409). Per una scadenza gia pagata e necessario prima stornare il pagamento (riportandola ad ATTESA).

Questa distinzione protegge il registro incassi da cancellazioni improprie.

Cestino + ripristino

Un nuovo pulsante 🗑 Cestino nell'header della pagina apre la vista delle scadenze cancellate. Per ogni riga sono disponibili:

• ↺ Ripristina: la scadenza torna nella lista attiva.
• ✗ Definitivo: eliminazione fisica irreversibile (solo se la scadenza e gia cancellata e in stato ATTESA).

Audit log delle modifiche

Ogni modifica a una scadenza (importo, date, stato, modalita incasso, riferimento, note) viene registrata nella tabella log_modifiche_scadenze con valore precedente, valore nuovo, utente e timestamp. Accesso via GET /api/scadenzario/:id/audit-log.

Questo risponde alla domanda piu frequente: “chi ha marcato questa fattura come pagata e quando?” L'audit cattura anche i cambi di stato via bulk (marca-pagata massiva, proroga), con una entry per ogni scadenza modificata.

Timeline scadenza

L'endpoint GET /api/scadenzario/:id/timeline restituisce la cronologia completa delle modifiche in ordine decrescente.

Operazioni massive

La barra azioni che compare con la selezione multipla include ora:

• 💰 Marca pagate: imposta stato PAGATA con data di pagamento comune, modalita e riferimento per tutte le scadenze selezionate. La data comune e un default: ogni scadenza e poi modificabile singolarmente via editing inline senza perdere l'impostazione di gruppo. L'audit registra il cambio su ciascuna.
• 🔁 Proroga…: sposta la dataScadenza di N giorni (anche negativi) su tutte le scadenze selezionate. Utile per concordare un piano di rientro con il cliente o spostare una scadenza vicina a una festivita.
• 📧 Solleciti: invariato, invia email automatiche (solo per scadenze SCADUTA).
• 🗑 Cestino: sposta nel cestino solo le scadenze in stato ATTESA; le altre vengono ignorate e riportate come bloccate nella risposta.

Matrice transizioni di stato (validate dal bulk)

Esempio operativo: chiudo 40 fatture di Natale

1. Filtrare la lista per Stato=ATTESA e periodo dicembre.
2. Spuntare Seleziona tutte in testata.
3. Premere 💰 Marca pagate.
4. Inserire data di pagamento 31/12/2025, modalita BONIFICO, riferimento “Saldo anno 2025”.
5. Il sistema aggiorna le 40 scadenze in una sola operazione e registra 40 entry di audit.
6. Se alcune sono state pagate in date diverse, aprirle singolarmente e modificare la dataPagamento — la modifica viene registrata nell'audit.

A partire dalla versione 2.2, il modulo Scadenzario adotta lo standard di certificazione NOX con i seguenti presidi:

Cestino e soft-delete

Gli elementi cancellati non vengono rimossi fisicamente ma spostati in un cestino interno (campi cancellatoIl / cancellatoDa). Dalla toolbar il pulsante Cestino alterna tra vista attivi e vista cestino. Dal cestino è possibile:

• Ripristinare l'elemento (riportarlo nella lista attiva) — operazione riservata ad amministratori.
• Eliminare definitivamente con motivazione obbligatoria — azione irreversibile, riservata ad amministratori, tracciata nell'audit log.

Azioni massive (bulk)

È possibile selezionare più elementi con le checkbox della prima colonna. Appare una barra inferiore con le azioni disponibili: Imposta data pagamento massiva (mantiene possibilità di modifica singola). La risposta indica N operazioni riuscite / M fallite; i dettagli delle fallite compaiono nella console browser (F12).

Guard periodo IVA chiuso (v 2.2)

Se il documento di origine della scadenza appartiene a un periodo IVA chiuso (registri IVA), la modifica della scadenza viene bloccata con HTTP 409. Per modificarla è necessario:

• riaprire il periodo IVA (solo admin + motivazione);
• oppure creare una nuova scadenza nel periodo corrente (consigliato).

Storico modifiche (audit log)

L'icona history nelle azioni di riga apre un modal con la storia completa delle modifiche: data, campo, valore precedente, valore nuovo, operatore, eventuale motivazione. I record di audit non sono modificabili né eliminabili via UI. Conservazione: indefinita (art. 2220 c.c. — 10 anni minimo).

Mascheramento dati sensibili (GDPR art. 32)

Se i campi modificati contengono dati sensibili (IBAN, Codice Fiscale, Partita IVA, password/token), l'audit log salva il valore mascherato anziché in chiaro:

Timeline aggregata

Per ciascun elemento è disponibile una vista Timeline che aggrega in ordine cronologico audit, eventi del ciclo di vita ed eventuali entità collegate (es. documenti, movimenti, storni).

RBAC uniforme

Tutte le azioni distruttive o massive (soft-delete, ripristino, eliminazione definitiva, bulk, storno) richiedono il ruolo ADMIN o superiore. Gli operatori possono continuare a creare / modificare / consultare secondo le proprie abilitazioni.

Scadenze multi-rata acconto/saldo (v 2.2, aprile 2026)

Feature #5 del pacchetto FATTURAZIONE v 2.2: permette di definire per ogni documento un piano di pagamento articolato in acconto + rate intermedie + saldo finale. Due nuovi campi su documento_scadenze:

• tipoRata (VARCHAR 20) — valori ammessi: ACCONTO, RATA, SALDO. Default RATA
• ordineRata (INT) — ordine di successione (1, 2, 3...). Default 1

Endpoint dedicato:

POST /api/fatturazione/scadenze-multi-rata/:docId
Body: { rate: [ { tipoRata, percentuale, giorni, descrizione }, ... ] }

Ogni elemento rate contiene:

• tipoRata: ACCONTO / RATA / SALDO
• percentuale: quota sul totale documento (la somma di tutte le rate deve essere esattamente 100; se diversa, HTTP 400)
• giorni: scadenza calcolata da dataDocumento + N giorni
• descrizione: nota libera (opzionale)

Esempio pratico — acconto 30% alla consegna + saldo 70% a 60gg:

[
  { "tipoRata": "ACCONTO", "percentuale": 30, "giorni": 0, "descrizione": "Acconto alla consegna" },
  { "tipoRata": "SALDO",   "percentuale": 70, "giorni": 60, "descrizione": "Saldo a 60gg DF" }
]

L'endpoint azzera le scadenze esistenti e ricrea il piano dalla data documento. Le nuove scadenze partono tutte in stato ATTESA e sono gestibili dalle normali funzioni di scadenzario (incasso, solleciti, cancellazione).

Solleciti automatici + interessi legali (v 2.2 wave 7, aprile 2026)

Il sistema gestisce 4 livelli di sollecito con template personalizzabili: 1° cortese (+7 gg), 2° (+30 gg), 3° ultimo avviso (+60 gg), 4° diffida ex art. 1454 c.c. (+90 gg). A ogni livello può essere associato il calcolo automatico degli interessi legali al tasso BCE vigente (2026: 5%, aggiornato annualmente con decreto MEF).

Sostituzioni di variabili nel template

Oggetto e corpo supportano le seguenti variabili che vengono sostituite al momento dell'invio:

Formula interessi legali

interessi = (importoScaduto × aliquotaBCE × giorniRitardo) / (365 × 100)

Se il template ha calcolaInteressiLegali=false, viene stampato € 0,00. Override aliquota su base per-template (campo aliquotaInteressi).

Tabelle e endpoint

• Tabelle: template_sollecito (4 livelli seed) + solleciti_documento (log invii)
• GET /api/fatturazione/solleciti/templates — elenco template attivi
• PUT /api/fatturazione/solleciti/templates/:id [ADMIN] — modifica oggetto/corpo/giorni/aliquota
• POST /api/fatturazione/solleciti/invia/:docId body {livello, scadenzaId?, destinatarioOverride?} — genera sollecito, sostituisce variabili, registra log; se scadenzaId non passato, usa la prima scadenza in stato ATTESA
• GET /api/fatturazione/solleciti/log/:docId — storico solleciti inviati al documento
• GET /api/fatturazione/solleciti/scaduti?giorni=N — cruscotto operativo di tutte le scadenze pendenti oltre N giorni con livello ultimo sollecito e dati soggetto

Invio SMTP reale solleciti (v 2.2 wave 8, aprile 2026)

Sostituisce la modalità log-only della wave 7 con invio effettivo via nodemailer. La configurazione SMTP è letta dalla tabella parametri (campi smtpHost, smtpPort, smtpUser, smtpPass, smtpSecure, smtpFrom) e deve essere testata (smtpTestato = true) prima dell'uso effettivo (bandiera di sicurezza).

Endpoint

• POST /api/fatturazione/solleciti-smtp/invia/:docId body {livello, scadenzaId?, destinatarioOverride?, allegaPdf?} — invio singolo. Ritorna {ok, esito, destinatario, importoScaduto, interessi, messageId}.
• POST /api/fatturazione/solleciti-smtp/invia-bulk [ADMIN] body {livello=1, giorniRitardoMinimo=7, limiteInvii=50} — invio massivo a tutte le scadenze candidate. Esclude automaticamente i destinatari già sollecitati al livello ≥ N.

Tracciamento doppio

Ogni invio SMTP riuscito/fallito viene loggato in due tabelle:

• solleciti_documento — log dettagliato del sollecito con livello, corpo, interessi, destinatario, esito
• log_invio_email_documento — log generale email (evento AUTO_SOLLECITO) per riepilogo storico

Le scadenze ora supportano incassi multipli. Se un cliente paga solo una parte (es. 40% subito, 30% a 30gg, 30% a 60gg), puoi registrare ogni incasso separatamente e la scadenza tiene traccia del residuo.

Quando registri un incasso, il dialog mostra:

• Il residuo corrente a fianco del label «Importo Incassato»
• Quick-button: «Tutto residuo» / «Metà» / «1/3»
• Banner ambra «Pagamento parziale: dopo questo incasso resteranno X €. La scadenza passerà a stato PARZIALE» se l'importo è minore del residuo

Stati possibili della scadenza:

• ATTESA: nessun pagamento
• PARZIALE: incassi parziali registrati (campo importoPagato < importo totale)
• PAGATA: completamente saldata
• SCADUTA: oltre la dataScadenza e non pagata

Spese banca / bolli su tratta — Modalità di addebito

Quando una Condizione di Pagamento ha attivi i flag «Includi spese bancarie» e/o «Includi bolli su tratta», NOX permette di scegliere come trattare quelle spese tramite il selettore «Modalità di addebito spese» (vedi Manuale Tabelle):

• 🏦 In scadenzario (default) — spese addebitate dalla banca al cliente in fase di incasso (RIBA / SEPA / tratta). Le rate vengono maggiorate dalle spese (es. 100 € rata + 5 € spese banca = 105 €) e nella nota della rata appare «+ spese € X.XX». Non vanno in fattura: non sono ricavi del cedente.
• 📋 In fattura — NOX aggiunge automaticamente al documento le righe «Spese bancarie» e/o «Bolli su tratta» con importo dai Parametri Azienda, aliquota 0%, natura N1 (escluso art. 15 DPR 633/72). Le rate non vengono maggiorate (sennò le spese sarebbero conteggiate due volte) e il totale documento include già le spese.

Validazione «Scadenzario disallineato» (fix 6 Maggio 2026)

Quando si apre un documento in modifica, NOX verifica che la somma degli importi delle rate corrisponda al totale documento. Il messaggio di errore «Scadenzario disallineato: totale scadenze X € ≠ totale documento Y €. Rigenerare le scadenze.» è ora più preciso:

• Le spese banca/bolli per rata (note «+ spese € X.XX») vengono scorporate dalla somma scadenze prima del confronto, evitando falsi allarmi quando la condizione di pagamento ha includeSpeseBanca/includeSpeseBolli attivi e modalità IN_SCADENZARIO.
• Se persiste un disallineamento reale, il messaggio cita esplicitamente l'importo scorporato: «... (escluse € X.XX di spese banca/bolli per rata) ...».

In caso di disallineamento reale, vedi sotto il banner di disallineamento con le 3 azioni dedicate.