← Tutti i progetti
Attivo ottobre 2026

Bollette Auto

Un sistema self-hosted che controlla la posta, scarica automaticamente le bollette dai portali dei fornitori, le archivia sul NAS di casa e ne estrae i dati in un cruscotto web — con notifiche su Telegram.

PythonDockerPlaywrightFastAPISQLiteSelf-hosted

Il problema

Ogni mese la stessa trafila: arriva l’email del fornitore, login al portale, scarica il PDF, rinominalo, salvalo nella cartella giusta. Moltiplicato per luce, gas, telefono e internet diventa un lavoretto noioso e ripetitivo — esattamente il genere di cosa che un computer dovrebbe fare al posto mio.

Cosa fa

Bollette Auto gira in background dentro un piccolo container Docker e, in autonomia:

  1. Controlla la posta via IMAP (Gmail e altre caselle) a intervalli regolari.
  2. Riconosce le email delle bollette in base al mittente.
  3. Recupera il PDF — dall’allegato, da un link nella mail o dal portale del fornitore.
  4. Archivia il file sul NAS con una struttura ordinata anno/FORNITORE/.
  5. Estrae i dati dal PDF e li salva in un database, per renderli consultabili.
  6. Notifica l’esito su Telegram — bolletta scaricata, oppure errore.

Come funziona

Il cuore del sistema è un ciclo di polling IMAP: per ogni casella parte un thread che controlla le nuove email, le smista al fornitore giusto e attiva lo scraper corrispondente. Il PDF scaricato passa all’archiviatore, che lo salva sul NAS (montato via CIFS) nella cartella dell’anno e del fornitore.

Due strategie di download

Tre modi in cui arriva una bolletta

Non tutti i fornitori si comportano allo stesso modo, e il sistema li ha imparati uno a uno:

Un filtro sull’oggetto della mail, configurabile per fornitore, evita di archiviare come “ricevute” le polizze o gli avvisi che arrivano dallo stesso mittente.

Cosa succede alla mail

Dopo l’elaborazione la mail viene segnata come letta e spostata in una cartella “elaborate”; quelle più vecchie di dodici mesi vengono eliminate, ma solo da quella cartella, mai dalla posta in arrivo (tra le caselle monitorate c’è la mia Gmail personale). Le notifiche di errore identiche non si ripetono e di notte restano in silenzio.

Design guidato dalla configurazione

Un unico file YAML descrive caselle email, fornitori, selettori e notifiche. La maggior parte dei fornitori si aggiunge senza toccare il codice; solo i portali “difficili” — single-page app con token in sessionStorage, API particolari — richiedono un piccolo scraper dedicato in Python.

Dai PDF al cruscotto

Le bollette non restano semplici PDF in una cartella. Ogni file viene analizzato (estrazione del testo con pdfplumber) per ricavarne importo, periodo, data della fattura, consumo e fornitore, e i dati confluiscono in un database SQLite.

Su questi dati gira un cruscotto web — un servizio a parte in FastAPI + Uvicorn, con frontend statico e grafici Chart.js:

I filtri (fornitore, anno, mese) sono globali e si mantengono passando da una scheda all’altra.

Attenzione alla sicurezza

Quando scade la sessione TIM

La sessione salvata dura qualche settimana. Quando è scaduta, a ottobre, rinnovarla è stato più difficile della prima volta: il browser pilotato da Playwright finisce in un loop infinito di reCAPTCHA, e nemmeno lanciando il vero Chrome con un profilo dedicato è bastato, perché TIM rifiuta in silenzio un login da un profilo nuovo. Nel mio Chrome di tutti i giorni il login funziona. Il metodo che ora funziona in modo affidabile è quindi fare il login lì come al solito e importare i cookie: li esporto con un’estensione del browser e uno script tiene solo quelli di TIM, verifica che la sessione carichi davvero la pagina delle fatture e scrive il file solo se è così. Il controllo esiste perché un precedente helper aveva sovrascritto una sessione buona con una non autenticata. Ultimo dettaglio: l’identità del browser che lo scraper presenta andava allineata alla versione di Chrome che uso davvero, altrimenti la sessione importata rischiava di essere rifiutata. Dopo il rinnovo, la bolletta di ottobre si è scaricata da sola.

Stato

In produzione e in continua crescita: i fornitori attivi coprono luce, gas, telefono, internet, acqua, assicurazione casa e bollo moto, e l’archivio conta ormai oltre 280 bollette. Il sistema è stato spostato da Docker Desktop (che si bloccava ai riavvii) a un Docker nativo in una distribuzione Linux su WSL2 sul mini PC, con avvio automatico. L’ultimo fornitore aggiunto, l’acqua (10 ottobre 2026), è stato solo una riga di configurazione. TIM resta il punto fragile: ogni qualche settimana la sessione va rinnovata a mano (vedi sopra).

Stack

Python · Playwright · IMAP · Docker (WSL2) · SQLite · FastAPI · NAS Synology (CIFS) · Telegram Bot API

Cosa ho imparato