Modulo Soggetti

Il modulo Soggetti rappresenta l'anagrafica unificata di NOX Enterprise Suite. Ogni persona fisica o giuridica viene registrata una sola volta e puo ricoprire simultaneamente piu ruoli: Cliente, Fornitore, Agente, Vettore, Paziente, Beneficiario.

Questo approccio elimina la duplicazione dei dati e garantisce coerenza in tutti i flussi operativi: fatturazione, contabilita, logistica, CRM e gestione clinica.

Header con reverse nome

L'intestazione della scheda mostra il nome nel formato COGNOME Nome (reverse) per facilitare l'ordinamento alfabetico e la ricerca rapida. Per le persone giuridiche viene visualizzata la ragione sociale.

Ogni soggetto puo avere uno o piu ruoli. L'attivazione di un ruolo abilita le sezioni condizionali corrispondenti.

Per creare un nuovo soggetto, seguire la procedura:

1. Accedere al menu Anagrafiche → Soggetti e premere il pulsante + Nuovo Soggetto.
2. Selezionare il tipo: Persona Fisica o Persona Giuridica.
3. Compilare i dati anagrafici obbligatori: cognome/nome (o ragione sociale), codice fiscale, indirizzo, comune, CAP, provincia.
4. Se applicabile, inserire la Partita IVA e il Codice SDI / PEC per la fatturazione elettronica.
5. Attivare uno o più ruoli tramite le checkbox nella sezione Ruoli.
6. Compilare le sezioni condizionali che appaiono in base ai ruoli selezionati.
7. Premere Salva per confermare la registrazione.

Formattazione automatica dei campi

La formattazione viene applicata automaticamente al salvataggio. I campi visualizzano il formato corretto anche durante la digitazione.

Codice Fiscale — Calcolo e inserimento manuale

• Il sistema calcola automaticamente il codice fiscale quando sono compilati Nome, Cognome, Data di Nascita, Sesso e Luogo di Nascita.
• Il pulsante refresh accanto al campo CF ricalcola il codice in qualsiasi momento.
• Se si inserisce il CF manualmente, il ricalcolo automatico si blocca e l'icona cambia in lucchetto (arancione). Il CF manuale viene preservato.
• Per sbloccare il ricalcolo automatico, premere il lucchetto.

Codice Fiscale e Partita IVA per società — Auto-fill

Per i tipi Persona Giuridica, Ditta Individuale, Professionista, Ente Pubblico, NOX riconosce due formati per il Codice Fiscale:

• 16 caratteri alfanumerici (CF persona fisica/professionista, schema AAAAAA00A00A000A): validazione con carattere di controllo (CIN).
• 11 cifre numeriche (CF società coincidente con Partita IVA): validazione con check digit Luhn modulo 10 (D.M. 23/12/1976).

Sotto il campo CF, una etichetta dinamica colorata mostra in tempo reale il tipo riconosciuto:

• 👤 Persona fisica — verde, formato 16 caratteri valido.
• 🏢 Società / Partita IVA — blu, formato 11 cifre valido.
• ✍ In digitazione — giallo, mostra quanti caratteri/cifre mancano.
• ⚠ Formato non riconosciuto — rosso.

Auto-compilazione bidirezionale CF ↔ P.IVA: nella maggioranza dei casi (~80%) per le società il Codice Fiscale coincide con la Partita IVA (entrambi 11 cifre identiche). NOX semplifica la digitazione:

• Inserendo la P.IVA per primo, se il campo CF è vuoto, il CF viene pre-compilato con lo stesso valore (debounce 250 ms).
• Inserendo il CF a 11 cifre per primo, se il campo P.IVA è vuoto, la P.IVA viene pre-compilata con lo stesso valore.
• L'auto-fill non sovrascrive mai un campo già valorizzato: l'utente può sempre digitare valori diversi.

Casi in cui CF e P.IVA sono diversi (ammessi ma rari):

• Enti non commerciali con attività commerciale mista: associazioni, fondazioni, comitati con CF dell'ente e P.IVA distinta per la sola attività soggetta a IVA.
• Società dopo cambio forma giuridica: il CF mantiene il numero originario mentre la P.IVA può essere riassegnata.

In questi casi, quando entrambi i campi sono compilati con valori differenti, NOX mostra un avviso giallo informativo «Attenzione: Codice Fiscale e Partita IVA risultano differenti — è il caso?». L'avviso non blocca il salvataggio, è solo un richiamo: se si tratta di un errore di battitura, l'utente può allineare i due valori; se invece la differenza è corretta, può ignorare l'avviso e salvare normalmente.

Tracciato XML SDI / FatturaPA: anche quando coincidono, NOX invia comunque entrambi i nodi separati nel tracciato (<CodiceFiscale> e <IdFiscaleIVA>) come previsto dalle specifiche tecniche del Sistema di Interscambio.

Autocomplete Luogo di Nascita e Località

• Digitare almeno 2 caratteri per attivare la ricerca comuni.
• Usare le frecce ↑↓ per navigare nella lista, Enter per selezionare, Esc per chiudere.
• Alla selezione, il sistema compila automaticamente: provincia, CAP, regione e codice catastale (per il calcolo CF).
• Dropdown robusto: la tendina filtrata dei comuni è ora in position:fixed e calcola dinamicamente la propria posizione tramite getBoundingClientRect() dell'input. Non può più essere «nascosta dentro il campo» o clippata da contenitori con overflow:hidden. Si riposiziona automaticamente anche quando l'utente scrolla la pagina o ridimensiona la finestra con il dropdown aperto.

Campi clinici (sezione Dati Clinici)

Per evidenziare i dati critici del paziente, i campi clinici hanno colori distintivi:

• Allergie e Farmaci Assunti — label e testo in rosso grassetto per massima evidenza
• Patologie — label e testo in verde grassetto

Campi obbligatori

La lista soggetti offre strumenti di ricerca avanzata:

1. Utilizzare la barra di ricerca in alto per cercare per nome, ragione sociale, codice fiscale, partita IVA, cellulare, telefono, email, codice, località, categoria o tag.
2. Applicare i filtri laterali per ruolo, stato (attivo/inattivo), comune o zona commerciale.
3. Fare clic su una riga per aprire la scheda dettaglio del soggetto.
4. Premere Modifica per abilitare la modifica dei campi. Le modifiche vengono tracciate nel log di audit.
5. Premere Salva per confermare le modifiche.

Barra azioni (footer scheda)

Il footer della scheda soggetto contiene i seguenti pulsanti:

La sezione Dati Commerciali appare quando il soggetto ha ruolo Cliente, Fornitore o Beneficiario. Contiene le condizioni economiche e di pagamento.

Visibile solo per soggetti con ruolo Agente. Definisce i parametri provvigionali e il portafoglio clienti.

Visibile solo per soggetti con ruolo Vettore. Parametri per la gestione delle spedizioni e dei DDT.

Disponibile per soggetti con ruolo Cliente o Fornitore. Permette di assegnare listini prezzi personalizzati e politiche di sconto.

1. Nella scheda soggetto, aprire la tab Listino & Sconti.
2. Selezionare il listino base da applicare al soggetto tra quelli configurati in anagrafica listini.
3. Definire eventuali sconti incondizionati (percentuale fissa applicata a tutti gli articoli).
4. Configurare sconti condizionati per categoria, famiglia articolo o singolo prodotto.
5. Impostare eventuali prezzi netti personalizzati che sovrascrivono il listino base per specifici articoli.
6. Salvare la configurazione. I prezzi verranno applicati automaticamente in fase di inserimento ordini e fatture.

Disponibile per soggetti con ruolo Cliente. Gestisce il ciclo di vita delle opportunita commerciali.

Visibile solo per soggetti con ruolo Paziente. Questa sezione contiene informazioni sanitarie protette dal GDPR e dal D.Lgs. 196/2003 (dati sensibili).

Per i soggetti con ruolo Cliente o Agente, la scheda presenta un pannello di statistiche commerciali calcolate in tempo reale:

Ogni soggetto può avere più sedi (legale, operativa, depositi, punti vendita) e più contatti (referenti, uffici, reparti).

Sedi

1. Nella scheda soggetto, aprire la tab Sedi.
2. Premere + Nuova Sede e compilare: denominazione, indirizzo, CAP, città, provincia.
3. Impostare il tipo sede: Legale, Operativa, Deposito, Punto vendita.
4. Contrassegnare una sede come predefinita per fatturazione e/o predefinita per spedizione.
5. La sede predefinita per fatturazione viene usata automaticamente nei documenti fiscali (Art. 21 DPR 633/72).
6. La sede predefinita per spedizione viene usata come destinazione nei DDT.

Contatti

1. Nella tab Contatti, premere + Nuovo Contatto.
2. Compilare: nome, cognome, ruolo/qualifica, telefono, cellulare, email.
3. Contrassegnare un contatto come referente principale per le comunicazioni.

Per i soggetti con ruolo Paziente o per minori/incapaci, è possibile associare un beneficiario o tutore legale che sarà l'intestatario dei documenti fiscali.

1. Nella scheda soggetto (Paziente), attivare il flag Ha tutore/beneficiario.
2. Compilare i dati del beneficiario: nome, cognome, data di nascita, luogo di nascita, codice fiscale.
3. In alternativa, selezionare un soggetto esistente come tutore tramite la ricerca.
4. Quando si crea un documento per questo paziente, il sistema propone automaticamente il tutore come intestatario della fattura.

Il modulo Soggetti è strettamente integrato con il modulo Documenti. Quando si seleziona un soggetto in un documento, il sistema:

1. Pre-compila i dati fiscali: denominazione, indirizzo, P.IVA, CF, codice SDI, PEC vengono inseriti automaticamente dalla scheda soggetto.
2. Applica le condizioni commerciali: tipo pagamento, condizioni pagamento, listino prezzi, sconti vengono applicati automaticamente.
3. Mostra la scheda cliente: sotto i dati del soggetto nel documento appare una barra con fatturato YTD, saldo dovuto, scadenze aperte, ultimi 5 documenti.
4. Propone gli ultimi 10 clienti: quando si clicca sul campo soggetto senza digitare, appare un dropdown con i 10 clienti usati più di recente.
5. Pre-compila l'agente: se il soggetto ha un agente di riferimento, viene assegnato automaticamente al documento con la provvigione predefinita.
6. Gestisce il tutore: per pazienti con tutore, il sistema propone automaticamente l'intestatario corretto per la fattura.
7. Applica la valuta: se il soggetto ha una valuta predefinita diversa da EUR, il documento viene convertito.

Il modulo Soggetti supporta l'importazione e l'esportazione massiva tramite il modulo Import / Export.

Esportazione

1. Accedere a Impostazioni → Import / Export.
2. Selezionare il modulo Anagrafica Soggetti.
3. Premere Configura Campi per selezionare quali campi esportare, riordinarli e assegnare alias personalizzati.
4. I campi disponibili vengono caricati direttamente dal database (80+ campi).
5. Scegliere il formato (CSV o Excel) e il separatore.
6. Premere Esporta. Il file viene scaricato con i campi selezionati.

Importazione

1. Scaricare il Template vuoto con le intestazioni dei campi configurati.
2. Compilare il file con i dati dei soggetti da importare.
3. Caricare il file e premere Importa.
4. Il sistema verifica i campi obbligatori (cognome/ragioneSociale), segnala duplicati e riporta il risultato (importati/errori).

Ogni scheda soggetto include una sezione dedicata alla gestione del consenso privacy ai sensi del Regolamento UE 2016/679 (GDPR) e del D.Lgs. 196/2003.

Per ogni consenso il sistema registra:

• Data di acquisizione — quando il consenso è stato raccolto
• Canale — cartaceo, email, web, telefono, PEC
• Flag attivo/revocato — stato corrente del consenso
• Data di revoca — se il soggetto ha esercitato il diritto di revoca

Aggiornamento funzionale del modulo Soggetti. Di seguito le novità introdotte.

Validazione formato e-mail su PEC e Email

I campi PEC ed Email della scheda soggetto ora validano il formato (pattern RFC 5322 semplificato). In caso di indirizzo malformato il campo viene evidenziato in rosso e il salvataggio chiede conferma.

Focus automatico su Telefono dopo selezione Localita

Dopo aver selezionato una Localita dal suggeritore (che compila automaticamente CAP e Provincia), il focus si sposta sul campo Telefono invece di tornare all'inizio del form. Flusso di digitazione più lineare.

Categorie predefinite

Sono disponibili nuove categorie soggetto preconfigurate:

• Cliente
• Fornitore
• Paziente
• Collaboratore
• Dipendente
• Professionista
• Ente Pubblico
• Associazione

Restano utilizzabili anche categorie personalizzate create dall'utente.

Fido Massimo in formato italiano

Il campo Fido Massimo utilizza ora il formato italiano con punto come separatore delle migliaia e virgola come decimale: 1.234,56. La digitazione accetta sia il punto che la virgola.

Navigazione CF con frecce

Quando il sistema propone di inserire un soggetto dopo la digitazione del codice fiscale, premendo la Freccia Giù dal campo CF si può navigare direttamente sui bottoni “Sì, inseriscilo” / “No, faccio io” senza usare il mouse.

Privacy auto-flag alla stampa Informativa

Alla stampa dell'Informativa Privacy dalla scheda soggetto, il campo flagInfoPrivacy viene impostato automaticamente a true. In questo modo il registro trattamenti riflette sempre lo stato reale della consegna dell'informativa.

Paginazione nel footer lista soggetti

La lista soggetti mostra in footer i controlli di paginazione con selettore righe per pagina (25 / 50 / 100 / 200).

Ordinamento per data modifica

La lista soggetti è ordinata di default per updatedAt decrescente: i soggetti modificati più di recente compaiono in cima.

Aggiornamento strutturale del modulo Soggetti: validazione fiscale estesa, gestione dei soggetti esteri, tracciamento modifiche, statistiche automatiche, operazioni massive e cestino con soft-delete.

Validazione fiscale estesa e blocco duplicati

Al salvataggio il sistema verifica:

• Codice Fiscale italiano: 16 caratteri alfanumerici con controllo del carattere di controllo (disp/pari) o 11 cifre con checksum P.IVA.
• Partita IVA italiana: 11 cifre con algoritmo Luhn mod 10.
• Duplicati: se esiste già un altro soggetto con lo stesso CF o P.IVA il salvataggio viene bloccato (errore 409) e il sistema indica l'id del soggetto già presente.

Gestione soggetti esteri

Per i soggetti non italiani il sistema non applica i controlli di formato/checksum italiani. L'attivazione del comportamento estero avviene in due modi:

• Scegliendo il tipo 🌎 Soggetto Estero nella riga dei tipi in alto alla scheda.
• Impostando il campo Paese con un codice diverso da IT (es. DE, FR, ES). Il campo è disponibile anche per i tipi Persona Fisica, Persona Giuridica, Professionista.

Quando il paese è estero, sotto i campi Codice Fiscale e Partita IVA viene mostrato il messaggio “🌎 Non verificabile per paese Estero” al posto degli errori di validazione italiani.

Audit log automatico delle modifiche

Ogni modifica alla scheda soggetto viene registrata nella tabella log_modifiche_soggetti, con valore precedente, valore nuovo, utente e data/ora. I campi tracciati sono 25, fra cui CF, P.IVA, ragione sociale, indirizzo, contatti, stato, flag privacy, agente di riferimento. La lista storica è accessibile via API GET /api/soggetti/:id/audit-log.

Statistiche automatiche del soggetto

I campi di riepilogo presenti sulla scheda soggetto sono ora aggiornati automaticamente ad ogni operazione sui documenti collegati (creazione, modifica, cambio stato, rinumerazione, duplicazione, cancellazione):

• Fatturato anno corrente e anno precedente
• Numero ordini complessivo
• Data e importo dell'ultima fattura
• Data ultimo ordine

È possibile forzare il ricalcolo globale con POST /api/soggetti/ricalcola-stats (utile dopo migrazioni o importazioni massive).

Timeline cronologica del soggetto

L'endpoint GET /api/soggetti/:id/timeline restituisce una vista aggregata degli eventi del soggetto: documenti emessi, attività CRM (appuntamenti, opportunità) e scadenze aperte, ordinate per data decrescente. Utile per ricostruire lo storico del rapporto commerciale o clinico.

Selezione multipla e azioni massive

Nella lista soggetti è disponibile una colonna di checkbox per la selezione multipla:

• Checkbox nell'intestazione di colonna: seleziona/deseleziona tutti i soggetti della pagina visibile.
• Checkbox per ogni riga: selezione singola; cliccare sul checkbox non apre la scheda del soggetto.
• Quando almeno un soggetto è selezionato compare una barra azioni blu in fondo alla lista con le operazioni disponibili.

Azioni disponibili:

• Attiva / Sospendi / Blocca: cambio massivo dello stato.
• Categoria…: assegnazione in blocco di una categoria (vuoto per rimuoverla).
• Privacy ON / OFF: imposta in blocco il flag informativa privacy.
• Elimina: sposta i soggetti nel cestino (soft-delete, reversibile).

Cestino e soft-delete

L'eliminazione di un soggetto (singola o massiva) è ora una cancellazione logica: il soggetto scompare dalla lista ma resta nel database con le colonne cancellatoIl e cancellatoDa valorizzate. I documenti collegati non vengono toccati.

• Pulsante 🗑 Cestino nel footer della lista: entra in modalità cestino e mostra solo i soggetti cancellati.
• Per ogni riga del cestino sono disponibili due azioni:
  • ↺ Ripristina: annulla la cancellazione, il soggetto torna nella lista attiva.
  • ✗ Definitivo: eliminazione fisica irreversibile. Blocca se il soggetto ha documenti collegati. Disponibile solo per utenti ADMIN o SUPERADMIN.
• In modalità cestino il clic sulla riga non apre la scheda di modifica (il soggetto è cancellato); vengono mostrati data e autore della cancellazione.

Controllo accessi granulare

L'accesso ai moduli è ora governato dalla configurazione menuConfig di ciascun utente. Un utente con ruolo USER può accedere ai moduli abilitati nel proprio profilo (Soggetti, Documenti, Catalogo, …), mentre operazioni distruttive o amministrative (cancellazione definitiva, parametri, gestione utenti, piano dei conti) restano riservate ai ruoli ADMIN e SUPERADMIN.

A partire dalla versione 2.2, il modulo Soggetti 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: Attiva, Disattiva, Soft-delete. Validazione CF/P.IVA lato server. La risposta indica N operazioni riuscite / M fallite; i dettagli delle fallite compaiono nella console browser (F12).

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.

Split payment PA — isPA + codiceIpa (v 2.2, aprile 2026)

In linea con il pacchetto FATTURAZIONE v 2.2 (feature #4) ogni soggetto dispone di due nuovi campi:

• isPA (boolean) — marca il soggetto come Pubblica Amministrazione
• codiceIpa (VARCHAR 20) — codice univoco Ufficio IPA (Indice PA), formato tipico UFXXXX

Quando si emette una fattura verso un soggetto con isPA=true, l'esigibilità IVA deve essere impostata a S (scissione dei pagamenti, art. 17-ter DPR 633/72): l'IVA non viene più incassata dal fornitore ma versata direttamente dalla PA all'Erario.

Endpoint dedicati:

• PATCH /api/fatturazione/soggetto/:id/is-pa body {isPA:true, codiceIpa:"UFABCD"}
• GET /api/fatturazione/soggetti-pa — elenco enti PA attivi (escludi cestino)

Aliquota provvigione default (v 2.2, aprile 2026)

Nuovo campo aliquotaProvvigioneDefault (NUMERIC 5,2) sul soggetto agente. Viene usata dal calcolo automatico delle provvigioni (feature #10) quando non è specificata un'aliquota esplicita al momento della creazione della provvigione.

Professionista: rivalsa INPS + cassa previdenziale default (v 2.2 wave 7)

Per i soggetti professionisti il sistema ora conserva la configurazione previdenziale di riferimento, applicata automaticamente a tutte le fatture emesse verso/da quel soggetto:

• tipoProfessionista (VARCHAR 20) — valori: INPS_GS (Gestione Separata), CNPADC (Dottori Commercialisti), ENPAP (Psicologi), ENPAM (Medici), ENPAV (Veterinari), EPAP (pluricategoriale attuari/chimici/agronomi/geologi)
• aliquotaRivalsaInpsDefault (NUMERIC 5,2) — % rivalsa INPS addebitata in fattura (max 4% per gest. separata art. 1 c.212 L. 662/1996)
• cassaPrevidenzaDefault (VARCHAR 20) — codice categoria cassa (TC01..TC22, FK logica a categorie_cassa_previdenza)

Quando si emette una fattura verso un soggetto professionista, questi campi forniscono i valori preimpostati al modulo documento. L'operatore può sempre fare override in fattura. Il calcolo di rivalsa, cassa e relativo impatto su base IVA è documentato in dettaglio nel manuale di Contabilità (§ Cassa previdenziale TC01..TC22).

Sulla scheda soggetto c'è un unico campo per il pagamento: «Condizioni di Pagamento». La singola Condizione include già al suo interno:

• Modalità SDI (codici MP01-MP23) — come si pagano i soldi (contanti, bonifico, RIBA, POS, ecc.)
• Tempistica (codici TP01-TP03) — quando e in quante volte (pagamento completo, a rate 30/60/90 gg, anticipo)
• Flag operativi — richiede IBAN, richiede riferimento, è pagamento immediato (bollo), è addebito diretto, applica sconto pagamento anticipato, ecc.

Configurare le Condizioni di Pagamento

Per definire o modificare le Condizioni vai in Tabelle > Condizioni Pagamento (sidebar Amministrazione). Per ogni Condizione configurabile:

• Codice (es. TP01-30GG) e descrizione breve/completa
• Modalità pagamento SDI: dropdown con MP01-MP23, viene scritta nel XML FatturaPA
• Flag operativi: richiede IBAN, richiede riferimento, pagamento immediato (bollo), addebito diretto, sconto pagamento anticipato
• Parametri: numero rate, giorni scadenza, fine mese sì/no, ecc. (JSON)

Esempi di Condizioni tipiche

Cosa appare nella scheda soggetto

Una sola dropdown «Condizioni di Pagamento» con label arricchita: per ogni voce vedi codice — descrizione — modalità SDI (es. «RIBA-30/60/90 — RIBA 30/60/90 gg — MP12 RIBA»). Sotto la dropdown un'etichetta blu mostra la modalità SDI associata alla condizione scelta. Se la Condizione non ha una modalità configurata appare un avviso giallo per ricordarti di completarla in Tabelle > Condizioni Pagamento.