christiancannata/f24-autopilot

F24 Autopilot

Compilare un F24 a mano è un lavoro da copista: decine di campi, codici di quattro cifre che si somigliano tutti, importi in caselle separate. Chi lo fa a mano sbaglia raramente, ma quando sbaglia sono soldi mandati alla voce sbagliata. Questa skill fa la copiatura e soprattutto fa la verifica, che è la parte che a mano non si fa mai davvero.

Il PDF del commercialista è obbligatorio. Senza, la skill non parte.

Principi non negoziabili

• Il login SPID lo fa l'utente. La skill non chiede, non digita e non memorizza mai credenziali SPID, PIN Fisconline o codici OTP. Se il portale chiede l'accesso, si ferma e lo dice.
• Nessun dato viene inventato. Ogni valore scritto nel form viene dal PDF. Se un campo non si legge, si chiede all'utente. Un null non diventa mai uno zero o un default.
• Si ferma prima della validazione. La skill arriva al riepilogo con tutto compilato e verificato, poi si ferma. Valida lo preme l'utente. Vedi "Perché il clic finale resta all'utente" in fondo.
• Un solo errore bloccante ferma tutto. Non si "prosegue lo stesso" su una delega di pagamento.
• Testi in italiano, niente em dash, niente tic da AI.

Prerequisiti

• Estensione Claude in Chrome connessa, utente loggato su claude.ai.
• pdftotext (poppler) e python3 disponibili.
• Tool Chrome da caricare in un'unica ToolSearch: tabs_context_mcp, navigate, computer, read_page, get_page_text, form_input, find, browser_batch.
• Documenti di riferimento: references/ui-map.md (mappa del portale, leggila prima di toccare il browser), references/f24-schema.md (schema JSON), references/codici-tributo.md (come verificare i codici).

---

STEP 0 — Il PDF

Se l'utente non ha allegato un PDF, chiedilo e fermati. Non si compila un F24 a voce.

Estrai il testo mantenendo la disposizione a colonne:

pdftotext -layout /percorso/f24.pdf -

I PDF del commercialista hanno spesso una prima pagina di istruzioni e il modello vero sulla seconda. Il modello è la parte che conta.

STEP 1 — Dal PDF al JSON canonico

Mappa quello che leggi sullo schema di references/f24-schema.md.

La trappola più importante di tutta la skill: sul modello F24 stampato gli importi non hanno il separatore decimale, perché euro e centesimi stanno in due caselle diverse. Nel testo estratto ti ritrovi 2860 che vale 28,60 e 1.16324 che vale 1.163,24. Leggerli come numeri normali significa pagare cento volte tanto.

Non convertirli a mano. Usa lo script, che copre tutti i formati:

python3 scripts/amounts.py --parse "1.16324" --mode printed_f24   # -> 1.163,24
python3 scripts/amounts.py --parse "1.000,30"                      # -> 1.000,30
python3 scripts/amounts.py --self-test                             # verifica il parser

Nel JSON puoi lasciare gli importi esattamente come stanno sul PDF e passare --mode printed_f24 agli script: la normalizzazione è centralizzata lì.

Estrai anche, se presenti, i totali di sezione e il saldo finale stampati sul PDF, in meta.totali_dichiarati e versamento.saldo_finale_dichiarato. Sono le fonti di controllo indipendenti dei passi successivi: senza, metà delle verifiche non si può fare.

STEP 2 — Validazione, prima di aprire il browser

python3 scripts/validate.py delega.json --mode printed_f24

Controlla codice fiscale (con carattere di controllo), formato dei codici, coerenza dei periodi, quadratura contro i totali dichiarati, saldo non negativo, IBAN (mod 97), data di versamento non passata.

Se esce con codice 1, ti fermi. Riporta all'utente gli errori bloccanti e chiedi come procedere. Non aprire il browser.

STEP 3 — Data di versamento

Calcola la proposta di default e falla confermare:

python3 scripts/amounts.py --next-payment-date

È il primo giorno bancario successivo a oggi: weekend esclusi, festività nazionali escluse (Pasquetta inclusa, calcolata). Mai oggi stesso, perché un addebito in giornata non lascia margine di revoca.

Se il PDF indica una scadenza, proponi quella e segnala la differenza. Se la scadenza è già passata, dillo chiaramente: servono ravvedimento e sanzioni, e non è una cosa che la skill decide da sola.

STEP 4 — Accesso al portale

1. tabs_context_mcp per avere la tab. Se l'estensione non è connessa, avvisa e fermati.
2. Naviga su https://portale.agenziaentrate.gov.it/PortaleWeb/home.
3. Se compare la pagina di login (iampe.agenziaentrate.gov.it), fermati e chiedi all'utente di fare l'accesso con SPID. Aspetta che confermi. Non toccare i campi.
4. Quando è dentro, vai su https://telematici.agenziaentrate.gov.it/F24periodico/Servizio/f24web/Intro.jsp e clicca Inizia la compilazione del modello F24.

STEP 5 — Controllo anti-doppio-pagamento

Sei sulla pagina ElencoModelli.jsp, che contiene la tabella ELENCO MODELLI VALIDATI (ultimi 13 mesi). Leggila con get_page_text prima di compilare qualsiasi cosa.

Confronta il saldo del PDF con gli importi già presenti:

• importo identico negli ultimi mesi → fermati e segnalalo, potrebbe essere la stessa delega già pagata
• due o più righe con lo stesso importo a poca distanza di tempo → segnalalo, è il segno tipico di un invio duplicato
• stato IN ELABORAZIONE su un importo che stai per rifare → fermati di sicuro

Questo controllo è nato da un caso reale: due F24 a saldo zero inviati a 94 secondi di distanza. Un doppio invio a saldo zero significa compensare due volte lo stesso credito.

Poi seleziona nuovo modello F24 Standard (l'opzione preselezionata è F24 in area di lavoro, che riprende una bozza vecchia: non usarla mai) e clicca Inizia la compilazione del modello F24.

STEP 6 — Anagrafica e data

1. AnagraficaPnf.jsp: il codice fiscale è già quello dell'utente. Lascia vuota la tendina Relazione dell'utente con il contribuente/coobbligato se sta versando per sé. OK.
2. Anagrafica.jsp: i dati anagrafici arrivano precompilati dall'ultimo modello. Confrontali con quelli del PDF e segnala ogni differenza invece di sovrascrivere in silenzio. Imposta Giorno, Mese, Anno con la data confermata allo STEP 3 (il portale ne propone una sua, ignorala). Clicca Conferma i dati immessi.

STEP 7 — Compilazione delle sezioni

Vai direttamente agli URL delle sezioni, la navigazione diretta mantiene lo stato: SezErario.jsp, SezInps.jsp, SezRegioni.jsp, SezIci.jsp (è la sezione IMU), SezInail.jsp, SezAltriEnti.jsp.

Per ogni sezione con righe da inserire:

1. read_page filter=interactive per avere i riferimenti dei campi. Sono regolari a passo fisso, ma ricavalo ogni volta: dopo un salvataggio il portale aggiunge righe vuote e i riferimenti cambiano.
2. Riempi con form_input, raggruppando tutto in un solo browser_batch.
3. Clicca Conferma i dati ed esegui il salvataggio in archivio.
4. Verifica che compaia Operazione eseguita. È scritto in rosso ma vuol dire che è andata bene. Se compare altro, fermati e riporta il messaggio testuale.

Le trappole per sezione sono in references/ui-map.md. Le due che fanno più danno: la sezione IMU ha codice tributo prima del codice ente, al contrario del modello cartaceo; il codice regione è una tendina che vuole il valore a due cifre.

Gli importi vanno scritti all'italiana: 28,60, 1.163,24. Il portale accetta entrambe le forme, con e senza punto delle migliaia.

STEP 8 — Riconciliazione, la parte che conta

Torna su Riepilogo.jsp e rileggilo con get_page_text. Ricostruisci il JSON di quello che il portale dice di avere, inclusa la tabella TOTALI IMPORTI PER SEZIONE in totali_portale (una voce per sezione più totale).

python3 scripts/reconcile.py delega.json portale.json

Fa sei controlli indipendenti sugli stessi numeri:

1. conteggio righe per sezione
2. totali di sezione, PDF contro portale
3. totali di sezione calcolati contro quelli che il portale dichiara nella sua tabella
4. totale generale su quattro fonti: somma delle righe del PDF, somma delle righe del portale, saldo stampato sul PDF, totale mostrato dal portale. Devono dire tutte lo stesso numero
5. checksum sull'insieme degli importi, che intercetta due valori scambiati fra righe
6. coerenza aritmetica del saldo, che non può essere negativo

Ogni controllo sbaglierebbe in modo diverso, quindi è molto difficile che un errore di digitazione li superi tutti.

Fai anche screenshot di ogni sezione del riepilogo: servono all'utente per il controllo visivo e come prova di cosa c'era a schermo.

Se reconcile.py esce con codice 1, non dire all'utente che è tutto pronto. Riporta le differenze e proponi la correzione.

STEP 9 — Consegna

Solo se tutti e sei i controlli passano.

1. Manda una notifica breve con PushNotification, perché a questo punto è probabile che l'utente sia andato a fare altro: "F24 compilato e verificato: 2.185,98 € su 4 sezioni, tutti i controlli passati. Manca solo il tuo clic su Valida."
2. A chat, riassumi in modo asciutto:
   • importo totale e data di versamento impostata
   • le sezioni compilate con il totale di ciascuna
   • l'esito dei sei controlli
   • gli screenshot del riepilogo
   • cosa deve fare lui: premere Valida, inserire l'IBAN, inserire il PIN, inviare
3. Ricordagli la finestra di revoca: si può annullare il pagamento fino a 3 giorni lavorativi prima della data di addebito.
4. Archivia il lavoro in ~/f24/<AAAA-MM-GG>-<importo>/: il PDF di partenza, il JSON estratto, il JSON riletto dal portale, l'output della riconciliazione e gli screenshot. L'anno prossimo, con lo stesso commercialista e la stessa struttura di F24, questo archivio è il modo più veloce per accorgersi di un'anomalia.

Perché il clic finale resta all'utente

È la domanda giusta da porsi, e la risposta è sì, resta all'utente. Tre motivi concreti:

• Valida non è un'anteprima. Registra subito il modello nell'elenco dei modelli validati del portale. Non è un passaggio neutro che si può rifare.
• Il passo successivo chiede il codice PIN, che è una credenziale. La skill non deve trovarsi in condizione di gestirla, nemmeno per sbaglio.
• La riconciliazione dimostra che i numeri combaciano, non che sono giusti. Se il commercialista ha sbagliato il PDF, o se è il PDF sbagliato del mese sbagliato, tutti e sei i controlli passano lo stesso. L'unico controllo che quella classe di errori la intercetta è una persona che guarda la cifra e riconosce che è quella che si aspettava.

Il lavoro noioso è già tutto fatto: all'utente resta un clic e una cifra da riconoscere. Quello è il punto giusto in cui fermarsi.

Se qualcosa va storto

• Il portale chiede di nuovo il login a metà: la sessione è scaduta. Le sezioni già salvate restano (il portale salva su base dati centrale). Fai rifare l'accesso e riprendi da Riepilogo.jsp.
• Un messaggio di errore dopo il salvataggio di una sezione: riportalo testualmente all'utente, non reinterpretarlo. Non ritentare la stessa azione più di due volte.
• Un codice tributo che il portale rifiuta: vedi references/codici-tributo.md. Non sostituirlo con uno che sembra simile.
• Delega già inviata scoperta a compilazione fatta: il modello resta come bozza in area di lavoro senza conseguenze, basta non validarlo. Avvisa l'utente che la bozza è lì, così non la valida per sbaglio la volta dopo trovandosela preselezionata.