{
    "openapi": "3.1.0",
    "info": {
        "title": "Evita Multe API – dati veicolo da targa (Italia)",
        "version": "1.0.0",
        "description": "Verifica assicurazione RCA, revisioni con storico chilometri, classe Euro, bollo auto e dati del veicolo partendo dalla targa.\n\nCrediti prepagati senza scadenza: si paga solo quando troviamo dati. Errori e targhe inesistenti non costano nulla. Chiavi `em_test_` restituiscono dati di esempio gratuiti (targa XX000XX = non trovata, ER000OR = fonte non disponibile).",
        "contact": {
            "name": "Evita Multe",
            "email": "office@evita-multe.it",
            "url": "https://evita-multe.it/api-targa"
        }
    },
    "servers": [
        {
            "url": "https://api.evita-multe.it"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        },
        {
            "apiKeyHeader": []
        }
    ],
    "paths": {
        "/v1/veicolo/{targa}": {
            "get": {
                "summary": "Dati veicolo (1 credito)",
                "description": "Tipo veicolo, classe ambientale Euro, guidabilità per neopatentati. Marca, modello, alimentazione e data di immatricolazione quando disponibili.",
                "parameters": [
                    {
                        "name": "targa",
                        "in": "path",
                        "required": true,
                        "description": "Targa italiana (auto AB123CD, moto AB12345); spazi e trattini vengono ignorati",
                        "schema": {
                            "type": "string",
                            "example": "AB123CD"
                        }
                    },
                    {
                        "name": "tipo",
                        "in": "query",
                        "description": "Tipo di veicolo: auto, moto o rimorchio. Serve solo se la targa esiste per più tipi (risposta 409 targa_ambigua), es. targhe AA00000 di moto e di rimorchi immatricolati prima del 1999",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "auto",
                                "moto",
                                "rimorchio"
                            ]
                        }
                    },
                    {
                        "name": "aggiorna",
                        "in": "query",
                        "description": "1 per rileggere il dato dalla fonte ignorando la cache (addebito normale)",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Veicolo trovato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "successo": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "endpoint": {
                                            "type": "string"
                                        },
                                        "targa": {
                                            "type": "string"
                                        },
                                        "tipo": {
                                            "type": "string",
                                            "enum": [
                                                "auto",
                                                "moto",
                                                "rimorchio"
                                            ]
                                        },
                                        "dati": {
                                            "$ref": "#/components/schemas/Veicolo"
                                        },
                                        "addebito": {
                                            "$ref": "#/components/schemas/Addebito"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Targa o parametri non validi",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Chiave API mancante o non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Crediti insufficienti",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nessun dato per la targa (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Targa registrata per più tipi di veicolo: ripeti con ?tipo= (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite di richieste al minuto superato (header Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Fonte ufficiale non disponibile (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/veicolo-vin/{vin}": {
            "get": {
                "summary": "Dati tecnici UE da VIN (1 credito)",
                "description": "Dati tecnici del veicolo a partire dal numero di telaio (VIN): marca, modello, versione, potenza, cilindrata, alimentazione, posti, massa, CO2. Copertura europea. Quando il VIN non identifica una sola versione la risposta ha corrispondenza \"parziale\": marca e modello (o modelli_possibili) più l'elenco versioni_possibili; i campi che variano tra le versioni non sono valorizzati.",
                "parameters": [
                    {
                        "name": "vin",
                        "in": "path",
                        "required": true,
                        "description": "Numero di telaio (VIN), 11-17 caratteri; spazi e trattini vengono ignorati",
                        "schema": {
                            "type": "string",
                            "example": "VF1BSR00012345678"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Veicolo trovato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "successo": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "endpoint": {
                                            "type": "string"
                                        },
                                        "vin": {
                                            "type": "string"
                                        },
                                        "dati": {
                                            "$ref": "#/components/schemas/VeicoloVin"
                                        },
                                        "addebito": {
                                            "$ref": "#/components/schemas/Addebito"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Targa o parametri non validi",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Chiave API mancante o non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Crediti insufficienti",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nessun dato per la targa (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Targa registrata per più tipi di veicolo: ripeti con ?tipo= (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite di richieste al minuto superato (header Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Fonte ufficiale non disponibile (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/assicurazione/{targa}": {
            "get": {
                "summary": "Copertura RCA (1 credito)",
                "description": "Compagnia, numero di polizza, scadenza polizza e fine periodo di tolleranza (15 giorni). Fonte: Portale dell'Automobilista. Aggiornato ogni 24 ore.",
                "parameters": [
                    {
                        "name": "targa",
                        "in": "path",
                        "required": true,
                        "description": "Targa italiana (auto AB123CD, moto AB12345); spazi e trattini vengono ignorati",
                        "schema": {
                            "type": "string",
                            "example": "AB123CD"
                        }
                    },
                    {
                        "name": "tipo",
                        "in": "query",
                        "description": "Tipo di veicolo: auto, moto o rimorchio. Serve solo se la targa esiste per più tipi (risposta 409 targa_ambigua), es. targhe AA00000 di moto e di rimorchi immatricolati prima del 1999",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "auto",
                                "moto",
                                "rimorchio"
                            ]
                        }
                    },
                    {
                        "name": "aggiorna",
                        "in": "query",
                        "description": "1 per rileggere il dato dalla fonte ignorando la cache (addebito normale)",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Esito copertura (anche \"non assicurato\" per veicoli esistenti)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "successo": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "endpoint": {
                                            "type": "string"
                                        },
                                        "targa": {
                                            "type": "string"
                                        },
                                        "tipo": {
                                            "type": "string",
                                            "enum": [
                                                "auto",
                                                "moto",
                                                "rimorchio"
                                            ]
                                        },
                                        "dati": {
                                            "$ref": "#/components/schemas/Assicurazione"
                                        },
                                        "addebito": {
                                            "$ref": "#/components/schemas/Addebito"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Targa o parametri non validi",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Chiave API mancante o non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Crediti insufficienti",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nessun dato per la targa (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Targa registrata per più tipi di veicolo: ripeti con ?tipo= (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite di richieste al minuto superato (header Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Fonte ufficiale non disponibile (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/revisione/{targa}": {
            "get": {
                "summary": "Storico revisioni e chilometri (2 crediti)",
                "description": "Tutte le revisioni registrate con esito e km, prossima scadenza calcolata con la cadenza dello storico (annuale per mezzi pesanti e rimorchi oltre 3,5 t, biennale per auto e moto), controllo anomalie chilometriche (contachilometri scalato).",
                "parameters": [
                    {
                        "name": "targa",
                        "in": "path",
                        "required": true,
                        "description": "Targa italiana (auto AB123CD, moto AB12345); spazi e trattini vengono ignorati",
                        "schema": {
                            "type": "string",
                            "example": "AB123CD"
                        }
                    },
                    {
                        "name": "tipo",
                        "in": "query",
                        "description": "Tipo di veicolo: auto, moto o rimorchio. Serve solo se la targa esiste per più tipi (risposta 409 targa_ambigua), es. targhe AA00000 di moto e di rimorchi immatricolati prima del 1999",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "auto",
                                "moto",
                                "rimorchio"
                            ]
                        }
                    },
                    {
                        "name": "cadenza",
                        "in": "query",
                        "description": "Cadenza revisione in mesi (12 per mezzi pesanti, rimorchi oltre 3,5 t, autobus, taxi e noleggio). Senza il parametro è ricavata dallo storico: vedi cadenza_origine",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                12,
                                24
                            ]
                        }
                    },
                    {
                        "name": "aggiorna",
                        "in": "query",
                        "description": "1 per rileggere il dato dalla fonte ignorando la cache (addebito normale)",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Storico trovato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "successo": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "endpoint": {
                                            "type": "string"
                                        },
                                        "targa": {
                                            "type": "string"
                                        },
                                        "tipo": {
                                            "type": "string",
                                            "enum": [
                                                "auto",
                                                "moto",
                                                "rimorchio"
                                            ]
                                        },
                                        "dati": {
                                            "$ref": "#/components/schemas/Revisione"
                                        },
                                        "addebito": {
                                            "$ref": "#/components/schemas/Addebito"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Targa o parametri non validi",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Chiave API mancante o non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Crediti insufficienti",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nessun dato per la targa (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Targa registrata per più tipi di veicolo: ripeti con ?tipo= (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite di richieste al minuto superato (header Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Fonte ufficiale non disponibile (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/bollo/{targa}": {
            "get": {
                "summary": "Bollo auto – beta (1 credito)",
                "description": "Importo, periodo e termine di pagamento del bollo per auto, autocarri e moto, calcolati da ACI sui dati di archivio per la regione di residenza dell'intestatario (per leasing e noleggio: la società proprietaria). Il calcolo non verifica i pagamenti: SCADUTO indica che il termine di pagamento del periodo è passato. Per i rimorchi ACI non restituisce un importo. Per la Lombardia il dato viene dall'archivio di Regione Lombardia e indica lo stato reale del pagamento (PAGATO, DOMICILIATO, DOVUTO, SCADUTO).",
                "parameters": [
                    {
                        "name": "targa",
                        "in": "path",
                        "required": true,
                        "description": "Targa italiana (auto AB123CD, moto AB12345); spazi e trattini vengono ignorati",
                        "schema": {
                            "type": "string",
                            "example": "AB123CD"
                        }
                    },
                    {
                        "required": true,
                        "name": "regione",
                        "in": "query",
                        "description": "Regione di residenza del proprietario: id 1-20 o nome (es. lombardia). Vedi /v1/regioni",
                        "schema": {
                            "type": "string",
                            "example": "lombardia"
                        }
                    },
                    {
                        "name": "tipo",
                        "in": "query",
                        "description": "Tipo di veicolo: auto, moto o rimorchio. Serve solo se la targa esiste per più tipi (risposta 409 targa_ambigua), es. targhe AA00000 di moto e di rimorchi immatricolati prima del 1999",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "auto",
                                "moto",
                                "rimorchio"
                            ]
                        }
                    },
                    {
                        "name": "aggiorna",
                        "in": "query",
                        "description": "1 per rileggere il dato dalla fonte ignorando la cache (addebito normale)",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Esito bollo",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "successo": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "endpoint": {
                                            "type": "string"
                                        },
                                        "targa": {
                                            "type": "string"
                                        },
                                        "tipo": {
                                            "type": "string",
                                            "enum": [
                                                "auto",
                                                "moto",
                                                "rimorchio"
                                            ]
                                        },
                                        "dati": {
                                            "$ref": "#/components/schemas/Bollo"
                                        },
                                        "addebito": {
                                            "$ref": "#/components/schemas/Addebito"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Targa o parametri non validi",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Chiave API mancante o non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Crediti insufficienti",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nessun dato per la targa (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Targa registrata per più tipi di veicolo: ripeti con ?tipo= (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite di richieste al minuto superato (header Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Fonte ufficiale non disponibile (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/completo/{targa}": {
            "get": {
                "summary": "Tutti i moduli (max 3 crediti)",
                "description": "Veicolo, assicurazione, revisione e – se indichi la regione – bollo, eseguiti in parallelo. Paghi solo i moduli trovati, al massimo 3 crediti.",
                "parameters": [
                    {
                        "name": "targa",
                        "in": "path",
                        "required": true,
                        "description": "Targa italiana (auto AB123CD, moto AB12345); spazi e trattini vengono ignorati",
                        "schema": {
                            "type": "string",
                            "example": "AB123CD"
                        }
                    },
                    {
                        "name": "regione",
                        "in": "query",
                        "description": "Regione di residenza del proprietario: id 1-20 o nome (es. lombardia). Vedi /v1/regioni",
                        "schema": {
                            "type": "string",
                            "example": "lombardia"
                        }
                    },
                    {
                        "name": "tipo",
                        "in": "query",
                        "description": "Tipo di veicolo: auto, moto o rimorchio. Serve solo se la targa esiste per più tipi (risposta 409 targa_ambigua), es. targhe AA00000 di moto e di rimorchi immatricolati prima del 1999",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "auto",
                                "moto",
                                "rimorchio"
                            ]
                        }
                    },
                    {
                        "name": "cadenza",
                        "in": "query",
                        "description": "Cadenza revisione in mesi (12 per mezzi pesanti, rimorchi oltre 3,5 t, autobus, taxi e noleggio). Senza il parametro è ricavata dallo storico: vedi cadenza_origine",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                12,
                                24
                            ]
                        }
                    },
                    {
                        "name": "aggiorna",
                        "in": "query",
                        "description": "1 per rileggere il dato dalla fonte ignorando la cache (addebito normale)",
                        "schema": {
                            "type": "integer",
                            "enum": [
                                1
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Almeno un modulo trovato",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "successo": {
                                            "type": "boolean"
                                        },
                                        "dati": {
                                            "type": "object",
                                            "properties": {
                                                "veicolo": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/Veicolo"
                                                        },
                                                        {
                                                            "type": "null"
                                                        }
                                                    ]
                                                },
                                                "assicurazione": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/Assicurazione"
                                                        },
                                                        {
                                                            "type": "null"
                                                        }
                                                    ]
                                                },
                                                "revisione": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/Revisione"
                                                        },
                                                        {
                                                            "type": "null"
                                                        }
                                                    ]
                                                },
                                                "bollo": {
                                                    "oneOf": [
                                                        {
                                                            "$ref": "#/components/schemas/Bollo"
                                                        },
                                                        {
                                                            "type": "null"
                                                        }
                                                    ]
                                                }
                                            }
                                        },
                                        "moduli": {
                                            "type": "object",
                                            "additionalProperties": {
                                                "type": "object",
                                                "properties": {
                                                    "stato": {
                                                        "type": "string",
                                                        "enum": [
                                                            "trovato",
                                                            "non_trovato",
                                                            "errore"
                                                        ]
                                                    },
                                                    "crediti": {
                                                        "type": "integer"
                                                    },
                                                    "cache": {
                                                        "type": "boolean"
                                                    },
                                                    "aggiornato_al": {
                                                        "type": "string",
                                                        "format": "date-time"
                                                    }
                                                }
                                            }
                                        },
                                        "addebito": {
                                            "$ref": "#/components/schemas/Addebito"
                                        },
                                        "meta": {
                                            "$ref": "#/components/schemas/Meta"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Targa o parametri non validi",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Chiave API mancante o non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "402": {
                        "description": "Crediti insufficienti",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Nessun dato per la targa (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Targa registrata per più tipi di veicolo: ripeti con ?tipo= (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Limite di richieste al minuto superato (header Retry-After)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Fonte ufficiale non disponibile (nessun addebito)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/account": {
            "get": {
                "summary": "Saldo e utilizzo (gratis)",
                "responses": {
                    "200": {
                        "description": "Dati account"
                    },
                    "401": {
                        "description": "Chiave non valida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Errore"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/regioni": {
            "get": {
                "summary": "Elenco regioni per il bollo (gratis, senza chiave)",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Regioni"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Authorization: Bearer em_live_..."
            },
            "apiKeyHeader": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key"
            }
        },
        "schemas": {
            "Addebito": {
                "type": "object",
                "properties": {
                    "crediti_usati": {
                        "type": "integer"
                    },
                    "saldo": {
                        "type": "integer"
                    },
                    "modalita": {
                        "type": "string",
                        "enum": [
                            "live",
                            "test"
                        ]
                    }
                }
            },
            "Meta": {
                "type": "object",
                "properties": {
                    "id_richiesta": {
                        "type": "string"
                    },
                    "durata_ms": {
                        "type": "integer"
                    },
                    "cache": {
                        "type": "boolean"
                    },
                    "aggiornato_al": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "Errore": {
                "type": "object",
                "properties": {
                    "successo": {
                        "type": "boolean",
                        "const": false
                    },
                    "errore": {
                        "type": "object",
                        "properties": {
                            "codice": {
                                "type": "string",
                                "enum": [
                                    "chiave_mancante",
                                    "chiave_non_valida",
                                    "account_disattivato",
                                    "email_non_verificata",
                                    "crediti_insufficienti",
                                    "targa_non_valida",
                                    "vin_non_valido",
                                    "regione_mancante",
                                    "regione_non_valida",
                                    "tipo_non_valido",
                                    "targa_ambigua",
                                    "targa_non_trovata",
                                    "vin_non_trovato",
                                    "troppe_richieste",
                                    "fonte_non_disponibile",
                                    "endpoint_non_trovato",
                                    "metodo_non_consentito"
                                ]
                            },
                            "messaggio": {
                                "type": "string"
                            }
                        }
                    },
                    "addebito": {
                        "$ref": "#/components/schemas/Addebito"
                    }
                }
            },
            "Veicolo": {
                "type": "object",
                "properties": {
                    "targa": {
                        "type": "string"
                    },
                    "tipo_veicolo": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "AUTOVEICOLO"
                    },
                    "classe_euro": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "EURO6"
                    },
                    "neopatentati": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "guidabile": {
                                "type": [
                                    "boolean",
                                    "null"
                                ]
                            },
                            "descrizione": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            }
                        }
                    },
                    "marca": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modello": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "versione": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "alimentazione": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "kw": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "cv": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "cilindrata": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "data_immatricolazione": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "anno_costruzione": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "posti": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Posti a sedere (fonte: openvehicle-data)"
                    },
                    "massa_kg": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Massa in ordine di marcia, kg (openvehicle-data)"
                    },
                    "massa_max_kg": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Massa massima ammissibile, kg (openvehicle-data)"
                    },
                    "co2_wltp": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Emissioni CO2 WLTP, g/km (openvehicle-data)"
                    },
                    "omologazione": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Numero di omologazione UE (openvehicle-data)",
                        "example": "e3*2007/46*0064"
                    },
                    "fonti": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Fonti dei dati, es. portale_automobilista, openvehicle_data"
                    }
                }
            },
            "VeicoloVin": {
                "type": "object",
                "properties": {
                    "vin": {
                        "type": "string"
                    },
                    "marca": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "modello": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "versione": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "alimentazione": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "kw": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "cv": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "cilindrata": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "cilindri": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "cambio": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Manual"
                    },
                    "categoria": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "M1"
                    },
                    "tipo_veicolo": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "Passenger car"
                    },
                    "trazione": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "co2_wltp": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "posti": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "massa_kg": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "massa_max_kg": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "classe_euro": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "omologazione": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "example": "e3*2007/46*0064"
                    },
                    "data_immatricolazione": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "anno_costruzione": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "corrispondenza": {
                        "type": "string",
                        "enum": [
                            "esatta",
                            "parziale"
                        ],
                        "description": "esatta: una sola versione; parziale: vedi versioni_possibili"
                    },
                    "modelli_possibili": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Solo se corrispondenza parziale e il VIN è compatibile con più modelli"
                    },
                    "versioni_possibili": {
                        "type": "array",
                        "description": "Solo se corrispondenza parziale, dalla più diffusa",
                        "items": {
                            "type": "object",
                            "properties": {
                                "modello": {
                                    "type": "string"
                                },
                                "versione": {
                                    "type": "string"
                                },
                                "alimentazione": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "kw": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ]
                                },
                                "cv": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ]
                                },
                                "cambio": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "anno": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ]
                                }
                            }
                        }
                    },
                    "fonti": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "example": [
                            "autoref",
                            "openvehicle_data"
                        ]
                    }
                }
            },
            "Assicurazione": {
                "type": "object",
                "properties": {
                    "targa": {
                        "type": "string"
                    },
                    "assicurato": {
                        "type": "boolean"
                    },
                    "stato": {
                        "type": "string",
                        "enum": [
                            "ATTIVA",
                            "IN_TOLLERANZA",
                            "SOSPESA",
                            "NON_ASSICURATO"
                        ]
                    },
                    "compagnia": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "numero_polizza": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "scadenza_polizza": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "scadenza_tolleranza": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "sospesa": {
                        "type": "boolean"
                    },
                    "tipo_veicolo": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "Revisione": {
                "type": "object",
                "properties": {
                    "targa": {
                        "type": "string"
                    },
                    "tipo_veicolo": {
                        "type": "string",
                        "enum": [
                            "AUTOVEICOLO",
                            "MOTOVEICOLO",
                            "RIMORCHIO"
                        ]
                    },
                    "ultima_revisione": {
                        "$ref": "#/components/schemas/VoceRevisione"
                    },
                    "prossima_scadenza": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "cadenza_mesi": {
                        "type": "integer",
                        "enum": [
                            12,
                            24
                        ]
                    },
                    "cadenza_origine": {
                        "type": "string",
                        "enum": [
                            "storico",
                            "predefinita",
                            "richiesta"
                        ],
                        "description": "storico: ricavata dagli intervalli tra le revisioni; predefinita: storico insufficiente, 12 per i rimorchi e 24 per gli altri veicoli; richiesta: dal parametro cadenza"
                    },
                    "scaduta": {
                        "type": [
                            "boolean",
                            "null"
                        ]
                    },
                    "numero_revisioni": {
                        "type": "integer"
                    },
                    "ultimo_km": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "km_medi_annui": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "anomalia_km": {
                        "type": "boolean",
                        "description": "true se i km sono diminuiti tra due revisioni"
                    },
                    "anomalie_km": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "da_data": {
                                    "type": "string",
                                    "format": "date"
                                },
                                "km_precedenti": {
                                    "type": "integer"
                                },
                                "a_data": {
                                    "type": "string",
                                    "format": "date"
                                },
                                "km_successivi": {
                                    "type": "integer"
                                },
                                "differenza_km": {
                                    "type": "integer"
                                }
                            }
                        }
                    },
                    "storico": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/VoceRevisione"
                        }
                    }
                }
            },
            "VoceRevisione": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "string",
                        "format": "date"
                    },
                    "esito": {
                        "type": "string",
                        "example": "REGOLARE"
                    },
                    "km": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "annullata": {
                        "type": "boolean"
                    },
                    "protocollo": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "Bollo": {
                "type": "object",
                "properties": {
                    "targa": {
                        "type": "string"
                    },
                    "regione": {
                        "type": "string"
                    },
                    "regione_id": {
                        "type": "integer"
                    },
                    "stato": {
                        "type": "string",
                        "enum": [
                            "NON_ANCORA_DOVUTO",
                            "DOVUTO",
                            "SCADUTO",
                            "PAGATO",
                            "DOMICILIATO"
                        ]
                    },
                    "scadenza": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "termine_pagamento": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date"
                    },
                    "prossimo_termine_pagamento": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "format": "date",
                        "description": "Solo Lombardia"
                    },
                    "domiciliazione_bancaria": {
                        "type": "boolean",
                        "description": "Solo Lombardia"
                    },
                    "importo_tassa": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "importo_sanzioni": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "importo_interessi": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "importo_totale": {
                        "type": [
                            "number",
                            "null"
                        ]
                    },
                    "kw": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "classe_euro": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "alimentazione": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            }
        }
    }
}