Migrazione API v2 › API v3
La migrazione all'API v3 richiede modifiche sia alla richiesta sia alla lettura del risultato.
Le principali differenze sono:
- un unico endpoint
POST; - selezione dei servizi tramite un array;
- dati raggruppati per ambito;
- esito esplicito per ogni servizio richiesto;
- date civili in formato ISO;
- omissione dei campi privi di valore.
L'autenticazione tramite x-api-key e la struttura generale della risposta rimangono invariate.
1. Aggiorna endpoint e metodo
API v2: POST https://api.infotarga.com/v2/queryAPI v3: POST https://api.infotarga.com/v3/queryL'API v3 non supporta richieste GET né URL con la targa incorporata nel percorso. La targa deve essere inclusa nel corpo JSON.
2. Sostituisci i parametri dei servizi
L'API v2 utilizza una proprietà booleana per ogni servizio:
L'API v3 utilizza un array obbligatorio:
| API v2 | API v3 | Nota |
|---|---|---|
details: true | "details" in services | |
insurance: true | "insurance" in services | |
emissions: true | "emissions" in services | |
licenseEligibility: true | "license" in services | |
inspection: true | "inspection" in services | |
theft: true | "theft" in services |
L'API v3 non seleziona servizi predefiniti. services deve contenere almeno un valore e non può contenere duplicati.
3. Aggiorna la lettura del risultato
L'API v2 restituisce gran parte dei dati direttamente in data:
L'API v3 raggruppa i dati del veicolo:
Dati generali e veicolo
Nell'API v3 i dati tecnici e identificativi sono raggruppati in vehicle.
| API v2 | API v3 | Nota |
|---|---|---|
type | vehicleType | Tipologia utilizzata per la richiesta. |
timestamp | lookedUpAt | Timestamp Unix in millisecondi. |
brand | vehicle.brand | |
model | vehicle.model | |
config | vehicle.trim | |
vin | vehicle.vin | |
details.type | vehicle.category | |
details.use | vehicle.use | Valore canonico nell'API v3. |
details.age | — | Non presente nell'API v3. |
details.ageYears | — | Non presente nell'API v3. |
engine.fuel | vehicle.engine.energySources | Array di fonti energetiche canoniche. |
engine.fuel | vehicle.engine.powertrain | Sistema di propulsione, quando determinabile. |
engine.kw | vehicle.engine.powerKw | |
engine.hp | vehicle.engine.powerMetricHp | Cavalli metrici. |
engine.cc | vehicle.engine.displacementCc |
I valori disponibili sono documentati nella sezione Alimentazione e propulsione.
Assicurazione
Il contenitore rimane insurance.
| API v2 | API v3 | Nota |
|---|---|---|
insurance.compliant | insurance.compliant | |
insurance.hasInsurance | insurance.hasInsurance | |
insurance.isSuspended | insurance.isSuspended | |
insurance.insuranceCompany | insurance.insurer | |
insurance.policyNumber | insurance.policyNumber | |
insurance.policyExpiryDate | insurance.policyExpiryDate | Formato YYYY-MM-DD nell'API v3. |
insurance.policyExpiryTimestamp | — | Non presente nell'API v3. |
insurance.coverExpiryDate | insurance.coverageExpiryDate | Formato YYYY-MM-DD nell'API v3. |
insurance.coverExpiryTimestamp | — | Non presente nell'API v3. |
insurance.refreshedAt | insurance.observedAt |
Emissioni
Il contenitore rimane emissions.
| API v2 | API v3 | Nota |
|---|---|---|
emissions.class | emissions.euroClass | Da stringa a oggetto strutturato. |
emissions.refreshedAt | emissions.observedAt |
La classe ambientale non è più una stringa. L'API v3 separa il livello Euro, l'eventuale fase e il regime applicabile:
La struttura completa è documentata nella sezione Classe ambientale.
Neopatentati
Il contenitore licenseEligibility diventa license.
| API v2 | API v3 | Nota |
|---|---|---|
licenseEligibility.noviceDriver | license.noviceDriverEligible | |
licenseEligibility.refreshedAt | license.observedAt |
Revisione
Il contenitore rimane inspection. Lo storico è ordinato dalla revisione più recente.
| API v2 | API v3 | Nota |
|---|---|---|
inspection.compliant | inspection.compliant | |
inspection.initialDueDate | inspection.initialDueDate | Formato YYYY-MM-DD nell'API v3. |
inspection.initialDueTimestamp | — | Non presente nell'API v3. |
inspection.nextDueDate | inspection.nextDueDate | Formato YYYY-MM-DD nell'API v3. |
inspection.nextDueTimestamp | — | Non presente nell'API v3. |
inspection.history[].date | inspection.history[].date | Formato YYYY-MM-DD nell'API v3. |
inspection.history[].status | inspection.history[].outcome | |
inspection.history[].km | inspection.history[].odometerKm | |
inspection.history[].timestamp | — | Non presente nell'API v3. |
inspection.history[].successful | — | Non presente nell'API v3. |
inspection.lastInspection | — | Utilizzare history[0]. |
inspection.refreshedAt | inspection.observedAt |
Furto
Nell'API v3 l'esito della ricerca è rappresentato da report.
| API v2 | API v3 | Nota |
|---|---|---|
theft.exists: false | theft.report: false | Nessuna denuncia rilevata. |
theft.exists: true e theft.data | theft.report | Oggetto con i dettagli della denuncia. |
theft.data.date | theft.report.date | Formato YYYY-MM-DD nell'API v3. |
theft.data.location | theft.report.location | |
theft.data.timestamp | — | Non presente nell'API v3. |
theft.data.type | — | Non presente nell'API v3. |
theft.lastUpdatedAt | theft.registryUpdatedDate | Formato YYYY-MM-DD nell'API v3. |
theft.refreshedAt | theft.observedAt |
La struttura completa dei campi è documentata nella pagina Risposta.
4. Gestisci l'esito dei servizi
L'API v3 include l'esito finale di ogni servizio richiesto:
Gli esiti possibili sono documentati nella pagina Servizi.
La presenza di un contenitore non sostituisce il relativo esito. Leggi sempre services per determinare il risultato dell'operazione richiesta.
5. Aggiorna date e valori assenti
Le date civili utilizzano il formato ISO YYYY-MM-DD.
La data di immatricolazione include anche la precisione:
L'API v2 utilizza frequentemente null per i dati mancanti. L'API v3 omette la proprietà.
false, 0 e gli array vuoti rimangono valori espliciti e non devono essere trattati come dati mancanti.
Verifica della migrazione
Prima di utilizzare l'API v3:
- sostituisci l'endpoint dell'API v2 con
/v3/query; - utilizza esclusivamente
POST; - sposta la targa nel corpo JSON;
- sostituisci i parametri booleani con
services; - aggiorna i percorsi dei campi;
- gestisci l'esito di ogni servizio;
- gestisci i campi assenti senza affidarti a
null; - aggiorna il parsing delle date.