So machen Sie in Händlersoftware aus einer VIN oder einer Bestandsliste ein Foto für jedes Fahrzeug

Ein Bestandsdatensatz in einem CRM, einem ERP oder einem Dealer-Management-System beginnt mit einer VIN, einer Bestandsnummer und einem Preis. Das Foto kommt, wenn der Fotograf auf den Hof kommt, und bei manchen Fahrzeugen kommt es nie: ein Fahrzeug, das noch unterwegs ist, eine Inzahlungnahme, die noch aufbereitet wird, ein Import, dessen Modellname zu nichts im Bild-Feed des DMS passt, ein Auto aus den 1990ern, für das nie jemand ein Pressefoto lizenziert hat. Jeder Bildschirm, der diesen Datensatz zeigt – die Liste des Verkäufers, die Bewertung des Einkäufers, das Angebot für den Kunden –, zeigt stattdessen einen grauen Platzhalter.

Die Händler- und Import-Tools auf Basis der API füllen diesen Platzhalter mit dem, was der Datensatz bereits enthält. Hat er eine VIN, ist das Bild nur eine kostenlose Dekodierung entfernt. Steht er nur als Zeile in einer Bestandsliste, führt die Freitext-Auflösung (resolve) ans Ziel. So oder so enthält der Datensatz am Ende eine stabile Fahrzeug-ID, und jeder Bildschirm stellt dasselbe Fahrzeug auf dieselbe Weise dar.

• Bei der Aufnahme dekodieren. Die VIN wird einmal dekodiert, wenn der Datensatz angelegt wird, und die Fahrzeug-ID aus dem Katalog wird daneben gespeichert. Nichts im weiteren Verlauf schreibt eine Marke oder ein Modell aus.
• Eine Ansicht für die Liste, eine für die Detailseite. Eine gerade side-Ansicht in breitem Format für Bestandslisten; front-3-4 für die Detailseite und das Angebot.
• Weit zurückreichende Baujahre. Import- und Gebrauchtwagenbestand reicht bis in die 1990er zurück und wird wie die Neuzugänge gerendert: Der Katalog umfasst 1990 bis zum aktuellen Modelljahr, japanische Inlandsmodelle eingeschlossen.
• Signierte URLs in der App. Das CRM läuft im Browser, daher lädt es schlüsselfreie, vom Server erzeugte signierte URLs, bis zu fünfzig pro Aufruf, die sich für Datensätze verlängern, die länger als eine Woche bestehen.

GET /api/v1/vin/{vin} kostet nichts und benötigt nur einen API-Schlüssel. Der Endpoint liefert Modelljahr, Marke, Modell, Ausstattungslinie, Karosserieklasse, Motor und jedes weitere Attribut, das die vPIC-Daten der NHTSA kennen, und – wenn der Katalog das Fahrzeug enthält – ein vehicle-Objekt mit seiner stabilen ID und einem fertigen image_path. Auch unvollständige VINs funktionieren: mindestens fünf Zeichen, * für jede unbekannte Stelle, plus ein optionaler year-Hinweis.

Importbestand kommt oft als Tabelle: ein Baujahr, eine Marke, ein Modellname in der Schreibweise, die das Auktionshaus verwendet hat, ein Grade- oder Ausstattungscode. POST /api/v1/images/resolve ist kostenlos und deterministisch: Der Endpunkt extrahiert Baujahr-, Farb- und Ansichtsbegriffe aus der Phrase, durchsucht den Katalog mit dem Rest und liefert exakte Parameter mit einem Konfidenzwert, auf dessen Grundlage Sie handeln können.

Das Fahrzeug stimmt (der Toyota Voxy von 2019), aber die Konfidenz ist low, weil „ZS“ eine Ausstattungslinie ist, die der Katalog nicht kennt, und um sie herum abgeglichen werden musste. Behandeln Sie bei einem Batch-Import high als erledigt und legen Sie medium und low zusammen mit der candidates-Liste einem Menschen vor. Wenn die Liste Baujahr und Marke bereits in eigenen Spalten enthält, senden Sie sie als Felder year und make und lassen Sie nur das Modell in query; der Abgleich wird dadurch deutlich sauberer. Eine Eingabe ohne Fahrzeugbegriffe ergibt einen 400, und eine Marke ohne passendes Modell einen 404, der die Baujahre der Marke auflistet, damit Sie nach dem Modell fragen können.

Egal, auf welchem Weg Sie dorthin gelangt sind: Speichern Sie vehicle.id (oder params.vehicle_id) im Bestandsdatensatz als einfache String-Spalte. Die ID ist deterministisch und dauerhaft: Dasselbe Fahrzeug hat bei jedem Deploy und nach jedem Katalog-Release dieselbe ID, sie eignet sich also sicher als Fremdschlüssel. Ab dann lautet jede Bildanfrage vehicle=veh_…, was sich nicht falsch schreiben lässt, und eine vom Hersteller umbenannte oder von einer Quelle neu eingeordnete Marke macht nie eine gespeicherte URL ungültig.

Bestandslisten sind breit und flach, daher ist die gerade Seitenansicht in einem 2:1-Rahmen die übliche Wahl: Jedes Fahrzeug zeigt in dieselbe Richtung und steht auf derselben Grundlinie. trim=1&padding=6 beschneidet das Bild vor dem Einpassen auf das Auto, sodass ein Hilux und ein Yaris die Zeile gleich ausfüllen; fit=contain hält die Leinwand exakt bei 640×320 mit transparenten Rändern. Die Detailseite verwendet front-3-4 bei 1024, und beide teilen sich einen Cache: Eine nicht angegebene Lackfarbe ist bei beiden Silber.

Das CRM läuft im Browser, und ein Browser darf niemals den API-Schlüssel enthalten. Wenn eine Ansicht eine Seite des Bestands auflistet, erzeugt der Server mit POST /api/v1/image-urls eine signierte URL pro Datensatz (bis zu fünfzig pro Aufruf, je ein Credit), und die Seite lädt sie wie jedes andere Bild. Für einen Datensatz, der monatelang im Bestand bleibt, sind zwei Einstellungen wichtig:

• ttl_seconds: 604800 mit renew: true: Die URL funktioniert über die siebentägige TTL hinaus, und jede weitere Woche, in der jemand den Datensatz tatsächlich öffnet, kostet einen weiteren Credit. Wochen, in denen niemand das Fahrzeug ansieht, kosten nichts.
• Ein Idempotency-Key pro Seite der Synchronisierung: Eine wiederholte Anfrage spielt die erste Antwort erneut ab und erzeugt nichts doppelt.

Beschränken Sie den Schlüssel, der die URLs erzeugt, im Dashboard auf die Origin des CRM, dann antwortet eine URL, die auf eine andere Website gelangt, mit 403. Wird der Schlüssel widerrufen, werden alle von ihm erzeugten URLs ungültig. Sollte das Guthaben einmal aufgebraucht sein, antwortet eine Verlängerung mit 402, und dieselbe URL funktioniert wieder, sobald Credits eingehen; die automatische Aufladung beseitigt diese Fehlerquelle. Den vollständigen Lebenszyklus finden Sie in der Dokumentation zu signierten URLs.

• SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) und client.createImageUrls(…), wie oben.
• MCP: decode_vin, resolve_vehicle, get_car_image und create_car_image_urls gehören zum Kern-Toolset, sodass ein Assistent mit dem Bestandssystem im Kontext „Foto für Bestand 4471“ anhand der VIN im Datensatz beantworten kann. Die Einrichtung finden Sie auf der MCP-Seite, die Felder und Fehler des Decoders in der VIN-Dokumentation.