Il problema della conoscenza del pubblico digitale

Il copione è sempre lo stesso: un Comune decide di inviare scadenze, avvisi e promemoria tramite App IO. Il servizio viene configurato, i messaggi sono pronti, ma nella riunione di giunta arriva la domanda più innocente del mondo: “Quanti dei nostri cittadini hanno l’app?”.

Le risposte sono vaghe: “tanti”, “dipende”, o una percentuale nazionale letta da qualche fonte. Nessuno sa quanti, tra le persone presenti nell’anagrafica o nel gestionale tributi, possano davvero ricevere quel messaggio. Eppure è il dato che decide se il canale funziona o se si sta parlando a una stanza vuota.

La risposta di Getprofiles

Da questa esigenza nasce getprofiles, uno strumento che interroga l’API GetProfile di App IO per fornire una risposta verificabile. Lo strumento prende il nome dalla relativa funzione resa disponibile dal sistema App IO e consente di trasformare un semplice elenco di codici fiscali in un report Excel dettagliato.

Il programma è scritto in Python, si esegue da riga di comando, legge un file Excel o CSV con una colonna di codici fiscali, chiama l’API per ciascuno e genera un report con due fogli: un riepilogo dei totali e un dettaglio per ogni codice fiscale.

Fasi di pre‑elaborazione

    • Normalizza i codici (rimuove spazi, converte tutto in maiuscolo).
    • Scarta i formati non validi.
    • Elimina i duplicati.

Un codice sbagliato non genera una chiamata inutile e non altera le statistiche, ma rimane nel report con la dicitura “Scartato”, così da poter correggere l’anagrafica a monte.

Interrogazione dell’API e interpretazione delle risposte

L’unica comunicazione verso l’esterno è la chiamata all’API di PagoPA, usando la chiave di sottoscrizione del servizio. L’API restituisce codici HTTP che getprofiles traduce in esiti comprensibili per i funzionari:

    • 200: il cittadino ha un profilo IO. Se ha bloccato i messaggi del servizio, l’esito è “Sì (attivo, messaggi bloccati)”, altrimenti “Sì (attivo)”.
    • 404: nessun profilo IO. Esito “No (nessun profilo)”.
    • 403: “Forbidden (da verificare)”. Non equivale a “non ha l’app”; richiede verifica manuale.
    • 401: chiave non valida. Il programma si interrompe immediatamente per evitare migliaia di chiamate inutili.
    • 429, errori 5xx o timeout: problemi transitori. Viene attivato un back‑off esponenziale con ripetizioni fino a cinque volte.

Questa distinzione fra “no”, “bloccato” e “da verificare” è cruciale: evita di aggregare tutti i casi in un unico “non raggiungibile”, falsificando il dato di cui il Comune ha realmente bisogno.

Come si utilizza getprofiles

Prerequisiti:

    • Python 3 installato.
    • Subscription key del servizio App IO, fornita da PagoPA.

Procedura:

    • Scaricare il progetto da GitHub e installare le dipendenze (pip install -r requirements.txt).
    • Impostare la chiave di API nella variabile d’ambiente IOAPISUBSCRIPTIONKEY oppure in config.ini (file escluso dal versionamento).
    • Eseguire il comando indicando file di input e colonna dei codici fiscali:
python main.py --input elenco.xlsx --column codicefiscale

Il programma mostra l’avanzamento con una stima dei secondi residui e, al termine, scrive il report in data/report.xlsx. Se la colonna non è specificata, cerca una colonna chiamata codice_fiscale.

Opzioni di esecuzione

    • --rate: regola le richieste al secondo (default 2).
    • --output: cambia il percorso del report.
    • --skip-existing: salta i codici già verificati in un run precedente.
    • --retry-failed: ripete solo le verifiche fallite.
    • --export-only: rigenera l’Excel dal checkpoint senza effettuare chiamate.

Queste opzioni rendono lo script adatto anche a elenchi molto lunghi, dove interruzioni di rete o cadute della VPN sono frequenti.

Resilienza e gestione degli errori

Il programma scrive ogni esito in un file di checkpoint riga per riga. Se si interrompe per errore o chiusura del portatile, al riavvio riparte dall’ultimo punto salvato. Anche una riga troncata a metà viene gestita senza invalidare il resto.

Per gli errori temporanei viene applicato un back‑off esponenziale: fino a cinque tentativi, con attese crescenti fino a un massimo di 60 secondi, rispettando l’intestazione Retry-After quando presente. Il timeout di ogni chiamata è di 10 secondi, tutti parametri modificabili da riga di comando.

Un’interruzione di sicurezza è prevista: se si accumulano dieci errori transitori consecutivi, lo script si ferma, segnalando un possibile disservizio lato API. Insistere in quel caso sarebbe controproducente.

Il report finale

Il file Excel prodotto contiene due fogli:

    • Riepilogo: conta 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 documento da presentare in giunta.
    • Dettaglio: elenca ogni codice fiscale con esito, stato HTTP, lingue preferite, eventuale errore, orario della verifica e numero di tentativi. Serve a chi deve approfondire casi particolari, come i “Forbidden” o i codici scartati.

I codici non ancora verificati compaiono come “In sospeso (rieseguire)”, così il report non finge mai di essere completo quando non lo è.

Buone pratiche nella gestione dei dati personali

Un elenco di codici fiscali è un insieme di dati personali sensibili. Anche se lo strumento è tecnicamente semplice, il suo utilizzo richiede rigorosi accorgimenti:

    • Finalità chiara: l’interrogazione deve servire a organizzare la comunicazione del servizio, non a curiosità o a creare elenchi per altri scopi. Concordare la finalità con il DPO e documentarla.
    • Chiave protetta: la subscription key è un segreto dell’ente. Deve essere conservata in variabili d’ambiente o file locali, mai in email o repository pubblici.
    • File sotto controllo: input, checkpoint e report contengono codici fiscali. Devono essere archiviati con le stesse misure di sicurezza dei dati anagrafici e cancellati quando non più necessari.
    • Esito come informazione di servizio: sapere che qualcuno non ha l’app o ha bloccato i messaggi serve a scegliere il canale più adeguato, non a classificare le persone.

Seguire queste regole garantisce conformità al GDPR e preserva la fiducia dei cittadini.

Conclusioni

Getprofiles fornisce ai comuni uno strumento pratico, robusto e trasparente per rispondere alla domanda cruciale: quanti cittadini hanno davvero App IO? Grazie a una gestione accurata dei codici fiscali, a un’interrogazione controllata dell’API di PagoPA e a un report chiaro, le amministrazioni possono valutare in anticipo l’efficacia del canale digitale, ottimizzare le proprie comunicazioni e risparmiare tempo e risorse.

L’approccio “una volta e per tutte” evita di lanciare servizi senza sapere se raggiungeranno il pubblico, riducendo il rischio di investimenti inutili e migliorando la qualità dell’interazione con i cittadini.