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:

1. Controlla la posta via IMAP (Gmail e altre caselle) a intervalli regolari.
2. Riconosce le email delle bollette in base al mittente.
3. Scarica il PDF 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

• 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.

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.

Stack

Python · Playwright · IMAP · Docker · 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.