Modulo Agenti & Provvigioni

Gestione agenti, maturazione provvigioni, liquidazioni con calcolo Enasarco e FIRR

v 2.3 Manuale Utente

Riferimenti normativi

Artt. 1742-1753 Codice Civile — Contratto di agenzia: disciplinano il rapporto tra preponente e agente. L'agente assume stabilmente l'incarico di promuovere la conclusione di contratti in una zona determinata, in cambio di una provvigione. Regolano diritto alla provvigione (art. 1748), esclusiva di zona (art. 1743), obblighi di informazione reciproca e indennita di fine rapporto (art. 1751).
D.Lgs. 303/1991 — Disciplina Enasarco: istituisce l'obbligo contributivo alla Fondazione Enasarco per agenti e rappresentanti di commercio. Il contributo e ripartito tra preponente e agente (attualmente nella misura del 17% ciascuno, con massimali annui). Il modulo calcola automaticamente la quota Enasarco su ogni liquidazione.
L. 12/1962 — Fondo Indennita Risoluzione Rapporto (FIRR): prevede l'accantonamento annuo presso Enasarco di un'indennita proporzionale alle provvigioni maturate dall'agente, da corrispondere alla cessazione del rapporto. Le aliquote variano in base agli scaglioni provvigionali.
D.Lgs. 65/1999 — Indennita di cessazione rapporto: recepisce la direttiva 86/653/CEE e disciplina l'indennita spettante all'agente alla cessazione del contratto, calcolata in base all'incremento di clientela apportato e ai vantaggi che il preponente continua a trarre dopo la cessazione del rapporto.

1Pagina Agenti

La pagina Agenti e il punto di accesso centralizzato per la gestione della rete commerciale. Si compone di una griglia di card, ciascuna rappresentante un agente attivo, e di una serie di filtri per la ricerca rapida.

Card grid

Ogni card agente mostra: nome (formato reverse COGNOME Nome), zona di competenza, numero clienti in portafoglio, provvigioni maturate nel periodo corrente e stato (attivo/sospeso). Le card sono ordinate alfabeticamente e possono essere riordinate per fatturato o provvigioni.

Filtri

La barra superiore consente di filtrare per: nome/cognome, zona commerciale, tipo contratto (monomandatario/plurimandatario), stato attivita. I filtri si combinano in AND.

Dettaglio agente — 4 Tab

Il clic su una card apre la scheda di dettaglio, organizzata in quattro tab:

Tab	Contenuto
Anagrafica	Dati personali, recapiti, codice fiscale, partita IVA, coordinate bancarie. Collegamento alla scheda Soggetto sottostante.
Provvigioni	Elenco delle provvigioni maturate, in liquidazione e liquidate. Filtri per periodo, stato, documento. Totali e grafici andamento.
Obiettivi	Target di fatturato e/o volume assegnati per periodo. Barra di avanzamento, percentuale raggiungimento, premi legati al superamento soglia.
Statistiche	Fatturato generato, trend anno su anno, top clienti, top articoli venduti, DSO medio dei clienti in portafoglio.

ⓘ Dalla card agente e possibile accedere direttamente alla creazione di una nuova liquidazione tramite il pulsante azione rapida.

2Configurazione Agente nel soggetto

Quando un soggetto ha il ruolo Agente attivo, nella sua scheda anagrafica appare la sezione di configurazione agente. Qui si definiscono tutti i parametri contrattuali e provvigionali.

Aprire la scheda del soggetto e verificare che il ruolo Agente sia attivo.
Compilare il Tipo contratto: monomandatario o plurimandatario (incide sulle aliquote Enasarco).
Inserire i dati del Mandato: data inizio, data fine (se a termine), zona esclusiva, rinnovo automatico.
Definire la Provvigione base: percentuale predefinita applicata sul fatturato netto.
Configurare le Provvigioni differenziate per categoria articolo o per singolo cliente, se necessario.
Impostare la Maturazione: alla fatturazione, all'incasso o alla consegna merce.
Attivare il calcolo Enasarco e indicare l'aliquota contributiva (il sistema applica i massimali vigenti).
Attivare il calcolo FIRR e verificare le aliquote per scaglione.
Salvare la configurazione.

Campo	Descrizione	Note
Tipo contratto	Monomandatario / Plurimandatario	Determina massimale Enasarco
Data inizio mandato	Decorrenza del rapporto di agenzia	Obbligatorio
Zona esclusiva	Zone commerciali assegnate	Art. 1743 C.C.
% Provvigione base	Percentuale predefinita	Sovrascrivibile per riga
Maturazione	Fatturazione / Incasso / Consegna	Art. 1748 C.C.
Aliquota Enasarco	Contributo previdenziale	D.Lgs. 303/1991
FIRR attivo	Accantonamento indennita	L. 12/1962
Ritenuta d'acconto	23% sul 50% del compenso	Standard agenti

⚠ La modifica del tipo contratto (da monomandatario a plurimandatario o viceversa) comporta la variazione dei massimali Enasarco. Il sistema ricalcola automaticamente i contributi dal periodo in corso.

3Provvigioni nei documenti

In ogni documento di vendita (ordine, DDT, fattura) e presente una tab Agente che consente di associare uno o piu agenti e gestire le provvigioni a livello di riga.

Aprire il documento di vendita e selezionare la tab Agente.
L'agente viene proposto automaticamente in base al cliente (portafoglio agente). E possibile modificarlo manualmente.
Per ogni riga del documento, il sistema genera automaticamente un record ProvvigioneRiga con: agente, percentuale provvigione, importo base, importo provvigione calcolato.
Se necessario, modificare la percentuale provvigione per riga (override della percentuale base agente).
E possibile assegnare agenti diversi a righe diverse dello stesso documento (es. vendita multi-zona).
Alla conferma del documento, le righe provvigione vengono salvate con stato coerente alla regola di maturazione configurata per l'agente.

Campo ProvvigioneRiga	Descrizione
Agente	Soggetto agente associato alla riga
% Provvigione	Percentuale applicata (da configurazione o override manuale)
Imponibile riga	Base di calcolo (importo netto della riga)
Importo provvigione	Calcolato: imponibile x % provvigione
Stato	MATURATA, IN_LIQUIDAZIONE o LIQUIDATA
Documento origine	Riferimento al documento di vendita

ⓘ La generazione delle ProvvigioneRiga e automatica: il sistema applica le regole configurate nella scheda agente. L'utente interviene solo in caso di eccezioni o override manuali.

4Provvigioni Agenti

La sezione Provvigioni Agenti offre una vista consolidata di tutte le provvigioni generate dal sistema. E accessibile dal menu principale ed e il punto di controllo per la gestione del ciclo provvigionale.

Lista e filtri

La lista mostra tutte le righe provvigione con: agente, documento, cliente, data, imponibile, percentuale, importo, stato. I filtri disponibili sono: periodo (da/a), agente, cliente, stato, tipo documento.

KPI

In testa alla pagina, una barra di indicatori sintetici mostra: totale provvigioni maturate, totale in liquidazione, totale liquidate, media percentuale provvigionale, numero agenti attivi nel periodo.

Ciclo di vita della provvigione

Stato	Descrizione	Transizione
MATURATA	La provvigione e maturata secondo la regola configurata (fatturazione, incasso o consegna). E pronta per essere inclusa in una liquidazione.	Automatica al verificarsi dell'evento di maturazione
IN_LIQUIDAZIONE	La provvigione e stata inclusa in un documento di liquidazione in stato Bozza o Confermata.	Inclusione nella liquidazione
LIQUIDATA	La provvigione e stata pagata all'agente. La liquidazione corrispondente e in stato PAGATA.	Pagamento della liquidazione

⚠ Le provvigioni in stato LIQUIDATA non possono essere modificate. In caso di errore e necessario emettere una nota di credito sul documento di origine, che genera automaticamente uno storno provvigionale.

5Liquidazioni

La Liquidazione e il documento che raggruppa le provvigioni maturate di un agente in un determinato periodo e ne calcola il netto da corrispondere, al netto dei contributi Enasarco, FIRR e ritenuta d'acconto.

Creazione di una liquidazione

Accedere al menu Agenti → Liquidazioni e premere + Nuova Liquidazione.
Selezionare l'agente e il periodo di riferimento (da/a).
Il sistema carica automaticamente tutte le provvigioni in stato MATURATA nel periodo selezionato.
Verificare le righe incluse. E possibile escludere manualmente singole provvigioni.
Il sistema calcola automaticamente: totale provvigioni lordo, contributo Enasarco (quota agente e quota preponente), accantonamento FIRR, ritenuta d'acconto e netto a pagare.
Salvare in stato BOZZA. La liquidazione e modificabile.
Premere Conferma per passare allo stato CONFERMATA. Le provvigioni incluse passano a IN_LIQUIDAZIONE.
Dopo il pagamento effettivo, registrare il pagamento per portare la liquidazione allo stato PAGATA. Le provvigioni passano a LIQUIDATA.

Stati della liquidazione

Stato	Descrizione	Azioni consentite
BOZZA	Liquidazione in preparazione, modificabile	Modifica righe, ricalcolo, conferma, eliminazione
CONFERMATA	Liquidazione validata, pronta per il pagamento	Stampa, registrazione pagamento, annullamento (torna a BOZZA)
PAGATA	Pagamento effettuato e registrato	Solo consultazione e stampa

Calcolo Enasarco, FIRR e netto

Voce	Calcolo	Riferimento
Totale provvigioni lordo	Somma importi provvigione incluse	—
Contributo Enasarco agente	Lordo x aliquota agente (entro massimale)	D.Lgs. 303/1991
Contributo Enasarco preponente	Lordo x aliquota preponente (entro massimale)	D.Lgs. 303/1991
Accantonamento FIRR	Calcolato per scaglioni sulle provvigioni annue	L. 12/1962
Ritenuta d'acconto	23% sul 50% del lordo provvigionale	DPR 600/73
Netto a pagare	Lordo − Enasarco agente − Ritenuta d'acconto	—

ⓘ Il contributo Enasarco del preponente non viene detratto dal netto agente ma e un costo aziendale aggiuntivo. Il FIRR viene accantonato e versato annualmente alla Fondazione Enasarco.

6Footer operativo

Il footer della pagina Agenti fornisce accesso rapido alle due viste operative principali:

Voce footer	Descrizione
Tutte le Provvigioni	Apre la vista consolidata di tutte le righe provvigione di tutti gli agenti, con filtri avanzati per periodo, agente, cliente, stato e documento. Consente selezione multipla per creazione rapida di liquidazioni.
Liquidazioni	Apre l'elenco di tutte le liquidazioni emesse, con filtri per agente, periodo, stato (BOZZA / CONFERMATA / PAGATA). Da qui e possibile creare nuove liquidazioni, confermare bozze in sospeso o registrare pagamenti.

ⓘ Entrambe le viste supportano l'esportazione in formato Excel e PDF tramite il pulsante Esporta.

7Margine per agente

Quando il campo costo unitario è compilato nelle righe dei documenti, il sistema calcola il margine per ogni riga e per l'intero documento. Questo dato, incrociato con la provvigione dell'agente, permette di valutare la redditività netta delle vendite:

Indicatore	Formula
Margine lordo	Imponibile − (Costo × Quantità)
Provvigione	Imponibile × % Provvigione
Margine netto	Margine lordo − Provvigione

ⓘ Utilizzare questa analisi per identificare agenti con vendite ad alto volume ma basso margine netto, e calibrare le percentuali provvigionali di conseguenza.

8Integrazione con documenti

L'agente viene collegato ai documenti in tre modi:

Automatico dal soggetto: se il cliente ha un agente di riferimento nella sua scheda anagrafica, viene assegnato automaticamente al documento.
Manuale dal documento: nel tab Agente del documento, è possibile selezionare o cambiare l'agente e la percentuale provvigionale.
Per riga: ogni riga del documento può avere un agente e una percentuale diversa (utile per vendite multi-agente).

Le provvigioni calcolate nei documenti alimentano la pagina Provvigioni Agenti dove si gestisce la maturazione, la liquidazione e l'ENASARCO.

✨Novita Aprile 2026 (v2.1) — Audit Contratto

Aggiornamento del modulo Agenti: tracciamento cronologico delle modifiche alla configurazione contrattuale (AgenteConfig).

Audit log della configurazione

Nella scheda dell'agente e stato aggiunto un nuovo tab 🕔 Storico contratto che elenca tutte le modifiche effettuate ai campi chiave della configurazione:

tipoContratto (MONOMANDATARIO / PLURIMANDATARIO / OCCASIONALE / DIPENDENTE)
provvigioneBase (% applicata di default)
provvigioneScaglioni e provvigioniCategorie (override per fascia fatturato e per categoria voce)
zone di competenza
numeroMandato, dataInizioMandato, dataFineMandato
aliquotaEnasarco, massimaleEnasarco, aliquotaFirr
noteContratto

Per ogni modifica il sistema registra valore precedente, valore nuovo, utente che ha salvato e data/ora. Lo storico risponde alla domanda: “quando e perche abbiamo alzato la provvigione base di Rossi dal 5 al 7%?”

Endpoint API: GET /api/agenti/:id/config-audit-log. La tabella DB di riferimento e log_modifiche_agente_config.

Nota sul soft-delete

Gli Agenti sono rappresentati come Soggetti con isAgente=true, quindi beneficiano gia del soft-delete (cancellatoIl/cancellatoDa) e del cestino del modulo Soggetti. Non e stato introdotto un cestino separato sul modulo Agenti per non duplicare l'anagrafica.

?Domande frequenti (FAQ)

Quando matura effettivamente la provvigione?

Dipende dalla configurazione nella scheda agente. Se impostata su "Fatturazione", la provvigione matura alla conferma della fattura. Se "Incasso", matura solo quando il pagamento del cliente viene registrato. Se "Consegna", matura alla conferma del DDT. L'art. 1748 C.C. prevede che la provvigione spetti quando l'operazione e stata conclusa per effetto dell'intervento dell'agente.

Come gestisco un agente con provvigioni diverse per categoria articolo?

Nella scheda agente, sezione Configurazione, e possibile definire una tabella provvigionale per categoria articolo. La percentuale specifica per categoria prevale sulla provvigione base. In fase di inserimento documento, il sistema seleziona automaticamente la percentuale corretta in base all'articolo.

Cosa succede se emetto una nota di credito su una fattura con provvigioni gia liquidate?

Il sistema genera automaticamente righe di storno provvigionale con importo negativo. Queste righe verranno incluse nella liquidazione successiva, riducendo il totale lordo. Le provvigioni originali restano in stato LIQUIDATA per tracciabilita.

Come viene calcolato il massimale Enasarco?

Il massimale Enasarco e annuo e differenziato tra agenti monomandatari e plurimandatari. Il sistema tiene traccia del progressivo annuo di ogni agente e smette di calcolare il contributo una volta raggiunto il massimale. I valori sono aggiornabili nelle impostazioni di sistema.

Posso annullare una liquidazione gia confermata?

Si, una liquidazione in stato CONFERMATA puo essere riportata a BOZZA tramite il pulsante "Annulla conferma". Le provvigioni incluse tornano allo stato MATURATA. Non e invece possibile annullare una liquidazione in stato PAGATA: in tal caso occorre creare una liquidazione di storno.

Come gestisco il FIRR a fine anno?

Il sistema calcola l'accantonamento FIRR su ogni liquidazione in base alle aliquote per scaglione (L. 12/1962). A fine anno, la funzione "Riepilogo FIRR" genera il prospetto per il versamento alla Fondazione Enasarco, raggruppato per agente con il dettaglio degli scaglioni applicati.

✓Certificazione v 2.2 — Presidi di compliance

🔑 Visibilità condizionata (certificazione v 2.2) — Questo modulo è accessibile solo se:
• Pacchetto VENDITE_B2B attivo sul workspace (configurabile da SUPERADMIN in /admin/pacchetti)
• Profilo attività compatibile: Ferramenta (opzionale), Agente di Commercio
• Permesso utente abilitato in Modifica Utente → Moduli
I tre livelli si applicano in intersezione. Dettagli completi in Gerarchia Pacchetti+Profilo+Utente.

A partire dalla versione 2.2, il modulo Agenti 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: Audit configurazione agente + obiettivi. 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:

Campo	Esempio originale	Nel log
IBAN	IT60X0542811101000000123456	`IT60****3456`
Codice Fiscale (PF)	RSSMRA80A01H501Z	`RSSMRA****501Z`
Partita IVA	12345678901	`123****901`
Password / token	(qualsiasi)	`*REDACTED*`

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.

ⓘIl DOCX di certificazione formale per questo modulo è disponibile: certificazione-agenti.docx (cartella manuali).

§Formato monetario nelle statistiche Agente — 1.234,00

Le statistiche del dettaglio Agente (Fatturato anno, Provvigioni maturate/liquidate, tabella mensile, obiettivi) e la lista agenti ora mostrano gli importi nel formato italiano corretto 1.234,00 con separatore migliaia di punto e virgola decimale.

Tutte le tab del dettaglio agente sono allineate:

Provvigioni: KPI maturate / liquidate / annullate, tabella imponibile-provvigione, tabella liquidazioni con totali Enasarco/Firr/Netto.
Obiettivi: Fatturato obiettivo, Fatturato raggiunto, Provvigione obiettivo.
Statistiche: KPI Fatturato anno, Provvigioni maturate/liquidate, andamento mensile.
Lista Agenti: provvigione base nelle card.

📱 PWA Agenti commercio — modulo `/m`

Nuovo modulo mobile-first per gli agenti di commercio: applicazione web installabile sul cellulare (PWA) per inserire ordini cliente direttamente dal campo, anche senza connessione di rete. Sincronizzazione automatica al ritorno online.

Come accedere

URL: https://www.gnox.it/m
Login con le stesse credenziali NOX (utente abilitato come Agente, oppure Admin / Superadmin).
L'utente Agente vede solo i propri clienti: il match avviene per email tra User.email e Soggetto.email (campo Soggetto con flag "È un agente").

Installazione sul cellulare

Android / Chrome / Edge: vai in Profilo → pulsante "Installa NOX Agenti", oppure usa il banner "Aggiungi a Home" che il browser propone spontaneamente.
iPhone / Safari: tocca l'icona Condividi (⮨) → "Aggiungi alla schermata Home". L'app si chiamerà "NOX Agenti" e partirà direttamente dalla home della PWA.

Funzionalità (5 tab)

Home: quick-action Nuovo ordine + lista degli ultimi 5 ordini con stato e totale.
Clienti: lista dei propri clienti con ricerca live (cognome/ragione sociale/codice/P.IVA/località), telefono ed email cliccabili. Tap sulla card pre-seleziona il cliente per il nuovo ordine.
Catalogo: voci attive con codice, descrizione, unità di misura, IVA e prezzo predefinito.
Nuovo ordine: wizard a 3 step (cliente → aggiungi articoli con quantità/prezzo/sconto/IVA modificabili → note + invio). Totali calcolati live. L'ordine viene creato in stato BOZZA; il numero progressivo definitivo viene assegnato dall'amministrazione al passaggio a CONFERMATO o EMESSO dal NOX desktop.
Ordini: storico ultimi 90 giorni con filtri (Tutti / Bozza / Confermati / Emessi) e sezione "Da inviare" per ordini creati offline ancora in coda.
Profilo: identità agente, last-sync per ogni tabella, pulsanti Sincronizza ora / Svuota cache offline / Apri NOX desktop / Esci.

Modalità offline

L'app continua a funzionare anche senza rete: clienti, catalogo e storico vengono memorizzati in cache locale sul dispositivo (IndexedDB). Quando crei un ordine offline:

L'ordine viene salvato in coda locale; il pulsante diventa "Salva offline" per chiarezza.
Sul topbar appare un'icona ☁↑ con il numero di ordini in attesa; tap per forzare l'invio.
Al ritorno online la sincronizzazione è automatica: gli ordini in coda vengono inviati uno per uno, e in caso di errore restano in coda con messaggio diagnostico (potrai riprovare o correggerli manualmente dal NOX desktop).
Le pagine Clienti / Catalogo / Storico mostrano un banner ambrato "Dati da cache offline" quando i dati visualizzati non sono aggiornati alla rete.

Limiti attuali (Fase 1)

Per scelta progettuale la prima release non include: scanner barcode con fotocamera, allegati foto, invio diretto a SDI dal mobile. Queste feature sono valutabili in una Fase 2 evolutiva insieme alla decisione se mantenere PWA o passare a un binario nativo distribuito da App Store / Google Play (via wrapper Capacitor).

✨ Novità PWA Agenti — versione `1.1`

La versione 1.1 dell'app Agenti introduce la firma elettronica del cliente e la rilevazione della posizione GPS direttamente sul nuovo ordine, oltre a una topbar più compatta. Il numero di versione è ora visibile nell'app.

Firma e posizione sul nuovo ordine

Nel wizard Nuovo ordine, dopo lo step «3. Note e Conferma» è stato aggiunto uno spazio per la firma del cliente col dito (firma su area touch) e per la rilevazione GPS della posizione, esattamente come nell'app Trasportatori per la firma dei DDT.

La firma è opzionale: se presente, l'app richiede anche il nome del firmatario.
La posizione GPS viene rilevata automaticamente al momento dell'invio (se il dispositivo concede il permesso di geolocalizzazione).
Firma e posizione vengono salvate anche in modalità offline insieme all'ordine in coda, e inviate al ritorno online.
Vengono memorizzate sul documento dell'ordine e restano consultabili dal NOX desktop.

Topbar più compatta

La barra superiore dell'app è stata ridotta in altezza (simile a quella del logo) per lasciare più spazio ai dati a schermo, utile soprattutto durante la composizione di un ordine.

Numero di versione visibile

La versione 1.1 è ora mostrata in app: come etichetta nella topbar e come riga «Versione 1.1» nella tab Profilo.

Modulo Agenti & Provvigioni

Riferimenti normativi

Card grid

Filtri

Dettaglio agente — 4 Tab

Lista e filtri

KPI

Ciclo di vita della provvigione

Creazione di una liquidazione

Stati della liquidazione

Calcolo Enasarco, FIRR e netto

Audit log della configurazione

Nota sul soft-delete

Cestino e soft-delete

Azioni massive (bulk)

Storico modifiche (audit log)

Mascheramento dati sensibili (GDPR art. 32)

Timeline aggregata

RBAC uniforme

📱 PWA Agenti commercio — modulo /m

Come accedere

Installazione sul cellulare

Funzionalità (5 tab)

Modalità offline

Limiti attuali (Fase 1)

✨ Novità PWA Agenti — versione 1.1

Firma e posizione sul nuovo ordine

Topbar più compatta

Numero di versione visibile

📱 PWA Agenti commercio — modulo `/m`

✨ Novità PWA Agenti — versione `1.1`