Изображения автомобилей для урегулирования страховых случаев и расчёта полисов

В форме расчёта страховки, в записи о полисе и в первичном уведомлении об убытке автомобиль указывается одинаково: по VIN, который вводит клиент или который считывается из регистрационного документа. Всё, что человек затем видит об автомобиле, — это текст: год, марка, модель и, возможно, комплектация. Вопрос «Это ваш автомобиль?» рядом со строкой текста располагает к ответу «да» на что угодно.

Изображение модели, в которую расшифровывается VIN, позволяет клиенту и аджастеру с первого взгляда убедиться, что в записи указан автомобиль нужного типа. Какой именно это автомобиль, изображение показать не может: рендер — студийная иллюстрация марки, модели и года из каталога, и он не изображает какое-либо конкретное физическое транспортное средство. Именно этот факт определяет всю описанную ниже интеграцию.

• Расшифровка при оформлении. Процесс расчёта или система полисов один раз бесплатно расшифровывает VIN и сохраняет id автомобиля из каталога вместе с полисом. Страховые случаи, открытые по полису, наследуют его.
• Один ракурс везде. front-3-4, основной ракурс, в одной и той же рамке на экране расчёта, в рабочем месте урегулирования убытков, в PDF с расчётом и на портале полисов, чтобы на каждом экране модель выглядела одинаково.
• Подписанные URL, а не ключ. Браузеры и генераторы PDF загружают URL без ключа, которые создаёт ваш сервер.
• Словами — то, чего не покажет изображение. Комплектация, опции, цвет по документам, повреждения и пробег остаются в тексте и на фотографиях, а изображение помечено как иллюстративное.

GET /api/v1/vin/{vin} бесплатен и требует ключа с images:read. Он возвращает декодированные поля из данных vPIC от NHTSA (год, марка, модель, комплектация, серия, класс кузова, двигатель и все прочие атрибуты, известные vPIC), а если автомобиль есть в каталоге — объект vehicle с его постоянным идентификатором и готовым image_path.

Посмотрите на trim: «Carrera, Carrera T, Carrera 4». Шаблон этого VIN охватывает три комплектации, поэтому даже декодирование не может сказать, какую из них страхует полис, а рендер 911 2024 года — тем более. Попросите клиента подтвердить комплектацию, храните её как текст вместе с series и body_class, а изображение пусть показывает модель.

• VIN с неверной контрольной цифрой всё равно декодируется — с valid: false и описанием проблемы в errors; suggested_vin отмечает символом ! знак, который vPIC считает ошибочным, — именно это и стоит показать человеку, который вводит номер.
• Форма, в которой есть только первые символы, может отправить частичный VIN: не менее пяти символов, * на месте каждой неизвестной позиции и, при необходимости, year.
• 404 означает, что в vPIC нет записи для этого шаблона. vPIC охватывает автомобили, выпущенные для рынка США, поэтому для других рынков начинайте с марки и модели через POST /api/v1/images/resolve — это тоже бесплатно.

Храните data.vehicle.id в полисе как обычную строку и копируйте его в каждый убыток, заявленный по этому полису. Идентификатор детерминирован и постоянен: у одного и того же автомобиля один и тот же id при каждом деплое и после каждого выпуска каталога, поэтому его можно безопасно использовать как внешний ключ, а во всех последующих запросах указывать vehicle=veh_78qtwrgh37bkr вместо марки и модели.

Если data.vehicle равно null, расшифрованных марки и модели нет в каталоге — как у прицепов и некоторых коммерческих шасси. Расшифрованные поля вы всё равно можете показывать. Показывайте их без изображения и никогда не подставляйте вместо него похожий автомобиль.

Экран расчёта стоимости, рабочее место урегулирования убытков и портал полисов — браузерные приложения, поэтому ваш сервер выпускает подписанные URL через POST /api/v1/image-urls: каждый URL в момент выпуска засчитывает своё изображение как изображение автомобиля текущего месяца, до 50 за вызов, и загружается бесплатно до истечения срока. Настройте кадр один раз и используйте те же параметры: front-3-4 в рамке 640×400 с fit: "contain" и trim с небольшим padding, чтобы купе и пикап заполняли рамку одинаково. Срок жизни каждого URL зависит от того, где он показывается:

• Рабочее место по урегулированию убытков. Создавайте URL при отрисовке экрана. Срок действия по умолчанию — 1 час — покрывает рабочую сессию, а для убытка, повторно открытого на следующий день, создаётся новый URL.
• PDF с расчётом. Когда PDF формируется из HTML, рендерер загружает изображение один раз и встраивает его, поэтому срока действия по умолчанию вполне хватает, а сервис PDF никогда не получает ваш ключ. format: "jpg" помещает изображение на белый фон — именно это и нужно документу.
• Портал полисов и письмо о продлении. Они живут дольше любого срока действия ссылки, поэтому создавайте URL с renew: true и ttl_seconds: 604800 (7 дней). URL продолжает работать, продление учитывает изображение один раз в том месяце, на который оно приходится, и ничего сверх этого, если оно уже было учтено в этом месяце, а renew_days: 365 — максимально допустимое значение — покрывает годовой срок действия полиса.

Задайте для ключа, который создаёт URL, список разрешённых источников на панели управления: URL, загруженный с другого сайта, возвращает 403 с origin_not_allowed, а почтовые клиенты и программы просмотра PDF, которые не отправляют Referer, по-прежнему его загружают. Отзыв ключа аннулирует все созданные им URL.

Размещайте пометку там, где находится изображение, а не только в сноске: в alt-тексте и в подписи под изображением. Рендер показывает марку, модель и год выпуска в выбранном вами цвете, а color может соответствовать цвету, указанному в полисе (название из набора или любой hex-код). И всё же это модель в этом цвете, а не автомобиль клиента.

• Бесплатно: декодирование VIN, resolve, запросы к каталогу и каждая загрузка подписанного URL в течение срока его действия.
• Одно изображение автомобиля: каждый автомобиль в каждом цвете и ракурсе учитывается один раз в месяц, сколько бы раз его ни доставляли, выпускали или продлевали, в любом размере и формате.
• Изображения автомобилей в месяц: воронка расчёта страховки видит много разных автомобилей, и каждый тариф включает определённое их число в месяц: Free — 100, Pro — 2 500, Business — 10 000; условия Enterprise согласуются индивидуально. Изображение, уже учтённое в этом месяце, отдаётся всегда, а запрос сверх лимита получает ответ 402 ещё до какого-либо учёта, поэтому выбирайте тариф по числу автомобилей, для которых вы делаете расчёты.

На платном тарифе лицензия распространяется на рендер в материалах, которые ваш продукт создаёт для своих пользователей, включая расчёт стоимости или отчёт, пока тариф активен; подробности — в лицензии.

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