Provvigioni Agenti

Ciclo completo: assegnazione agente → calcolo → maturazione → liquidazione con ENASARCO e ritenuta. Accessibile da Agenti & Provvigioni e Provvigioni Agenti.

Soggetto con flag “È agente”. Campi: tipo contratto (mono/plurimandatario), provvigione base %, zone, matricola ENASARCO.

Priorità: riga > documento > agente. Formula: imponibileRiga × provvigionePerc.

Le provvigioni maturano al passaggio del documento a CONFERMATO/EMESSO. All'annullamento, vengono annullate automaticamente.

1. Filtrare per agente e stato MATURATA.
2. Selezionare periodo (dal/al).
3. Premere “Nuova Liquidazione”.
4. Il sistema calcola il totale. Le provvigioni passano a IN_LIQUIDAZIONE.
5. Dalla scheda liquidazione: confermare → LIQUIDATA.

Esempio: 3 fatture, imponibili 5.000+3.000+7.000 = 15.000€, provv. 10% = 1.500€ lordi. Ritenuta 11,50% = 172,50€. Netto: 1.327,50€.

Filtri: agente, stato (MATURATA/IN_LIQUIDAZIONE/LIQUIDATA/ANNULLATA), periodo. Paginazione 50/pag. KPI per agente: da liquidare, in liquidazione, liquidate, totale anno.

Tabella: fattura, data, agente, cliente, imponibile, %, importo, stato, liquidazione. Selezione multipla per totale selezionato. Checkbox per selezionare tutte le righe filtrate.

Aggiornamento del modulo Provvigioni: operazioni massive su righe provvigione e liquidazioni, tracciamento cronologico dei cambi di stato.

Bulk: crea liquidazione da righe selezionate

Nella lista provvigioni, selezionando una o piu righe MATURATA con le checkbox, compare il pulsante Crea liquidazione da selezionate nella barra azioni. Il sistema crea una liquidazione per ogni agente (raggruppamento automatico) includendo solo le righe selezionate. Le righe non MATURATA vengono riportate come bloccate. Utile quando si vogliono liquidare solo alcune righe specifiche senza coinvolgere tutta la maturazione del periodo.

Endpoint: POST /api/provvigioni/bulk con action crea-liquidazione-da-selezionate.

Bulk su liquidazioni

Nella lista liquidazioni e stata aggiunta la selezione multipla. Con una o piu liquidazioni selezionate compare la barra azioni con:

• Conferma: N liquidazioni BOZZA → CONFERMATA in una sola operazione.
• Paga: N liquidazioni CONFERMATA → PAGATA con data comune e riferimento opzionale. Le righe collegate passano a LIQUIDATA.
• Annulla: riporta le liquidazioni ad ANNULLATA; le righe tornano MATURATA e possono essere rilavorate.

Endpoint: POST /api/provvigioni/liquidazioni/bulk. Ogni operazione bulk registra un audit entry per ogni liquidazione modificata.

Audit log e Timeline liquidazione

Ogni cambio di stato o modifica a una liquidazione (singolo o bulk) viene registrato nella tabella log_modifiche_liquidazioni. Endpoint:

• GET /api/provvigioni/liquidazioni/:id/audit-log
• GET /api/provvigioni/liquidazioni/:id/timeline

Nota fiscale

Le ProvvigioneRiga e le Liquidazioni sono dati con rilevanza contabile verso l'agente. Non sono previsti soft-delete o cestino: il flusso contabilmente corretto per neutralizzare una liquidazione e l'annullamento (stato ANNULLATA), che riporta le righe a MATURATA.

A partire dalla versione 2.2, il modulo Provvigioni 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 su singola liquidazione. Liquidazione CONFERMATA non modificabile. 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.

Provvigioni auto-calcolate da fattura (v 2.2, aprile 2026)

Feature #10 del pacchetto FATTURAZIONE v 2.2: introduce il calcolo automatico della provvigione agente a partire dall'imponibile del documento emesso. La provvigione viene registrata in una nuova tabella dedicata e può essere successivamente liquidata nella liquidazione periodica.

Nuova tabella provvigioni_documento

• documento_id (INT) — FK al documento (fattura emessa)
• agente_id (INT) — FK al soggetto agente
• aliquota_provvigione (NUMERIC 5,2) — percentuale applicata
• imponibile_base (NUMERIC 14,2) — base di calcolo (imponibile documento)
• importo_provvigione (NUMERIC 14,2) — risultato calcolato
• liquidato (BOOLEAN) + liquidazione_id — già confluita in una liquidazione
• note (TEXT) — eventuali note libere

Calcolo aliquota: default agente

Il soggetto agente dispone ora del campo aliquotaProvvigioneDefault (NUMERIC 5,2). Se al momento della creazione della provvigione non viene specificata un'aliquota esplicita, viene applicato questo default. Utile per agenti con condizioni standardizzate.

Endpoint

POST /api/fatturazione/provvigioni-auto/:docId [ADMIN]
Body: { agenteId, aliquotaProvvigione? }

Risposta: { id, aliquota, imponibileBase, importoProvvigione }.

GET /api/fatturazione/provvigioni-auto?agenteId=X&liquidato=false — elenco provvigioni filtrate. Il flag liquidato permette di distinguere le provvigioni già confluite in una liquidazione (chiuse) da quelle ancora disponibili (aperte).