Il codice fiscale è una stringa di sedici caratteri che quasi tutti scriviamo a memoria, ma che pochi sanno davvero leggere. Dietro c’è un algoritmo preciso, definito da un decreto ministeriale degli anni Settanta, una tabella di comuni che cambia nel tempo e un meccanismo poco conosciuto per gestire i casi in cui due persone avrebbero lo stesso codice: l’omocodia. In questo articolo provo a smontarlo pezzo per pezzo.
La struttura in sedici caratteri
Un codice fiscale delle persone fisiche è composto così:
- 3 lettere per il cognome
- 3 lettere per il nome
- 2 cifre per l’anno di nascita
- 1 lettera per il mese di nascita
- 2 cifre per il giorno di nascita e il sesso
- 4 caratteri per il comune (o lo stato estero) di nascita
- 1 lettera di controllo
Cognome
Si prendono le prime tre consonanti del cognome, nell’ordine in cui compaiono. Se le consonanti non bastano si aggiungono le vocali, sempre nell’ordine. Se il cognome è più corto di tre lettere si completa con una X. Spazi, apostrofi e accenti si ignorano.
Nome
Il nome segue quasi la stessa regola, con un’eccezione importante: se il nome ha quattro o più consonanti, si prendono la prima, la terza e la quarta. Altrimenti si procede come per il cognome: consonanti, poi vocali, poi X.
Anno, mese, giorno e sesso
L’anno è rappresentato dalle sue ultime due cifre. Il mese è codificato con una lettera:
| Mese | Lettera | Mese | Lettera |
|---|---|---|---|
| Gennaio | A | Luglio | L |
| Febbraio | B | Agosto | M |
| Marzo | C | Settembre | P |
| Aprile | D | Ottobre | R |
| Maggio | E | Novembre | S |
| Giugno | H | Dicembre | T |
Il giorno di nascita è scritto su due cifre. Per le donne si aggiunge 40: una donna nata il 5 avrà quindi 45. È così che il codice fiscale codifica anche il sesso.
Il codice del comune
I quattro caratteri successivi sono il codice catastale (detto anche codice Belfiore) del comune di nascita: una lettera seguita da tre cifre. Per chi è nato all’estero si usa invece il codice dello stato, che inizia sempre con la lettera Z.
Qui sta la parte più delicata: i comuni cambiano. Vengono istituiti, fusi, soppressi. Un validatore serio deve quindi conoscere anche i comuni non più esistenti e, idealmente, il periodo in cui ciascun codice era valido.
Il carattere di controllo
L’ultimo carattere serve a intercettare gli errori di battitura. Si calcola così:
- Si considerano i primi quindici caratteri.
- A ciascun carattere in posizione dispari (1ª, 3ª, 5ª…) si associa un valore preso da una tabella apposita. A quelli in posizione pari si associa un valore più semplice: le cifre valgono se stesse e le lettere valgono da A=0 a Z=25.
- Si sommano tutti i valori.
- Si divide per 26: il resto, da 0 a 25, si converte in lettera (0=A, 1=B, … 25=Z).
La tabella dei valori dispari è:
| Carattere | Valore | Carattere | Valore |
|---|---|---|---|
| 0 / A | 1 | I / 8 | 19 |
| 1 / B | 0 | J / 9 | 21 |
| 2 / C | 5 | K | 2 |
| 3 / D | 7 | L | 4 |
| 4 / E | 9 | M | 18 |
| 5 / F | 13 | N | 20 |
| 6 / G | 15 | O | 11 |
| 7 / H | 17 | P | 3 |
| Q | 6 | R | 8 |
| S | 12 | T | 14 |
| U | 16 | V | 10 |
| W | 22 | X | 25 |
| Y | 24 | Z | 23 |
L’omocodia
Due persone diverse possono avere gli stessi dati di partenza, e quindi lo stesso codice. In questo caso si parla di omocodia. Chi aveva già il codice lo tiene; al nuovo arrivato l’anagrafe tributaria assegna una variante.
La variante si ottiene sostituendo una cifra con una lettera, secondo questa corrispondenza:
| Cifra | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|---|---|---|---|---|---|---|---|---|---|
| Lettera | L | M | N | P | Q | R | S | T | U | V |
Le posizioni numeriche sono sette (anno, giorno, codice del comune). La sostituzione parte da destra: prima si sostituisce l’ultima cifra del codice del comune, poi, se serve ancora, anche quella precedente, e così via. Dopo ogni sostituzione si ricalcola il carattere di controllo.
In teoria le combinazioni possibili sono 127, e un buon validatore le riconosce tutte. Nella pratica le varianti assegnate seguono l’ordine progressivo da destra.
Valido non vuol dire esistente
Un codice può essere perfettamente corretto dal punto di vista algoritmico e non essere intestato a nessuno. Per verificarne l’esistenza l’Agenzia delle Entrate offre un servizio online gratuito di verifica del codice fiscale, che controlla anche la corrispondenza con i dati anagrafici. È pensato per controlli singoli, non per l’uso automatico.
Tenere aggiornati i dati dei comuni
Per scrivere un validatore serio la parte difficile non è l’algoritmo, ma la tabella dei comuni. Il riferimento open source più completo che conosco è python-codicefiscale di Fabio Caccamo, una libreria Python con licenza MIT che codifica, decodifica e valida il codice fiscale, gestisce l’omocodia e si usa anche da riga di comando.
from codicefiscale import codicefiscale
codicefiscale.is_valid("CCCFBA85D03L219P") # True
codicefiscale.is_omocode("CCCFBA85D03L219P") # False
codicefiscale.decode("CCCFBA85D03L219P") # dati anagrafici + elenco omocodici
Il suo punto di forza sono proprio i dati: una pipeline automatica li aggiorna ogni settimana prendendoli direttamente dall’archivio di ANPR. È anche il motivo per cui l’ho studiata a fondo, e da lì sono partito per questo articolo.
Ha però due limiti. È disponibile solo in Python, e chi lavora in PHP o JavaScript deve arrangiarsi. Inoltre, se la si usa come dipendenza, i dati arrivano da un progetto di terzi: oggi è mantenuto benissimo, ma domani l’autore potrebbe smettere di aggiornarlo o archiviarlo. La soluzione è replicare la stessa idea in proprio: andare alle fonti ufficiali e generare un file locale, con uno script che si rilancia periodicamente.
Le fonti ufficiali
- Archivio storico dei comuni di ANPR: un file CSV con codice catastale, denominazione, sigla della provincia e date di istituzione e cessazione di ogni comune, compresi quelli soppressi o fusi.
- Elenco dei Paesi esteri di ISTAT: contiene i codici che iniziano con Z, usati per chi è nato all’estero.
Il formato del file locale
Un JSON indicizzato per codice catastale, con un elenco di periodi di validità. È compatto, si carica in un attimo e permette di verificare che il comune esistesse alla data di nascita:
{
"L219": [
{ "nome": "TORINO", "provincia": "TO", "dal": "1861-03-17", "al": null }
]
}
Gli script che seguono fanno tutti la stessa cosa: scaricano il CSV, costruiscono il JSON, controllano che il risultato sia plausibile e solo allora sostituiscono il file esistente. Così un download andato male non cancella mai dati buoni.
Python
#!/usr/bin/env python3
"""Scarica l'archivio comuni ANPR e genera comuni.json."""
import csv, io, json, os, urllib.request
URL = "https://www.anagrafenazionale.interno.it/wp-content/uploads/ANPR_archivio_comuni.csv"
APERTO = {"", "9999-12-31"}
with urllib.request.urlopen(URL, timeout=60) as r:
testo = r.read().decode("utf-8-sig")
comuni = {}
for riga in csv.DictReader(io.StringIO(testo)):
al = riga["DATACESSAZIONE"].strip()
comuni.setdefault(riga["CODCATASTALE"].strip(), []).append({
"nome": riga["DENOMINAZIONE_IT"].strip(),
"provincia": riga["SIGLAPROVINCIA"].strip(),
"dal": riga["DATAISTITUZIONE"].strip(),
"al": None if al in APERTO else al,
})
if len(comuni) < 7000:
raise SystemExit("Dati sospetti: comuni.json non aggiornato")
with open("comuni.tmp.json", "w", encoding="utf-8") as f:
json.dump(comuni, f, ensure_ascii=False, separators=(",", ":"))
os.replace("comuni.tmp.json", "comuni.json")
PHP
<?php
const URL = 'https://www.anagrafenazionale.interno.it/wp-content/uploads/ANPR_archivio_comuni.csv';
$fh = fopen(URL, 'r') or exit("Download fallito\n");
$header = array_map('trim', fgetcsv($fh, null, ',', '"', ''));
$header[0] = preg_replace('/^\xEF\xBB\xBF/', '', $header[0]);
$comuni = [];
while (($row = fgetcsv($fh, null, ',', '"', '')) !== false) {
if (count($row) !== count($header)) continue;
$r = array_map('trim', array_combine($header, $row));
$al = $r['DATACESSAZIONE'];
$comuni[$r['CODCATASTALE']][] = [
'nome' => $r['DENOMINAZIONE_IT'],
'provincia' => $r['SIGLAPROVINCIA'],
'dal' => $r['DATAISTITUZIONE'],
'al' => in_array($al, ['', '9999-12-31'], true) ? null : $al,
];
}
fclose($fh);
if (count($comuni) < 7000) exit("Dati sospetti: comuni.json non aggiornato\n");
file_put_contents('comuni.tmp.json', json_encode($comuni, JSON_UNESCAPED_UNICODE));
rename('comuni.tmp.json', 'comuni.json');
JavaScript (Node.js, senza dipendenze)
// aggiorna-comuni.mjs — richiede Node 18+ per fetch
import { writeFile, rename } from 'node:fs/promises';
const URL = 'https://www.anagrafenazionale.interno.it/wp-content/uploads/ANPR_archivio_comuni.csv';
function parseCsv(text, sep = ',') {
const rows = [];
let row = [], field = '', inQuotes = false;
for (let i = 0; i < text.length; i++) {
const c = text[i];
if (inQuotes) {
if (c === '"' && text[i + 1] === '"') { field += '"'; i++; }
else if (c === '"') inQuotes = false;
else field += c;
} else if (c === '"') inQuotes = true;
else if (c === sep) { row.push(field); field = ''; }
else if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; }
else if (c !== '\r') field += c;
}
if (field || row.length) { row.push(field); rows.push(row); }
return rows;
}
const res = await fetch(URL);
if (!res.ok) throw new Error(`Download fallito: ${res.status}`);
const [header, ...righe] = parseCsv((await res.text()).replace(/^\uFEFF/, ''));
const col = Object.fromEntries(header.map((h, i) => [h.trim(), i]));
const comuni = {};
for (const r of righe) {
if (r.length !== header.length) continue;
const v = (k) => r[col[k]].trim();
const al = v('DATACESSAZIONE');
(comuni[v('CODCATASTALE')] ??= []).push({
nome: v('DENOMINAZIONE_IT'),
provincia: v('SIGLAPROVINCIA'),
dal: v('DATAISTITUZIONE'),
al: ['', '9999-12-31'].includes(al) ? null : al,
});
}
if (Object.keys(comuni).length < 7000) throw new Error('Dati sospetti: comuni.json non aggiornato');
await writeFile('comuni.tmp.json', JSON.stringify(comuni));
await rename('comuni.tmp.json', 'comuni.json');
Usare il file per validare
Con le date in formato ISO il confronto si fa direttamente fra stringhe. In JavaScript, lato browser o server:
function comuneValido(comuni, codice, nascita) { // nascita: 'AAAA-MM-GG'
return (comuni[codice] ?? []).some(
(p) => p.dal <= nascita && (p.al === null || nascita <= p.al)
);
}
Ricordatevi di decodificare prima l’omocodia: se il codice del comune contiene lettere, vanno riconvertite in cifre con la tabella vista sopra.
Stati esteri
Per i Paesi esteri vale lo stesso schema: si scarica l’elenco ISTAT e si genera un secondo JSON, oppure si aggiungono i codici Z allo stesso file, con la sigla della provincia vuota.
Aggiornamento automatico
Basta una riga di cron, per esempio il primo del mese alle 4 di notte:
0 4 1 * * cd /opt/codicefiscale && /usr/bin/python3 aggiorna_comuni.py
In alternativa, se il progetto sta su GitHub, una Action schedulata può rigenerare il JSON e committarlo, che è esattamente quello che fa python-codicefiscale.
Nota per la revisione: prima di pubblicare, verificare l’indirizzo attuale del CSV sul sito ANPR, il separatore e i nomi esatti delle colonne, e completare lo script per gli stati esteri con le colonne del file ISTAT.
Un generatore sul sito
Da sviluppare: generatore con le varianti omocodiche nell’ordine ufficiale, con l’avvertenza che il codice valido è solo quello rilasciato dall’Agenzia delle Entrate e che le varianti mostrate sono teoriche.
Fonti
Da completare: decreto ministeriale istitutivo, specifiche dell’Agenzia delle Entrate, archivio comuni ANPR, libreria python-codicefiscale di riferimento.