python-codicefiscale

python-codicefiscale is a library for encode/decode Italian fiscal code - codifica/decodifica del Codice Fiscale.

Features

• NEW REST API for web-based validation via FastAPI
• NEW JWT Token Generator for easy API testing with Clerk authentication
• NEW VAT Number (Partita IVA) validation and encoding
• NEW Auto-updated data (once a week) directly from ANPR data-source.
• NEW Command Line Interface available.
• Transliteration for name/surname
• Multiple birthdate formats (date/string) (you can see all the supported string formats here)
• Automatic birthplace city/foreign-country code detection from name
• Omocodia support

Installation

Basic Installation

pip install python-codicefiscale

With FastAPI Support (for REST API)

pip install 'python-codicefiscale[api]'

🚀 Quick Start for New Users

Development Setup (API Testing)

# 1. Clone and install
git clone https://github.com/fabiocaccamo/python-codicefiscale.git
cd python-codicefiscale
pip install uv && uv sync

# 2. Setup JWT token generation for API testing
cd frontend && npm install && npm run setup

# 3. Start API server and test
cd .. && uv run python -m codicefiscale.__main_api__ &
cd frontend && npm run test-api

The setup script will guide you through:

• ✅ Configuring Clerk authentication (or disabling it for simple testing)
• ✅ Generating JWT tokens for API access
• ✅ Testing all API endpoints

For complete setup instructions: See NEW_USER_SETUP.md

Usage

Python

Import

from codicefiscale import codicefiscale

Encode

codicefiscale.encode(
    lastname="Caccamo",
    firstname="Fabio",
    gender="M",
    birthdate="03/04/1985",
    birthplace="Torino",
)

# "CCCFBA85D03L219P"

Decode

codicefiscale.decode("CCCFBA85D03L219P")

# {
#     "code": "CCCFBA85D03L219P",
#     "gender": "M",
#     "birthdate": datetime.datetime(1985, 4, 3, 0, 0),
#     "birthplace": {
#         "name": "TORINO"
#         "province": "TO",
#         "code": "L219",
#     },
#     "omocodes": [
#         "CCCFBA85D03L219P",
#         "CCCFBA85D03L21VE",
#         "CCCFBA85D03L2MVP",
#         "CCCFBA85D03LNMVE",
#         "CCCFBA85D0PLNMVA",
#         "CCCFBA85DLPLNMVL",
#         "CCCFBA8RDLPLNMVX",
#         "CCCFBAURDLPLNMVU",
#     ],
#     "raw": {
#         "code": "CCCFBA85D03L219P",
#         "lastname": "CCC",
#         "firstname": "FBA",
#         "birthdate": "85D03",
#         "birthdate_year": "85"
#         "birthdate_month": "D",
#         "birthdate_day": "03",
#         "birthplace": "L219",
#         "cin": "P",
#     },
# }

Check

codicefiscale.is_valid("CCCFBA85D03L219P")

# True

codicefiscale.is_omocode("CCCFBA85D03L219P")

# False

VAT Number (Partita IVA) Support

from codicefiscale.codicefiscale import partitaiva

# Validate a VAT number
partitaiva.is_valid("01234567890")
# True

# Generate VAT number from base 10 digits
partitaiva.encode("0123456789")
# "01234567890"

# Decode VAT number
partitaiva.decode("01234567890")
# {
#     "code": "01234567890",
#     "valid": True,
#     "base_number": "0123456789",
#     "check_digit": "0",
#     "calculated_check_digit": "0",
# }

REST API

Start the FastAPI validation server:

python -m codicefiscale.__main_api__

The API will be available at http://localhost:8000 with automatic documentation at http://localhost:8000/docs.

Authentication

The API supports optional Clerk authentication. To enable authentication:

1. Set up a Clerk account and create an application
2. Set the environment variable:

   export CLERK_PUBLISHABLE_KEY="pk_test_..."

3. Include the Bearer token in API requests:

   curl -H "Authorization: Bearer <your-clerk-jwt-token>" ...

Note: If CLERK_PUBLISHABLE_KEY is not set, the API runs without authentication (public access).

API Endpoints

Fiscal Code Validation:

# Without authentication (if disabled)
curl -X POST "http://localhost:8000/fiscal-code/validate" \
     -H "Content-Type: application/json" \
     -d '{"code": "CCCFBA85D03L219P"}'

# With Clerk authentication (if enabled)
curl -X POST "http://localhost:8000/fiscal-code/validate" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-clerk-jwt-token>" \
     -d '{"code": "CCCFBA85D03L219P"}'

VAT Number Validation:

curl -X POST "http://localhost:8000/vat/validate" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-clerk-jwt-token>" \
     -d '{"partita_iva": "01234567890"}'

Fiscal Code Generation:

curl -X POST "http://localhost:8000/fiscal-code/encode" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-clerk-jwt-token>" \
     -d '{
       "lastname": "Caccamo",
       "firstname": "Fabio", 
       "gender": "M",
       "birthdate": "03/04/1985",
       "birthplace": "Torino"
     }'

Command Line

This library can be used also as a CLI tool, for more info run:

python -m codicefiscale --help

Encode (CLI)

python -m codicefiscale encode --firstname Fabio --lastname Caccamo --gender M --birthdate 03/04/1985 --birthplace Torino

Decode (CLI)

python -m codicefiscale decode CCCFBA85D03L219P

Testing

# clone repository
git clone https://github.com/fabiocaccamo/python-codicefiscale.git && cd python-codicefiscale

# create virtualenv and activate it
python -m venv venv && . venv/bin/activate

# upgrade pip
python -m pip install --upgrade pip

# install requirements
pip install -r requirements.txt -r requirements-test.txt

# install pre-commit to run formatters and linters
pre-commit install --install-hooks

# run tests using tox
tox

# or run tests using pytest
pytest

License

Released under MIT License.

---

Supporting

• ⭐ Star this project on GitHub
• Follow me on GitHub
• 💙 Follow me on Bluesky
• 💰 Sponsor me on Github

See also

• python-benedict - dict subclass with keylist/keypath support, I/O shortcuts (base64, csv, json, pickle, plist, query-string, toml, xml, yaml) and many utilities. 📘

• python-fontbro - friendly font operations. 🧢

• python-fsutil - file-system utilities for lazy devs. 🧟‍♂️ ✅ Project cleaned up and all branches merged