Documentazione API verifica targa: endpoint, campi JSON ed errori
Guida tecnica all'API REST di Evita-Multe per verificare veicoli immatricolati in Italia partendo dalla targa: copertura RC auto, storico revisioni con chilometri, bollo e dati tecnici. Qui trovi autenticazione, formato delle risposte, codici di errore e esempi pronti da copiare.
Panoramica
L'API restituisce dati letti in tempo reale da fonti pubbliche ufficiali (Portale dell'Automobilista, Motorizzazione Civile, ACI), con una cache breve per ridurre i tempi di risposta. Ogni modulo si chiama separatamente, oppure tutti insieme con /v1/completo.
https://api.evita-multe.it/v1I dati riguardano il veicolo: l'API non restituisce né il numero di telaio (VIN) né i dati dell'intestatario.
Autenticazione
Ogni richiesta include la chiave API nell'header Authorization: Bearer <chiave> (in alternativa X-API-Key: <chiave>). Le chiavi live iniziano con em_live_, quelle di test con em_test_, e si gestiscono (e rigenerano) dalla dashboard del portale.
curl https://api.evita-multe.it/v1/assicurazione/FM204NE \ -H "Authorization: Bearer em_live_LA_TUA_CHIAVE"
Usa la chiave live solo lato server: non inserirla in app mobili o JavaScript eseguito nel browser.
Ambiente di test
Con la chiave em_test_ tutti gli endpoint rispondono con dati di esempio realistici e la stessa struttura della produzione, senza consumare crediti (30 richieste al minuto). Per provare i casi di errore usa queste targhe:
XX000XX→ 404targa_non_trovataER000OR→ 503fonte_non_disponibile- qualsiasi altra targa valida → 200 con dati di esempio
Struttura della risposta
Tutti gli endpoint usano lo stesso involucro, così puoi gestire risposte ed errori con un'unica funzione.
| Campo | Descrizione |
|---|---|
| successo | true se la risposta contiene dati |
| endpoint, targa | modulo chiamato e targa normalizzata |
| dati | campi specifici del modulo (vedi sotto) |
| addebito | crediti_usati, saldo residuo, modalita (live o test) |
| meta | id_richiesta, durata_ms, cache, aggiornato_al (quando il dato è stato letto dalla fonte) |
| errore | solo con successo: false, contiene codice e messaggio |
Assicurazione RC auto
1 creditoStato della copertura RC auto letto dalla banca dati ufficiale: compagnia, numero di polizza, scadenza e fine del periodo di tolleranza di 15 giorni.
| Campo (dati.) | Tipo | Valori |
|---|---|---|
| assicurato | bool | true se la copertura è attiva o in tolleranza |
| stato | string | ATTIVA, IN_TOLLERANZA, SOSPESA, NON_ASSICURATO |
| compagnia | string | nome della compagnia assicurativa |
| numero_polizza | string | numero di polizza |
| scadenza_polizza | date | scadenza della polizza (YYYY-MM-DD) |
| scadenza_tolleranza | date | ultimo giorno del periodo di tolleranza |
| sospesa | bool | polizza sospesa dal contraente |
{
"successo": true,
"endpoint": "assicurazione",
"targa": "FM204NE",
"dati": {
"targa": "FM204NE",
"assicurato": true,
"stato": "ATTIVA",
"compagnia": "COMPAGNIA DI ESEMPIO S.P.A.",
"numero_polizza": "000123456789",
"scadenza_polizza": "2027-03-13",
"scadenza_tolleranza": "2027-03-28",
"sospesa": false,
"tipo_veicolo": "AUTOVEICOLO",
"fonti": [
"portale_automobilista"
]
},
"addebito": {
"crediti_usati": 1,
"saldo": 599,
"modalita": "live"
},
"meta": {
"id_richiesta": "req_104231",
"durata_ms": 1840,
"cache": false,
"aggiornato_al": "2026-10-21T09:15:02+00:00"
}
}Revisioni e chilometri
2 creditiStorico completo delle revisioni dalla Motorizzazione con data, esito e chilometri letti, prossima scadenza calcolata e rilevamento automatico delle scalature del contachilometri.
| Campo (dati.) | Tipo | Valori |
|---|---|---|
| ultima_revisione | object | {data, esito, km, annullata, protocollo} |
| prossima_scadenza | date | calcolata secondo le regole del Codice della strada |
| scaduta | bool | true se la scadenza è già passata |
| numero_revisioni | int | revisioni presenti nello storico |
| ultimo_km / km_medi_annui | int | ultima lettura e media annua (null se non calcolabile) |
| anomalia_km | bool | true se i km sono diminuiti tra due revisioni |
| anomalie_km[] | array | {da_data, km_precedenti, a_data, km_successivi, differenza_km} |
| storico[] | array | tutte le revisioni, dalla più recente |
{
"successo": true,
"endpoint": "revisione",
"targa": "FM204NE",
"dati": {
"targa": "FM204NE",
"ultima_revisione": {
"data": "2025-04-14",
"esito": "REGOLARE",
"km": 98412,
"annullata": false,
"protocollo": "600000001"
},
"prossima_scadenza": "2027-04-30",
"scaduta": false,
"numero_revisioni": 3,
"ultimo_km": 98412,
"km_medi_annui": 12650,
"anomalia_km": true,
"anomalie_km": [
{
"da_data": "2021-03-22",
"km_precedenti": 71250,
"a_data": "2023-03-30",
"km_successivi": 64980,
"differenza_km": -6270
}
],
"storico": [
{
"data": "2025-04-14",
"esito": "REGOLARE",
"km": 98412,
"annullata": false,
"protocollo": "600000001"
},
{
"data": "2023-03-30",
"esito": "REGOLARE",
"km": 64980,
"annullata": false,
"protocollo": "500000001"
},
{
"data": "2021-03-22",
"esito": "REGOLARE",
"km": 71250,
"annullata": false,
"protocollo": "400000001"
}
],
"fonti": [
"portale_automobilista"
]
},
"addebito": {
"crediti_usati": 2,
"saldo": 599,
"modalita": "live"
},
"meta": {
"id_richiesta": "req_104231",
"durata_ms": 1840,
"cache": false,
"aggiornato_al": "2026-10-21T09:15:02+00:00"
}
}Dati del veicolo
1 creditoTipo di veicolo, classe ambientale Euro e idoneità per neopatentati dal Portale dell'Automobilista. Marca, modello, alimentazione, potenza e immatricolazione vengono aggiunti quando presenti nel nostro archivio (altrimenti null).
| Campo (dati.) | Tipo | Valori |
|---|---|---|
| tipo_veicolo | string | AUTOVEICOLO, MOTOVEICOLO, RIMORCHIO… |
| classe_euro | string | EURO0 … EURO6 |
| neopatentati.guidabile | bool | idoneità per neopatentati |
| marca / modello / versione | string|null | quando disponibili |
| alimentazione / kw / cv / cilindrata | mixed|null | quando disponibili |
| data_immatricolazione | date|null | YYYY-MM-DD |
| fonti | array | fonti usate per la risposta |
{
"successo": true,
"endpoint": "veicolo",
"targa": "FM204NE",
"dati": {
"targa": "FM204NE",
"tipo_veicolo": "AUTOVEICOLO",
"classe_euro": "EURO6",
"neopatentati": {
"guidabile": true,
"descrizione": "Il veicolo può essere guidato da un neopatentato."
},
"marca": "FIAT",
"modello": "Panda 3a serie",
"versione": "1.2 Easy",
"alimentazione": "Benzina",
"kw": 51,
"cv": 69,
"cilindrata": 1242,
"data_immatricolazione": "2018-03-01",
"anno_costruzione": 2018,
"fonti": [
"portale_automobilista"
]
},
"addebito": {
"crediti_usati": 1,
"saldo": 599,
"modalita": "live"
},
"meta": {
"id_richiesta": "req_104231",
"durata_ms": 1840,
"cache": false,
"aggiornato_al": "2026-10-21T09:15:02+00:00"
}
}Bollo auto (beta)
1 creditoSituazione della tassa automobilistica dal servizio ACI della regione indicata. Il parametro regione (residenza del proprietario) è obbligatorio: accetta id numerico, nome o slug, ad esempio lombardia o emilia-romagna.
| Campo (dati.) | Tipo | Valori |
|---|---|---|
| stato | string | DOVUTO (da pagare entro il termine), SCADUTO (termine superato, con sanzioni), NON_ANCORA_DOVUTO (pagato, prossimo periodo non ancora aperto) |
| decorrenza / scadenza | date | inizio e fine del periodo di tassa da pagare (YYYY-MM-DD) |
| termine_pagamento | date | ultimo giorno per pagare senza sanzioni (YYYY-MM-DD) |
| importo_tassa / importo_sanzioni / importo_interessi | number | EUR |
| importo_totale | number | EUR, totale da pagare |
| kw / cv_fiscali / classe_euro | mixed | dati fiscali usati per il calcolo |
| regione / regione_id | mixed | regione interrogata |
{
"successo": true,
"endpoint": "bollo",
"targa": "FM204NE",
"dati": {
"targa": "FM204NE",
"regione": "Lombardia",
"regione_id": 9,
"stato": "DOVUTO",
"residenza": "LOMBARDIA (MI)",
"decorrenza": "2026-10-01",
"scadenza": "2027-09-30",
"termine_pagamento": "2026-10-31",
"mesi_validita": 12,
"importo_tassa": 132.48,
"importo_sanzioni": 0,
"importo_interessi": 0,
"importo_totale": 132.48,
"alimentazione": "BENZINA",
"kw": 51,
"cv_fiscali": 14,
"classe_euro": "EURO 6",
"uso": "PROPRIO",
"categoria": "AUTOVETTURE",
"fonti": [
"aci"
]
},
"addebito": {
"crediti_usati": 1,
"saldo": 599,
"modalita": "live"
},
"meta": {
"id_richiesta": "req_104231",
"durata_ms": 1840,
"cache": false,
"aggiornato_al": "2026-10-21T09:15:02+00:00"
}
}Verifica completa
max 3 creditiInterroga in parallelo veicolo, assicurazione e revisione, più il bollo se passi regione. Paghi solo i moduli che restituiscono dati, con un tetto di 3 crediti. In dati trovi un oggetto per modulo; moduli riporta l'esito di ciascuno (trovato, non_trovato o errore), i crediti e l'uso della cache.
{
"successo": true,
"endpoint": "completo",
"targa": "FM204NE",
"dati": {
"veicolo": {
"…": "…"
},
"assicurazione": {
"…": "…"
},
"revisione": {
"…": "…"
},
"bollo": {
"…": "…"
}
},
"moduli": {
"veicolo": {
"stato": "trovato",
"crediti": 1,
"cache": true,
"aggiornato_al": "2026-09-02T14:20:11+00:00"
},
"assicurazione": {
"stato": "trovato",
"crediti": 1,
"cache": false,
"aggiornato_al": "2026-10-21T09:15:02+00:00"
},
"revisione": {
"stato": "trovato",
"crediti": 2,
"cache": false,
"aggiornato_al": "2026-10-21T09:15:03+00:00"
},
"bollo": {
"stato": "non_trovato",
"crediti": 0,
"cache": false,
"aggiornato_al": null
}
},
"addebito": {
"crediti_usati": 3,
"saldo": 597,
"modalita": "live"
},
"meta": {
"id_richiesta": "req_104233",
"durata_ms": 4120,
"cache": false
}
}/account · /regioni
GET /v1/account restituisce saldo crediti, limite di richieste e utilizzo degli ultimi 30 giorni. GET /v1/regioni elenca le regioni accettate dal parametro regione del bollo. Entrambi sono gratuiti.
Codici di errore
Gli errori hanno sempre la forma {"successo": false, "errore": {"codice": "…", "messaggio": "…"}} e non consumano crediti.
| HTTP | Codice | Significato |
|---|---|---|
| 400 | targa_non_valida | Formato targa non valido |
| 400 | regione_mancante / regione_non_valida | Parametro regione assente o errato (bollo) |
| 401 | chiave_mancante / chiave_non_valida | Chiave API assente o errata |
| 402 | crediti_insufficienti | Saldo insufficiente: ricarica dal portale |
| 403 | email_non_verificata / account_disattivato | Account non attivo |
| 404 | targa_non_trovata | Nessun dato per questa targa |
| 429 | troppe_richieste | Limite al minuto superato, rispetta l'header Retry-After |
| 503 | fonte_non_disponibile | La fonte ufficiale non risponde, riprova più tardi |
Addebito e limiti
- Paghi solo le risposte con dati (HTTP 200). Targhe non trovate, errori di validazione e fonti non disponibili costano 0 crediti.
- Costi: assicurazione 1, veicolo 1, bollo 1, revisioni 2, completo massimo 3 crediti. Un credito costa da €0,24 a €0,10 IVA esclusa in base al pacchetto, e i crediti non scadono. Vedi i pacchetti.
- Limiti: 1000 richieste al minuto per chiave, live e di test, anche durante la prova gratuita. Gli header
X-RateLimit-LimiteX-RateLimit-Remainingindicano lo stato; oltre il limite ricevi 429 conRetry-After. - Ogni risposta ha l'header
X-Request-Id, utile per ritrovare la richiesta nello storico del portale o per l'assistenza.
Freschezza dei dati
Le fonti vengono interrogate in tempo reale. Per contenere i tempi conserviamo l'ultimo risultato per un periodo breve; meta.cache e meta.aggiornato_al indicano se e quando il dato è stato letto dalla fonte.
| Modulo | Cache massima | Tempo tipico senza cache |
|---|---|---|
| assicurazione | 24 ore | 1–3 s |
| revisione | 7 giorni | 2–5 s |
| bollo | 7 giorni | 4–10 s |
| veicolo | 180 giorni (dati tecnici stabili) | 1–3 s |
Esempi di codice
<?php
$ch = curl_init("https://api.evita-multe.it/v1/revisione/FM204NE");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Authorization: Bearer em_live_LA_TUA_CHIAVE"],
]);
$res = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status === 200) {
echo $res["dati"]["prossima_scadenza"];
if ($res["dati"]["anomalia_km"]) echo " - attenzione: km scalati";
} else {
echo $res["errore"]["codice"];
}const res = await fetch("https://api.evita-multe.it/v1/assicurazione/FM204NE", {
headers: { Authorization: "Bearer em_live_LA_TUA_CHIAVE" },
signal: AbortSignal.timeout(30000),
});
const body = await res.json();
if (res.ok) {
console.log(body.dati.compagnia, body.dati.scadenza_polizza);
} else {
console.error(res.status, body.errore.codice);
}import requests
r = requests.get(
"https://api.evita-multe.it/v1/completo/FM204NE",
params={"regione": "lombardia"},
headers={"Authorization": "Bearer em_live_LA_TUA_CHIAVE"},
timeout=30,
)
data = r.json()
if r.ok:
print(data["dati"]["assicurazione"]["scadenza_polizza"], data["addebito"])
else:
print(r.status_code, data["errore"]["codice"])Buone pratiche di integrazione
- Imposta un timeout client di almeno 30 secondi.
- Tratta il 404 come una risposta valida ("nessun dato"), non come un errore da ripetere.
- Su 503 e 429 riprova con attesa crescente (ad esempio 5, 15 e 60 secondi), rispettando
Retry-After. - Se ti servono più moduli per la stessa targa, usa
/v1/completo: una sola chiamata, moduli interrogati in parallelo, costo massimo 3 crediti. - Normalizza le targhe nel tuo sistema (maiuscole, senza spazi) per riconoscere i duplicati prima di chiamare l'API.
- Controlla il saldo con
GET /v1/accounto leggiaddebito.saldoin ogni risposta per ricaricare in tempo.
Domande frequenti
Come ottengo una chiave API?
Crea un account gratuito su api.evita-multe.it e conferma l'email. Nella dashboard trovi una chiave live (em_live_) con 20 crediti gratuiti e una chiave di test (em_test_) illimitata che restituisce dati di esempio.
Qual è il formato della risposta?
JSON UTF-8. Le risposte riuscite hanno successo: true, l'oggetto dati con i campi del modulo, addebito con crediti usati e saldo, e meta con id richiesta, durata, uso della cache e data di lettura dalla fonte. Gli errori hanno successo: false e un oggetto errore con codice e messaggio.
Quali targhe sono supportate?
Targhe italiane di autoveicoli, motoveicoli e rimorchi. Spazi e trattini vengono ignorati e maiuscole e minuscole sono indifferenti: FM204NE, fm-204ne e FM 204NE (codificata come FM%20204NE) danno lo stesso risultato. Le targhe estere non sono supportate.
Quanto costa una chiamata?
Assicurazione, veicolo e bollo costano 1 credito, lo storico revisioni 2, la chiamata completa al massimo 3. Un credito costa da €0,24 a €0,10 IVA esclusa in base al pacchetto. Le risposte senza dati (404, errori, fonte non disponibile) non costano nulla.
Esiste una specifica OpenAPI?
Sì, la specifica OpenAPI 3.1 è disponibile su https://api.evita-multe.it/openapi.json e si importa in Postman, Insomnia o nei generatori di SDK.
Che timeout devo impostare?
Almeno 30 secondi. Le risposte dalla cache arrivano in millisecondi, le interrogazioni dirette alle fonti ufficiali richiedono in genere 1-5 secondi, il bollo fino a 10.
Pronto per la prima chiamata?
20 crediti gratuiti e una chiave di test illimitata, senza carta di credito.
Domande tecniche o volumi elevati: [email protected]