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.
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:
- Controlla la posta via IMAP (Gmail e altre caselle) a intervalli regolari.
- Riconosce le email delle bollette in base al mittente.
- Recupera il PDF — dall’allegato, da un link nella mail o dal portale del fornitore.
- Archivia il file sul NAS con una struttura ordinata
anno/FORNITORE/. - Estrae i dati dal PDF e li salva in un database, per renderli consultabili.
- 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
- Browser (Playwright) — per i portali che richiedono navigazione interattiva.
Lo scraper è guidato dalla configurazione: i selettori CSS della pagina di
login e del download sono descritti in un file YAML, quindi aggiungere un
fornitore “standard” non richiede scrivere codice. Per robustezza il download
prova più strategie in sequenza (URL nell’
onclick, download nativo del browser, apertura in nuova scheda, link diretto). - API diretta — per i portali che espongono API REST. Uno scraper dedicato fa login e scarica il PDF senza avviare un browser: più veloce e più affidabile.
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:
- Allegato PDF — il caso più semplice: la mail contiene già il file. Basta un blocco di configurazione, nessun codice. È così per l’assicurazione di casa e per l’acqua.
- Link nell’email — niente allegato, ma un collegamento a una pagina pubblica. Per il bollo della moto la ricevuta è una pagina HTML (o un PDF PagoPA) che il sistema scarica e, se serve, stampa in PDF. Per la luce di Sorgenia il link porta a una pagina da cui si recupera il PDF. In entrambi i casi niente login e niente codici SMS: per Sorgenia avevo già costruito uno scraping del portale con i cookie, e l’ho scartato quando ho visto che il link nella mail bastava.
- Portale — quando proprio non c’è altra via, login con un browser o con le API del fornitore. Per TIM, protetto da reCAPTCHA, faccio il login a mano una volta e il sistema riusa la sessione salvata, avvisandomi su Telegram quando scade.
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:
- Panoramica — schede riepilogo, grafici di spesa e consumo mensile, ripartizione per fornitore e spesa annuale.
- Bollette — tabella paginata con filtri per fornitore, anno e mese.
- Forniture — una scheda per fornitore con i dati di fornitura (POD / codice cliente).
- Andamento — prezzo della materia prima nel tempo e consumo per fornitore.
I filtri (fornitore, anno, mese) sono globali e si mantengono passando da una scheda all’altra.
Attenzione alla sicurezza
- Credenziali del NAS fuori dal codice, in variabili d’ambiente.
- Utente del NAS dedicato, con i soli permessi di lettura/scrittura sulla cartella delle bollette (principio del minimo privilegio).
- App Password per Gmail invece della password dell’account.
- Nessun segreto versionato: tutto ciò che è sensibile resta fuori dal repository.
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
-
I portali cambiano spesso il proprio HTML: tenere i selettori nella configurazione, e non nel codice, rende la manutenzione questione di secondi.
-
Separare “scraper generico guidato da YAML” da “scraper dedicato” mantiene il sistema semplice per il caso comune e flessibile per quello difficile.
-
Limite noto: i portali con autenticazione a due fattori non sono gestiti. Quando il portale chiede un codice SMS conviene cercare un’altra strada (come il link nella mail).
-
Mail che sfuggono: il sistema legge solo la posta in arrivo non letta, quindi una mail che salta l’inbox (un filtro la archivia) o che ho già aperto io non viene vista. Per i fornitori con API basta rilanciare lo scraper; per quelli con solo l’allegato bisogna rimettere la mail come non letta. Una scansione periodica di sicurezza è un’idea, non ancora fatta.
-
Il codice Python è dentro l’immagine Docker: dopo una modifica serve ricostruire, non basta riavviare.