Catalogo Prodotti / Servizi

Il modulo Catalogo Prodotti/Servizi rappresenta l'archivio unificato di tutte le voci che possono essere inserite nei documenti commerciali e clinici di NOX Enterprise Suite. Ogni voce viene classificata in uno degli 8 tipi previsti e puo contenere informazioni specifiche in base alla propria natura (farmaco, articolo, prestazione, ecc.).

L'approccio a catalogo unico consente di gestire in un solo punto prezzi, aliquote IVA, codici, descrizioni e regole di magazzino, evitando duplicazioni e garantendo coerenza in tutti i flussi: fatturazione, ordini, DDT, ricette e prestazioni cliniche.

Il catalogo prevede 8 tipi di voce. Il tipo determina le sezioni disponibili nella scheda e il comportamento in fase di inserimento nei documenti.

Per creare una nuova voce di catalogo, seguire la procedura:

1. Accedere al menu Anagrafiche → Catalogo Prodotti/Servizi e premere il pulsante + Nuova Voce.
2. Selezionare il tipo di voce tra gli 8 disponibili (FARMACO, ARTICOLO, PRESTAZIONE, KIT, PARCELLA, SPESE, BOLLO, TESTO_LIBERO).
3. Compilare la tab Dati base: codice, descrizione, unita di misura, prezzo di vendita, aliquota IVA, eventuale sconto predefinito.
4. Compilare la tab Dettaglio (visibile per FARMACO, ARTICOLO, PRESTAZIONE) con i campi specifici del tipo selezionato (v. sezione 4).
5. Se il tipo prevede gestione magazzino (FARMACO, ARTICOLO), compilare la tab Magazzino con giacenza iniziale, scorta minima, lotto e scadenza (v. sezione 5).
6. Se il tipo e KIT, compilare la scheda 🧰 Componenti con la distinta base dei componenti (v. sezione 6).
7. Premere Salva per confermare la registrazione nel catalogo.

Tab Dati base — campi principali

Conto di costo

Il campo facoltativo Conto di costo dice su quale conto registrare questa voce quando la si compra: per esempio un canone di noleggio su «Godimento beni di terzi». Vale anche se il fornitore ha un suo conto di costo. Lasciato su Automatico, il conto lo sceglie NOX dal fornitore o dal tipo di voce (vedi il manuale Contabilità). La tendina propone solo conti di costo.

La tab Dettaglio presenta campi specifici in base al tipo di voce selezionato.

Dettaglio FARMACO

Dettaglio ARTICOLO

Prezzi, margini e ricarico

Dettaglio PRESTAZIONE

Disponibile per le voci di tipo FARMACO e ARTICOLO. Gestisce giacenze, scorte e tracciabilita dei lotti.

Oltre ai dati base e magazzino, la scheda articolo prevede altre tab per informazioni logistiche, fisiche e di catalogazione. Tutti questi campi vengono salvati e alcuni alimentano le analisi di magazzino (es. la scheda Riordino).

🚚 Tab Logistica e riordino

📐 Tab Dimensioni (caratteristiche fisiche)

🏷️ Varianti e catalogazione

Con il pacchetto Taglie & Colori, in fondo alla scheda di un articolo già salvato c'è il pulsante Taglie e colori…: apre la griglia su quell'articolo, da cui diventa il modello e genera una combinazione (un articolo vero) per ogni taglia e colore. Su un modello il pulsante si chiama Griglia taglie e colori; una combinazione non ce l'ha. Senza il pacchetto il pulsante non c'è. Vedi il Manuale Taglie & Colori.

Una voce di tipo KIT e composta da una distinta base di componenti. Ogni componente e a sua volta una voce di catalogo (FARMACO, ARTICOLO, PRESTAZIONE, ecc.) e nel kit si indica la sua quantità. Unità di misura, prezzo, aliquota IVA e sconto vengono dalla scheda del prodotto: si cambiano lì, e il kit (e i documenti fatti da quel momento) li prende da solo. Non serve togliere e rimettere il componente.

Creazione della distinta base

1. Aprire la scheda della voce KIT e selezionare, a sinistra, la scheda 🧰 Componenti.
2. Nella casella «Cerca voce da aggiungere…» scrivere almeno parte del codice o della descrizione (oppure * per vederle tutte) e cliccare la voce: diventa un componente. Il pulsante 📋 accanto apre l'elenco completo del catalogo da sfogliare.
3. Impostare la quantità del componente nella sua riga. È l'unico valore del componente che si sceglie nel kit.
4. Per togliere un componente: il pulsante ✕ in fondo alla riga.
5. Premere Salva: si salvano la voce e i suoi componenti. Se i componenti non si possono salvare (per esempio per un permesso mancante) compare un avviso.
6. Il totale del KIT viene calcolato automaticamente come somma dei componenti (quantita x prezzo - sconto, per ciascuna riga).

Quando si inserisce un KIT in un documento (fattura, ordine, DDT), il sistema offre 3 modalita di inserimento:

Opzione “Mantieni prezzo bundle”

Nel popup di inserimento KIT è presente la checkbox “Mantieni prezzo bundle del kit — distribuisci lo sconto sui componenti”. Quando attiva (e si sceglie una delle due modalità di esplosione), i prezzi dei componenti vengono scalati proporzionalmente in modo che la loro somma resti uguale al prezzo bundle del KIT.

Formula: fattore = prezzoBundleKit / sommaPrezziComponenti, applicato a ogni prezzoUnitario di riga esplosa.

Oltre ai dati standard, ogni voce di catalogo puo essere arricchita con contenuti extra configurabili dall'amministratore.

Configurazione

L'amministratore definisce i campi extra da Impostazioni → Configurazione Catalogo → Contenuti Extra. Per ogni campo extra e possibile specificare:

• Nome del campo e etichetta visualizzata
• Tipo di dato (testo, numero, data, lista valori, booleano)
• Obbligatorieta e valore predefinito
• Tipi di voce a cui si applica (es. solo FARMACO, oppure tutti)

Visualizzazione

I contenuti extra appaiono nella scheda della voce di catalogo in una sezione dedicata sotto le tab standard. Sono visibili anche nella griglia di lista tramite colonne configurabili e possono essere utilizzati come criteri di filtro e ricerca.

La lista del catalogo prodotti/servizi supporta filtri persistenti salvati nel localStorage del browser. Questo significa che i filtri impostati dall'utente vengono mantenuti tra una sessione e l'altra.

1. Nella lista catalogo, impostare i filtri desiderati: tipo di voce, stato (attivo/inattivo), categoria, testo libero.
2. I filtri vengono salvati automaticamente nel localStorage del browser al momento dell'applicazione.
3. Alla successiva apertura della pagina, i filtri vengono ripristinati automaticamente.
4. Per azzerare tutti i filtri, premere il pulsante Azzera filtri.

Per le voci di tipo FARMACO, e disponibile il flag Richiede Posologia nella tab Dettaglio.

Funzionamento

• Quando il flag e attivo, il sistema visualizza un avviso ogni volta che il farmaco viene inserito in un documento o in una ricetta, ricordando all'operatore di indicare la posologia.
• L'avviso non e bloccante: l'operatore puo proseguire anche senza compilare la posologia, ma l'avviso resta visibile fino alla compilazione.
• La posologia viene registrata come nota di riga nel documento ed e stampata nella ricetta o nel documento consegnato al paziente.

Gli articoli del catalogo con flag Gestione Magazzino attivo vengono tracciati nelle giacenze. L'integrazione prevede:

Il catalogo può essere importato ed esportato tramite Impostazioni → Import / Export → Catalogo Prodotti.

1. Selezionare il modulo Catalogo Prodotti nella griglia.
2. Premere Configura Campi per scegliere quali dei 59+ campi includere.
3. Assegnare alias personalizzati alle intestazioni se necessario.
4. Esportare in CSV o Excel, oppure importare da file con mappatura automatica.

Anche dalla lista del catalogo si esporta e si importa in CSV. Il file esportato si reimporta così com'è: le colonne (Codice, Descrizione, Tipo, UM, Prezzo, IVA %, Natura IVA, Attiva) si riconoscono senza badare a maiuscole e accenti, e i prezzi si leggono con la virgola o col punto. Le voci il cui codice è già a catalogo non vengono toccate: NOX le conta a parte («già a catalogo»).

Gli articoli possono essere organizzati in categorie gerarchiche per facilitare la navigazione e l'analisi.

1. Le categorie si gestiscono dalla sezione Parametri → Gestione Tabelle.
2. Ogni articolo può appartenere a una categoria.
3. Le categorie alimentano i filtri nella lista catalogo, l'analisi ABC per categoria in Magazzino, e il report per categoria nella Dashboard.

Sono due concetti diversi che spesso vengono confusi. Il Tipo definisce cosa è una voce e cambia il funzionamento del software; la Categoria è solo un'etichetta tua per raggrupparla.

TIPO (Tipo voce)

È una classificazione di sistema, a elenco fisso (Farmaco, Integratore, Omeopatico, Fitoterapico, Vitamina, Prodotto/Articolo, Prestazione, Parcella, Kit, Testo libero…). Definisce la natura della voce e cambia il comportamento del software:

• determina quali campi e tab compaiono nella scheda — ad esempio un Articolo ha la tab Magazzino/giacenze, un Kit ha i componenti, un Farmaco ha AIC e posologia, una Prestazione è un servizio senza magazzino;
• determina come la voce si comporta nei documenti;
• determina quali voci appaiono nel catalogo in base al profilo attività.

Non si inventa: si sceglie da una lista predefinita. È obbligatorio.

CATEGORIA

È un'etichetta libera creata dall'utente (col pulsante ⚙️ Gestisci Categorie), puramente organizzativa. Serve a raggruppare, filtrare e cercare le voci senza cambiare nulla nel funzionamento. È opzionale. Esempi: “Vitamine gruppo B”, “Antinfiammatori naturali”, “Creme viso”, “Consulenze”.

Dove si imposta la Categoria

Nella scheda della voce, tab Dati base.

Ogni articolo del catalogo supporta tre codici identificativi per l'integrazione con sistemi di scansione:

Nel modulo Magazzino, il campo scanner barcode nella toolbar cerca per tutti e tre i codici. La stampa etichette genera etichette con barcode Code 128 leggibili dagli scanner.

Aggiornamento strutturale del modulo Catalogo: validazione codici, tracciamento modifiche, statistiche di vendita automatiche, operazioni massive e cestino con soft-delete.

Controlli fiscali al salvataggio

Una voce si inserisce una volta e finisce su mille fatture: se l'IVA è sbagliata, sono sbagliate tutte, e non lo si scopre inserendo — lo si scopre dallo SdI, mesi dopo. Perciò al salvataggio il sistema verifica:

• Aliquota IVA: sono ammesse solo quelle che esistono in Italia — 4, 5, 10 e 22 — più lo zero per le operazioni senza IVA. Il 20% e il 21% restano accettati perché un documento vecchio si può ancora ristampare.
• Natura IVA: deve essere uno dei codici del tracciato (da N1 a N7).
• Aliquota e natura si escludono: o l'IVA c'è e la natura no, o l'IVA è zero e la natura dice perché. Averle tutte e due è lo scarto 00400; non averne nessuna con IVA a zero è lo 00401.
• Prezzi: non possono essere negativi (uno sconto si fa sulla riga, non sul listino).
• Unità di misura entro 10 caratteri e descrizione entro 1000: sono i limiti del tracciato della fattura elettronica.
• Articolo tenuto a magazzino: senza unità di misura le giacenze sono numeri senza nome, quindi viene richiesta.
• Kit: non può contenere se stesso, né componenti in quantità zero.

Gli stessi controlli valgono per l'import da foglio di calcolo — anzi soprattutto lì, perché da un file entrano centinaia di voci in un colpo — e per il cambio massivo di aliquota, che prima accettava qualunque numero e non guardava se le voci toccate avessero una natura incompatibile.

Validazione EAN-13 e blocco duplicati

Al salvataggio il sistema verifica:

• Codice a barre: EAN-13, EAN-8 o UPC-A (12 cifre), sempre con il controllo della cifra finale (mod 10). Codici non conformi vengono rifiutati con errore 400. Vale per la scheda e anche per Scansiona e associa dal telefono: un codice che nessun lettore può leggere non si associa.
• Duplicati EAN: se esiste già un'altra voce viva — combinazioni di taglie e colori comprese — con lo stesso codice a barre il salvataggio viene bloccato (errore 409) e il sistema indica la voce già presente. Un UPC-A e lo stesso codice a 13 cifre con lo zero davanti sono considerati lo stesso codice.
• Aliquote: su una voce si scrivono 4, 5, 10 e 22% (0 con la natura), più quelle che l'azienda ha aggiunto nella tabella delle aliquote IVA. Il 20 e il 21% storici restano sulle voci vecchie che li hanno, ma non si assegnano più.
• Duplicati codice interno: analogo blocco sul campo codice. Se il codice appartiene a una voce che sta nel cestino, il messaggio lo dice: conviene ripristinarla invece di rifarla, perché così si porta dietro giacenze, listini e storico.

Audit log automatico delle modifiche

Ogni modifica alla scheda voce viene registrata nella tabella log_modifiche_voci_catalogo con valore precedente, valore nuovo, utente e data/ora. I campi tracciati sono 21, tra cui codice, descrizione, tipo voce, categoria, prezzi (default, acquisto, ingrosso, dettaglio), aliquota IVA, EAN, fornitore, stato, marca. La lista storica è accessibile via API GET /api/catalogo/:id/audit-log.

Statistiche di vendita automatiche

I campi di riepilogo della voce sono aggiornati automaticamente ad ogni operazione sui documenti che contengono la voce (creazione, modifica, cambio stato, duplicazione, cancellazione):

• Unità vendute anno corrente e anno precedente: solo le fatture di vendita (la nota di credito toglie) e i DDT di vendita non ancora fatturati; acquisti, ordini, preventivi, bozze, annullati e documenti nel cestino non contano
• Numero vendite (righe documento totali)
• Data ultimo movimento
• Prezzo medio di vendita

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

Timeline cronologica della voce

L'endpoint GET /api/catalogo/:id/timeline restituisce una vista aggregata degli eventi della voce: righe documento in cui è stata usata, movimenti di magazzino e modifiche registrate nell'audit, ordinati per data decrescente. Utile per ricostruire lo storico di utilizzo e variazioni del prodotto.

Selezione multipla e azioni massive

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

• Checkbox in intestazione: seleziona/deseleziona tutte le voci visibili nella pagina corrente.
• Checkbox per ogni riga: selezione singola; cliccare sulla spunta non apre la scheda.
• Quando almeno una voce è selezionata compare una barra azioni blu in fondo alla lista.

Azioni disponibili:

• Attiva / Disattiva: cambio massivo del flag attiva. Un modello di taglie e colori si porta dietro le sue combinazioni; una voce nel cestino non si attiva (va prima ripristinata). Lo stesso vale per l'interruttore sulla riga.
• Categoria…: assegnazione in blocco di una categoria (vuoto per rimuoverla).
• % IVA…: aggiornamento massivo dell'aliquota IVA di default.
• Tipo…: una voce con giacenza o movimenti di magazzino non diventa prestazione, kit, bollo o testo libero: resta com'è, e NOX dice quali e perché. Per lo stesso motivo nella scheda non si spegne «Gestione magazzino» su una voce che ha movimenti: si riscriverebbero i movimenti dei documenti già emessi.
• Elimina: sposta le voci nel cestino (soft-delete, reversibile), con gli stessi controlli della cancellazione singola: un modello di taglie e colori che ha ancora combinazioni resta dov'è, e NOX dice quali voci non ha cestinato e perché.

Cestino e soft-delete

L'eliminazione di una voce (singola o massiva) è ora una cancellazione logica: la voce scompare dalla lista attiva ma resta nel database con le colonne cancellatoIl e cancellatoDa valorizzate. Le righe documento storiche non vengono toccate.

• Pulsante 🗑 Cestino nel footer della lista: entra in modalità cestino e mostra solo le voci cancellate.
• Per ogni riga del cestino sono disponibili due azioni:
  • ↺ Ripristina: annulla la cancellazione, la voce torna attiva.
  • ✗ Definitivo: eliminazione fisica irreversibile. Blocca se la voce è ancora usata in righe documento. Disponibile solo per utenti ADMIN o SUPERADMIN.
• In modalità cestino il clic sulla riga non apre la scheda; vengono mostrati data e autore della cancellazione.

A partire dalla versione 2.2, il modulo Catalogo 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. Vincoli su righe documento e movimenti magazzino. 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.