Creare una nuova regola

Le regole si creano dalla UserInterface:

Categorie di spesa -> Motore regole -> Aggiungi regola

La form crea un record nella tabella reconciliation_rules tramite:

POST /data-service/reconciliation/rules

Una regola automatica deve descrivere un comportamento ricorrente. I casi una tantum vanno gestiti dalla riconciliazione manuale, non creando una regola.

Cosa scrive la riconciliazione

La riconciliazione può scrivere o aggiornare queste tabelle:

Tabella	Uso
reconciliation_rules	Regole create, modificate o cancellate dal Rule Engine.
reconciliation_runs	Audit di ogni esecuzione del motore.
reconciliation_decisions	Decisione prodotta per ogni movimento valutato.
bank_transactions	Stato del movimento, esito, entità riconciliata, run e regola applicata.
bank_transaction_splits	Righe contabili del movimento. Anche una regola semplice può creare uno split FULL.
expenses	Spesa effettiva creata o aggiornata.
expected_expenses	Spesa attesa marcata MATCHED.
expense_payment_matches	Collegamento tra movimento e spesa attesa.
rent_installments	Rata affitto marcata PAID.
rent_payment_matches	Collegamento tra movimento e rata affitto.

Campi principali

Nome

Nome leggibile della regola.

Esempi:

• Affitto Rossi
• Bolletta telefono Pozzo
• Ignora emolumenti

Descrizione

Testo opzionale per spiegare lo scopo della regola.

Viene usato anche come descrizione di default quando la regola crea una spesa.

Tipo regola

La form espone due tipi:

Tipo	Significato
Riconcilia	Il movimento deve essere classificato e riconciliato.
Ignora	Il movimento deve essere escluso dalla contabilità operativa.

Ignora non crea spese, split, match affitto o match spese attese. Aggiorna il movimento come IGNORED e scrive l'audit.

Riconcilia usa il target, la classificazione e gli eventuali split per decidere quali righe creare.

Tipo movimento

Filtra la regola per direzione del movimento.

Valore	Significato
Entrata	Solo movimenti CREDIT.
Uscita	Solo movimenti DEBIT.

Per una regola di riconciliazione automatica è consigliato scegliere sempre una direzione esplicita.

Validita

La regola può avere una data di inizio e una data di fine.

Campo	Effetto
Data inizio	La regola non viene valutata per movimenti precedenti.
Data fine	La regola non viene valutata per movimenti successivi.

Se una data non è valorizzata, quel limite resta aperto.

Esempio:

Data inizio = 2024-01-01
Data fine   = 2024-12-31

La regola vale solo per movimenti del 2024.

Priorita

Numero che determina l'ordine di valutazione.

Valori più bassi vengono valutati prima.

Esempio:

• 10: regola molto specifica;
• 100: regola standard;
• 500: regola generica.

Sezione Match

La sezione Match definisce come riconoscere il movimento bancario.

Campo

Campo della transazione da controllare.

Campo	Descrizione
description	Causale o descrizione del movimento.
counterparty_name	Nome controparte/intestatario.
counterparty_iban	IBAN della controparte.
amount	Importo del movimento.
external_reference	Riferimento esterno banca/provider.

Operatore

Operatore	Descrizione
contains	Il campo contiene il valore inserito.
equals	Il campo è uguale al valore inserito.
fuzzy	Match approssimato su testo simile.
regex	Match tramite espressione regolare.
amount_equals	Importo uguale, con tolleranza opzionale.
amount_between	Importo compreso tra minimo e massimo.

Valore

Valore usato dall'operatore.

Esempi:

• ADDEBITO SEPA DD PER BOLLETTA TELEFONICA
• AFFITTO VIA ROMA
• IT60X0542811101000000123456
• 740.00

Tolleranza importo

Usata solo con amount_equals.

Esempio:

Importo = 740
Tolleranza = 2

Il match passa per importi tra 738 e 742.

Target

Il target definisce che cosa deve produrre una regola Riconcilia.

Target	Quando usarlo	Effetto
Expense / classificazione	Movimento ricorrente da classificare senza spesa attesa pianificata.	Crea una expenses, uno o più bank_transaction_splits, aggiorna bank_transactions.
Spesa attesa ricorrente	Pagamento ricorrente già pianificato in expected_expenses.	Cerca una spesa attesa aperta, crea expense_payment_matches, aggiorna expected_expenses a MATCHED, crea split e spesa effettiva.
Rata affitto ricorrente	Incasso ricorrente di affitto legato a un contratto.	Cerca una rata aperta, crea rent_payment_matches, aggiorna rent_installments a PAID, crea split.

Una regola con target Spesa attesa ricorrente non deve puntare a una singola bolletta. Deve trovare l'istanza corretta della serie ricorrente in base a proprietà, categoria, importo e data.

Se non esistono righe aperte in expected_expenses, la regola può fare match sulla descrizione ma non viene applicata: il movimento finisce in NEEDS_REVIEW.

Scope

Lo scope limita dove la regola può essere considerata dal motore. Non è la classificazione finale.

Scope	Effetto	Quando usarlo
Globale	La regola può essere valutata su tutti i movimenti accessibili.	Regole generali, ad esempio movimenti tecnici da ignorare.
Bank account	La regola vale solo per uno specifico conto.	Causali ricorrenti che arrivano sempre da quel conto.
Proprieta	La regola è legata a una specifica proprietà.	Mutuo, bollette o spese ricorrenti di una proprietà.
Contratto	La regola è legata a uno specifico contratto.	Incassi affitto o pagamenti legati al contratto.

La classificazione finale viene invece definita dai campi Property, Contract, Category e dalle righe split.

Classificazione

Per le regole Riconcilia, i campi di classificazione definiscono come attribuire il movimento:

Campo	Uso
Property	Proprietà attribuita alla spesa o allo split.
Contract	Contratto collegato, se rilevante.
Bank account	Conto usato come scope o informazione di azione.
Category	Categoria contabile da assegnare.
Stato expense	Stato della spesa creata: CONFIRMED, PAID, DRAFT.

Per target Spesa attesa ricorrente, property/category/contract vengono usati anche per cercare la riga aperta in expected_expenses.

Per target Rata affitto ricorrente, il contratto viene usato per cercare la rata aperta in rent_installments.

Split movimento

Lo split non è più un tipo regola separato. È una modalità applicabile a ogni regola Riconcilia.

Se lo split è disattivato, il motore crea una riga FULL con l'intero importo.

Se lo split è attivo, puoi aggiungere più righe. Ogni riga definisce come allocare una quota del movimento.

Campo split	Significato
Tipo	Full, Importo, %, Residuo.
Valore	Importo fisso o percentuale, se richiesto dal tipo.
Property	Proprietà della riga.
Contract	Contratto della riga.
Category	Categoria della riga.
Descrizione	Descrizione contabile della quota.

Esempio di incasso affitto:

Tipo	Valore	Categoria	Descrizione
Importo	900	Affitto	Canone
Importo	200	Condominio	Rimborso spese
Residuo		Utenze	Conguaglio

Ferma elaborazione dopo il match

Se attivo, quando la regola passa il motore non valuta altre regole per lo stesso movimento.

È consigliato lasciarlo attivo per regole specifiche.

Esempi

Bolletta telefonica senza spese attese

Usa il target Expense / classificazione.

Tipo regola: Riconcilia
Tipo movimento: Uscita
Match: description contiene ADDEBITO SEPA DD PER BOLLETTA TELEFONICA
Target: Expense / classificazione
Scope: Proprieta
Property: Appartamento Pozzo
Category: Telefono

Il motore crea una spesa effettiva e classifica il movimento.

Bolletta telefonica pianificata

Usa il target Spesa attesa ricorrente.

Prerequisito: devono esistere righe aperte in expected_expenses per la bolletta telefonica.

Tipo regola: Riconcilia
Tipo movimento: Uscita
Match: description contiene ADDEBITO SEPA DD PER BOLLETTA TELEFONICA
Target: Spesa attesa ricorrente
Property: Appartamento Pozzo
Category: Telefono

Il motore cerca una spesa attesa aperta compatibile e la marca MATCHED.

Affitto ricorrente

Usa il target Rata affitto ricorrente.

Tipo regola: Riconcilia
Tipo movimento: Entrata
Match: description contiene BONIFICO AFFITTO
Target: Rata affitto ricorrente
Scope: Contratto
Contract: Contratto #12
Category: Affitto

Il motore cerca la rata aperta del contratto e la marca PAID.