Endpoints

1) Отримати метадані фільтрів

GET /api/v1/vehicle-auction/vehicles/filters

Використовуйте цей endpoint для побудови пошукового інтерфейсу. Він повертає списки опцій, значення за замовчуванням, межі діапазонів, фільтри локацій, метадані фільтрів доставки та метадані документів продажу.

Відповідь містить:

1. опції статусу лота та підстатусу аукціону
2. опції типу аукціону
3. марки та моделі, згруповані за маркою
4. типи транспортних засобів
5. числові діапазони: ціна, рік, пробіг, двигун
6. додаткові фільтри: колір, паливо, трансмісія, привід, стан запуску, пошкодження, циліндри, наявність ключа
7. метадані фільтра за датою аукціону
8. метадані фільтра тільки на сьогодні
9. метадані фільтра документів продажу
10. метадані фільтра типу продавця
11. метадані фільтрів доставки
12. фільтри локацій: штат, майданчик, назва офісу, zip/radius

2) Пошук автомобілів (повний payload лота)

GET /api/v1/vehicle-auction/vehicles

Повертає список автомобілів, які відповідають фільтрам.
Кожен елемент повертається в тому самому повному форматі “lot payload”, що й endpoint одного автомобіля.

Примітки

• Коли zip + radius використовуються, відповідь може містити distance поле для кожного лота.
• Відстань розраховується за координатами лота; координати майданчика використовуються як fallback, якщо вони доступні.
• Фільтри документів продажу та типу продавця працюють за принципом best-effort і залежать від доступних вихідних даних.

3) Отримати один автомобіль

GET /api/v1/vehicle-auction/vehicles/{vinOrLotNumber}

Повертає один автомобіль у повному форматі lot payload.

Основні поля відповіді

• slug_vin — публічний VIN автомобіля або номер лоту
• vin — VIN у верхньому регістрі
• platform, platform_id, lot_number
• title, year, make, model, type
• auction — стан аукціону, розклад, buy now / timed прапорці, sold metadata
• pricing — поточна ставка, buy now price, остання ціна продажу, орієнтовний історичний діапазон
• location — відображувана локація, рекомендований порт доставки, штат
• seller — назва продавця та визначений тип
• condition — стан запуску, ключ, loss, пошкодження
• odometer — пробіг у mi/km
• vehicle_specs — двигун, трансмісія, паливо, привід, тип кузова, airbags, restraint system
• sale_document — визначена назва документа, тип, локалізований опис, export, registration, page ID, pending flag
• media — зображення, відео, 360 data
• facility — ID майданчика, штат, ZIP, координати, назва офісу
• distance — відстань від запитаного ZIP, коли використовується radius search
• details — розширений raw IAAI detail block, якщо доступний

4) Отримати історію автомобіля

GET /api/v1/vehicle-auction/vehicles/{vinOrLotNumber}/history

Повертає рядки історії продажів для лота.

Відповідь містить

• vehicle.slug_vin
• vehicle.vin
• vehicle.platform
• vehicle.lot_number
• history[].platform
• history[].date — форматується як Y-m-d
• history[].price
• history[].status

5) Отримати схожі автомобілі

GET /api/v1/vehicle-auction/vehicles/{vinOrLotNumber}/related

Повертає схожі автомобілі з тієї самої платформи, марки та моделі.
Відповідь розділена на:

• source — запитаний автомобіль
• upcoming — схожі активні або майбутні автомобілі
• past — схожі продані або видалені автомобілі

6) Отримати доставку для конкретного автомобіля

GET /api/v1/vehicle-auction/vehicles/{vinOrLotNumber}/shipping

Повертає підібрані ціни доставки від аукціону до порту для одного конкретного автомобіля.

Відповідь містить

• vehicle — platform, lot number, VIN, title, type
• auction_location.display — зрозуміла для людини локація аукціону
• auction_location.facility_id
• auction_location.matched_location_id — ID підібраної inland shipping location
• auction_location.match_score — similarity score, який використовується для matching
• shipping.recommended_port
• shipping.recommended_price_usd
• shipping.has_shipping_price
• shipping.available_ports — список підібраних портів і цін

7) Отримати доставку за VIN / номером лота / slug

GET /shipping/auction-to-port

Повертає ціни доставки від аукціону до порту без попереднього виклику endpoint одного автомобіля.

8) Отримати аукціонні локації

GET /locations

Повертає аукціонні майданчики / офіси та кількість аукціонів на сьогодні.

Відповідь містить

• platform
• facility_id
• name
• name_desc
• city
• state_code
• state_name
• zip
• latitude
• longitude
• location_url
• sale_day
• sale_time
• time_zone
• today_auction_count
• distance коли використовується ZIP/radius search