Il copione è sempre lo stesso. Si decide di spedire le comunicazioni del Comune tramite App IO: scadenze, avvisi, promemoria. Il servizio viene configurato, i messaggi sono pronti. Poi, nella riunione di giunta, arriva la domanda più innocente del mondo: “Ma quanti dei nostri cittadini hanno l’app?”
Silenzio. Qualcuno dice “tanti”, qualcun altro “dipende”, un terzo cita una percentuale nazionale letta da qualche parte. Nessuno sa dire quanti, tra le persone che abbiamo in anagrafica o nel gestionale dei tributi, possano davvero ricevere quel messaggio. Eppure è il dato che decide se il canale funziona o se stiamo parlando a una stanza vuota.
Da questa domanda nasce getprofiles (e che prende il nome dalla relativa funzione resa disponibile dal sistema AppIO), uno strumento che ho scritto per darle una risposta verificabile. Vediamo cosa fa, come si usa e, soprattutto, cosa bisogna tenere a mente quando si maneggiano codici fiscali.
Indice degli argomenti
Cittadini raggiungibili su App IO: il dato che manca agli enti
Chi lavora in un ente locale sa che il canale digitale si misura sempre dopo, mai prima. Si lancia un servizio, si guardano gli accessi, si contano i pagamenti. Raramente ci si chiede in anticipo quale parte della popolazione di riferimento sia, in concreto, raggiungibile.
Con App IO la risposta esiste, ma sta dietro un’API. Per ogni codice fiscale, PagoPA può dire se esiste un profilo e se quel cittadino accetta messaggi dal nostro servizio. Farlo a mano, uno alla volta, è impensabile. Farlo con uno script scritto di fretta è un modo sicuro per perdere i risultati al primo errore di rete, o per farsi bloccare dal limite di richieste.
Serviva qualcosa di più robusto di uno script usa e getta, ma abbastanza semplice da poter essere letto, capito e verificato da chi lo usa. Un singolo comando, un file in ingresso, un file Excel in uscita.
Come getprofiles verifica i cittadini raggiungibili su App IO
getprofiles è un programma Python a riga di comando. Legge un file Excel o CSV con una colonna di codici fiscali, interroga una per una l’API GetProfile di App IO e produce un report Excel con due fogli: un riepilogo con i totali e un dettaglio con l’esito per ogni codice fiscale.
Pulizia dei codici fiscali e lavoro in locale
Prima di chiamare l’API fa tre cose di pulizia. Normalizza i codici (via spazi, tutto maiuscolo), scarta quelli con formato non valido, elimina i duplicati. Un codice sbagliato non genera una chiamata inutile e non sporca le statistiche, ma resta visibile nel report con la dicitura “Scartato”, così si può correggere l’anagrafica a monte.
Tutto gira in locale, sul vostro computer. L’unica comunicazione verso l’esterno è la chiamata all’API di PagoPA, con la chiave del vostro servizio. Nessun server intermedio, nessun cloud nostro.
Tutto fatto con l’AI, dando le specifiche dell’API (getprofiles), senza particolari conoscenze.
PagoPA e la stima dei cittadini raggiungibili su App IO
L’API risponde con codici HTTP, e il lavoro interessante sta nel tradurli in qualcosa che un funzionario possa leggere senza aprire la documentazione. Lo strumento li mappa così:
Come leggere gli esiti dell’API GetProfile
• Risposta 200: il cittadino ha un profilo IO. Se ha bloccato i messaggi del nostro servizio, l’esito è “Sì (attivo, messaggi bloccati)”, altrimenti “Sì (attivo)”.
• Risposta 404: nessun profilo IO. Esito “No (nessun profilo)”.
• Risposta 403: esito “Forbidden (da verificare)”. Attenzione, non equivale a “non ha l’app”. Va controllato a mano, e il report lo tiene separato proprio per non confondere i due casi.
• Risposta 401: la chiave non è valida. Non è un problema del singolo cittadino, quindi il programma si ferma subito invece di bruciare migliaia di chiamate inutili.
• Risposta 429, errori 5xx, timeout: problemi transitori. Si riprova con attesa crescente, come vediamo più avanti.
Questa distinzione fra “no”, “bloccato” e “da verificare” è la differenza fra un dato utilizzabile e un numero che sembra preciso ma non lo è. Mettere tutto in un unico “non raggiungibile” avrebbe falsato proprio la cifra che ci interessa.
Verificare i cittadini raggiungibili su App IO passo per passo
Servono Python 3 e la subscription key del vostro servizio su App IO, quella che PagoPA assegna all’ente. Senza chiave, nessuno strumento può interrogare niente, ed è giusto così.
Installazione e protezione della chiave di servizio
Si scarica il progetto e si installano le dipendenze:
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
La chiave si fornisce in uno di due modi. Il preferibile è la variabile d’ambiente IO_API_SUBSCRIPTION_KEY. In alternativa si copia config.example.ini in config.ini e si incolla la chiave nella sezione [api]. La chiave non è mai scritta nel codice, e config.ini è escluso dal controllo di versione.
Comando e opzioni per generare il report
Poi si lancia il comando, indicando il file e il nome della colonna:
python main.py –input elenco.xlsx –column codice_fiscale
Il programma mostra l’avanzamento con una stima dei secondi residui e, alla fine, scrive il report in data/report.xlsx. Se non indicate la colonna, cerca una colonna chiamata codice_fiscale.
Le opzioni utili da conoscere sono poche. –rate regola le richieste al secondo (per default 2, un ritmo prudente). –output cambia il percorso del report. –skip-existing salta i codici già verificati in un run precedente, comodo sui grandi elenchi. –retry-failed fa lo stesso ma riprova solo quelli finiti in errore. –export-only rigenera l’Excel dal checkpoint senza fare nemmeno una chiamata.
Getprofiles tra checkpoint e affidabilità dei dati di App IO
Chi ha lanciato elaborazioni lunghe sa come va a finire: alla riga 3.000 cade la VPN, e il lavoro è da rifare. getprofiles è pensato per sopravvivere a questo.
Ogni esito viene scritto subito in un file di checkpoint, riga per riga. Se il programma si interrompe, per un errore o perché avete chiuso il portatile, al riavvio si riparte da dove si era arrivati. Anche una riga troncata a metà scrittura viene gestita senza invalidare il resto.
Per gli errori temporanei vale il backoff esponenziale: il programma riprova fino a cinque volte, aspettando ogni volta di più, fino a un massimo di 60 secondi, e rispetta l’intestazione Retry-After quando il server la manda. Il timeout di ogni chiamata è di 10 secondi. Sono tutti parametri modificabili da riga di comando.
Infine c’è un interruttore di sicurezza. Se si accumulano dieci errori transitori consecutivi, il programma si ferma, dichiarando che probabilmente c’è un disservizio lato API. Insistere in quel caso significherebbe solo martellare un servizio in difficoltà e riempire il report di errori che non dicono nulla.
Il report sui cittadini raggiungibili su App IO
Il file Excel finale ha due fogli. Il Riepilogo riporta le righe lette, le vuote scartate, i duplicati rimossi, i codici univoci considerati e, per ogni tipo di esito, il numero e la percentuale. È il foglio da portare in giunta.
Il Dettaglio elenca ogni codice fiscale con esito, stato HTTP, lingue preferite, eventuale errore, orario della verifica e numero di tentativi. È il foglio per chi deve lavorare sui casi particolari, ad esempio i “Forbidden” da controllare o i codici scartati da correggere.
Un dettaglio che ho voluto: i codici non ancora verificati compaiono come “In sospeso (rieseguire)”. Il report non finge mai di essere completo quando non lo è.
Dati personali e verifica dei profili App IO
Un elenco di codici fiscali è un insieme di dati personali: lo strumento è tecnicamente semplice, ma l’uso responsabile non lo è altrettanto. Alcune regole di buon senso, che valgono prima ancora di lanciare il comando.
Le cautele per codici fiscali, chiavi e report
• Finalità chiara. Interrogare l’API ha senso se serve a organizzare la comunicazione del servizio, non per curiosità o per costruire elenchi di altro genere. Concordatelo con il DPO e annotatelo.
• Chiave protetta. La subscription key è un segreto dell’ente. Va tenuta in una variabile d’ambiente o in un file locale, mai in un’email, mai in un repository.
• File sotto controllo. Input, checkpoint e report contengono codici fiscali. Conservateli dove conservate il resto dei dati dell’ente e cancellateli quando non servono più.
• Esito come informazione di servizio. Sapere che qualcuno non ha l’app o ha bloccato i messaggi serve a scegliere il canale giusto, non a classificare le persone.
Per questo il progetto su GitHub non contiene nessun dato reale: né elenchi, né report, né chiavi. Solo il codice, i test e la documentazione.
Come usare il dato sui cittadini raggiungibili con App IO
Il numero in sé è l’inizio, non la fine. Ci sono almeno tre strade concrete che il report rende percorribili.
Pianificazione dei canali
La prima è la pianificazione dei canali. Se una quota rilevante dell’elenco non ha un profilo, App IO da sola non basta e conviene prevedere un secondo canale per chi resta fuori: posta, SMS, sportello. Meglio saperlo prima della scadenza che dopo.
Comunicazione mirata
La seconda è la comunicazione mirata. Chi non ha l’app può essere invitato ad attivarla, con un volantino allegato a un avviso già in partenza, un banner sul sito, una parola dello sportello. Con il dato in mano, la campagna si misura: rilanciando lo strumento dopo qualche mese si vede se il numero si è mosso.
Messaggi bloccati e qualità del servizio
La terza è la lettura dei messaggi bloccati. Un cittadino che ha l’app ma ha silenziato il servizio ci sta dicendo qualcosa sul nostro modo di scrivere, sulla frequenza, sull’utilità percepita. È un indicatore di qualità del servizio che di solito nessuno guarda.
Getprofiles su GitHub per misurare la copertura di App IO
getprofiles è disponibile anche su GitHub, con codice, test automatici e documentazione di utilizzo. Il codice è breve, commentato e suddiviso in moduli piccoli (lettura dell’input, validazione, client API, checkpoint, report), proprio perché chiunque lo usi possa leggerlo e capire cosa succede ai dati prima di fidarsene.
Se lo usate nel vostro ente e trovate un caso che non gestisce, segnalatelo. Se avete una modifica utile, proponetela. Le amministrazioni hanno già troppi strumenti chiusi che nessuno sa verificare: uno in più che si può aprire, leggere e correggere non farà male a nessuno.
C’è un punto più generale. Nella PA digitale si parla molto di piattaforme e poco di quegli strumenti piccoli che stanno a valle e rendono i dati delle piattaforme utilizzabili. App IO ha messo a disposizione un canale; a noi tocca capire come usarlo. Forse è questa la domanda da portare nella prossima riunione di giunta, al posto di “quanti hanno l’app”: quanti ne raggiungiamo, e cosa possiamo fare per raggiungere gli altri?
Repository GitHub: https://github.com/AndreaTironi1/getprofiles
Partecipa alla community