Полета по източник

Поддържаните източници на инвентар захранват един API, но не публикуват едни и същи неща. Германска платформа на едро дава пълен протокол от оглед и каталог на оборудването по DAT; японски лот за износ дава протокол от огледа на търга и оценка на състоянието; корейските обяви носят характеристики и по избор данни за състоянието. Тази страница е честната карта кой какво ви дава, за да решите какво може да обещае продуктът ви, преди да го изградите.

Три слоя данни

Всеки автомобил в API е описан на три нива на нормализиране. Да знаете на кой слой е дадено поле ви казва веднага колко преносимо е.

Общото ядро е гарантирано в смисъл, че полето винаги е в договора; отделна стойност пак може да е null, когато конкретен източник не я публикува. fuel_group, например, е празно за повечето японски лотове — а лот без записано гориво съвпада с всеки филтър fuel, а не с нито един, така че филтрирането по гориво никога не прави тези лотове недостъпни.

Какво ви дава всеки източник

Прочетете тази таблица, преди да определите обхвата на функция. „Оскъдно“ не е бъг за докладване — това е, което публикува аукционната къща.

Данни за състоянието: матрица на покритието

Това е таблицата, от която хората реално имат нужда. Тя казва кои ключове на vehicle_details можете да очаквате от кой източник. Празно означава, че текущата интеграция не обещава това поле. То може да не е налично при източника, още да не е обогатено или да е пропуснато заради правата; липсата не е присъда за чисто състояние.

Бележки по източник, които си струва да знаете

Японски търгове — цената е начално наддаване

Активен японски лот няма крайна цена, докато не приключи, така че current_price при japan е началното наддаване, а не разход. Някои лотове не публикуват начална цена, а противоречивите импортирани цени не се показват. Номиналните начални цени може да са далеч под крайната. Четете я като долна граница. buy_now_price никога не се задава за този източник и в резултат класирането по най-добра стойност ще отбелязва някои от тези лотове прекалено оптимистично.

Японските редове са с произход JP. Използвайте country=JP или site=japan и /api/auction/japan/{id} за съхранените детайли. /api/car-details не приема Япония. Използвайте ID като низ от търсенето, без да го превръщате в JavaScript число.

OpenLane — видове протоколи

OpenLane класифицира всеки протокол, който публикува. type е четимото име, а type_id — суровият код на източника.

Единственият протокол от оглед на Auto1 се нормализира в същия списък с тип inspection_report и без type_id.

Японски търгове — протоколът от търга

Японските протоколи от търговете и снимките са незадължителни импортирани данни. Използвайте върнатата галерия и наличните записи за протоколи; текущият импорт не обещава нормализиран запис auction_sheet за всеки лот, извлечен VIN или актуално извличане на детайли от източника. Спецификацията от източника и данните от съпоставените посредници остават в car_identification; адресите на импортираните протоколи са в JapanMerged.AuctionSheetUrls.

Отваряне и изтегляне на протоколи

Следвайте точно върнатия адрес /report-vault/{site}/{auction_id}/{token}; токенът идентифицира вече известен протокол и не е адрес на източника, който можете да съставите. Този маршрут за доставка в момента не изисква API ключ. Успешният отговор е двоичен файл с неговия Content-Type, а не JSON обвивка. download=1 иска прикачен файл. 302 сочи към страница при източника; 400 означава невалиден токен, 404 — няма съвпадащ протокол, а 503 — базата данни не е достъпна. Не препращайте API ключа си към целта на пренасочването.

KB ChaChaCha — диагностика и оглед

Четете vehicle_details.kb_diagnosis и vehicle_details.kb_inspection поотделно: единият протокол може да е наличен, а другият — не. Те запазват данните от източника, вместо да ги превръщат в универсална оценка за произшествия. Използвайте числовия carSeq за /api/car-details?site=kbchachacha&id=... или точния съхранен идентификатор от картата в търсенето за /api/auction/kbchachacha/{id}.

Конфликти в имената, за които да внимавате

Една и съща дума означава различни неща при различните източници — точно затова съществува нормализираният блок. Файл за изтегляне е Documents[] в Auto1 — докато Documents в OpenLane е речник с булеви стойности за документите, а не списък с файлове. Ако четете car_identification директно, проблемът е ваш. Ако четете vehicle_details.documents — не е.

Страна на волана

steering се нормализира до left или right. Използват се изрични данни от източника, където се поддържат; иначе се извежда от пазара на регистрация. Това е изведено поле, когато няма изрична стойност от източника, а не универсална гаранция от физически оглед. Японският внос може да включва автомобили с ляв волан, затова не извеждайте страната на волана от държавата в клиента си.

Тъй като всяка обява попада в едната или другата страна, двете стойности разделят инвентара: бройките им дават общия брой без филтри. Като филтър приема две стойности, всяка с четири равностойни записа — left, lhd, left-hand, left_hand и right, rhd, right-hand, right_hand — а всичко друго е 400. Приема се от /api/search, /api/top-offers, /api/listVehicles и всеки ендпойнт за фасети — макар че при фасетите се изчислява в момента, а не се чете от предварително изчислената таблица, така че е по-бавно от извикване без филтри.

Код, който оцелява при разликите

Everyone else has a summary.
    serviceVisits: d.service_history ?? null,
    serviceSummary: d.service_history_summary ?? null,

    // Most listings carry no reports at all. Empty is normal, not an error.
    reports: d.inspection_reports ?? [],

    repairCost: d.estimated_repair_costs ?? null,
  };
}

// Wrong: this breaks the day a source is added, and hides data today.
if (auction.site_name === "auto1") { /* ... */ }

• Никога не задавайте списъка с източници ръчно. Четете го от /api/sites при стартиране. Непознат slug е 400 с посочено име, така че остарял ръчен списък превръща нов източник в счупено внедряване.
• Проектирайте за най-плиткия източник, който обслужвате. Никой източник не гарантира пълна сервизна история за всяка кола. Обещавайте я там, където я има, и деградирайте плавно, където я няма.
• Третирайте car_identification като без версии. Ключовете му следват собствените имена на всеки източник и се променят, когато източникът се промени. Всичко, от което зависите дългосрочно, трябва да идва от общото ядро или от vehicle_details.
• details_pending: true не е грешка. Означава, че детайлите още не са събрани. Проверявайте периодично, вместо да опитвате в плътен цикъл, и показвайте данните от картата, които вече имате.