Come trasformare un VIN o un elenco dello stock in una foto per ogni veicolo in un software per concessionari

Una scheda di veicolo in giacenza in un CRM, in un ERP o in un gestionale per concessionari (DMS) nasce come VIN, numero di stock e prezzo. La foto arriva quando arriva il fotografo del piazzale, e per alcuni veicoli non arriva mai: un'unità in transito, una permuta ancora in fase di ricondizionamento, un veicolo d'importazione il cui nome di modello non corrisponde a nulla nel feed di immagini del DMS, un'auto degli anni '90 di cui nessuno ha mai acquistato in licenza una foto stampa. Ogni schermata che mostra quella scheda, l'elenco del venditore, la valutazione dell'acquirente, il preventivo del cliente, mostra invece un segnaposto grigio.

Gli strumenti per concessionari e importatori sull’API riempiono quel segnaposto con ciò che il record contiene già. Se ha un VIN, l’immagine è a una decodifica gratuita di distanza. Se ha solo una riga in un elenco di stock, ci arriva il resolve a testo libero. In ogni caso il record finisce per contenere un id veicolo stabile e ogni schermata mostra la stessa auto nello stesso modo.

• Decodifica all'acquisizione. Il VIN viene decodificato una sola volta, alla creazione del record, e l'ID del veicolo nel catalogo viene salvato accanto a esso. Nessun passaggio a valle scrive una marca o un modello.
• Una vista per l'elenco, una per il dettaglio. Una vista side pura in un riquadro largo per gli elenchi dello stock; front-3-4 per la pagina di dettaglio e il preventivo.
• Anni lontani. Lo stock di importazione e usato risale agli anni ’90 e viene renderizzato come i nuovi arrivi: il catalogo copre dal 1990 all’anno modello corrente, incluse le denominazioni del mercato interno giapponese.
• URL firmati all'interno dell'app. Il CRM gira nel browser, quindi carica URL firmati senza chiave generati dal server, fino a cinquanta per chiamata, rinnovandoli per i record che restano attivi più di una settimana.

GET /api/v1/vin/{vin} è gratuito e richiede solo una chiave API. Restituisce anno, marca, modello, allestimento, tipo di carrozzeria e motore decodificati, insieme a ogni altro attributo noto ai dati vPIC della NHTSA e, quando il catalogo contiene il veicolo, un oggetto vehicle con il suo id stabile e un image_path già pronto. Funzionano anche i VIN parziali: almeno cinque caratteri, * per ogni posizione sconosciuta, più un suggerimento year facoltativo.

Le auto d'importazione arrivano spesso sotto forma di foglio di calcolo: un anno, una marca, un nome di modello scritto come l'ha scritto la casa d'aste, un codice di grado o di allestimento. POST /api/v1/images/resolve è gratuito e deterministico: estrae dalla frase le parole relative ad anno, colore e vista, cerca nel catalogo con ciò che resta e restituisce parametri esatti con un livello di confidenza su cui può basarsi.

Il veicolo è corretto (la Toyota Voxy del 2019) ma la confidenza è low, perché "ZS" è un allestimento che il catalogo non conosce e la corrispondenza ha dovuto aggirarlo. In un’importazione batch, consideri high come risolto e sottoponga medium e low a una persona insieme all’elenco candidates. Quando il foglio ha già anno e marca in colonne separate, li invii nei campi year e make e lasci solo il modello in query; la corrispondenza diventa molto più precisa. Una frase senza termini relativi a veicoli restituisce un 400, e una marca senza un modello corrispondente restituisce un 404 che elenca gli anni della marca, così può chiedere il modello.

Qualunque sia il percorso seguito, memorizzi vehicle.id (o params.vehicle_id) nel record di magazzino come semplice colonna di tipo stringa. È deterministico e permanente: lo stesso veicolo ha lo stesso id in ogni deploy e dopo ogni rilascio del catalogo, quindi è sicuro come chiave esterna. Da quel momento ogni richiesta di immagine è vehicle=veh_…, che non può essere scritta in modo errato, e una marca rinominata da un produttore o riclassificata da una fonte non rompe mai un URL memorizzato.

Gli elenchi di inventario sono larghi e bassi, quindi la vista laterale dritta in un riquadro 2:1 è la scelta abituale: ogni veicolo è rivolto nella stessa direzione e poggia sulla stessa linea di base. trim=1&padding=6 ritaglia sull’auto prima di adattarla, così un Hilux e una Yaris riempiono la riga allo stesso modo; fit=contain mantiene la tela esattamente a 640×320 con margini trasparenti. La pagina di dettaglio usa front-3-4 a 1024 e le due condividono una cache: una vernice non specificata è argento in entrambe.

Il CRM gira in un browser, e un browser non deve mai contenere la chiave API. Quando una schermata elenca una pagina di veicoli in stock, il server genera un URL firmato per record con POST /api/v1/image-urls (fino a cinquanta per chiamata; l'immagine di ogni URL conta come immagine di veicolo del mese) e la pagina li carica come qualsiasi immagine. Per un record che resta in stock per mesi contano due impostazioni:

• ttl_seconds: 604800 con renew: true: l'URL continua a funzionare oltre il TTL di sette giorni, e un rinnovo conta l'immagine una volta nel mese in cui avviene, e nulla di più se era già stata conteggiata in quel mese. I mesi in cui nessuno guarda l'auto non contano nulla.
• Una Idempotency-Key per ogni pagina della sincronizzazione: una richiesta ripetuta riproduce la prima risposta e non genera nulla due volte.

Limiti la chiave di generazione all’origine del CRM dalla dashboard e un URL finito su un altro sito risponderà 403. Revocare la chiave invalida tutti gli URL che ha generato. Se le immagini di veicoli del piano per il mese sono esaurite, un rinnovo risponde 402 e lo stesso URL torna a funzionare quando la quota si azzera o il piano viene aggiornato. Il ciclo di vita completo è nella documentazione sugli URL firmati.

• SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) e client.createImageUrls(…), come sopra.
• MCP: decode_vin, resolve_vehicle, get_car_image e create_car_image_urls fanno parte del set di strumenti principale, quindi un assistente con il gestionale dello stock nel contesto può rispondere a "foto per lo stock 4471" partendo dal VIN nel record. La configurazione è nella pagina MCP; i campi e gli errori del decoder sono nella documentazione VIN.