Fahrzeugbilder für Schadensmeldungen und Versicherungsangebote

Ein Angebotsformular, ein Versicherungsdatensatz und eine Schadenmeldung benennen das Fahrzeug alle auf dieselbe Weise: über seine VIN, vom Kunden eingegeben oder aus einem Zulassungsdokument abgelesen. Alles, was eine Person danach über das Auto sieht, ist Text: ein Baujahr, eine Marke, ein Modell und vielleicht eine Ausstattungsvariante. Wer neben einer Textzeile fragt „Ist das Ihr Fahrzeug?“, lädt dazu ein, zu allem Ja zu sagen.

Ein Bild des Modells, zu dem die VIN decodiert wird, lässt Kunde und Sachbearbeiter auf einen Blick prüfen, ob der Datensatz die richtige Art von Auto nennt. Welches Auto es genau ist, kann es nicht zeigen: Ein Rendering ist eine Studio-Illustration einer Marke, eines Modells und eines Jahres aus dem Katalog und stellt kein bestimmtes physisches Fahrzeug dar. Diese eine Tatsache prägt die gesamte unten beschriebene Integration.

• Bei der Erfassung decodieren. Der Angebotsprozess oder das Policensystem decodiert die VIN einmal kostenlos und speichert die Fahrzeug-ID des Katalogs mit der Police. Schadensfälle zu dieser Police übernehmen sie.
• Eine Ansicht überall. front-3-4, die Hauptansicht, in einem einheitlichen Rahmen auf dem Angebotsbildschirm, im Schadenbearbeitungs-Arbeitsplatz, im Angebots-PDF und im Kundenportal, sodass jeder Bildschirm das Modell auf dieselbe Weise zeigt.
• Signierte URLs, nie der Schlüssel. Browser und PDF-Renderer laden schlüsselfreie URLs, die Ihr Server erzeugt.
• Text für das, was ein Bild nicht sagen kann. Ausstattung, Optionen, die eingetragene Farbe, Schäden und Kilometerstand bleiben Text und Fotos, und am Bild steht, dass es nur beispielhaft ist.

GET /api/v1/vin/{vin} ist kostenlos und erfordert einen Schlüssel mit images:read. Die Antwort enthält die decodierten Felder aus den vPIC-Daten der NHTSA (Baujahr, Marke, Modell, Ausstattungslinie, Serie, Karosserieklasse, Motor und jedes weitere Attribut, das vPIC kennt) und, wenn der Katalog das Fahrzeug enthält, ein vehicle-Objekt mit seiner stabilen ID und einem fertigen image_path.

Lesen Sie trim: „Carrera, Carrera T, Carrera 4“. Das Muster dieser VIN umfasst drei Ausstattungsvarianten, daher kann nicht einmal die Dekodierung sagen, welche davon die Police versichert, und ein Rendering des 911 von 2024 erst recht nicht. Bitten Sie den Kunden, die Ausstattungsvariante zu bestätigen, speichern Sie sie zusammen mit series und body_class als Text, und lassen Sie das Bild das Modell zeigen.

• Eine VIN mit falscher Prüfziffer wird trotzdem dekodiert, mit valid: false und dem Problem in errors; suggested_vin markiert das Zeichen, das vPIC für falsch hält, mit ! – genau das sollten Sie der Person zeigen, die die VIN eingibt.
• Ein Formular, das nur die ersten Zeichen kennt, kann eine unvollständige VIN senden: mindestens fünf Zeichen, mit * für jede unbekannte Stelle und optional einem year.
• Ein 404 bedeutet, dass vPIC kein passendes Muster kennt. vPIC deckt Fahrzeuge für den US-Markt ab; für andere Märkte beginnen Sie daher mit Marke und Modell über POST /api/v1/images/resolve, das ebenfalls kostenlos ist.

Speichern Sie data.vehicle.id als einfachen String an der Police und kopieren Sie den Wert in jeden Schadenfall, der dazu eröffnet wird. Die ID ist deterministisch und dauerhaft: Dasselbe Fahrzeug hat bei jedem Deployment und nach jedem Katalog-Release dieselbe ID. Sie eignet sich also bedenkenlos als Fremdschlüssel, und jede spätere Anfrage nennt vehicle=veh_78qtwrgh37bkr, statt Marke und Modell auszuschreiben.

Wenn data.vehicle null ist, sind die decodierte Marke und das Modell nicht im Katalog, etwa bei Anhängern und manchen Nutzfahrzeug-Fahrgestellen. Die decodierten Felder können Sie trotzdem anzeigen. Zeigen Sie sie ohne Bild an, und setzen Sie nie ein ähnliches Auto an seine Stelle.

Die Angebotsansicht, der Arbeitsplatz für Schadenfälle und das Policenportal sind Browser-Apps, daher erzeugt Ihr Server signierte URLs mit POST /api/v1/image-urls: 1 Credit pro URL beim Erzeugen, bis zu 50 pro Aufruf, und das Laden ist bis zum Ablauf kostenlos. Legen Sie den Bildausschnitt einmal fest und verwenden Sie dieselbe Form wieder: front-3-4 in einem 640×400-Rahmen mit fit: "contain" und trim mit etwas padding, damit ein Coupé und ein Pickup den Rahmen gleich ausfüllen. Wie lange jede URL gültig sein sollte, hängt davon ab, wo sie angezeigt wird:

• Der Arbeitsplatz für Schadenfälle. Erzeugen Sie die URL, wenn die Ansicht aufgebaut wird. Die Standardlaufzeit von 1 Stunde deckt eine Arbeitssitzung ab, und ein Schadenfall, der morgen erneut geöffnet wird, erhält eine neue URL.
• Das Angebots-PDF. Wird das PDF aus HTML gerendert, lädt der Renderer das Bild einmal und bettet es ein; die Standard-Lebensdauer reicht also völlig, und der PDF-Dienst hat nie Zugriff auf Ihren Key. format: "jpg" legt das Bild auf einen weißen Hintergrund, genau das, was ein Dokument braucht.
• Das Policenportal und die Verlängerungs-E-Mail. Diese überdauern jede Gültigkeitsdauer, erzeugen Sie die URL daher mit renew: true und ttl_seconds: 604800 (7 Tage). Die URL funktioniert weiterhin, jede weitere Woche, in der sie geöffnet wird, kostet 1 Credit, und renew_days: 365, der höchste zulässige Wert, deckt eine einjährige Versicherungslaufzeit ab.

Hinterlegen Sie für den Schlüssel, der die URLs erzeugt, im Dashboard eine Liste erlaubter Origins: Eine von einer anderen Website geladene URL antwortet mit 403 und origin_not_allowed, während E-Mail-Clients und PDF-Viewer, die keinen Referer senden, sie weiterhin laden. Wird der Schlüssel widerrufen, werden alle von ihm erzeugten URLs ungültig.

Platzieren Sie den Hinweis dort, wo das Bild ist, nicht nur in einer Fußnote: im Alt-Text und in einer Bildunterschrift. Das Rendering zeigt Marke, Modell und Baujahr in einer von Ihnen gewählten Lackfarbe, und color kann der Farbe in der Police folgen (ein Preset-Name oder ein beliebiger Hex-Wert). Es bleibt dennoch das Modell in dieser Farbe, nicht das Auto des Kunden.

• Kostenlos: die VIN-Decodierung, Resolve, Katalogabfragen und jeder Aufruf einer signierten URL innerhalb ihrer Gültigkeitsdauer.
• 1 Credit: für jedes an Ihren Server gelieferte Bild oder jede erzeugte URL sowie für jede weitere Woche, in der eine sich erneuernde URL geöffnet wird.
• Unterschiedliche Fahrzeuge: Ein Angebotsprozess sieht viele verschiedene Fahrzeuge, und jeder Plan begrenzt die Zahl unterschiedlicher Fahrzeuge pro Monat: Free 100, Pro 2.500 und Business 15.000; Enterprise ohne Obergrenze. Ein Fahrzeug, das in diesem Monat bereits ausgeliefert wurde, ist immer erlaubt. Eine Anfrage über dem Limit wird abgelehnt, bevor etwas berechnet wird. Wählen Sie den Plan also nach den Fahrzeugen, für die Sie Angebote erstellen, nicht nach den Credits.

Mit einem kostenpflichtigen Plan deckt die Lizenz ein Rendering in allem ab, was Ihr Produkt für seine Nutzer erstellt, auch in einem Angebot oder Bericht, solange der Plan aktiv ist; Einzelheiten finden Sie in der Lizenz.

• SDK: client.decodeVin(vin, { year? }) und client.createImageUrls(…) wie oben; client.resolve(query) für ein Fahrzeug ohne VIN.
• MCP: decode_vin und create_car_image_urls gehören zum Kern-Toolset, sodass ein Assistent mit dem Schadenfall im Kontext die Bitte „Zeig mir das versicherte Modell“ anhand der hinterlegten VIN beantworten kann. Die Einrichtung finden Sie auf der MCP-Seite.