Актуални цени

Два вида цени и си струва да знаете кой държите. Съхранените характеристики, състояние, наличност и цени отразяват последното успешно обновяване на тези полета. Обява с фиксирана цена също може да се промени при източника между обновяванията; цената от цикъла е последното наблюдение, а не гаранция за текуща наличност или оферта за покупка.

Изключението е активен търг с открито наддаване, при който сумата може да се промени всеки път, когато някой наддаде. Отговарящите на условията лотове в OpenLane получават актуално наддаване при заявки за детайли. Наскоро извлечено наддаване се използва повторно в рамките на TTL на актуалната цена. Студено обновяване може да е още в процес или да се провали, като остави съхранената цена.

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

Кои източници

Не задавайте този списък ръчно — четете live_prices.sites от GET /api/contract.

Четене на отговора

Когато цената е обновена, тялото с детайлите получава:

"live_price": {
  "price": 25900,
  "currency": "EUR",
  "source": "openlane",
  "fetched_at": 1786659750
}

price е суровото наддаване в аукционната къща. fetched_at е Unix време в секунди — използвайте него, а не собствения си часовник, за индикатор „към“. В същото време съществуващите ценови полета се презаписват със стойности, преизчислени от това наддаване, и в двата ендпойнта за детайли, така че клиент, който изобщо игнорира live_price, пак показва правилното число.

Къде стои блокът

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

// /api/auction/{site_slug}/{auction_id} — обвито в "auction"
{ "success": true,
  "auction": { "auction_id": 11409652,
               "current_price": 25900,
               "current_final": 33566,
               "public_price_eur": 33926,
               "live_price": { "price": 25900, "currency": "EUR" } } }

// /api/car-details — с формата на източника, така че същите ключове са на горното ниво
{ "success": true, "site": "openlane", "auction_id": 11409652,
  "current_price": 25900,
  "current_final": 33566,
  "public_price_eur": 33926,
  "auction": { "extracted_fields": { "images": [] } },
  "live_price": { "price": 25900, "currency": "EUR" } }

Ценовите полета са JSON числа

Цените са JSON числа и в двата ендпойнта, независимо дали е имало актуално обновяване. Преди договор 2026-08-18 те се сериализираха като низове при нормално четене, но като числа, когато актуалната цена е обновена — едно и също поле, два типа, сменящи се по нещо, което клиентът нито контролира, нито може да предвиди.

- "current_price": "25600.00"
+ "current_price": 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

Когато няма актуална цена

Блокът live_price липсва винаги, когато цената не е обновена. Това покрива няколко различни ситуации и освен двете, отбелязани по-долу, те не се различават в отговора с детайли:

• Източникът не е OpenLane — поддържаният източник за актуални цени.
• Търгът вече е приключил.
• Колата все още няма наддавания. Често при закритите търгове, където кола без текущо наддаване не публикува цена изобщо.
• current_price остава null и това е правилният, окончателен отговор — не липсваща стойност, за която да опитвате отново. Този случай можете да разпознаете: отговорът с детайли съдържа is_blind: true и това е единственият надежден начин да различите „никога няма да има цена“ от „в момента няма цена“.
• Актуалните цени не са налични в това внедряване.
• Обновената стойност не е пристигнала навреме за този отговор. Този случай е различен и отговорът ви го казва — вижте live_price_pending по-долу.

Липсата му никога не означава, че съхранената цена е грешна. Означава, че гледате цена от цикъла, което е нормалното състояние за огромното мнозинство обяви. За да различите „актуалните цени не са налични“ от „тази кола в момента няма“, прочетете live_prices.enabled от /api/contract веднъж при стартиране; където функцията изобщо не съществува, целият блок live_prices липсва.

live_price_pending: обновяването, което закъсня

Заявката ви никога не чака аукционната къща. Когато актуална стойност не е налична веднага, отговорът се връща незабавно с последната известна цена плюс live_price_pending: true, а обновената стойност е готова след няколко секунди. Нищо не се губи; просто е изпуснала вашия отговор.

Използвайте флага, за да насрочите едно отложено повторно четене. Ако наддаването още не е налично, запазете последната наблюдавана цена с времето ѝ, вместо да проверявате безкрайно; по-късно обновяване по желание на потребителя може да успее. Отговорът в изчакване се изпраща с Cache-Control: no-store и X-Live-Price: pending, така че браузър, CDN или споделено прокси не може да отговори на повторната ви заявка със същото тяло, което е изпуснало цената.

async function vehicleWithLivePrice(site, id) {
  const first = await getJson(`/api/auction/${site}/${id}`);
  if (first.auction.live_price || !first.auction.live_price_pending) return first;

  // Обновяването е изпуснало бюджета, но още върви. Точно още едно четене.
  await new Promise((r) => setTimeout(r, 2000));
  return getJson(`/api/auction/${site}/${id}`);
}

Периодични проверки

Обновената цена остава актуална за live_prices.ttl_seconds (по подразбиране 120), а Cache-Control: max-age в отговора съвпада. Проверката по-често от това връща същата стойност и не ви дава нищо — спазвайте max-age. Това е за всяко четене, а не абонамент: да поискате колата веднъж ви дава наддаването в този момент; не продължава да следи, докато държите страницата. Наддаване, което се промени след това, се появява при следващото ви четене след изтичане на TTL.

Какви промени да очаквате

Актуалното наддаване може да се различава от последното съхранено наблюдение. API не обещава максимална разлика; използвайте върнатата стойност и времето fetched_at. Третирайте live_price като корекция, а не поток — правилното е да го четете, когато потребителят отвори автомобил, и грешното — да го проверявате в цикъл.

Какво остава с цени от цикъла

Само пътят за детайли е актуален. /api/search, /api/top-offers, ендпойнтите за пазарни анализи и всяко сортиране или филтриране по цена четат цени от цикъла.

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