API Codice Fiscale Inverso: Decodifica e Validazione via REST

Cosa restituisce l'API

Una singola chiamata GET a un codice fiscale restituisce tutte le informazioni che lo stesso codice contiene, già strutturate in JSON.

Esempio di Chiamata e Risposta

Request:

GET https://api.codicefiscaleinverso.it/v1/decode/RSSMRA85M01H501Z

Response (200 OK):

{
  "cf": "RSSMRA85M01H501Z",
  "valid": true,
  "surname_consonants": "RSS",
  "name_consonants": "MRA",
  "birth_date": "1985-08-01",
  "birth_day": 1,
  "birth_month": 8,
  "birth_year": 1985,
  "gender": "M",
  "birth_place": {
    "type": "comune",
    "code": "H501",
    "name": "Roma",
    "province": "RM",
    "country": "IT"
  },
  "omocodia": false,
  "omocodia_level": 0,
  "cin_valid": true,
  "cin_char": "Z"
}

Per un codice fiscale appartenente a qualcuno nato all'estero, il campo birth_place cambia struttura:

"birth_place": {
  "type": "estero",
  "code": "Z112",
  "country_name": "Germania",
  "country_iso": "DE"
}

Tutte le risposte usano UTF-8. Date in formato ISO 8601 (YYYY-MM-DD). I nomi di comuni e paesi sono in italiano, coerenti con la nomenclatura ufficiale dell'Agenzia delle Entrate.

Endpoint Disponibili

GET /v1/decode/{cf}

Decodifica un singolo codice fiscale. Restituisce tutti i campi descritti sopra.

Codici di risposta:

GET /v1/validate/{cf}

Validazione del solo carattere di controllo (CIN) senza restituire il payload completo. Risposta più leggera, utile per controlli inline nei form.

{
  "cf": "RSSMRA85M01H501Z",
  "cin_valid": true,
  "cin_expected": "Z",
  "cin_found": "Z"
}

Questo endpoint è quello consigliato per la validazione real-time nei campi di inserimento, dove la velocità conta più del dettaglio. Per la documentazione tecnica completa del calcolo CIN, vedi come funziona il carattere di controllo del codice fiscale.

POST /v1/decode/batch

Decodifica di più codici fiscali in una singola richiesta. Accetta un array JSON nel body.

Request body:

{
  "items": [
    "RSSMRA85M01H501Z",
    "BNCGPP92T10F205V",
    "VRDLGU78A15L219S"
  ]
}

Response:

{
  "results": [
    { "cf": "RSSMRA85M01H501Z", "valid": true, ... },
    { "cf": "BNCGPP92T10F205V", "valid": true, ... },
    { "cf": "VRDLGU78A15L219S", "valid": false, "error": "cin_mismatch" }
  ],
  "total": 3,
  "valid_count": 2,
  "error_count": 1
}

Il limite per il piano gratuito è 50 codici per chiamata. Per volumi superiori, vedi la sezione piani.

Piani e Limiti

Il piano Free non richiede registrazione. Le chiamate vengono conteggiate per IP. Per attivare Standard o Pro, scrivi a api@codicefiscaleinverso.it con una descrizione del progetto.

Gestione degli errori

Struttura dell'Errore

Ogni risposta con codice HTTP 4xx include un oggetto error nel body:

{
  "error": {
    "code": "invalid_length",
    "message": "Il codice fiscale deve essere di 16 caratteri.",
    "cf_received": "RSSMRA85M01H501"
  }
}

Codici di errore

I codici cin_mismatch, unknown_belfiore e unknown_z_code restituiscono HTTP 200 perché la decodifica parziale viene comunque eseguita: il campo valid sarà false con la causa specificata in validation_errors.

Omocodia: Come l'API la Gestisce

Un codice fiscale omocodico ha lettere al posto di cifre in posizioni specifiche (anno, giorno, o le quattro posizioni del Belfiore). L'API gestisce l'omocodia in modo trasparente.

Se il codice in input è omocodico, la risposta include:

"omocodia": true,
"omocodia_level": 1,
"omocodia_positions": [7, 8],
"decoded_base_cf": "RSSMRA85M01H501Z"

Il campo omocodia_level indica il livello di sostituzione (1 = una cifra sostituita, fino a 7 = tutte le cifre sostituibili sono state sostituite). Il campo decoded_base_cf restituisce il codice con le cifre originali ripristinate, utile per confronti con database che non gestiscono l'omocodia.

Per la spiegazione completa del meccanismo, vedi l'algoritmo del codice fiscale DM 1974.

Codice di esempio per l'Integrazione

JavaScript / Fetch

async function decodeCF(cf) {
  const res = await fetch(
    `https://api.codicefiscaleinverso.it/v1/decode/${cf}`
  );
  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error.message);
  }
  return res.json();
}

// Utilizzo
decodeCF('RSSMRA85M01H501Z').then(data => {
  console.log(data.birth_date);       // "1985-08-01"
  console.log(data.gender);           // "M"
  console.log(data.birth_place.name); // "Roma"
});

Python / requests

import requests

def decode_cf(cf: str) -> dict:
    url = f"https://api.codicefiscaleinverso.it/v1/decode/{cf}"
    response = requests.get(url)
    response.raise_for_status()
    return response.json()

result = decode_cf("RSSMRA85M01H501Z")
print(result["birth_date"])           # 1985-08-01
print(result["birth_place"]["name"])  # Roma

PHP / cURL

function decodeCF(string $cf): array {
    $url = "https://api.codicefiscaleinverso.it/v1/decode/" . urlencode($cf);
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new RuntimeException("API error: HTTP $status");
    }
    return json_decode($body, true);
}

$data = decodeCF("RSSMRA85M01H501Z");
echo $data["birth_date"];          // 1985-08-01
echo $data["birth_place"]["name"]; // Roma

Casi d'Uso Comuni

Validazione Real-Time nei Form di Registrazione

Il caso d'uso più diffuso. Durante la registrazione, non appena l'utente finisce di digitare il codice fiscale, una chiamata a /v1/validate/{cf} verifica il carattere di controllo in meno di 100 ms. Se il CIN è sbagliato, il campo si colora di rosso prima che l'utente clicchi su "Invia".

Questo elimina uno dei motivi più frequenti di abbandono nei form italiani: l'utente invia, il server rifiuta, l'utente non capisce perché. Il feedback immediato riduce l'errore prima che diventi un ticket di supporto.

Pre-compilazione e Arricchimento Anagrafico

Chi raccoglie il codice fiscale in fase di onboarding può usare /v1/decode/{cf} per pre-popolare automaticamente i campi data di nascita, sesso e comune di nascita. L'utente vede i dati comparire e li conferma invece di digitarli da zero: meno attrito, meno errori di trascrizione.

Audit di database esistenti

Piattaforme con archivi di codici fiscali accumulati negli anni — e-commerce, software gestionali, portali associativi — usano l'endpoint batch per identificare i codici non validi prima che causino problemi in dichiarazioni o fatture. Per archivi molto grandi, l'endpoint batch da 50 CF per chiamata copre 50.000 codici in 1.000 chiamate, gestibili in background.

Integrazione in Flussi di Fatturazione Elettronica

Prima di trasmettere una fattura al Sistema di Interscambio, una chiamata a /v1/validate/{cf} verifica che il codice fiscale del destinatario abbia un CIN valido. Un codice con CIN errato causa il rifiuto della fattura da parte del SdI: meglio intercettarlo prima della trasmissione.

CORS e Chiamate da Browser

L'API supporta CORS per tutte le origini nel piano Free (header Access-Control-Allow-Origin con valore *). Questo significa che puoi chiamare l'endpoint direttamente da JavaScript nel browser senza un proxy server.

Per il piano Standard e Pro, le origini ammesse si configurano nel pannello di controllo, utile per ambienti di produzione dove si vuole evitare che la chiave API sia esposta nel codice frontend.

SLA e Disponibilità

Il database dei comuni italiani include i codici storici dei comuni soppressi, necessari per decodificare correttamente i codici fiscali di persone nate in comuni che non esistono più. Il database dei codici Z include tutti i paesi riconosciuti dall'Italia, compresi quelli storici come Jugoslavia e URSS.

Domande Frequenti