codice-fiscale-it

Calcolo, decodifica e verifica del codice fiscale italiano. Algoritmo ufficiale del DM 23/12/1976, archivio completo dei comuni (anche soppressi) e degli stati esteri, zero dipendenze, TypeScript.

Installazione

npm install codice-fiscale-it

Uso

import {
  calcolaDaComune,
  verificaCodiceFiscale,
  decodificaCodiceFiscale,
} from 'codice-fiscale-it';

// Calcolo dal nome del comune
calcolaDaComune({
  cognome: 'Rossi',
  nome: 'Mario',
  sesso: 'M',
  giorno: 1,
  mese: 1,
  anno: 1980,
  comune: 'Roma',
});
// => 'RSSMRA80A01H501U'

// Verifica formale (struttura + carattere di controllo)
verificaCodiceFiscale('RSSMRA80A01H501U'); // => true

// Decodifica: cosa dice il codice
decodificaCodiceFiscale('RSSMRA80A01H501U', 2026);
// => {
//   sesso: 'M', giorno: 1, mese: 1, annoStimato: 1980,
//   belfiore: 'H501', omocodia: false, controlloValido: true, ...
// }

Omocodia

Quando due persone genererebbero lo stesso codice, l'Agenzia delle Entrate sostituisce le cifre con lettere (0→L, 1→M, ... 9→V) partendo da destra. La libreria riconosce la sostituzione, ricostruisce il codice base e valida il carattere di controllo sul codice reale.

const d = decodificaCodiceFiscale('RSSMRA80A0MH501P', 2026);
d.omocodia;        // => true
d.giorno;          // => 1  (dal codice normalizzato)
d.controlloValido; // => true

Nati all'estero

Per chi è nato fuori dall'Italia si usa il codice dello stato, che inizia per Z. Basta passare il nome del paese:

calcolaDaComune({ /* ... */ comune: 'Francia' }); // usa Z110

Nomi con caratteri non italiani

Accenti, apostrofi e lettere latine estese vengono gestiti: Đ e Ð diventano D, Ł diventa L, Ø diventa O, ß diventa SS, Æ diventa AE. Senza queste sostituzioni quei caratteri verrebbero cancellati e il codice uscirebbe sbagliato.

calcolaDaComune({ cognome: 'Nikolic', nome: 'Đorđe', /* ... */ });
// il nome contribuisce con DRD, non con le sole lettere sopravvissute

Archivio comuni

import { cercaComune, comuneDaBelfiore, suggerisciComuni } from 'codice-fiscale-it';

cercaComune('Roma');            // => ['H501', 'RM', 'ROMA', 1]
cercaComune('forlì');           // accenti e apostrofi ignorati
cercaComune('Peschiera', 'VR'); // provincia per disambiguare gli omonimi
comuneDaBelfiore('F205');       // => ['F205', 'MI', 'MILANO', 1]
suggerisciComuni('PESCA', 5);   // per autocomplete

Ogni voce è [codice Belfiore, sigla provincia, nome, attivo], dove attivo vale 1 per i comuni esistenti e 0 per quelli soppressi (servono per chi è nato in un comune che oggi non esiste più).

API

| Funzione | Cosa fa | |---|---| | calcolaDaComune(input) | Codice fiscale dal nome del comune. null se il comune non esiste | | calcolaCodiceFiscale(input) | Come sopra, ma con il codice Belfiore già noto | | verificaCodiceFiscale(cf) | true se struttura e carattere di controllo sono corretti | | decodificaCodiceFiscale(cf, anno) | Estrae data, sesso, luogo; gestisce le omocodie | | carattereControllo(primi15) | Il sedicesimo carattere dai primi quindici | | cercaComune(nome, provincia?) | Voce dell'archivio per nome | | comuneDaBelfiore(codice) | Voce dell'archivio per codice catastale | | suggerisciComuni(prefisso, limite?) | Voci attive che iniziano per prefisso |

Note

• Il codice calcolato coincide con quello ufficiale tranne nei casi di omocodia, dove la variante la assegna solo l'Agenzia delle Entrate: fa fede la tessera sanitaria.
• Il secolo di nascita non è ricavabile con certezza dal codice (l'anno ha due cifre): annoStimato usa l'anno corrente come pivot.
• La verifica è formale: dice che il codice è ben formato, non che appartenga a una persona esistente.

Perché esiste

Nata dal motore di quantomispetta.it, calcolatori fiscali italiani che mostrano il procedimento passo per passo. Estratta come libreria a sé perché l'algoritmo serviva pulito, tipizzato e senza dipendenze.

Licenza

MIT