Документация

Базовый URL

Все запросы к API выполняются по следующему базовому URL:

https://api.encarapi.com

Например, для получения предложений:

GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true

Аутентификация

Аутентифицируйте свои запросы с помощью API-ключа. Передайте его как параметр запроса или через заголовок Authorization.

# Send your API key in the x-api-key header (recommended):
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true"

# The api_key query parameter also works:
GET https://api.encarapi.com/api/catalog?manufacturer=bmw&fuel=diesel&lang=en&count=true&api_key=YOUR_API_KEY

5-дневный пробный период

Протестируйте API в течение 5 дней со всеми тремя площадками (Encar, KB Chachacha, K Car), включая синхронизацию изменений (последние 7 дней), пакетные запросы (1 000 id в день) и предпросмотр архива (100 удалённых объявлений в день). 100 000 строк каталога и 2 000 запросов деталей всего (не более 1 000 в день). Справочные файлы для скачивания (CSV) входят в платные планы. Полный экспорт каталога доступен начиная с плана Business. После пробного периода ваша подписка продолжается на плане Starter по цене 149 €/месяц - отменить можно в любой момент до 5-го дня.

Значения на русском (lang=ru)

Каждый эндпоинт, который принимает lang=en, принимает и lang=ru: отображаемые значения приходят на русском, всё остальное остаётся прежним (id, коды, цены, числа, названия полей). Если для значения нет русского названия, возвращается английское. Русские названия со временем могут уточняться, поэтому связывайте данные по id и кодам, а не по названиям.

• Переводятся: топливо, коробка передач, привод, цвет кузова и салона, класс кузова, тип продажи, названия регионов и городов, названия опций и общие слова в названиях комплектаций (Diesel -> дизель, 7-Seater -> 7 мест). Поколения моделей: Carnival 4 Gen -> Carnival 4 поколение. Марки, модели и комплектации остаются на латинице, как на российских автоплощадках.
• Фильтры принимают и русские значения: fuel=дизель, color=белый, region=Сеул, city=Сувон, drivetrain=полный, sell_type=лизинг. Английские значения продолжают работать.
• /api/enums?lang=ru добавляет nameRu к каждому значению и выводит значения drivetrain и sell_type. /api/nav?lang=ru возвращает русский DisplayValue; Value остаётся английским кодом для фильтрации. Справочные CSV с lang=ru получают русское название дополнительной колонкой после последней.
• /api/vehicle/{id}?lang=ru и bulk-эндпоинт возвращают значения spec Encar, названия category и названия optionsDecoded на русском, а объявления KB Chachacha так же, как в каталоге.
• /api/catalog/export?lang=ru - тот же файл с колонками названий на русском; порядок колонок и все остальные колонки не меняются.
• Не переводятся: отчёты о проверке, страховая история, диагностика Encar, истории автомобилей Encar, детальные данные K Car, пакеты опций Encar (свободный текст из объявления), а также эндпоинты грузовиков и экскаваторов (при lang=ru они отвечают на английском).

# Russian values, filtered with Russian values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?fuel=дизель&city=Сувон&lang=ru&count=true"

# Filter values with their Russian labels (nameRu)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/enums?lang=ru"

Значения на немецком (lang=de)

lang=de работает так же, как lang=ru: отображаемые значения приходят на немецком, всё остальное остаётся прежним (id, коды, цены, числа, названия полей). Если немецкого названия нет, возвращается английское.

• Переводятся: топливо, коробка передач, привод, цвета, класс кузова, тип продажи, названия опций, а также названия моделей и комплектаций из наших немецких таблиц (C-Class -> C-Klasse, 5-Series -> 5er, Carnival 4 Gen -> Carnival 4. Generation, 7-Seater -> 7-Sitzer, Sedan -> Limousine). Регионы - английские названия, города остаются на английском.
• Фильтры принимают и немецкие значения: fuel=Benzin, color=Weiß, transmission=Automatik, drivetrain=Allrad, sell_type=Leasingübernahme, model_group=C-Klasse. Немецкие названия моделей могут объединять рестайлинги: Carnival 4. Generation охватывает Carnival 4 Gen и The New Carnival 4 Gen.
• Списки, детальные данные, bulk и экспорт работают как с lang=ru: nameDe в /api/enums и /api/taxonomy/option-packages, немецкий DisplayValue в /api/nav, колонки *_de в справочных CSV, catalog_export_de.csv для экспорта. Не переводится то же, что и при lang=ru.

# German values, filtered with German values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?manufacturer=Mercedes-Benz&model_group=C-Klasse&fuel=Benzin&lang=de&count=true"

Три площадки, один API

API отдает актуальные объявления с трех крупнейших корейских площадок подержанных автомобилей. Каждая конечная точка по умолчанию возвращает Encar, поэтому существующие интеграции продолжают работать без изменений. Две другие подключаются через параметр source.

Выбор источников

source принимают /api/catalog, /api/nav, /api/enums, /api/model-search, /api/catalog/export, /api/catalog/changes и CSV-файлы таксономии.

# All three marketplaces, English values
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=all&manufacturer=bmw&fuel=diesel&lang=en&count=true"

# K Car only
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/catalog?source=kcar&manufacturer=hyundai&lang=en"

# One KB Chachacha vehicle
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.encarapi.com/api/vehicle/kbc:12345678?lang=en"

Если задан source, каждый элемент содержит поле Source. Идентификаторы Encar остаются обычными числами. Идентификаторы KB Chachacha и K Car имеют префикс (kbc:..., kcar:...) - передавайте их в /api/vehicle/{id} без изменений. При lang=en названия моделей и комплектаций всех трех площадок возвращаются на английском.

Дилеры часто размещают один и тот же автомобиль на Encar и KB Chachacha. Объявление KB Chachacha сопоставляется с активным объявлением Encar по корейскому госномеру, а если KB Chachacha не публикует номер - по месяцу первой регистрации, пробегу и цене; сопоставление пересчитывается несколько раз в день, после каждого прохода по каталогам Encar и KB Chachacha. Сопоставленные объявления KB Chachacha не возвращаются /api/catalog, /api/catalog/export и другими эндпоинтами каталога, с source или без него (в том числе при одном source=kbc), поэтому один и тот же автомобиль никогда не появляется дважды - если Encar включён, он возвращается как объявление Encar.

В /api/catalog/changes?source=kbc и /api/vehicle/kbc:{id} такие объявления содержат IsDuplicate: true и DuplicateOf (ID объявления Encar, числовая строка); как и у элементов Encar, оба поля присутствуют, только когда они равны true. Когда отметка ставится или снимается, лента изменений записывает событие updated, у которого changedFields содержит duplicate. Чтобы локальная копия совпадала с /api/catalog, удаляйте элементы KB Chachacha, которые приходят с IsDuplicate: true, и добавляйте их обратно, когда придёт обновление без этого поля.

Лента изменений принимает один источник за вызов (encar, kbc или kcar) и ведет отдельный курсор для каждого.

Покрытие по площадкам

Не каждая площадка публикует каждое поле.

• KB Chachacha публикует количество мест для части своих объявлений.
• Детализация KB Chachacha = элемент каталога плюс публичный блок истории (признак ДТП, полная гибель, затопление, коммерческое использование, залоги, диагностика рамы и кузовных панелей). Каждый элемент KB Chachacha также содержит InsuranceClaims: число страховых случаев, указанное на странице объявления. Детали также содержат InspectionReportUrl и InspectionReportType - лист осмотра, который KB Chachacha показывает для автомобиля (link = отчёт на сайте компании, проводившей осмотр, scan = только отсканированные изображения на странице объявления, null = пока неизвестно). Если InspectionAvailable имеет значение true, GET /api/inspection/kbc:{id} возвращает этот лист как структурированные данные в том же формате, что и отчёт об осмотре Encar (master, outers, inners, images), плюс блок source - примерно для двух из пяти объявлений KB Chachacha со ссылкой на лист.
• У K Car нет отдельных документов отчетов; количество ДТП, страховые выплаты и смены владельца входят в детализацию автомобиля.

Фильтрация по полю, которое площадка не предоставляет, исключает автомобили этой площадки из результатов. Пример: frame_clean=true с source=all возвращает только объявления Encar и K Car.

Конечные точки API

Все доступные конечные точки для получения данных корейских автомобилей.

Данные для выпадающих списков (CSV)

Скачайте списки марок, моделей и бейджей в формате CSV, закэшируйте их и стройте свои выпадающие списки на их основе - без запросов фасетов на каждый клик и без офлайн-сопоставления. Каждый файл содержит столбец с количеством, а файл бейджей несёт разбивку по типам кузова (Купе / Седан / Кабриолет).

Часто задаваемые вопросы