Jak zamienić VIN lub arkusz stanów magazynowych w zdjęcie każdego pojazdu w oprogramowaniu dla dealerów

Rekord pojazdu w CRM, ERP lub systemie do zarządzania salonem (DMS) zaczyna się od numeru VIN, numeru magazynowego i ceny. Zdjęcie pojawia się, gdy przyjdzie fotograf, a dla części pojazdów nie pojawia się nigdy: auto w transporcie, samochód z odkupu wciąż w przygotowaniu, import, którego nazwa modelu nie pasuje do niczego w źródle zdjęć DMS, auto z lat 90., do którego nikt nie wykupił licencji na zdjęcie prasowe. Każdy ekran z tym rekordem – lista sprzedawcy, wycena dla skupującego, oferta dla klienta – pokazuje zamiast zdjęcia szary obrazek zastępczy.

Narzędzia dla dealerów i importerów korzystające z API wypełniają to miejsce na podstawie danych, które rekord już zawiera. Jeśli ma VIN, od obrazu dzieli go jedno bezpłatne dekodowanie. Jeśli ma tylko wiersz w zestawieniu stanu magazynowego, wystarczy resolve z dowolnego tekstu. Tak czy inaczej rekord otrzymuje stały identyfikator pojazdu, a każdy ekran pokazuje ten sam samochód w ten sam sposób.

• Dekodowanie przy przyjęciu. VIN jest dekodowany raz, przy tworzeniu rekordu, a identyfikator pojazdu z katalogu zapisywany obok niego. Nic na dalszych etapach nie wpisuje ręcznie marki ani modelu.
• Jeden widok na listę, drugi na stronę szczegółów. Prosty side w szerokim kontenerze dla list pojazdów na stanie; front-3-4 dla strony szczegółów i oferty.
• Starsze roczniki. Pojazdy importowane i używane sięgają lat 90., a renderują się tak samo jak nowości: katalog obejmuje roczniki od 1990 do bieżącego roku modelowego, łącznie z modelami przeznaczonymi na rynek japoński.
• Podpisane adresy URL w aplikacji. CRM działa w przeglądarce, więc wczytuje generowane przez serwer podpisane adresy URL bez klucza, do pięćdziesięciu na wywołanie, odnawiane dla rekordów istniejących dłużej niż tydzień.

GET /api/v1/vin/{vin} jest bezpłatny i wymaga tylko klucza API. Zwraca zdekodowany rok, markę, model, wersję wyposażenia, typ nadwozia, silnik i każdy inny atrybut znany danym vPIC NHTSA, a gdy pojazd jest w katalogu – obiekt vehicle z jego stałym identyfikatorem i gotową ścieżką image_path. Działają też niepełne numery VIN: co najmniej pięć znaków, * w miejscu każdej nieznanej pozycji oraz opcjonalna wskazówka year.

Samochody z importu często trafiają w formie arkusza kalkulacyjnego: rok, marka, nazwa modelu w pisowni stosowanej przez dom aukcyjny, kod klasy lub wersji wyposażenia. POST /api/v1/images/resolve jest bezpłatny i deterministyczny: wyodrębnia z frazy słowa oznaczające rok, kolor i widok, przeszukuje katalog pozostałą częścią i zwraca dokładne parametry wraz z poziomem pewności, na podstawie którego można podjąć decyzję.

Pojazd jest prawidłowy (Toyota Voxy z 2019 roku), ale poziom pewności to low, ponieważ „ZS” to wersja, której katalog nie zna, więc dopasowanie musiało ją pominąć. Przy imporcie wsadowym należy traktować high jako gotowe, a medium i low przekazać do sprawdzenia człowiekowi wraz z listą candidates. Gdy arkusz ma już rok i markę w osobnych kolumnach, należy wysłać je w polach year i make, a w query zostawić tylko model; dopasowanie będzie wtedy znacznie dokładniejsze. Fraza bez słów opisujących pojazd zwraca 400, a marka bez pasującego modelu zwraca 404 z listą roczników tej marki, aby można było zapytać o model.

Niezależnie od wybranej ścieżki należy zapisać vehicle.id (lub params.vehicle_id) w rekordzie pojazdu jako zwykłą kolumnę tekstową. 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. Od tej chwili każde żądanie obrazu to vehicle=veh_…, czego nie da się błędnie wpisać, a marka przemianowana przez producenta lub inaczej sklasyfikowana przez źródło nigdy nie zepsuje zapisanego adresu URL.

Listy pojazdów na stanie są szerokie i niskie, więc zwykle wybiera się prosty widok z boku w ramce 2:1: każdy egzemplarz jest zwrócony w tę samą stronę i stoi na tej samej linii bazowej. trim=1&padding=6 przycina obraz do samochodu przed dopasowaniem, więc Hilux i Yaris wypełniają wiersz w ten sam sposób; fit=contain utrzymuje płótno dokładnie 640×320 z przezroczystymi marginesami. Strona szczegółów używa front-3-4 w rozmiarze 1024, a oba widoki współdzielą pamięć podręczną: niewskazany kolor lakieru jest w obu przypadkach srebrny.

CRM działa w przeglądarce, a przeglądarka nigdy nie może przechowywać klucza API. Gdy ekran wyświetla stronę stanów magazynowych, serwer generuje jeden podpisany URL na rekord za pomocą POST /api/v1/image-urls (do pięćdziesięciu na wywołanie; obraz każdego URL-a liczy się jako obraz pojazdu w miesiącu), a strona ładuje je jak każdy inny obraz. W przypadku rekordu, który pozostaje w ofercie przez miesiące, ważne są dwa ustawienia:

• ttl_seconds: 604800 z renew: true: URL działa także po upływie siedmiodniowego TTL, a odnowienie liczy obraz raz w miesiącu, w którym nastąpi, i nic więcej, jeśli obraz został już policzony w tym miesiącu. Miesiące, w których nikt nie ogląda samochodu, nie są liczone.
• Jeden Idempotency-Key na każdą stronę synchronizacji: ponowione żądanie odtwarza pierwszą odpowiedź i niczego nie generuje dwa razy.

Ograniczenie klucza generującego URL-e do originu CRM w panelu sprawia, że URL, który wycieknie na inną stronę, zwraca 403. Odwołanie klucza unieważnia wszystkie wygenerowane nim URL-e. Jeśli obrazy pojazdów z planu na dany miesiąc zostały wykorzystane, odnowienie zwraca 402, a ten sam URL znów działa po odnowieniu limitu lub podniesieniu planu. Pełny cykl życia opisano w dokumentacji podpisanych URL-i.

• SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) i client.createImageUrls(…), jak wyżej.
• MCP: decode_vin, resolve_vehicle, get_car_image i create_car_image_urls należą do podstawowego zestawu narzędzi, więc asystent, który ma w kontekście system magazynowy, może odpowiedzieć na prośbę „zdjęcie dla pozycji 4471” na podstawie VIN z rekordu. Konfiguracja jest opisana na stronie MCP; pola i błędy dekodera znajdują się w dokumentacji VIN.