Immagini di auto per sinistri e preventivi assicurativi

Un modulo di preventivo, una scheda di polizza e una prima denuncia di sinistro identificano tutti il veicolo allo stesso modo: tramite il VIN, digitato da un cliente o letto da un documento di immatricolazione. Tutto ciò che una persona vede poi dell'auto è testo: un anno, una marca, un modello e forse un allestimento. Chiedere «È questo il suo veicolo?» accanto a una riga di testo invita a rispondere sì a qualsiasi cosa.

Un'immagine del modello corrispondente al VIN permette al cliente e al perito di verificare a colpo d'occhio che la pratica indichi il tipo di auto giusto. Non può mostrare quale auto: un render è un'illustrazione da studio di marca, modello e anno di catalogo e non raffigura alcun veicolo fisico specifico. Questo solo fatto determina l'intera integrazione descritta di seguito.

• Decodifica all'acquisizione. Il flusso di preventivo o il sistema delle polizze decodifica il VIN una sola volta, gratuitamente, e salva l'ID veicolo del catalogo con la polizza. I sinistri aperti sulla polizza lo ereditano.
• Una sola vista ovunque. front-3-4, l'angolazione principale, in un unico riquadro nella schermata del preventivo, nell'area di gestione sinistri, nel PDF del preventivo e nel portale delle polizze, così ogni schermata mostra il modello allo stesso modo.
• URL firmati, mai la chiave. Browser e renderer PDF caricano URL senza chiave generati dal Suo server.
• Parole per ciò che un'immagine non può dire. Allestimento, optional, colore registrato, danni e chilometraggio restano testo e foto, e l'immagine indica di essere rappresentativa.

GET /api/v1/vin/{vin} è gratuito e richiede una chiave con images:read. Restituisce i campi decodificati dai dati vPIC di NHTSA (anno, marca, modello, allestimento, serie, tipo di carrozzeria, motore e ogni altro attributo noto a vPIC) e, quando il catalogo contiene il veicolo, un oggetto vehicle con il suo id stabile e un image_path pronto all'uso.

Legga il campo trim: "Carrera, Carrera T, Carrera 4". Lo schema di questo VIN copre tre allestimenti, quindi nemmeno la decodifica può dire quale assicura la polizza, e tanto meno un render della 911 del 2024. Chieda al cliente di confermare l'allestimento, lo conservi come testo insieme a series e body_class e lasci che l'immagine mostri il modello.

• Un VIN con una cifra di controllo errata viene comunque decodificato, con valid: false e il problema in errors; suggested_vin contrassegna con ! il carattere che vPIC ritiene errato, ed è ciò da mostrare a chi sta digitando.
• Un modulo che dispone solo dei primi caratteri può inviare un VIN parziale: almeno cinque caratteri, con * per ogni posizione sconosciuta e un year facoltativo.
• Un 404 significa che vPIC non ha alcun record per lo schema. vPIC copre i veicoli prodotti per il mercato statunitense, quindi per altri mercati parta da marca e modello con POST /api/v1/images/resolve, anch’esso gratuito.

Memorizzi data.vehicle.id nella polizza come semplice stringa e lo copi in ogni sinistro aperto su di essa. L'id è deterministico e permanente: lo stesso veicolo ha lo stesso id in ogni deploy e dopo ogni release del catalogo, quindi è sicuro come chiave esterna, e ogni richiesta successiva indica vehicle=veh_78qtwrgh37bkr invece di specificare marca e modello.

Quando data.vehicle è null, la marca e il modello decodificati non sono presenti nel catalogo, come accade con rimorchi e alcuni telai commerciali. I campi decodificati restano comunque a Sua disposizione. Li mostri senza immagine e non metta mai un'auto simile al loro posto.

La schermata dei preventivi, la postazione di gestione sinistri e il portale delle polizze sono app per browser, quindi il Suo server genera URL firmati con POST /api/v1/image-urls: ogni URL conteggia la sua immagine come immagine di veicolo del mese al momento della generazione, fino a 50 per chiamata, e si può caricare gratuitamente fino alla scadenza. Inquadri l’immagine una volta e riutilizzi la stessa forma: front-3-4 in un riquadro 640×400 con fit: "contain", e trim con un po’ di padding, così una coupé e un pickup riempiono il riquadro allo stesso modo. Quanto debba durare ogni URL dipende da dove viene mostrato:

• La postazione di gestione sinistri. Generi l'URL quando la schermata viene visualizzata. La durata predefinita di 1 ora copre una sessione di lavoro, e un sinistro riaperto domani riceve un nuovo URL.
• Il PDF del preventivo. Quando il PDF viene generato da HTML, il renderer carica l’immagine una volta e la incorpora, quindi la durata predefinita è più che sufficiente e il servizio PDF non detiene mai la Sua chiave. format: "jpg" appiattisce l’immagine su sfondo bianco, che è ciò che serve a un documento.
• Il portale delle polizze e l'email di rinnovo. Restano in uso più a lungo di qualsiasi durata massima, quindi generi gli URL con renew: true e ttl_seconds: 604800 (7 giorni). L'URL continua a funzionare, un rinnovo conteggia l'immagine una volta nel mese in cui avviene, e nulla di più se era già stata conteggiata quel mese, e renew_days: 365, il massimo consentito, copre una polizza di durata annuale.

Assegni alla chiave che genera gli URL un elenco di origini consentite nella dashboard: un URL caricato da un altro sito risponde 403 con origin_not_allowed, mentre i client email e i visualizzatori PDF, che non inviano alcun Referer, lo caricano comunque. La revoca della chiave invalida tutti gli URL che ha generato.

Metta l’etichetta dove si trova l’immagine, non solo in una nota a piè di pagina: nel testo alternativo e in una didascalia sotto l’immagine. Il render mostra marca, modello e anno in una vernice a Sua scelta, e color può seguire il colore indicato in polizza (il nome di un preset o qualsiasi hex). Resta comunque il modello in quella vernice, non l’auto del cliente.

• Gratuiti: la decodifica del VIN, resolve, le ricerche nel catalogo e ogni caricamento di un URL firmato entro la sua validità.
• Un’immagine di veicolo: ogni veicolo in ogni colore e vista, conteggiato una volta al mese indipendentemente da quante volte viene distribuito, generato o rinnovato, in qualsiasi dimensione e formato.
• Immagini di veicoli al mese: un funnel di preventivi vede molti veicoli diversi, e ogni piano ne include un certo numero al mese: Free 100, Pro 2500 e Business 10.000; Enterprise è su trattativa. Un’immagine già conteggiata questo mese viene sempre servita, e una richiesta oltre la quota risponde 402 prima che venga conteggiato qualcosa, quindi scelga il piano in base ai veicoli per cui emette preventivi.

Con un piano a pagamento, la licenza copre un render all’interno di ciò che il Suo prodotto genera per i propri utenti, inclusi un preventivo o un report, per tutto il tempo in cui il piano è attivo; i dettagli sono nella licenza.

• SDK: client.decodeVin(vin, { year? }) e client.createImageUrls(…), come sopra; client.resolve(query) per un veicolo senza VIN.
• MCP: decode_vin e create_car_image_urls fanno parte del set di strumenti principale, quindi un assistente con il sinistro nel contesto può rispondere a "mostrami il modello assicurato" partendo dal VIN registrato. La configurazione è nella pagina MCP.