Авто ДанниПлатформа за автомобилни данни
ENВходЗапочнете безплатно
договор 2026-10-05
Статус

Промени

Всяка версия на договора и какво се е променило в нея. Версията, която обслужва това внедряване, е във всеки отговор като contract_version, в момента 2026-10-05.

2026-09-03подобрение2026-09-19

Текущо покритие на източниците и API документация

  • Документирани са поддържаните източници, включително KB ChaChaCha и текущият импорт на японски автомобили под site=japan. Япония използва съхранени детайли за търговете, а не /api/car-details.
  • Добавени са търсене в архива, детайли от архива и статистика на покритието, фасети и филтри по година на производство, фасети и филтриране по версия, както и права за източници и полета за всеки ключ.
  • Използвайте /api/classifieds/* и обхвата classifieds; /api/theparking/* и правата theparking остават съвместими наследени синоними.
  • Документирани са кешираните файлове в report-vault, статусът на диагностиката и огледа от KB, данните за японските оферти и непроверените цени на резултатите.
  • Версията на договора е 2026-09-03. Този преглед на документацията е от 2026-09-19; той не означава нов договор на сървъра или внедряване.
2026-08-29корекция2026-08-29

Одит на документацията — три неща, които справочникът твърдеше погрешно

  • Само документация. Не е променен код, не е преместено поле, нито един параметър не е сменил значението си, а contract_version остава 2026-08-19. Справочникът беше проверен ред по ред спрямо работещата услуга и три неща в него се оказаха грешни. Ако сте писали код по тях, струва си да ги проверите.
  • event_type в историята на цените никога не е имал показаната от нас стойност. Примерът показваше "event_type": "price_change". Такава стойност не съществува. Полето приема точно три стойности — initial, baseline и change — и винаги е било така. Клиент, който търси price_change, е изхвърлял всяко събитие. Сега са документирани и пълният набор от полета за събитие, подредбата от най-старото и ограничението от 5000 събития.
  • /api/search/auction-ids връща голи числови идентификатори, а не двойки site:id. Примерът показваше ["encar:38112900", "auto1:AB12CD"]. Ендпойнтът връща стойностите на auction_id като обикновени JSON числа, без източник и следователно без гаранция за уникалност между източниците. Той е филтър, а не схема за адресиране; използвайте /api/search, когато ви трябват карти, които можете да адресирате. Описани са и трите му възможни резултата — празен списък при 503 означава „неизвестно“, а не „нула“.
  • Дълбочината на страниране беше описана по-ограничително, отколкото е. /api/listVehicles също няма ограничение на отместването, а ограничението от 5000 важи за маршрутите на каталога, топ офертите и обявите от theparking. Политиката за дълбочина вече казва кое е кое и кои обвивки изобщо носят page / page_size / max_page.
  • Новодокументирано, преди липсващо: протоколът от търга при japanauction (тип auction_sheet в inspection_reports); vehicle_id, manufacturer_slug, model_group_slug и fuel_type в двата отговора с детайли; кои ендпойнти пропускат метаданните на обвивката и кои не са включени за нов ключ; пълни таблици с полетата за пазарните снимки, разбивката на калкулатора, историята по VIN, /api/contract и фасетите на theparking; че served_url е път, който се свързва с базовия URL; че филтрите brand/model/fuel/gearbox/seller на theparking различават главни и малки букви; че калкулаторът записва Обединеното кралство като UK, а фасетите за автомобили — като GB; и страница „Рецепти“ с шест цялостни сценария.
2026-08-28корекция2026-08-28

Корекции в точността на съпоставянето на марки и преброяването на резултатите — договорът е непроменен

  • Договорът за схемата е непроменен: не е добавено, премахнато или пре-типизирано поле, нито един параметър не е сменил името или допустимите си стойности и нито един ендпойнт не е сменил адреса, метода или удостоверяването си. contract_version остава 2026-08-19. Клиент, който чете отговорите общо, не се нуждае от промени в кода — променят се числата.
  • Филтърът по марка вече съпоставя марката, а не изписването. Източниците не са съгласни как се пише марка — openlane публикува „Volkswagen“, където каталогът и всеки друг източник пишат „VW“ — а марката се съпоставяше само по публикуваното име, така че търсенето по марка тихо изпускаше всеки източник с различно изписване. Сега се съпоставя по идентичността на марката или по името ѝ, така че ?brand=vw, ?brand=VW и ?brand=175 връщат един и същ инвентар. Очаквайте търсенията по марка да връщат повече редове и бройките по марка да се увеличат; обновете тестовете със снимки, фиксирани на старите стойности.
  • Един запис за модел в каталога на фасетите. В /api/models и /api/facets модел, изписан с различни главни/малки букви от различните източници, се показваше два пъти, като всеки ред носеше част от бройката. Записите вече се обединяват по идентичността на модела, а не по показаното име, така че всеки модел се появява веднъж, с едно стабилно изписване и бройката, която реално връща търсенето. Бройките за засегнатите модели се увеличават. Собственото ви премахване на дубликати вече не е нужно, макар и безвредно.
  • Общият брой при филтрирано търсене вече съвпада с връщаните редове. Преброяването и самите редове не прилагаха едно и също правило за затворените лотове, така че филтрирано търсене можеше да отчете няколкостотин съвпадения и да остане без редове преди последната страница. total, total_pages и редовете вече съвпадат; total става малко по-малък и верен за филтрираните търсения. Търсенията без филтри никога не са били засегнати, а include_ended=true / is_active=false все още включват затворените лотове.
2026-08-27подобрение2026-08-27

Взаимно филтрирани фасети, бройки за всяка опция, ограничени галерии в картите и estimated_value_eur

  • Вече работи и се обслужва по договор 2026-08-19: нито едно поле не е сменило типа си, нито един параметър — името или допустимите си стойности, и нито един ендпойнт — адреса, метода или удостоверяването си, така че самият договор не се е променил. Единствената промяна, която не е само добавка, е първата — тя премахва четири ключа от тялото на един ендпойнт; всичко останало е добавка.
  • Не е само добавка: GET /load-models вече не слива метаданните на договора в картата с марки. contract_version, request_id, server_time и data_updated_at са премахнати от това тяло, защото ключовете му са имена на марки и тези четири се четяха като марки. Четете идентификатора за корелация от заглавката X-Request-ID — той винаги е бил там. Филтрирането на четирите ключа остава безвредно и правилно.
  • Допълнителна оценка от източника в евро, където е налична. Това е оценка, а не цена, която може да се плати. Никога не я замествайте с обявена цена или реален резултат от продажба.
  • Бройките във фасетите вече са взаимно филтрирани. /api/brands, /api/models, /api/sites и списъците /api/years, /api/fuels, /api/gearboxes, /api/countries (поотделно и чрез /api/facets) отчитат другите филтри в заявката, като всяко измерение игнорира само своя — така price_to=5000&fields=brands връща бройката на всяка марка под 5000 евро, а списъците пропускат опциите без оставащи съвпадения. Затова ендпойнтите за фасети приемат набора от филтри на търсенето; is_active и include_ended не са сред тях, защото фасетите винаги описват лотове, чийто търг още е отворен. Без филтри отговорите са байт по байт същите като преди.
  • Бройки за всяка опция при години, горива, скоростни кутии и държави: year_counts, fuel_counts, gearbox_counts и country_counts — всяко масив от {value, count} в същия ред като съответния списък със стойности. Те следват същата семантика на взаимно филтриране. Марките, моделите и сайтовете вече връщаха бройки. Клиентите, които четат само обикновените масиви, не са засегнати.
  • Ендпойнтите със списъци ограничават вградените галерии до 8 снимки. /api/search и /api/listVehicles вграждат най-много първите 8 записа в реда на показване за всеки ред, основната първа. На картите им трябва само миниатюра; всичко, което третира images[] в ред от търсенето като пълната галерия, трябва да чете vault_gallery от ендпойнта с детайли или /api/auction-images/{site}/{id}. Ендпойнтите с детайли не са променени и все още връщат пълни галерии плюс броя на чакащите.
  • live_price_pending вече се случва при студено отваряне. Първото четене на активен търг в OpenLane се връща веднага с live_price_pending: true, X-Live-Price: pending и Cache-Control: no-store, вместо да чака наддаването; документираният единствен повторен опит след ~2 с взема обновената стойност от кеша. Интеграциите, които вече следват тази рецепта, не са засегнати.
  • Пътищата /image-vault/* отговарят с 302 към предварително подписан адрес на обекта, вместо да предават байтовете през API. Масовите HTTP клиенти и браузъри го следват прозрачно, а пренасоченият обект се кешира като непроменлив, така че прехвърлянето се плаща веднъж за снимка.
2026-08-19нова функция2026-08-19

Версия на договора 2026-08-19 — обединени фасети, вградени галерии, gzip и условни заявки

  • Всяка промяна в тази версия е добавка. Нито едно поле не е сменило типа си, не е премахнато поле, не е сменена стойност по подразбиране и нито един ендпойнт не е сменил формата на отговора си — интеграция, писана за 2026-08-18, работи без промяна.
  • Новият GET /api/facets връща марки, години, горива, държави, скоростни кутии и сайтове в един отговор, като fields= избира подмножеството, което показвате. Всяко поле е дословно данните на собствения му ендпойнт, така че стойността означава точно това, което означава там. Обхват search и таксува една единица от квотата вместо шест. models остава на /api/models — той е в рамките на марка.
  • Измерение на фасет, което не може да бъде обслужено, се отчита под errors, докато всички останали измерения се връщат нормално, така че едно бавно поле не може да изпразни страничната лента с филтри. Ендпойнтите за отделните измерения са непроменени и остават поддържани.
  • GET /api/search приема is_active като документирания запис на превключвателя за приключили лотове: is_active=true (по подразбиране) скрива затворените лотове, is_active=false ги показва в допълнение към активните. Това не е филтър по полето is_active в отговора и не връща само приключили лотове. include_ended е същият превключвател, обърнат, и е непроменен; ако се изпратят и двата, печели include_ended.
  • GET /api/auction/{site}/{id} вече вгражда vault_gallery — точното тяло на /api/auction-images/{site}/{id} (images, count, pending) — така че страницата с детайли е една заявка вместо две. images и gallery_images са непроменени. Двата маршрута четат един запис от кеша и никога не могат да се разминат, а докато pending не е нула, и двата се обслужват с max-age=10, така че клиент с периодични проверки вижда снимките, щом пристигнат.
  • Изпратете Accept-Encoding: gzip и всеки отговор над 2 KB се връща компресиран — от порядъка на една осма от байтовете при пълна страница от търсенето. Повечето HTTP клиенти го договарят прозрачно; някои (особено PHP Guzzle в определени конфигурации) трябва да го включат изрично.
  • /api/search вече носи ETag, както маршрутите за фасети и каталог. Върнете го в If-None-Match и непроменената страница отговаря с 304 Not Modified без тяло. ETag в целия API са слаби (W/"...") по замисъл, така че един таг остава валиден независимо дали тялото е компресирано — сравнявайте ги като непрозрачни низове.
  • GET /api/contract обявява новата повърхност: schemas.auction_detail.optional изброява vault_gallery, schemas.brands_models_facets.optional изброява errors, а version е 2026-08-19.
2026-08-18несъвместима промяна2026-08-18

Версия на договора 2026-08-18 — ценовите полета са JSON числа

  • Ценовите полета вече винаги са JSON числа. Те се сериализираха като низове ("25600.00") при нормално четене, но като числа (25600.0), когато актуалната цена е обновена — едно и също поле, два типа, в зависимост от нещо, което клиентът нито контролира, нито може да предвиди. Не е нужна промяна, ако четете с Number(...), float(...) или в динамичен тип; статично типизиран клиент, който ги декларира като низове, трябва да ги промени на числа.
  • Засегнати полета: start_price, current_price, current_final, current_tax, current_tax_delivery, buy_now_price, buynow_final, buynow_tax, buynow_tax_delivery, final_price, public_price_eur, current_bgn и buynow_bgn.
  • /api/car-details вече връща ценовите полета. Преди не връщаше нито едно от тях, така че двата ендпойнта с детайли не бяха съгласни колко струва колата. Те пристигат под същите имена на горното ниво на отговора, защото това тяло е във формата на източника и няма обвивка auction. Чиста добавка.
  • Новото поле live_price_pending: true означава, че обновяването от източника е изпуснало бюджета на заявката и още върви — прочетете още веднъж след ~2 с и спрете. Тези отговори носят Cache-Control: no-store и X-Live-Price: pending, така че повторното четене не се обслужва от кеша.
  • GET /api/contract обявява новите полета: schemas.auction_detail.optional вече изброява ценовите полета, live_price и live_price_pending.
2026-08-17нова функция2026-08-17

Версия на договора 2026-08-17 — актуални цени при активни търгове

  • Активен търг в openlane вече получава наддаването си, обновено от аукционната къща, докато заявката се обслужва. Няма отделен ендпойнт и параметър за включване: поискайте колата както досега и ако отговаря на условията, получавате текущата стойност.
  • Прилага се за GET /api/auction/{site}/{id} и GET|POST /api/car-details. Търсенето, топ офертите, пазарните анализи и всяко сортиране или филтриране по цена остават с цени от цикъла, така че страница с детайли законно може да показва по-висок current_price от картата в търсенето, от която е отворена — това е наддаване, което се е променило след последния цикъл, а не несъответствие.
  • Обновеният отговор носи блок live_price ({price, currency, source, fetched_at}) и има преизчислени current_price, current_final, current_tax, current_tax_delivery и public_price_eur, така че клиент, който игнорира live_price, пак показва правилното число. buy_now_price и buynow_final никога не се променят.
  • GET /api/contract получава блок live_prices ({enabled, sites, ttl_seconds}). Четете него, вместо да задавате ръчно кои източници поддържат актуални цени, и го използвайте, за да различите „това внедряване не може да обновява цени“ от „тази кола в момента няма“.
  • Обновената цена се използва повторно за ttl_seconds (по подразбиране 120), а Cache-Control: max-age се намалява съответно. Проверката по-често от TTL връща същата стойност.
  • Потокът с обяви получи source_exclude и include_total и вече отчита total_capped (преброяването е спряло на 100 000) и total_unavailable (преброяването не е завършило в рамките на бюджета си) заедно с total. /api/theparking/facets получи limit и value_counts.
2026-08-14нова функция2026-08-14

Версия на договора 2026-08-14 — японски търгове, vehicle_details, премахнати полета, свързани с акаунта

  • Добавени са японските аукционни къщи (USS, ARAI, AUCNET, BAYAUC, CAA) като седми източник под slug japanauction: валидна стойност за site при търсене, детайли за търг, история на цените, снимки и car-details. За japanauction и auto1 /api/car-details приема ID/UUID на офертата, а не числовото ID на търга.
  • Добавен е нормализираният блок vehicle_details в /api/auction/{site}/{id} и /api/car-details — състояние, документи, протоколи от огледи, сервизна история, оборудване, гаранция, характеристики и местоположение, в една форма за всички източници. Пропуска се, докато е details_pending.
  • /api/countries вече връща JP. country=europe е изключване, а не списък: в момента изключва KR (Encar) и JP (японските търгове), а редовете без записана държава се третират като европейски.
  • Търговските данни, свързани с акаунта, вече се премахват на границата на отговора: такси на търговете, история на наддаването, транспорт и всеки ключ delivery*/selfpickup*, плюс идентичността на акаунта ни на купувач във всяка платформа и вътрешните метаданни от обработката. Имейл адресите се премахват от свободния текст. Публикуваните цени, режимът на ДДС, прогнозната цена на ремонта и местоположението на продавача не са засегнати.
2026-08нова функция2026-08-06

Поток с европейски обяви на дребно

  • Добавени са /api/theparking/listings, /api/theparking/facets и /api/theparking/models под новия обхват theparking.
  • Обяви на дребно, събрани от 681 портала източници в 39 европейски държави, с тип продавач и портал източник на всеки ред.
  • Приключилите и платените обяви се изключват от всеки отговор.
2026-06-10нова функция2026-06-10

Версия на договора 2026-06-10

  • Публикувана е версия на договора 2026-06-10 с ограничения на странирането (limit 100, offset 5000).
  • Документиран е публичният достъп от сайта за GET заявки към инвентара, фасетите, каталога, SEO, снимките и състоянието.
  • Документирани са картите от търсенето, детайлите за търговете, галериите, отговорите на каталога и ограниченията на странирането.
2026-05подобрение2026-05-20

Мащаб на архива със снимки и API за галерии

  • Архивът със снимки надхвърли 50 млн. готови WebP файла с served_url от CDN в ендпойнта за галерии.
  • Обявите отбелязват готовите адреси от архива, когато са налични.
  • Ендпойнти за асинхронно/синхронно предварително изтегляне на снимки от Encar при поискване.
2026-03нова функция2026-03-01

Публичен инвентар от много източници

  • Единен публичен поток от Auto1, OpenLane, Schadeautos и Copart DE.
  • Нормализирани clean_make / clean_model / fuel_group / gearbox_group / public_price_eur.
  • Система за архивиране на неактивните лотове (пълен ред + archived_at).