---
title: "API за автомобилни търгове: практическо ръководство за актуални данни от търгове"
description: "Какво връща API за автомобилни търгове, кои европейски търгове са достъпни програмно, как се идентифицират обявите и какво да проверите при доставчика."
slug: car-auction-api-guide
canonical: https://thecarapi.com/bg/blog/car-auction-api-guide
category: Основи
author: Инженерен екип на Авто Данни
published: 2026-02-11
updated: 2026-08-07
tags: [API за автомобилни търгове, автомобилни данни, инвентар от търгове, REST API]
---

# API за автомобилни търгове: практическо ръководство за актуални данни от търгове

Всеки екип, който изгражда върху инвентар от търгове, се блъска в същите три стени: идентичност, актуалност и снимки. Ето как реално се държат данните и какво да попитате доставчика, преди да подпишете.

API за автомобилни търгове е интерфейс за четене на инвентара на едро: лотовете, които търговци, износители и ремаркетинг платформи търгуват помежду си, преди колата изобщо да стигне до площадка за продажба на дребно. Звучи като решен проблем — обявите са публични, страниците се показват в браузъра, данните са там. На практика това е една от най-хаотичните области на данни в автомобилния бранш, а хаосът е структурен, не случаен.

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

## Какво реално съдържат данните за инвентара от търгове

Полезен мисловен модел: всеки лот от търг има четири слоя и те се обновяват с напълно различна скорост.

| Слой | Какво съдържа | Колко често се променя |
| --- | --- | --- |
| Идентичност | Платформа източник, ID на лота, VIN, когато е публикуван, марка, модел, версия, година | Веднъж, при обявяването |
| Спецификация | Пробег, гориво, скоростна кутия, мощност, купе, оборудване, отметки за щети | Рядко — само корекции |
| Търговски | Текущо наддаване, цена „купи сега“, състояние на резерва, край на търга, такси | Постоянно, понякога всяка минута |
| Медия | Галерии, протоколи за състоянието, близки планове на щети, протоколи от оглед | Веднъж, после изтича заедно с лота |

_Третирането на четирите като едни данни с едно TTL на кеша е най-честата архитектурна грешка в тази област._

Търговският слой е причината наивното кеширане да се проваля. Цена, извлечена преди четиридесет минути, не е цена; тя е историческо наблюдение. Медийният слой пък е обратният проблем — галериите почти никога не се променят, но адресите от източника често спират да работят до дни след затварянето на лота, така че всичко, което не сте копирали, е изгубено.

## Европейският пейзаж на търговете

Пазарът на едро в Европа не е една платформа. Това са шепа големи платформи с различни модели на достъп, различни географски центрове и — критично — различни представи какво е „модел“.

- **Auto1** — със седалище в Германия, най-голямата общоевропейска платформа на едро по обем. Ориентирана към търговци.
- **OpenLane** — ремаркетинг платформата зад това, което исторически беше ADESA Europe и CarsOnTheWeb. Силна в Бенелюкс, Франция и Германия.
- **Schadeautos** — нидерландска, специализирана в повредени автомобили, с необичайно подробни описания на щетите.
- **Copart Germany** — германското подразделение на групата за търгове с повредени коли. Вътре в митническия съюз на ЕС, което напълно променя сметката за митата спрямо повредени коли от САЩ.
- **Encar** — водещата платформа за употребявани коли в Южна Корея. Високо качество на обявите, честна култура за километража и пазар, който изнася много.
- **Японски търгове** — големите местни аукционни къщи (USS, ARAI, AUCNET, BAYAUC, CAA), обединени в един източник, с протокол от огледа, оценка на състоянието и страна на волана за всеки лот.

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

> **Цените на дребно са отделен набор от данни** — Цените от търговете на едро разказват само половината история. За да знаете дали един лот е евтин, ви трябва обявената цена на дребно за същата кола на същия пазар. Държим ги отделно съзнателно — вижте [пазарните анализи](/market-data) — защото смесването на обяви с търсенето в търгове дава резултати, по които никой не може да действа.

## Идентичността е трудният проблем, не събирането

Повечето екипи приемат, че трудността е в изтеглянето на страниците. Не е. Трудността е да отговорите на въпроса „това същата кола ли е?“ между дванадесет платформи, всяка от които е измислила собствена класификация.

Конкретен пример. Един и същ физически автомобил може да е обявен като `BMW 320d Touring xDrive`, `BMW 3-Series 320 d Touring`, `BMW SERIE 3 TOURING 320dA xDrive` и `BMW 320` с вида на купето в отделно поле. Групирайте ги по равенство на низовете и получавате четири модела. Групирайте ги твърде агресивно и 320d се слива с 320i, което е друга кола на друга цена.

VIN би решил това. VIN обаче е рядкост — много обяви на едро го показват само на влезли търговци или изобщо не, а попълнеността варира силно по източник и държава. Всяка архитектура, която приема VIN за ключ за свързване, ще работи прекрасно на тестовите ви данни и ще се срине в продукция.

Работещият отговор е слой за нормализиране, който създава стабилни канонични полета до суровите стойности от източника, така че да филтрирате по чистата версия и пак да можете да проверите оригинала:

```json
{
  "auction_id": 38112900,
  "site_name": "encar",
  "car_name_en": "BMW 320d xDrive Touring M Sport",
  "clean_make": "BMW",
  "clean_model": "320d",
  "registration_year": 2020,
  "mileage": 45000,
  "fuel_group": "Diesel",
  "gearbox_group": "Automatic",
  "public_price_eur": 21500,
  "has_technical_damage": false,
  "car_identification": { "...": "raw source payload, unmodified" }
}
```

_`clean_make` / `clean_model` / `fuel_group` са канонични за всички източници. `car_identification` пази недокоснатите данни от източника за случаите, когато нормализирането греши и трябва да видите защо._

## Стабилни идентификатори между източниците

Идентификаторите на лотовете са уникални в рамките на една платформа и безсмислени между платформите. Две платформи спокойно може и двете да имат лот `4471928`. Идентичността, която оцелява, е двойката:

```text
site_name + auction_id     →  encar/38112900
                            →  auto1/1313664441
                            →  openlane/11125938
```

Всеки ендпойнт за детайли, снимки и история трябва да се адресира с тази двойка. Ако доставчикът ви дава синтетичен вътрешен идентификатор вместо това, попитайте какво става с него при повторно индексиране на източник — синтетичните идентификатори, които се сменят при реиндексиране, тихо ще счупят всеки външен ключ в базата ви.

## Актуалност и какво означава число като „3 минути“

Доставчиците посочват закъснение на синхронизацията. Числото е почти безсмислено, без да знаете какво измерва. Питайте конкретно:

1. Това закъснението за **появата на нови обяви** ли е или за **промените в цените на съществуващи обяви**? Обикновено това са различни системи с различни бюджети.
2. Медиана ли е или най-лошият случай? Медиана от три минути с p99 от четири часа е много различен продукт.
3. Какво става с лота, когато **приключи**? Изчезва ли, отбелязва ли се или тихо замръзва на последната наблюдавана цена? Замръзнал продаден лот, който още изглежда активен, ще повреди всеки ценови модел, обучен върху него.
4. Еднакво ли е закъснението за всички източници, или един източник се обновява на час и се усреднява в ласкаещо общо число?

> **Капанът на остарелия лот** — Ако приключилите търгове не се отбелязват изрично, търсенето ви „най-евтиното BMW 320d в Германия“ в крайна сметка ще върне кола, продадена преди три седмици на цена, която никой вече не може да получи. Проверете, че API показва изрично състояние на жизнения цикъл и че филтрирането по него е по подразбиране, а не по избор.

## Снимките са по-голям разход от данните

Една обява на едро има от 20 до 60 снимки. При милион активни автомобила това са десетки милиони снимки и те са частта от данните, която потребителите ви реално гледат. Три свойства ги правят скъпи:

- **Изтичат.** Адресите в CDN на източника често спират да работят, щом лотът се затвори. Ако продуктът ви показва исторически продажби, директните връзки гарантират счупени галерии.
- **Защитени са срещу hotlink.** Много източници проверяват `Referer` или изискват сесия. Вграждането на адресите от източника директно във фронтенда води до периодични, трудни за възпроизвеждане проблеми със снимките.
- **Не са оптимизирани.** Оригинални JPEG по 3–6 MB са наред за браузър на компютър с бърз интернет и катастрофални за мобилна решетка с обяви.

Практическото изискване е архив: снимките се копират при импортиране, прекодират се в WebP и се сервират от CDN на доставчика под адреси, които надживяват лота. Попитайте дали сервираният адрес остава стабилен след края на търга — този единствен въпрос отличава медиен API от препращач на връзки.

```bash
curl -s "https://api.thecarapi.com/api/auction-images/openlane/11125938" \
  -H "X-API-Key: $API_KEY"
```

_Ендпойнтите за галерии се адресират със същата двойка `site/id` като детайлите и историята на цените._

## Първа интеграция от край до край

Формата на работеща интеграция почти винаги е една и съща: откриване на речника за филтрите, търсене, след това извличане на детайли и снимки само за това, което потребителят отвори.

```bash
# 1. Научете речника — никога не задавайте ръчно низове за марки или горива
curl -s "https://api.thecarapi.com/api/brands" -H "X-API-Key: $API_KEY"
curl -s "https://api.thecarapi.com/api/fuels"  -H "X-API-Key: $API_KEY"

# 2. Търсене — филтриране на сървъра, страниране с limit/offset
curl -s "https://api.thecarapi.com/api/search?brand=bmw&fuel=Diesel\
&year_from=2018&price_to=30000&sort=price_low&limit=24" \
  -H "X-API-Key: $API_KEY"

# 3. Детайли само за лота, който потребителят е отворил
curl -s "https://api.thecarapi.com/api/auction/encar/38112900" -H "X-API-Key: $API_KEY"

# 4. Галерията се зарежда мързеливо, след отваряне на детайлите
curl -s "https://api.thecarapi.com/api/auction-images/encar/38112900" -H "X-API-Key: $API_KEY"
```

Два навика, които си струва да възприемете от самото начало. Първо, изграждайте интерфейса за филтри от ендпойнтите на каталога, а не от ръчен списък — речниците на източниците се променят и ръчно зададено `Petrol`, което при източника стане `Gasoline`, се проваля тихо като празен резултат. Второ, подавайте `include_total=false` при безкрайно превъртане; преброяването на съвпадащите редове често е най-скъпата част на търсенето, а числото рядко ви трябва.

## Какво да проверите, преди да се обвържете

Списък, който е спасил не една интеграция от пренаписване шест месеца по-късно:

- **Версии на договора.** Носи ли всеки отговор версия на схемата и има ли документиран период за отпадане? Тихите преименувания на полета са най-честият източник на сривове в продукция.
- **Проследяване на заявките.** Има ли идентификатор на заявката в отговора и в заглавка, така че разговорът с поддръжката да е за конкретно извикване, а не за описание на такова?
- **Достъп до архива.** Можете ли да четете вече приключили лотове? Без история няма ценови модели, няма сравнения и няма как да прецените дали активен лот е добре оценен.
- **Лимити на заявките и дълбочина на страниране.** Колко дълбоко можете да странирате? Твърдо ограничение на отместването до няколко хиляди реда прави масовото сверяване невъзможно и често не е документирано.
- **Ограничаване на функции.** Търсене, детайли, снимки и история налични ли са в началния план, или полезната половина е зад корпоративен план, който ще откриете едва при мащаб?
- **Достъп до суровите данни.** Когато нормализирането сгреши — а ще сгреши — можете ли да видите какво реално е казал източникът?

## Накъде след това

Ако преценявате дали да събирате това сами или да го купите, [реалната разбивка на разходите за скрейпване на търгове](/blog/scraping-car-auction-sites-vs-api) поставя числа и на двете. Ако вече сте решили да нормализирате няколко потока сами, [ръководството за нормализиране](/blog/vehicle-data-normalization) разглежда подробно проблемите с класификациите. А [API справочникът](/docs) документира всеки споменат тук ендпойнт с актуалните параметри.

## Frequently asked questions

### Има ли официален публичен API за Auto1, OpenLane или Encar?

Нито една от големите европейски платформи на едро не публикува универсален самообслужващ се API за инвентар за произволни външни разработчици. Там, където има програмен достъп, той обикновено минава през търговско партньорство или дилърски акаунт с договорни условия. Условията се различават по платформи и държави и се променят, затова проверете директно с всяка платформа за конкретния си случай.

### Как се съпоставя един и същ автомобил между различните платформи за търгове?

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

### Какъв идентификатор да пазя в собствената си база данни?

Пазете slug на платформата източник заедно със собствения идентификатор на лота в платформата — например `encar/38112900`. Тази двойка е стабилна, с нея се адресира всеки ендпойнт за детайли, снимки и история на цените и оцелява при реиндексиране. Избягвайте да разчитате на синтетичен вътрешен идентификатор на доставчика, освен ако той не гарантира, че е стабилен при реиндексиране.

### Защо снимките от обявите на търгове спират да работят след няколко седмици?

Платформите източници прекратяват адресите на медията, щом лотът се затвори, а много от тях прилагат защита срещу hotlink, която проверява referrer на заявката. Всеки продукт, който показва исторически обяви, се нуждае от снимки, копирани и хоствани отново при импортиране, а не свързани, иначе галериите му ще се разпадат със затварянето на лотовете.

### Трябват ли ми исторически данни от търгове, или актуалният инвентар е достатъчен?

Актуалният инвентар е достатъчен, за да изградите продукт за търсене. Не е достатъчен, за да прецените дали даден лот е добре оценен — за това трябват сравними приключили продажби — нито за обучение на какъвто и да е ценови модел. Ако ценовите анализи са някъде в плановете ви, потвърдете достъпа до архива, преди да изберете доставчик — историята, която никога не сте събрали, не може да се добави впоследствие.