Zo maakt u in dealersoftware van een VIN of een voorraadlijst een foto voor elk voertuig

Een voorraadrecord in een CRM, een ERP of een dealermanagementsysteem begint als een VIN, een voorraadnummer en een prijs. De foto komt pas als de fotograaf langskomt, en voor sommige voorraad komt die er nooit: een auto die nog onderweg is, een inruilauto die nog wordt opgeknapt, een import waarvan de modelnaam met niets in de beeldfeed van het DMS overeenkomt, een auto uit de jaren 90 waarvan niemand ooit een persfoto in licentie heeft genomen. Elk scherm dat dat record toont, de lijst van de verkoper, de taxatie van de inkoper, de offerte voor de klant, toont in plaats daarvan een grijze placeholder.

De dealer- en importtools op de API vullen die placeholder met wat het record al bevat. Heeft het een VIN, dan is de afbeelding slechts één gratis decodering verwijderd. Staat er alleen een regel op een voorraadlijst, dan komt resolve met vrije tekst er ook. Hoe dan ook bevat het record uiteindelijk een stabiel voertuig-id, en toont elk scherm dezelfde auto op dezelfde manier.

• Decoderen bij intake. Het VIN wordt één keer gedecodeerd, bij het aanmaken van het record, en het voertuig-id uit de catalogus wordt ernaast opgeslagen. Niets verderop in de keten spelt een merk of model uit.
• Eén aanzicht voor de lijst, één voor de detailpagina. Een recht side-aanzicht in een breed kader voor voorraadlijsten; front-3-4 voor de detailpagina en de offerte.
• Ver terug in de tijd. Import- en occasionvoorraad gaat terug tot de jaren negentig en wordt net zo gerenderd als de nieuwe binnenkomers: de catalogus loopt van 1990 tot het huidige modeljaar, inclusief modellen voor de Japanse thuismarkt.
• Ondertekende URL's in de app. Het CRM draait in een browser, dus laadt het ondertekende URL's zonder sleutel die de server aanmaakt, tot vijftig per aanroep, en vernieuwt die voor records die langer dan een week bestaan.

GET /api/v1/vin/{vin} kost niets en vereist alleen een API-key. Het geeft het gedecodeerde jaar, merk, model, uitvoering, carrosserietype, motor en elk ander attribuut terug dat de vPIC-gegevens van NHTSA kennen, en, als de catalogus het voertuig bevat, een vehicle-object met het stabiele id en een kant-en-klaar image_path. Gedeeltelijke VIN's werken ook: minimaal vijf tekens, * voor elke onbekende positie, plus een optionele year-hint.

Importvoorraad komt vaak binnen als spreadsheet: een bouwjaar, een merk, een modelnaam in de spelling die het veilinghuis toevallig gebruikte, een grade- of uitvoeringscode. POST /api/v1/images/resolve is gratis en deterministisch: het haalt de woorden voor jaar, kleur en aanzicht uit de zin, doorzoekt de catalogus met wat overblijft en geeft exacte parameters terug met een betrouwbaarheidsscore waarop u kunt handelen.

Het voertuig klopt (de Toyota Voxy uit 2019), maar de betrouwbaarheid is low, omdat "ZS" een uitvoering is die de catalogus niet kent en eromheen moest worden gematcht. Behandel bij een batchimport high als afgerond, en leg medium en low met de lijst candidates voor aan een mens. Staan het bouwjaar en merk al in eigen kolommen in de lijst, stuur ze dan mee als de velden year en make en laat alleen het model in query staan; de match wordt dan veel zuiverder. Een zin zonder voertuigwoorden geeft een 400, en een merk zonder passend model een 404 met de bouwjaren van dat merk, zodat u naar het model kunt vragen.

Welke route u ook hebt genomen, sla vehicle.id (of params.vehicle_id) op in het voorraadrecord als een gewone tekstkolom. Deze is deterministisch en permanent: hetzelfde voertuig heeft dezelfde id bij elke deploy en na elke catalogusrelease, dus hij is veilig als foreign key. Vanaf dat moment is elk afbeeldingsverzoek vehicle=veh_…, wat niet verkeerd gespeld kan worden, en een merk dat door een fabrikant is hernoemd of door een bron anders is ingedeeld, maakt nooit een opgeslagen URL kapot.

Voorraadlijsten zijn breed en laag, dus het rechte zijaanzicht in een 2:1-kader is de gebruikelijke keuze: elk voertuig kijkt dezelfde kant op en staat op dezelfde basislijn. trim=1&padding=6 snijdt bij tot de auto voordat er wordt ingepast, zodat een Hilux en een Yaris de rij op dezelfde manier vullen; fit=contain houdt het canvas precies 640×320 met transparante marges. De detailpagina gebruikt front-3-4 op 1024, en de twee delen een cache: een lakkleur die u niet opgeeft, is op beide zilver.

Het CRM draait in een browser, en een browser mag nooit de API-sleutel bevatten. Als een scherm een pagina met voorraad toont, maakt de server per record één ondertekende URL aan met POST /api/v1/image-urls (tot vijftig per aanroep; de afbeelding van elke URL telt als voertuigafbeelding van de maand) en laadt de pagina ze als elke andere afbeelding. Twee instellingen zijn belangrijk voor een record dat maandenlang op voorraad blijft:

• ttl_seconds: 604800 met renew: true: de URL blijft werken na de TTL van zeven dagen, en een verlenging telt de afbeelding één keer in de maand waarin die plaatsvindt, en niets extra als de afbeelding die maand al was geteld. Maanden waarin niemand de auto bekijkt, tellen niets.
• Een Idempotency-Key per pagina van de synchronisatie: een herhaald verzoek geeft opnieuw het eerste antwoord terug en maakt niets dubbel aan.

Beperk de sleutel waarmee u URL’s aanmaakt in het dashboard tot de origin van het CRM, dan geeft een URL die op een andere site terechtkomt 403 terug. Als u de sleutel intrekt, worden alle URL’s ongeldig die ermee zijn aangemaakt. Als de voertuigafbeeldingen van het abonnement voor de maand op zijn, geeft een verlenging 402 terug en werkt dezelfde URL weer zodra het tegoed wordt gereset of het abonnement wordt verhoogd. De volledige levenscyclus staat in de documentatie over ondertekende URL’s.

• SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) en client.createImageUrls(…), zoals hierboven.
• MCP: decode_vin, resolve_vehicle, get_car_image en create_car_image_urls zitten in de kerntoolset, zodat een assistent met het voorraadsysteem in zijn context "foto voor voorraadnummer 4471" kan beantwoorden op basis van de VIN in het record. De installatie staat op de MCP-pagina; de velden en foutmeldingen van de decoder staan in de VIN-documentatie.