Documentazione

Autenticazione

LM API usa un header X-Api-Key per l'autenticazione. I dati base (comuni, province, valute) sono accessibili senza chiave. I dati avanzati (CCNL, geocoding, validazione email) richiedono un piano.

Ottenere una API key

POST

curl -X POST https://api.lorenzomalferrari.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "tuaemail@esempio.com", "name": "Nome Cognome"}'

# Risposta
{
  "data": {
    "key": "lmapi_aBcDeFgH...",
    "plan": "free",
    "name": "Nome Cognome"
  }
}

Usare la API key

curl -H "X-Api-Key: lmapi_la-tua-key" \
     https://api.lorenzomalferrari.com/api/v1/it/ccnl

La API key deve essere passata solo tramite header. Inserirla nella query string (?api_key=...) restituisce un errore 400.

Base URL

Tutte le richieste usano il prefisso:

https://api.lorenzomalferrari.com/api/v1

Il versionamento è nel path. La versione v1 è stabile e non avrà breaking changes. Nuove versioni future useranno v2, ecc.

Rate Limit

Ogni richiesta include header informativi sul rate limit:

Header	Descrizione
`X-RateLimit-Limit`	Limite richieste al minuto
`X-RateLimit-Remaining`	Richieste rimanenti
`X-RateLimit-Reset`	Secondi prima del reset

Piano	Limite
Senza key	60 req/min
Free	30 req/min
Pro	120 req/min
Max	240 req/min

Superato il limite, la risposta è 429 Too Many Requests.

Paginazione

Gli endpoint che restituiscono molti risultati sono paginati. Usa i parametri ?page= e ?per_page= (default 50, max 100).

GET /api/v1/it/abi-cab?province=MI&page=2&per_page=20

# Risposta
{
  "data": [...],
  "current_page": 2,
  "last_page": 42,
  "per_page": 20,
  "total": 838
}

Ricerca

Molti endpoint supportano il parametro ?q= per la ricerca testuale (minimo 2 caratteri). La ricerca è case-insensitive.

GET /api/v1/it/abi-cab?q=intesa&province=MI
GET /api/v1/it/ateco?q=software
GET /api/v1/search?q=Milano  # ricerca unificata su tutti i dataset

Cache e ETag

Le risposte includono header ETag e Cache-Control. Per evitare richieste inutili, invia l'header If-None-Match con il valore dell'ETag precedente.

# Prima richiesta
curl -v https://api.lorenzomalferrari.com/api/v1/continents
# Response header: ETag: "abc123"

# Richieste successive
curl -H "If-None-Match: \"abc123\"" https://api.lorenzomalferrari.com/api/v1/continents
# Response: 304 Not Modified (nessun body, risparmio banda)

Gestione errori

Tutti gli errori restituiscono un oggetto JSON con campi error e code:

{
  "error": "API key non valida o disattivata.",
  "code": "INVALID_API_KEY"
}

HTTP	Codice	Significato
400	`KEY_IN_URL_FORBIDDEN`	API key passata in query string
401	`API_KEY_REQUIRED`	Endpoint richiede autenticazione
401	`INVALID_API_KEY`	Chiave non valida o disattivata
403	`FEATURE_NOT_AVAILABLE`	Funzionalità non nel piano
403	`IP_NOT_ALLOWED`	IP non in whitelist
404	—	Risorsa non trovata
422	—	Parametri mancanti o non validi
429	`RATE_LIMIT_EXCEEDED`	Troppe richieste
429	`MONTHLY_LIMIT_EXCEEDED`	Quota mensile esaurita
429	`IP_BLOCKED`	IP bloccato per tentativi falliti

Esempi pratici

Autocomplete comuni

GET

curl "https://api.lorenzomalferrari.com/api/v1/it/municipalities/autocomplete?q=Milano"

{
  "data": [{
    "name": "Milano",
    "cadastral_code": "F205",
    "province": { "code": "MI", "name": "Milano" },
    "zips": [{ "zip": "20121" }]
  }]
}

Validazione Codice Fiscale

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/validate/fiscal-code" \
  -H "Content-Type: application/json" \
  -d '{"code": "RSSMRA85T10A944Q"}'

{
  "data": {
    "valid": true,
    "type": "codice_fiscale",
    "normalized": "RSSMRA85T10A944Q"
  }
}

Conversione valuta

GET

curl "https://api.lorenzomalferrari.com/api/v1/exchange-rates/convert?from=EUR&to=USD&amount=100"

{
  "data": {
    "from": "EUR",
    "to": "USD",
    "amount": 100,
    "converted": 116.94,
    "rate_used": 1.1694,
    "source": "BCE"
  }
}

Reverse geocoding

GET

curl "https://api.lorenzomalferrari.com/api/v1/it/municipalities/reverse?lat=41.90&lng=12.49"

{
  "data": {
    "name": "Roma",
    "cadastral_code": "H501",
    "distance_km": 2.89,
    "province": { "code": "RM" }
  }
}

Calcolatori

Gli endpoint di calcolo accettano dati fiscali/finanziari in input e restituiscono risultati elaborati secondo la normativa italiana vigente. Tutti gratuiti, nessun piano richiesto.

Calcolo IRPEF

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/calculate/irpef" \
  -H "Content-Type: application/json" \
  -d '{"gross_income": 35000, "year": 2024}'

{
  "data": {
    "gross_income": 35000,
    "irpef": 7490,
    "net_income": 27510,
    "effective_rate": 21.4,
    "brackets": [
      { "up_to": 28000, "rate": 23, "tax": 6440 },
      { "up_to": 35000, "rate": 35, "tax": 2450 }
    ]
  }
}

Busta paga netta da RAL

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/calculate/payslip" \
  -H "Content-Type: application/json" \
  -d '{"ral": 28000, "contract_type": "indeterminato", "ccnl_code": "CCNL-COMM"}'

{
  "data": {
    "ral": 28000,
    "monthly_gross": 2153.85,
    "inps_employee": 194.58,
    "irpef_monthly": 398.42,
    "net_monthly": 1560.85,
    "net_annual": 20291.05
  }
}

Rata mutuo ammortamento francese

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/calculate/mortgage" \
  -H "Content-Type: application/json" \
  -d '{"amount": 200000, "rate": 3.5, "years": 25}'

{
  "data": {
    "amount": 200000,
    "rate_annual": 3.5,
    "years": 25,
    "installment": 1000.62,
    "total_paid": 300186,
    "total_interest": 100186
  }
}

Calcolatori fiscali

Calcolatori specifici per tributi immobiliari e locazione, basati sulla normativa italiana vigente. Tutti gratuiti, nessun piano richiesto.

Calcolo IMU

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/calculate/imu" \
  -H "Content-Type: application/json" \
  -d '{
    "rendita_catastale": 800,
    "category": "A/2",
    "municipality_code": "F205",
    "is_main_residence": false
  }'

{
  "data": {
    "rendita_catastale": 800,
    "coefficient": 160,
    "cadastral_value": 128000,
    "aliquota": 0.86,
    "imu_annual": 1100.8,
    "imu_first_rate": 550.4,
    "imu_second_rate": 550.4,
    "is_main_residence": false
  }
}

Cedolare secca

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/calculate/cedolare-secca" \
  -H "Content-Type: application/json" \
  -d '{
    "canone_annuo": 9600,
    "regime": "ordinario"
  }'

{
  "data": {
    "canone_annuo": 9600,
    "aliquota": 21,
    "imposta": 2016,
    "netto_percepito": 7584,
    "acconto_giugno": 1612.8,
    "acconto_novembre": 403.2,
    "saldo_giugno_successivo": 0
  }
}

Calcolatori HR

Calcolatori per la gestione del personale: malattia, maternità, ferie, preavviso. Basati sulle tabelle INPS e CCNL aggiornate.

Indennità malattia INPS

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/calculate/malattia" \
  -H "Content-Type: application/json" \
  -d '{
    "retribuzione_giornaliera": 65.00,
    "giorni_malattia": 10,
    "tipo_lavoratore": "operaio"
  }'

{
  "data": {
    "giorni_malattia": 10,
    "giorni_carenza": 3,
    "giorni_indennizzati": 7,
    "percentuale_inps": 50,
    "indennita_giornaliera": 32.5,
    "totale_indennita": 227.5,
    "note": "Dal 4° al 20° giorno: 50% retribuzione"
  }
}

Decodifica

Gli endpoint di decodifica estraggono informazioni strutturate da codici opachi (codice fiscale, IBAN) e arricchiscono i dati con lookup su banche dati pubbliche.

Decodifica Codice Fiscale

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/it/fiscal-code/decode" \
  -H "Content-Type: application/json" \
  -d '{"code": "RSSMRA85T10A944Q"}'

{
  "data": {
    "surname_code": "RSS",
    "name_code": "MRA",
    "birth_year": 1985,
    "birth_month": "dicembre",
    "birth_day": 10,
    "gender": "M",
    "birth_municipality": {
      "cadastral_code": "A944",
      "name": "Bari",
      "province": "BA"
    },
    "check_digit": "Q",
    "valid": true
  }
}

Decodifica IBAN con lookup banca

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/decode/iban" \
  -H "Content-Type: application/json" \
  -d '{"iban": "IT60X0542811101000000123456"}'

{
  "data": {
    "iban": "IT60X0542811101000000123456",
    "valid": true,
    "country": "IT",
    "check_digits": "60",
    "abi": "05428",
    "cab": "11101",
    "account": "000000123456",
    "bank": {
      "name": "Intesa Sanpaolo S.p.A.",
      "city": "Milano"
    }
  }
}

Developer Tools

Strumenti di utilità per sviluppatori: generatori, hash, conversioni di formato. Tutti gratuiti e senza autenticazione.

Generazione hash

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/generate/hash" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "testo da hashare",
    "algorithms": ["md5", "sha256"]
  }'

{
  "data": {
    "input": "testo da hashare",
    "md5": "c4ca4238a0b923820dcc509a6f75849b",
    "sha256": "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069"
  }
}

Conversione colore

POST

curl -X POST "https://api.lorenzomalferrari.com/api/v1/convert/color" \
  -H "Content-Type: application/json" \
  -d '{"input": "#C8902A", "from": "hex"}'

{
  "data": {
    "hex": "#C8902A",
    "rgb": { "r": 200, "g": 144, "b": 42 },
    "hsl": { "h": 37, "s": 65, "l": 47 },
    "css_rgb": "rgb(200, 144, 42)",
    "css_hsl": "hsl(37, 65%, 47%)"
  }
}

SDK PHP

SDK ufficiale per PHP 8.1+ con Guzzle:

// Installazione
composer require lm-it/lm-api-client

// Utilizzo
use LmApi\LmApiClient;

$api = new LmApiClient('la-tua-api-key');

// Autocomplete comuni
$comuni = $api->municipalitiesAutocomplete('Milano');

// Validazione IBAN
$result = $api->validateIban('IT60X0542811101000000123456');

// Conversione valuta
$conversion = $api->convert('EUR', 'USD', 100);

// Aliquote IVA
$iva22 = $api->vatRates(22);

// Reverse geocoding
$comune = $api->reverseGeocode(41.90, 12.49);

Webhook

Registra webhook per ricevere notifiche quando i dati vengono aggiornati. Ogni notifica include una firma HMAC-SHA256 nell'header X-LmApi-Signature.

Eventi disponibili

Evento	Quando
`sync.completed`	Un sync automatico ha aggiornato i dati
`data.changed`	Dati specifici sono cambiati

Verifica firma

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_LMAPI_SIGNATURE'];
$expected = 'sha256=' . hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Firma valida — processa l'evento
}

Documentazione

Indice

Autenticazione

Ottenere una API key

Usare la API key

Base URL

Rate Limit

Paginazione

Ricerca

Cache e ETag

Gestione errori

Esempi pratici

Autocomplete comuni

Validazione Codice Fiscale

Conversione valuta

Reverse geocoding

Calcolatori

Calcolo IRPEF

Busta paga netta da RAL

Rata mutuo ammortamento francese

Calcolatori fiscali

Calcolo IMU

Cedolare secca

Calcolatori HR

Indennità malattia INPS

Decodifica

Decodifica Codice Fiscale

Decodifica IBAN con lookup banca

Developer Tools

Generazione hash

Conversione colore

SDK PHP

Webhook

Eventi disponibili

Verifica firma