User Guide

Manuale Utente - Safety21 Financial

Benvenuti nel manuale utente dell'applicativo Safety21 Financial. Questo documento descrive tutte le funzionalità disponibili per la gestione dei flussi finanziari, degli enti creditori e delle comunicazioni interne.

Indice

Accesso e Home Page
Gestione Enti Creditori
Gestione Flussi CBI
Chat e Comunicazioni
Attività di Sistema
Aggregazione Transazioni Parziali

1. Accesso e Home Page

Dopo aver effettuato il login con le proprie credenziali, l'utente accede alla Home Page. La pagina presenta un video di sfondo istituzionale e un menu di navigazione principale per accedere alle diverse sezioni dell'applicativo.

2. Gestione Enti Creditori

Questa sezione permette di gestire l'anagrafica degli Enti Creditori censiti nel sistema.

Visualizzazione: Elenco paginato degli enti con possibilità di filtro.
Creazione/Modifica: È possibile aggiungere nuovi enti o modificare quelli esistenti inserendo dati come:
- Codice Ente
- Denominazione
- Codice Ufficio / Tipo Ufficio
- Codice Catastale Comune
- Ufficio Pagatore
Importazione: Funzionalità per importare massivamente gli enti da file esterni (se supportato).

3. Gestione Flussi CBI

Il cuore dell'applicativo è la gestione dei flussi CBI per la riconciliazione degli incassi.

3.1. Caricamento File

L'utente può caricare nuovi file CBI nel sistema.

Il sistema analizza il contenuto del file, estrae l'header, il footer e le singole transazioni.
Viene creato un record per il file e le relative transazioni vengono salvate per la lavorazione.

3.2. Lista File

Visualizza l'elenco di tutti i file CBI caricati.

Stato: Permette di vedere se è presente la "Data Tramissione Seda" o è ancora in lavorazione.
Selezione Multipla: È possibile selezionare più file tramite le checkbox per eseguire operazioni bulk.
Azioni Singole:
- Dettaglio: Accede alla pagina di lavorazione del file.
- Elimina: Rimuove il file e le transazioni associate (se non consolidato).
- Cont. Provvisorio: Apre un'anteprima del file contabile con possibilità di download senza impatti.
- Cont. Definitivo: Apre un'anteprima del file contabile con possibilità di conferma definitiva.
Azioni Bulk (su selezione multipla):
- Riepilogo: Visualizza un riepilogo aggregato dei file selezionati.
- Cont. Provvisorio: Apre un'anteprima del file contabile provvisorio aggregato.
- Cont. Definitivo: Apre un'anteprima del file contabile definitivo per tutti i file selezionati (non disponibile per file già trasmessi a SEDA).

Nota tecnica: Le operazioni singole e bulk utilizzano la stessa logica interna. Quando si opera su un singolo file, il sistema utilizza le stesse API bulk passando il file come unico elemento. Questo garantisce comportamento consistente in entrambi gli scenari.

Flusso Contabilità con Preview

Sia la Contabilità Provvisoria che la Definitiva utilizzano lo stesso flusso con anteprima:

Selezione: Utente seleziona uno o più file CBI
Apertura Preview: Click su "Cont. Provvisorio" o "Cont. Definitivo"
Visualizzazione Anteprima:
- Modal con header blu per Provvisorio, verde per Definitivo
- Tabella con i dati che verranno inclusi nel file
- Tab per vedere il contenuto raw del file
Download:
- Provvisorio: Pulsante "Scarica Provvisorio" - scarica senza impatti sul sistema
- Definitivo: Pulsante "Conferma Definitivo e Scarica" - richiede conferma, poi imposta le date e scarica

Nota sulla Contabilità Definitiva

Quando viene confermato il download del file di Contabilità Definitiva, il sistema esegue automaticamente le seguenti operazioni:

Imposta la Data Trasmissione SEDA sul file CBI
Aggiorna la Data Trasmissione su tutti i pagamenti collegati alle transazioni rendicontabili del file
Ricarica la pagina per mostrare la data aggiornata nella griglia

Una volta che un file è stato trasmesso a SEDA, non sarà più possibile generare nuovamente il file definitivo. Il pulsante verrà disabilitato e apparirà con l'icona del lucchetto.

Avviso per File Già Trasmessi

Quando si tenta di aprire la preview della Contabilità Definitiva per una selezione di file che include file già trasmessi a SEDA:

Viene visualizzato un avviso arancione nella parte superiore del modal
L'avviso elenca i nomi dei file già trasmessi
Il pulsante "Conferma Definitivo e Scarica" viene disabilitato
L'utente deve rimuovere i file già trasmessi dalla selezione prima di poter procedere

Questo controllo garantisce che i file già rendicontati non vengano reinviati accidentalmente.

3.3. Dettaglio e Riconciliazione

Nella pagina di dettaglio del file, l'operatore lavora sulle singole transazioni.

Filtri

La sezione filtri permette di ricercare rapidamente le transazioni desiderate:

Data Contabile Da/A: Filtra per intervallo di date
Importo Min/Max: Filtra per range di importo
Stato: Mostra solo transazioni quadrate (verde) o non quadrate (rosso)
Cerca in Causale: Ricerca testuale nella causale
Rendicontabile: Filtra per transazioni rendicontabili/non rendicontabili
Lavorabile: Filtra per transazioni lavorabili o escluse
- Solo Lavorabili (default): Mostra solo le transazioni attive
- Tutti: Mostra tutte le transazioni
- Solo Non Lavorabili: Mostra solo le transazioni escluse

Tabella Transazioni

La tabella offre una visione immediata dello stato di ogni transazione:

Indicatori Visivi:
- Verde Chiaro: L'importo della transazione corrisponde esattamente al totale degli incassi agganciati nel sistema.
- Rosso Chiaro: C'è una discrepanza tra l'importo della transazione e gli incassi trovati.
- Grigio con testo barrato: Transazione marcata come "Non Lavorabile".
Colonna "Lavorabile": Switch che indica se la transazione è lavorabile o esclusa.
Colonna "Incassi Agganciati": Mostra il numero di pagamenti trovati e il loro importo totale (es. 3 / € 150,00).
Colonna "Rend.": Mostra un badge "SI" verde se la transazione è stata marcata come "Rendicontabile".
Colonna "Data Cont.": Indica la Data Contabile della transazione (data effettiva di ricezione fondi).

Gestione Transazioni Non Lavorabili

Le transazioni possono essere marcate come "Non Lavorabili" quando non sono pertinenti o devono essere escluse dalla lavorazione:

Singola transazione: Utilizzare lo switch nella colonna "Lavorabile"
Azioni Bulk: Selezionare più transazioni con le checkbox e usare i pulsanti:
- Imposta Non Lavorabile: Esclude le transazioni selezionate
- Imposta Lavorabile: Ripristina le transazioni escluse

Le transazioni non lavorabili:

Rimangono nel database e non vengono eliminate
Sono visualizzate con sfondo grigio e testo barrato
Sono nascoste per default (filtro "Solo Lavorabili" attivo)
Non vengono considerate nei conteggi e nei report (se configurato)

Cliccando sul pulsante "Actions" di una riga:

Edit: Modifica manuale dei dati della transazione.
Aggancia Incassi: Avvia la procedura automatica per cercare e collegare i pagamenti nel sistema (basandosi sulla causale/URI).
Dettaglio Incassi: Apre una finestra con l'elenco dettagliato dei pagamenti agganciati (Ente, Comando, Data, Importo, Causale, IUV). Utile per indagare sulle discrepanze.
Rendicontabile: Marca la transazione come verificata e pronta per la rendicontazione.

4. Chat e Comunicazioni

Il sistema include un modulo di chat integrato per la comunicazione tra gli utenti.

Messaggi: Invio e ricezione di messaggi testuali.
Allegati: Possibilità di scambiare file.
Notifiche: Conteggio dei messaggi non letti.

5. Attività di Sistema

Sezione di audit e monitoraggio che registra le operazioni principali effettuate nel sistema (es. caricamento file, modifiche dati), utile per tracciare la storia delle attività.

6. Aggregazione Transazioni Parziali

Quando le transazioni CBI relative allo stesso flusso di riversamento arrivano in giorni diversi (transazioni parziali), è necessario aggregarle manualmente per distribuire correttamente i pagamenti.

6.1. Identificazione Transazioni Parziali

Le transazioni parziali condividono lo stesso ID Flusso Riversamento (estratto dalla causale) ma hanno date contabili diverse. Il sistema le identifica automaticamente durante l'upload.

6.2. Creazione Aggregazione

Dalla pagina dettaglio di una transazione, cliccare su "Aggrega Transazioni"
Il sistema mostra le transazioni candidate con lo stesso ID Flusso
Selezionare le transazioni da aggregare (minimo 2)
Cliccare su "Crea Aggregazione"

6.3. Distribuzione Pagamenti

Dopo la creazione dell'aggregazione:

Cliccare su "Esegui Distribuzione" per avviare la distribuzione euristica automatica
Il sistema assegna i pagamenti alle transazioni basandosi su:
- Corrispondenza importi
- Prossimità delle date
Se gli importi non corrispondono, lo stato passa a "Con Errori"

6.4. Assegnazione Manuale

Quando la distribuzione automatica non riesce a quadrare gli importi:

Cliccare su "Assegnazione Manuale"
Selezionare il pagamento da assegnare
Scegliere la transazione di destinazione
Il pagamento erediterà la DataContabile e DataRiversamento dalla transazione selezionata

6.5. Finalizzazione e Sincronizzazione

Quando gli importi corrispondono:

Cliccare su "Finalizza e Sincronizza"
Il sistema aggiorna DataContabile e DataRiversamento su PaymentRepository
L'aggregazione diventa non modificabile (Completed)

6.6. Gestione Errori di Sincronizzazione

In caso di errori durante la sincronizzazione:

Lo stato passa a "Sincronizzazione Fallita" o "Parzialmente Fallita"
Viene mostrato il pulsante "Ritenta Sincronizzazione"
L'operatore può rivedere gli errori e riprovare la sincronizzazione

6.7. Stati dell'Aggregazione

Stato	Descrizione
Bozza	Aggregazione in fase di configurazione
Validata	Distribuzione completata, importi corrispondenti
Con Errori	Mismatch importi, richiede intervento manuale
Completata	Finalizzata e sincronizzata con successo
Sincronizzazione Fallita	Errori durante la sincronizzazione

6.8. Eliminazione Aggregazione

Le aggregazioni possono essere eliminate solo se non finalizzate:

Aprire il dettaglio dell'aggregazione
Cliccare su "Elimina"
Confermare l'operazione
Le transazioni tornano allo stato standalone

7. Gestione Connessioni SQL Server Cluster

7.1. Funzionamento Automatico

L'applicazione gestisce automaticamente la connessione a cluster SQL Server in configurazione Active-Passive. Quando i database esterni (PaymentRepository e ViolationControl) sono configurati su server in cluster, il sistema:

Determina automaticamente quale server è in modalità scrittura
Memorizza nella cache la connessione attiva
Aggiorna periodicamente (ogni 30 minuti) la cache delle connessioni
Effettua failover automatico in caso di cambio del server primario

7.2. Per gli Amministratori

La configurazione del cluster è gestita nel file appsettings.json:

Parametro	Descrizione	Default
`HealthCheckIntervalMinutes`	Intervallo controllo periodico	30 minuti
`ConnectionTestTimeoutSeconds`	Timeout test connessione	5 secondi
`Servers`	Lista dei server nel cluster	-
`Enabled`	Abilita/disabilita gestione cluster	true

7.3. Log e Diagnostica

Il sistema logga automaticamente:

Quale server è stato selezionato come primario
Risultati dei controlli periodici
Eventuali errori di connessione

Per verificare lo stato delle connessioni, consultare i log dell'applicazione cercando:

SqlServerClusterHealthCheckWorker
SqlServerConnectionManager

Documento aggiornato al 15/12/2025

8. Storico Estrazioni Contabili

8.1. Introduzione

La funzionalità Storico Estrazioni Contabili permette di tracciare e visualizzare tutte le estrazioni di contabilità definitiva effettuate per ogni file CBI.

8.2. Estrazioni Incrementali

È ora possibile effettuare estrazioni contabili incrementali. Questo significa che:

Ogni estrazione include solo le transazioni rendicontabili non ancora esportate
Se nuove transazioni vengono marcate come rendicontabili dopo una prima estrazione, sarà possibile effettuare una nuova estrazione che includerà solo queste nuove righe
Non c'è più un blocco dopo la prima estrazione definitiva

8.3. Indicatori nella Lista File CBI

Colonna "Totale Contabilizzato"

Nella lista dei file CBI è presente la colonna Totale Contabilizzato che mostra:

L'importo totale delle transazioni già esportate
Il numero di estrazioni effettuate (tra parentesi)

Righe Colorate in Verde

Le righe evidenziate in verde indicano che il file CBI è completamente contabilizzato, ovvero:

Tutte le transazioni lavorabili sono state rendicontate
Tutte le transazioni rendicontabili sono state incluse in una contabilità definitiva

8.4. Consultazione dello Storico

Per visualizzare lo storico delle estrazioni:

Nella lista file CBI, cliccare sul menu azioni (⋮) del file desiderato
Selezionare "Storico Estrazioni Contabili"
Si aprirà una finestra con l'elenco di tutte le estrazioni effettuate

Informazioni Visualizzate

Per ogni estrazione vengono mostrate:

Data/ora dell'estrazione
Utente che ha effettuato l'estrazione
Numero transazioni incluse
Importo totale esportato
Nome file generato (se disponibile)

Dettaglio Transazioni

Cliccando sull'intestazione di ogni estrazione, è possibile espandere il dettaglio per vedere:

Elenco completo delle transazioni incluse
Importo di ogni transazione
Data contabile e data valuta
Data di trasferimento assegnata
Numero e importo dei pagamenti collegati

8.5. Download e Anteprima File Archiviati

Per ogni estrazione contabile effettuata dopo il 18/12/2025, il sistema archivia una copia del file generato. Dalla finestra storico:

Download: Cliccando sull'icona di download, è possibile scaricare il file esattamente come generato al momento dell'estrazione.
Anteprima: Cliccando sull'icona di anteprima, si apre una finestra che mostra i dati contenuti nel file in formato tabellare, senza dover scaricare il file.

Nota: Per le estrazioni precedenti a questa data, il file non è stato archiviato e verrà mostrato il messaggio "File non archiviato".

8.6. Indicazione Transazioni Già Contabilizzate

Nella pagina di dettaglio del file CBI, ogni transazione mostra una nuova colonna "Già Contabilizzato":

Badge Verde "Sì": La transazione è stata inclusa in una contabilità definitiva. Passando il mouse sul badge, viene mostrata la data di contabilizzazione.
Badge Grigio "No": La transazione non è ancora stata contabilizzata.

Questo permette all'operatore di vedere immediatamente quali transazioni sono già state esportate e quali sono ancora da lavorare.

8.7. Flusso di Lavoro Tipico

Prima estrazione: L'operatore marca come rendicontabili le transazioni pronte e crea la contabilità definitiva
Lavorazione successiva: Nuove transazioni vengono lavorate e marcate come rendicontabili
Seconda estrazione: L'operatore crea una nuova contabilità definitiva che include solo le nuove righe
Consultazione: È sempre possibile consultare lo storico per vedere cosa è stato esportato e quando

9. Ricerca Pagamenti Efil

9.1. Pagamenti Per Date

La pagina Efil > Pagamenti Per Date permette di cercare i pagamenti ricevuti in un determinato intervallo di date direttamente dal servizio Efil.

9.2. Filtri Lato Client (Subfiltro)

Poiché Efil non supporta filtri avanzati nella ricerca, è disponibile un pannello di subfiltro lato client che permette di filtrare i risultati già scaricati:

Cliccare su "Mostra/Nascondi Subfiltro" per aprire il pannello
Campi filtro disponibili:
- IUV
- Debitore
- Codice Fiscale / P.IVA
- Numero Avviso
- Importo Min/Max
- Causale
- Servizio
- Canale di Pagamento
- ID Riscossione
- ID Flusso
Il filtraggio è in tempo reale mentre si digita
Il contatore in alto mostra quanti record corrispondono ai filtri

9.3. Colorazione Righe

Le righe nella tabella sono colorate per identificare rapidamente lo stato dei pagamenti:

Verde (table-success): Pagamento con ID Flusso Riversamento presente - il pagamento è stato riversato.
Rosso (table-danger): Pagamento senza ID Flusso Riversamento - il pagamento non risulta ancora riversato.

Documento aggiornato al 18/12/2025 - Aggiunta sezione Storico Estrazioni Contabili, Download/Anteprima file, Indicazione transazioni contabilizzate, Subfiltro Efil, Guida in linea accessibile dal menu applicativo

10. Data Pagamento Diversa da Data Accredito

10.1. Quando Utilizzare Questa Funzionalità

In alcuni casi, la data effettiva del pagamento può essere diversa dalla data di accredito bancario (Data Valuta). Questo accade tipicamente quando:

Il contribuente effettua il pagamento il giorno X
La banca accredita l'importo il giorno X+N (dopo alcuni giorni lavorativi)

Esempio concreto:

Pagamento effettuato: 15 Gennaio 2026
Accredito bancario: 18 Gennaio 2026
La transazione CBI riporta Data Valuta = 18/01/2026

In questi scenari, il sistema non riesce a trovare la corrispondenza automatica con i pagamenti nel repository perché cerca con la data sbagliata.

10.2. Come Inserire la Data Pagamento

Dalla pagina Dettaglio File CBI, individuare la transazione problematica
Cliccare sul menu Actions → Edit
Nel campo "Data Pagamento" inserire la data effettiva del pagamento
Cliccare Salva

⚠️ Vincolo importante: La Data Pagamento deve essere minore o uguale alla Data Valuta. Non è possibile inserire una data di pagamento successiva alla data di accredito.

10.3. Indicatore Visivo nella Griglia

Le transazioni con Data Pagamento valorizzata sono facilmente identificabili nella griglia:

Viene mostrata una colonna dedicata "Data Pagamento"
Se la data è valorizzata, appare con un'icona calendario (⚠️) arancione
Se la data non è valorizzata, appare un trattino "-"

10.4. Come Funziona la Ricerca Pagamenti

Quando una transazione ha il campo Data Pagamento compilato:

Parametro Query	Valore Utilizzato
Data Pagamento (PaymentDate)	Data Pagamento inserita
Data Accredito (CreditDate)	Data Valuta della transazione

Quando il campo Data Pagamento è vuoto (comportamento standard):

Parametro Query	Valore Utilizzato
Data Pagamento (PaymentDate)	Data Valuta
Data Accredito (CreditDate)	Data Valuta

10.5. Impatto sulla Contabilità

📋 Nota tecnica: Nella contabilità estratta, la Data Pagamento sarà sempre uguale alla Data Valuta (data accredito), indipendentemente dalla data di pagamento effettiva inserita.

Questo garantisce coerenza nei file contabili:

Le date nel file estratto corrispondono sempre alla data di accredito bancario
La funzionalità Data Pagamento serve solo per la ricerca nel repository pagamenti

10.6. Flusso di Lavoro Tipico

Identificazione problema: L'operatore nota che una transazione non quadra (rosso) nonostante dovrebbero esserci pagamenti collegati
Verifica date: Controlla nel sistema esterno la data effettiva del pagamento
Modifica transazione: Inserisce la Data Pagamento corretta
Riaggiancio: Il sistema ora trova correttamente i pagamenti
Rendicontazione: L'operatore marca la transazione come rendicontabile

10.7. Domande Frequenti

D: Devo sempre compilare la Data Pagamento? R: No, solo quando la data effettiva del pagamento è diversa dalla Data Valuta e il sistema non trova automaticamente i pagamenti.

D: Posso inserire una Data Pagamento successiva alla Data Valuta? R: No, il sistema non lo permette. La data di pagamento deve sempre essere precedente o uguale alla data di accredito.

D: La Data Pagamento viene usata per la contabilità? R: No, nella contabilità viene sempre usata la Data Valuta. La Data Pagamento serve solo per la ricerca dei pagamenti.

Documento aggiornato al 23/01/2026 - Aggiunta sezione Data Pagamento Diversa da Data Accredito