Изображения автомобилей для аукционных объявлений

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

Рендер из каталога заполняет место изображением нужного модельного года. Но аукцион — именно то место, где рендер никогда не должен выдаваться за сам автомобиль: участники торгов оценивают состояние, а рендер его не показывает, потому что он не изображает какой-либо конкретный физический автомобиль. Всё описанное ниже вытекает из необходимости учитывать оба этих факта одновременно.

• Рендер для каждого лота по его VIN, который показывается только до появления собственных фото лота.
• Выбор из каталога для лотов, VIN которых не декодируется.
• Подпись на изображении: «Рендер из каталога, не этот лот».
• Один URL на лот, созданный один раз с Idempotency-Key и действующий до конца торгов.

GET /api/v1/vin/{vin} — бесплатный метод. Если автомобиль есть в каталоге, ответ содержит data.vehicle.id — стабильный идентификатор, который нужно сохранить в лоте; декодированные комплектация, кузов и двигатель остаются в тексте лота. Каталог охватывает годы с 1990 по 2027, поэтому старые автомобили на аукционе получают рендеры так же, как новейшие. В руководстве по страхованию декодирование разобрано поле за полем, а в документации по VIN описаны неполные VIN и ошибки.

Некоторые лоты поступают без VIN, который удаётся декодировать: автомобиль, выпущенный для другого рынка, VIN с опечаткой в источнике, акт приёмки с годом, маркой и моделью — и больше ничего. Добавьте в форму приёмки три выпадающих списка на основе GET /api/v1/vehicles — это бесплатный и публичный эндпоинт: ?year= возвращает марки, у которых есть модель этого года, а ?year=&makeId= — модели этой марки, каждую с id автомобиля для этого модельного года.

Этот же каталог доступен как открытый пакет @meterapp/vehicle-db, поэтому выпадающие списки могут работать и офлайн с тем же самым списком. В любом случае у лота оказывается такой же id, как у декодированного VIN, и дальше по цепочке никто не вписывает название автомобиля вручную.

Когда весь список лотов от комитента приходит разом, POST /api/v1/vehicles/check принимает до 2 000 записей за вызов — каждую в том написании, что в списке, с номером лота в качестве ref — и отвечает по каждой: совпадение с id для сохранения, варианты, промах или некорректная строка. Ничего не рендерится и ничего не списывается; подробности — в документации по vehicles.

Разместите пометку на самом изображении, куда падает взгляд участника торгов, и в alt-тексте, а не только в описании под ним. Состояние, пробег, повреждения, опции и фактический цвет автомобиля указываются в тексте лота, а когда появятся фотографии — на них. Когда приходят фотографии, рендер убирается.

Создавайте URL лота при приёмке через POST /api/v1/image-urls с Idempotency-Key, составленным из аукциона и лота, из букв, цифр, ., _, : и -. URL засчитывает своё изображение как изображение автомобиля за месяц в момент создания, поэтому без ключа повторная приёмка создала бы второй URL. С ключом:

• Запрос с тем же ключом и тем же телом в течение 24 ч возвращает первый ответ повторно, включая тот же URL, с заголовком Idempotent-Replayed: true и без повторного списания.
• Тот же ключ с другим телом запроса вернёт 422, а повторный запрос, опередивший первый, — 409 с Retry-After. Поэтому при создании лота зафиксируйте всё в теле запроса, включая срок действия, и храните его вместе с лотом.
• Также сохраните URL в данных лота: ключ защищает повторные запросы, а сохранённый URL страницы используют до конца торгов.

При импорте всего каталога разом можно выпустить URL не более чем для 50 лотов за вызов, с отдельным ключом на каждый пакет; каждый URL в ответе повторяет автомобиль и параметры, для которых он был выпущен.

ttl_seconds может составлять до 604800 (7 дн.); большее значение сокращается до этого предела. Если торги закрываются в течение недели, укажите время, оставшееся до закрытия. Тогда изображение-заглушка перестанет работать одновременно с окончанием торгов, а после этого URL будет возвращать 403.

• Торги дольше 7 дн.: создавайте URL с renew: true, максимальным ttl_seconds и renew_days, покрывающим весь срок торгов. Продление засчитывает изображение один раз в том месяце, на который оно приходится, и ничего сверх того, если оно уже было учтено в этом месяце; недели, когда лот никто не открывает, ничего не стоят, а продление прекращается на renews_until.
• Оставляйте max_uses равным 0 (значение по умолчанию): URL без ограничений публично кэшируется на весь срок действия, а URL с лимитом получает private, no-store и отправляет каждую загрузку на исходный сервер.
• Ограничьте ключ, создающий URL, доменами вашего аукциона на панели управления: изображение лота, скопированное на другой сайт, вернёт 403.

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