Obrazy samochodów do likwidacji szkód i ofert ubezpieczeniowych

Formularz wyceny, polisa i pierwsze zgłoszenie szkody identyfikują pojazd w ten sam sposób: po numerze VIN wpisanym przez klienta lub odczytanym z dowodu rejestracyjnego. Wszystko, co człowiek potem widzi o samochodzie, to tekst: rok, marka, model i ewentualnie wersja wyposażenia. Pytanie „Czy to Państwa pojazd?” obok linijki tekstu zachęca do odpowiedzi „tak” na cokolwiek.

Obraz modelu wskazanego przez VIN pozwala klientowi i likwidatorowi szkód od razu sprawdzić, czy w dokumentacji figuruje właściwy typ samochodu. Nie pokazuje jednak, o który konkretnie samochód chodzi: render jest studyjną ilustracją marki, modelu i roku z katalogu i nie przedstawia żadnego konkretnego fizycznego pojazdu. Ten jeden fakt kształtuje całą opisaną niżej integrację.

• Dekodowanie przy przyjęciu. Proces wyceny lub system polis dekoduje VIN raz, bezpłatnie, i zapisuje identyfikator pojazdu z katalogu razem z polisą. Szkody zgłaszane w ramach polisy dziedziczą ten identyfikator.
• Jeden widok wszędzie. front-3-4, główne ujęcie, w jednym polu na ekranie wyceny, w stanowisku obsługi szkód, w PDF z wyceną i w portalu polis, dzięki czemu każdy ekran pokazuje model w ten sam sposób.
• Podpisane URL-e, nigdy klucz. Przeglądarki i generatory PDF wczytują URL-e bez klucza, generowane przez Państwa serwer.
• Słowa tam, gdzie obraz nie wystarczy. Wersja, wyposażenie dodatkowe, kolor w dokumentacji, uszkodzenia i przebieg pozostają w tekście i na zdjęciach, a przy obrazie widnieje informacja, że jest poglądowy.

GET /api/v1/vin/{vin} jest bezpłatny i wymaga klucza z uprawnieniem images:read. Zwraca zdekodowane pola z danych vPIC agencji NHTSA (rok, marka, model, wersja wyposażenia, seria, typ nadwozia, silnik i każdy inny atrybut znany vPIC), a gdy pojazd jest w katalogu – także obiekt vehicle z jego stałym id i gotową ścieżką image_path.

Proszę odczytać trim: „Carrera, Carrera T, Carrera 4”. Wzorzec tego VIN obejmuje trzy wersje wyposażenia, więc nawet dekodowanie nie określi, którą z nich obejmuje polisa, a render 911 z 2024 roku tym bardziej. Należy poprosić klienta o potwierdzenie wersji, zapisać ją jako tekst razem z series i body_class, a obraz niech pokazuje model.

• VIN z błędną cyfrą kontrolną nadal zostanie zdekodowany, z valid: false i opisem problemu w errors; suggested_vin oznacza znakiem ! pozycję, którą vPIC uważa za błędną — to właśnie należy pokazać osobie wpisującej numer.
• Formularz, który ma tylko pierwsze znaki, może wysłać częściowy VIN: co najmniej pięć znaków, z * w miejscu każdej nieznanej pozycji i opcjonalnym year.
• 404 oznacza, że vPIC nie ma zapisu tego wzorca. vPIC obejmuje pojazdy produkowane na rynek amerykański, więc dla innych rynków należy zacząć od marki i modelu przez POST /api/v1/images/resolve, co również jest bezpłatne.

Należy zapisać data.vehicle.id w polisie jako zwykły ciąg znaków i kopiować go do każdej szkody zgłoszonej z tej polisy. Identyfikator jest deterministyczny i trwały: ten sam pojazd ma ten sam identyfikator przy każdym wdrożeniu i po każdym wydaniu katalogu, więc można go bezpiecznie używać jako klucza obcego, a każde kolejne żądanie podaje vehicle=veh_78qtwrgh37bkr zamiast marki i modelu.

Gdy data.vehicle ma wartość null, zdekodowanej marki i modelu nie ma w katalogu, jak w przypadku przyczep i niektórych podwozi użytkowych. Zdekodowane pola nadal można wyświetlić. Należy je pokazać bez obrazu i nigdy nie wstawiać w ich miejsce podobnego samochodu.

Ekran wyceny, panel obsługi szkód i portal polis to aplikacje przeglądarkowe, więc serwer generuje podpisane URL-e przez POST /api/v1/image-urls: każdy URL zalicza swój obraz jako obraz pojazdu w danym miesiącu w chwili wygenerowania, do 50 na wywołanie, a jego wczytywanie jest bezpłatne aż do wygaśnięcia. Kadr warto ustalić raz i używać go ponownie: front-3-4 w ramce 640×400 z fit: "contain" oraz trim z niewielkim padding, aby coupé i pickup wypełniały ramkę tak samo. Czas ważności każdego URL-a zależy od miejsca, w którym jest wyświetlany:

• Stanowisko obsługi szkód. URL należy generować w chwili renderowania ekranu. Domyślny czas ważności (1 godzina) wystarcza na sesję pracy, a szkoda otwarta ponownie następnego dnia dostaje nowy URL.
• PDF z ofertą. Gdy PDF jest generowany z HTML, renderer raz wczytuje obraz i go osadza, więc domyślny czas ważności w zupełności wystarcza, a usługa PDF nigdy nie ma dostępu do Państwa klucza. format: "jpg" spłaszcza obraz na białe tło, a tego właśnie potrzebuje dokument.
• Portal polis i e-mail o odnowieniu. Działają dłużej niż jakikolwiek czas ważności, dlatego należy generować URL z renew: true i ttl_seconds: 604800 (7 dni). URL nadal działa, odnowienie liczy obraz raz w miesiącu, w którym nastąpi, i nic więcej, jeśli został już policzony w tym miesiącu, a renew_days: 365, najdłuższa dozwolona wartość, obejmuje roczny okres polisy.

Kluczowi generującemu URL-e należy przypisać listę dozwolonych originów w panelu: URL wczytany z innej witryny zwraca 403 z origin_not_allowed, a programy pocztowe i przeglądarki PDF, które nie wysyłają nagłówka Referer, nadal go wczytują. Unieważnienie klucza kończy działanie wszystkich wygenerowanych nim URL-i.

Opis należy umieścić tam, gdzie jest obraz, a nie tylko w przypisie: w tekście alternatywnym i w podpisie pod obrazem. Render pokazuje markę, model i rocznik w wybranym lakierze, a color może odpowiadać kolorowi z polisy (nazwa gotowego koloru lub dowolny kod hex). Nadal jest to jednak model w tym lakierze, a nie samochód klienta.

• Bezpłatne: dekodowanie VIN, resolve, zapytania do katalogu i każde wczytanie podpisanego URL w okresie jego ważności.
• Jeden obraz pojazdu: każdy pojazd w każdym lakierze i ujęciu, liczony raz w miesiącu niezależnie od tego, ile razy zostanie dostarczony, wygenerowany lub odnowiony, w dowolnym rozmiarze i formacie.
• Obrazy pojazdów miesięcznie: lejek ofertowy obejmuje wiele różnych pojazdów, a każdy plan zawiera określoną ich liczbę miesięcznie: Free 100, Pro 2500 i Business 10 000; w planie Enterprise warunki są negocjowane. Obraz już naliczony w tym miesiącu jest zawsze serwowany, a żądanie ponad limit otrzymuje odpowiedź 402, zanim cokolwiek zostanie naliczone, więc plan warto dobrać do liczby wycenianych pojazdów.

W planie płatnym licencja obejmuje render umieszczony w materiałach, które Państwa produkt tworzy dla swoich użytkowników, w tym w ofercie lub raporcie, przez cały okres aktywności planu; szczegóły zawiera licencja.

• SDK: client.decodeVin(vin, { year? }) i client.createImageUrls(…), jak wyżej; client.resolve(query) dla pojazdu bez numeru VIN.
• MCP: decode_vin i create_car_image_urls należą do podstawowego zestawu narzędzi, więc asystent mający szkodę w kontekście może odpowiedzieć na prośbę „pokaż ubezpieczony model” na podstawie VIN zapisanego w aktach. Konfiguracja jest opisana na stronie MCP.