Удостоверяване и обхвати
Три равностойни начина за подаване на ключ, ограниченията, които ключът може да носи, и групите обхвати, които дават достъп до всеки ендпойнт.
Всеки ендпойнт освен двете проверки за работа (/api/health/live и /api/health/ready) изисква API ключ. Подайте ключа по един от тези начини:
| Начин | Заглавка или параметър | Бележки |
|---|---|---|
| Заглавка | X-API-Key: <key> | Препоръчително за извиквания от сървър към сървър. |
| Bearer | Authorization: Bearer <key> | Равностойно на X-API-Key. |
| Параметър в адреса | ?api_key=<key> | Изключено по подразбиране; използвайте само ако е изрично разрешено за ключа ви. Ключовете в адресите попадат в журнали и referrer. |
# Заглавка — нормалният случай
curl -H "X-API-Key: $API_KEY" "https://api.thecarapi.com/api/sites"
# Bearer — същото поведение, удобно, когато HTTP слоят ви вече работи с OAuth
curl -H "Authorization: Bearer $API_KEY" "https://api.thecarapi.com/api/sites"Ограничения на ключа
| Ограничение | Ефект при нарушение |
|---|---|
| Списък с разрешени IP или CIDR | Заявките извън списъка връщат 403. |
| Списък с разрешени произходи | Заявките от браузър от други произходи връщат 403. |
| Дата на изтичане | Заявките след датата връщат 401. |
| Статус (отменен, спрян) | Всички заявки връщат 403. |
| Набор от обхвати | Заявка към маршрут, който ключът ви не покрива, връща 403 с {"success": false, "error": "API key is not authorized for this route"}. В тялото няма машинно четим код на грешка — разклонявайте по статуса, а не по текста на съобщението. |
Пет неуспешни опита за удостоверяване от един IP задействат временно блокиране срещу налучкване: всяка следваща заявка от този адрес отговаря с 429 за 15 минути, включително заявките с валиден ключ. Успешното удостоверяване нулира брояча, така че клиент, който поправи ключа си при първия или втория неуспех, никога не стига прага. Не повтаряйте 401 в цикъл.
Публикувани групи обхвати
| Обхват | Публикуван достъп |
|---|---|
search | Търсене в инвентара, фасети за филтри (поотделно или заедно през /api/facets), източници и пълният каталог с модели |
catalog | Каталог на производителите и групите модели |
seo | Популярни търсения и разпознаване на slug за марка/модел |
auctions | Детайли за търг, групови детайли, снимки, история на цените и история по VIN |
details | Пълни детайли за автомобила, включително извличане от източника |
top-offers | Търгове с цена под пазарната референция |
classifieds | Поток с европейски обяви, фасети, модели и разпознаване на адреса на източника (theparking остава наследен синоним). Масовият експорт не е включен |
classifieds-export | Масов експорт на обяви. Дава се само на одобрени акаунти |
archive | Търсене в историческия инвентар, съхранени детайли, покритие, фасети и статистика на крайните цени |
market | Пазарна оценка плюс пазарните ценови снимки от Cars.bg и търговете |
ships | Търсене на кораби, позиция и маршрут и собствените пратки на ключа |
watches | Запазени търсения на автомобили с проверка за нови съвпадения и webhook |
carvalue | Инструментът CarValue: оценка по VIN или марка/модел и разчитане на VIN от снимка. Акаунтът на ключа също трябва да има достъп до CarValue |
vehiclescan | Инструментът Vehicle Scan: запазени заявки за автомобили и съвпадащите оферти. Акаунтът на ключа също трябва да има достъп до Vehicle Scan |
calculator | Калкулатор за разходи по вноса и поддържани държави |
ops | Състояние на услугата, договорът и индексът на API |
* дава достъп до всеки маршрут. Обхватът може да е и буквално правило за адрес вместо група. public е наследен пакет за съвместимост — фасети за търсене, каталог, SEO, търгове, калкулатор и състояние — запазен за по-стари интеграции; новите ключове се издават с групите по-горе.
Права за полета
| Група | Полета | По подразбиране |
|---|---|---|
listing | Идентичност, характеристики, снимки, време и режим на ДДС | Винаги се запазва |
source_prices | current_price, buy_now_price, start_price, final_price | Включено |
landed_prices | current_final, buynow_final, public_price_eur, current_bgn, buynow_bgn | Включено |
house_valuation | estimated_value_eur | Включено, където е налично |
vehicle_identity | chassis_number, car_id, vin_ocr | Включено, където е налично; достъпът до маршрута за история по VIN е отделен |
crawl_meta | created_at, updated_at, first_seen_at, last_seen_at, last_available_at, last_changed_at | Включено, където е налично |
landed_breakdown | current_tax, buynow_tax, current_tax_delivery, buynow_tax_delivery | Отделно разрешение |
market_reference | is_top_offer, top_offer_savings, top_offer_savings_pct, market_reference | Отделно разрешение |
korea_merge | source_comparison, canonical_offer | Отделно разрешение |
Това са настройки по подразбиране при издаване, а не обещание за съществуващ ключ. Достъпът до ендпойнт не дава автоматично всяко поле в отговора: например top-offers може да е достъпен, докато блокът му market_reference е пропуснат. Примерите показват илюстративни полета; използвайте OpenAPI схемата и обработвайте пропуснатите незадължителни полета. Частните данни на наддаващите и идентификационните данни на акаунтите остават изключени независимо от правата за полета.
Какво получава новият ключ по подразбиране
Обхватите се дават за всеки ендпойнт, а новият клиентски ключ се издава с включена обща повърхност и изключено всичко останало. Ако маршрут отговори с 403 на ключа ви, той не е счупен — не е разрешен и операторът може да го включи.
| Ендпойнти | |
|---|---|
| Включени по подразбиране | /api/search, /api/brands, /api/models, /api/types, /api/years, /api/production-years, /api/fuels, /api/countries, /api/gearboxes, /api/sites, /load-models, /api/facets, /api/catalog/*, /api/seo/*, /api/auction/* (включително /api/auction/batch), /api/auction-images/*, /api/vin/*, /api/archive/*, /api/calculator/*, /api/top-offers, /api/classifieds/* (без експорта), /api/car-details, /api/contract, /api/health, / |
| Дават се по договор | /api/market/valuation, /api/vessels/*, /api/shipments, /api/watches, /api/carvalue/*, /api/vehiclescan/* |
| Дават се при заявка | /api/cars-bg-market, /api/auction-market, /api/listVehicles (и /listVehicles), /api/search/auction-ids |
| Заключени — само за одобрени акаунти | /api/classifieds/export (масов експорт). Не е наличен със стандартен ключ; свържете се с нас, за да кандидатствате. |
/api/health/live и /api/health/ready не изискват ключ и не се влияят от обхватите.