Istruzioni operative di RateOS

Scarica .md

RateOS — Istruzioni operative

Versione: 2.0 Studio: Andrea Torresi — Dottore Commercialista e Revisore Legale Ultimo aggiornamento: 5 maggio 2026

Indice

  1. Cosa è RateOS
  2. Primo avvio
  3. Operatività quotidiana
  4. Caricare un avviso bonario
  5. Gestione clienti Persone Fisiche
  6. Download F24 e prospetti Excel
  7. Invio email al cliente
  8. Personalizzazione testi email
  9. Memo automatici di scadenza
  10. Pulizia e manutenzione
  11. Risoluzione problemi
  12. Riferimenti normativi

1. Cosa è RateOS

RateOS è l'applicazione interna dello Studio per automatizzare il ciclo completo della rateazione degli avvisi bonari emessi dall'Agenzia delle Entrate ai sensi degli artt. 36-bis DPR 600/1973, 54-bis DPR 633/1972 e 36-ter DPR 600/1973.

Il sistema:

2. Primo avvio

Da fare una sola volta, alla prima installazione su un nuovo computer.

2.1 Avvia l'applicazione

Apri PowerShell nella cartella RateOS e digita:

.\venv\Scripts\python.exe -m uvicorn web.app:app --host 127.0.0.1 --port 8000 --reload

Lascia il terminale aperto. Apri il browser su:

http://127.0.0.1:8000

2.2 Configura le credenziali

Vai su Configurazione (icona ingranaggio in alto a destra). Compila:

Database TiDB Cloud - Host, Porta, Database, Username, Password — ottieni questi dati creando un cluster Serverless gratuito su tidbcloud.com. Procedura passo-passo nella pagina Setup guidato.

Server SMTP - Server SMTP, Porta, Indirizzo mittente, App Password — per Google Workspace usa smtp.gmail.com:587 e una App Password generata su myaccount.google.com/apppasswords.

2.3 Testa le connessioni

Sulla stessa pagina: - Testa connessione DB — deve restituire "Connesso a TiDB v…" - Testa invio email — deve restituire "Login SMTP OK su…"

Se entrambi rispondono OK, click Salva configurazione.

2.4 Riavvia il server e inizializza il database

Da terminale: Ctrl+C per fermare il server, poi rilancia il comando del punto 2.1.

Apri un secondo terminale nella stessa cartella e digita:

.\venv\Scripts\python.exe main.py --init-db

Crea le tabelle e popola i template email di default. Il messaggio finale deve essere:

Database RateOS inizializzato su TiDB Cloud.

3. Operatività quotidiana

Lanciare l'applicazione

Ogni volta che apri il computer, riavvia il server con:

.\venv\Scripts\python.exe -m uvicorn web.app:app --host 127.0.0.1 --port 8000 --reload

Apri il browser su http://127.0.0.1:8000.

Spegnere l'applicazione

Nel terminale del server premi Ctrl+C. Per chiudere completamente, chiudi il terminale.

4. Caricare un avviso bonario

4.1 Persona Giuridica (S.R.L., S.p.A., S.n.c., …)

  1. Click Carica avviso dalla home oppure dalla navbar.
  2. Seleziona il PDF dell'avviso bonario originale dell'AdE.
  3. Click Estrai dati.
  4. Verifica i dati estratti nella pagina di conferma:
  5. Codice atto, anno imposta, tipo comunicazione (9001/9002/9003), importo, date.
  6. Ragione sociale (verrà troncata automaticamente a 25 caratteri come richiesto dal form AdE).
  7. Domicilio fiscale (indirizzo, comune, provincia).
  8. Email del cliente (opzionale, ma necessaria per i memo).
  9. Numero rate: scegli un valore tra 2 e 20. Campo obbligatorio, da decidere caso per caso secondo la liquidità del cliente.
  10. (Opzionale) Spunta Invia subito al cliente se vuoi che, al termine del calcolo, parta automaticamente l'email con prospetto Excel + ZIP F24.
  11. Click Calcola piano e scarica F24.

Il sistema interroga l'AdE, scarica gli F24 e ti porta alla dashboard.

4.2 Persona Fisica

Stesso flusso del punto 4.1, ma in più devi indicare anagrafica nascita (data, provincia, comune, sesso) — dato richiesto dal form AdE per i soggetti aso=F e non presente nel PDF dell'avviso.

Conviene pre-registrare il cliente PF una sola volta (vedi sezione 5), così al successivo upload del suo avviso i dati nascita vengono caricati automaticamente.

5. Gestione clienti Persone Fisiche

Vai su Clienti PF dalla navbar.

Pre-registrare un PF

Compila il form a destra ("Registra Persona Fisica"): - Codice fiscale (16 caratteri, alfanumerico) - Cognome, Nome - Data nascita (GG/MM/AAAA), Provincia (sigla), Comune - Sesso (M / F) - Email (opzionale)

Click Registra. Da quel momento, ogni avviso bonario di quel CF importerà automaticamente l'anagrafica.

Aggiornare l'anagrafica

Riapri il form per lo stesso CF: i nuovi valori sovrascrivono quelli vecchi.

6. Download F24 e prospetti Excel

Per singola rata

In dashboard, espandi la card cliente, espandi la pratica e click sul bottone F24 della rata desiderata.

Per pratica completa (tutti gli F24 in ZIP)

In dashboard, sull'header della pratica click ZIP F24. Scarica un singolo archivio compresso con tutti gli F24 della pratica.

Nome del file:

F24_{ragionesociale_o_cognome_nome}_{codice_atto}.zip

Prospetto Excel del piano

Sull'header della pratica click Excel. Scarica un workbook con due fogli: - Riepilogo — anagrafica cliente, dati pratica, importo totale, importo residuo, riferimenti normativi. - Piano rate — tabella completa con #, scadenza, capitale, interessi, totale, stato (futura/imminente/scaduta/pagata) con colorazione, riga totali.

Nome del file:

Prospetto_{ragionesociale_o_cognome_nome}_{codice_atto}.xlsx

7. Invio email al cliente

Invio "prima volta"

Manda al cliente in un'unica email: prospetto Excel + ZIP con tutti gli F24 + corpo del messaggio dal template prima_invio.

Modalità A — Automatica al caricamento Spunta la checkbox Invia subito al cliente nella pagina di conferma upload. L'email parte appena terminato il calcolo del piano.

Modalità B — Manuale dalla dashboard Espandi la pratica e click Invia al cliente sull'header.

Reinvio

Se l'email è già stata inviata, il bottone diventa Reinvia al cliente e c'è il badge "✓ Email cliente inviata". Cliccare reinvia l'email aggiornata (utile se hai modificato il template o cambiato i dati della pratica).

Requisiti

8. Personalizzazione testi email

Vai su Configurazione → Modifica testi email oppure direttamente su /configurazione/email-templates.

Template disponibili

Segnaposti dinamici

Quando salvi oggetto e corpo, puoi usare questi segnaposti tra parentesi graffe:

Segnaposto Descrizione Disponibile in
{nome_destinatario} Ragione sociale (PNF) o Nome+Cognome (PF) Entrambi
{codice_atto} Codice atto AdE Entrambi
{importo_totale} Totale dell'avviso o della rata (formato italiano) Entrambi
{numero_rate} Numero rate del piano Solo prima_invio
{importo_prima_rata} Capitale + interessi prima rata Solo prima_invio
{scadenza_prima_rata} Data scadenza prima rata (GG/MM/AAAA) Solo prima_invio
{numero_rata} Numero della rata in scadenza Solo memo_scadenza
{scadenza} Data di scadenza (GG/MM/AAAA) Solo memo_scadenza

I segnaposti vengono sostituiti al momento dell'invio. Se scrivi un segnaposto inesistente, viene lasciato letterale nel testo.

Esempio di personalizzazione

Oggetto: Studio Torresi — Piano rate atto {codice_atto}

Corpo:
Gentile {nome_destinatario},

abbiamo elaborato per Lei il piano di rateazione su {numero_rate} rate
(prima rata: € {importo_prima_rata} entro il {scadenza_prima_rata}).

Resto a disposizione,
Andrea Torresi

9. Memo automatici di scadenza

Lo scheduler interno (automazione/scheduler.py, basato su APScheduler) viene avviato automaticamente al lancio dell'applicazione. Ogni giorno all'orario configurato in /configurazione esegue invia_memo_scadenze per tutte le soglie configurate.

Configurazione (UI /configurazione → card "Memo automatici scadenze")

Le modifiche si applicano senza riavviare il server: lo scheduler si riconfigura automaticamente al salvataggio.

Idempotenza e multi-PC

Ogni rata tiene traccia delle soglie già inviate nella colonna memo_inviati_gg (CSV). Per impedire email duplicate quando più PC dello studio sono accesi contemporaneamente è implementato un lock cooperativo SQL: solo il primo PC che esegue l'UPDATE atomico ottiene il diritto di inviare; gli altri vedono la soglia già marcata e saltano.

In caso di errore SMTP, il claim viene rilasciato (la soglia torna disponibile) così un retry successivo può ritentare.

Esecuzione manuale (CLI)

.\venv\Scripts\python.exe -c "from notifiche.memo_service import invia_memo_scadenze; print(invia_memo_scadenze())"

9-bis. Distribuzione multi-PC nello studio

Se RateOS è installato su più postazioni dello studio, tutti i PC condividono lo stesso database TiDB Cloud (basta usare le stesse credenziali in /configurazione). Per condividere anche gli allegati F24 e i PDF degli avvisi segui questi passi:

Archivio condiviso su NAS / share di rete

  1. Crea uno share di rete accessibile a tutti i PC, es. \\nas-studio\studio\rateos\ oppure un disco mappato S:\rateos\.
  2. Su ciascun PC, imposta la variabile d'ambiente di sistema: RATEOS_DATA_DIR = \\nas-studio\studio\rateos (Pannello di Controllo → Sistema → Impostazioni avanzate → Variabili d'ambiente → Variabili di sistema → Nuova).
  3. Riavvia RateOS su tutti i PC. Tutti vedranno lo stesso archivio F24 + PDF input + .env.

Vantaggi: - Un solo .env da configurare (sul NAS), tutti i PC ereditano credenziali. - F24 generati da PC1 sono immediatamente accessibili da PC2. - Backup unico sullo share.

Senza condivisione, ogni PC ha il proprio %LOCALAPPDATA%\RateOS\ con allegati locali (DB però rimane condiviso → le pratiche sono visibili a tutti, ma i PDF F24 solo sul PC che li ha generati).

Scheduler memo: lasciare attivo su tutti

Grazie al lock SQL cooperativo, puoi tranquillamente lasciare MEMO_ATTIVO=true su tutti i PC: solo uno invierà effettivamente l'email per ogni rata/soglia, gli altri vedranno il claim già preso. Questo garantisce continuità anche se un PC è spento.

10. Pulizia e manutenzione

Pulire l'archivio (TUTTO)

Vai su Configurazione, in fondo alla pagina nel riquadro rosso Pulizia archivio:

  1. Scrivi PULISCI nel campo (esattamente, in maiuscolo).
  2. Click Pulisci tutto, conferma il dialog.

Vengono eliminati: - Tutte le righe da clienti, pratiche, rate. - Tutti i file PDF in allegati_f24/. - Tutti i PDF di input in allegati_pdf_input/.

⚠️ Operazione non reversibile. Fai sempre prima un backup esportando i prospetti Excel di tutte le pratiche, oppure un dump del DB.

Backup

Backup files Copia regolarmente le cartelle allegati_f24/ e allegati_pdf_input/ su disco esterno o cloud privato dello studio.

Backup database Il cluster TiDB Cloud Serverless è ridondato lato AWS. Per backup on-demand:

.\venv\Scripts\python.exe -c "from sqlalchemy import inspect; from database.models import engine; ..."

Più semplicemente, esporta i prospetti Excel di tutte le pratiche aperte come backup leggibile.

Aggiornamenti

Quando arriva un'evoluzione del software:

  1. Ctrl+C per fermare il server.
  2. Sostituisci i file aggiornati nella cartella RateOS.
  3. Aggiorna le dipendenze: .\venv\Scripts\python.exe -m pip install -r requirements.txt.
  4. Esegui le eventuali migrazioni: .\venv\Scripts\python.exe main.py --init-db.
  5. Riavvia il server.

11. Risoluzione problemi

"SMTPAuthenticationError 534" durante invio email

Stai usando la password dell'account Google. Devi usare un'App Password di 16 caratteri. Vedi myaccount.google.com/apppasswords.

"Errore di validazione AdE" durante calcolo piano

Il portale ratef24 ha rifiutato i dati. Cause più comuni: - Ragione sociale > 25 caratteri — il sistema tronca automaticamente, ma se il troncamento taglia in modo strano (es. "ADRIATICA BUSINESS SOLUTI"), il portale può rifiutare. - Codice atto errato o non ancora attivo sul portale AdE. - Data di ricevimento futura rispetto a quella di sistema.

"Tabella piano rate non trovata"

Il portale AdE ha risposto con una pagina diversa dal previsto: probabile manutenzione del sito o cambiamento del template HTML. Riprova più tardi; se persiste, contattare il fornitore del software per aggiornamento del parser.

Il PDF non viene letto correttamente

RateOS legge solo PDF testuali (avvisi originali). Se l'avviso è una scansione, serve un OCR (modulo non ancora attivo). Carica il PDF originale ricevuto dall'AdE.

"SSL: CERTIFICATE_VERIFY_FAILED" su connessione DB

Su Windows manca il bundle CA. RateOS usa certifi automaticamente; se il problema persiste:

.\venv\Scripts\python.exe -m pip install --upgrade certifi

"Cliente non ha email registrata"

Aggiungi l'email del cliente nel form di conferma upload, oppure dalla pagina Clienti PF (per i PF) o direttamente sul DB (per i PNF, attualmente l'edit non è esposto in UI — rimane sul roadmap).

Server non si avvia, errore "address already in use"

Un'altra istanza di RateOS è già in esecuzione su porta 8000.

netstat -ano | findstr :8000
taskkill /PID <pid> /F

Oppure cambia porta nel comando di avvio (--port 8001).

12. Riferimenti normativi

Norma Oggetto Codice tributo
Art. 36-bis DPR 600/1973 Controllo automatizzato dichiarazioni redditi 9001
Art. 54-bis DPR 633/1972 Controllo automatizzato IVA 9002
Art. 36-ter DPR 600/1973 Controllo formale 9003
Art. 3-bis D.Lgs. 462/1997 Pagamento rateale (max 20 rate trimestrali, interessi 3,5% annuo) —
Art. 2 c. 2 D.Lgs. 462/1997 Sanzione ridotta a 1/3 se prima rata entro 60 giorni —
Provv. AdE prot. 17431 / 6 marzo 2017 Definizione modello F24 precompilato —

Contatti e supporto

Documento generato il 5 maggio 2026. RateOS v2.0.