Как получить фото каждого автомобиля в дилерском ПО по VIN или складской таблице

Запись об автомобиле в наличии в CRM, ERP или системе управления дилерским центром (DMS) начинается с VIN, складского номера и цены. Фото появляется, когда приходит фотограф площадки, а для некоторых машин не появляется вовсе: автомобиль в пути, машина, сданная в трейд-ин и ещё проходящая предпродажную подготовку, импортный автомобиль, название модели которого не совпадает ни с чем в фиде изображений DMS, машина 1990-х, на пресс-фото которой никто не покупал лицензию. На каждом экране с этой записью — в списке продавца, в оценке у закупщика, в предложении клиенту — вместо фото серая заглушка.

Инструменты для дилеров и импорта, работающие на API, заполняют эту заглушку тем, что уже есть в записи. Если в ней есть VIN, до изображения — одно бесплатное декодирование. Если есть только строка в складской ведомости, поможет resolve по свободному тексту. В любом случае в записи оказывается постоянный id автомобиля, и на каждом экране один и тот же автомобиль выглядит одинаково.

• Расшифровка при поступлении. VIN расшифровывается один раз, при создании записи, и id автомобиля из каталога сохраняется рядом с ним. Дальше по цепочке марка и модель нигде не пишутся текстом.
• Один ракурс для списка, другой для карточки. Прямой side в широкой рамке для списков автомобилей в наличии; front-3-4 для страницы автомобиля и коммерческого предложения.
• Глубокий охват по годам. Импортные и подержанные автомобили уходят в 1990-е, и они рендерятся так же, как новые поступления: каталог охватывает период с 1990 по текущий модельный год, включая модели для внутреннего японского рынка.
• Подписанные URL внутри приложения. CRM работает в браузере, поэтому загружает подписанные URL без ключа, выпущенные сервером, — до пятидесяти за вызов — и обновляет их для записей, которые живут дольше недели.

GET /api/v1/vin/{vin} бесплатен, и для него нужен только API-ключ. Он возвращает расшифрованные год, марку, модель, комплектацию, тип кузова, двигатель и все остальные атрибуты, известные данным vPIC от NHTSA, а если автомобиль есть в каталоге, то и объект vehicle с его постоянным id и готовым image_path. Частичные VIN тоже подходят: не менее пяти символов, * на каждой неизвестной позиции и необязательная подсказка year.

Импортные автомобили часто поступают в виде таблицы: год, марка, название модели в том написании, которое использовал аукцион, код комплектации или грейда. POST /api/v1/images/resolve бесплатен и детерминирован: он извлекает из фразы слова, обозначающие год, цвет и ракурс, ищет по каталогу по оставшейся части и возвращает точные параметры с уровнем уверенности, на который можно опираться.

Автомобиль определён верно (Toyota Voxy 2019 года), но уверенность — low, потому что «ZS» — это комплектация, которую каталог не знает, и её пришлось обойти при сопоставлении. При пакетном импорте считайте high готовым результатом, а medium и low передавайте человеку вместе со списком candidates. Если в таблице год и марка уже указаны в отдельных столбцах, передавайте их в полях year и make, а в query оставляйте только модель — сопоставление станет намного точнее. Фраза без слов, относящихся к автомобилю, возвращает 400, а марка без подходящей модели — 404 со списком годов этой марки, чтобы вы могли уточнить модель.

Каким бы путём вы к нему ни пришли, сохраните vehicle.id (или params.vehicle_id) в записи складского автомобиля как обычный строковый столбец. Он детерминирован и постоянен: у одного и того же автомобиля один и тот же id при каждом развёртывании и после каждого релиза каталога, поэтому его можно безопасно использовать как внешний ключ. С этого момента каждый запрос изображения — это vehicle=veh_…, где невозможно допустить опечатку, а марка, переименованная производителем или иначе заведённая источником, никогда не сломает сохранённый URL.

Списки автомобилей в наличии широкие и невысокие, поэтому обычно выбирают прямой вид сбоку в рамке 2:1: каждый автомобиль смотрит в одну сторону и стоит на одной базовой линии. trim=1&padding=6 обрезает изображение по автомобилю перед вписыванием, поэтому Hilux и Yaris заполняют строку одинаково; fit=contain сохраняет холст ровно 640×320 с прозрачными полями. На странице с подробностями используется front-3-4 размером 1024, и у обоих общий кеш: если цвет не указан, он серебристый в обоих случаях.

CRM работает в браузере, а в браузере никогда не должен храниться API-ключ. Когда на экране отображается страница складских позиций, сервер создаёт по одному подписанному URL на запись с помощью POST /api/v1/image-urls (до пятидесяти за вызов; изображение каждого URL засчитывается как изображение автомобиля за месяц), и страница загружает их как обычные изображения. Для записи, которая месяцами остаётся в наличии, важны две настройки:

• ttl_seconds: 604800 с renew: true: URL продолжает работать после семидневного TTL, а продление засчитывает изображение один раз в месяце, на который оно приходится, и ничего сверх, если оно уже было учтено в этом месяце. Месяцы, когда автомобиль никто не смотрит, не учитываются.
• Отдельный Idempotency-Key для каждой страницы синхронизации: повторный запрос воспроизводит первый ответ и ничего не выпускает дважды.

Ограничьте ключ, выпускающий URL, источником (origin) CRM в панели управления — и URL, попавший на другой сайт, вернёт 403. Отзыв ключа аннулирует все выпущенные им URL. Если изображения автомобилей по тарифу на месяц израсходованы, продление вернёт 402, а тот же URL снова заработает после сброса лимита или повышения тарифа. Полный жизненный цикл описан в документации по подписанным URL.

• SDK: client.decodeVin(vin, { year? }), client.resolve(query), client.getImage({ vehicle, … }) и client.createImageUrls(…), как показано выше.
• MCP: decode_vin, resolve_vehicle, get_car_image и create_car_image_urls входят в базовый набор инструментов, поэтому ассистент, у которого в контексте есть складская система, может ответить на запрос «фото для позиции 4471» по VIN из записи. Настройка описана на странице MCP; поля и ошибки декодера — в документации по VIN.