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

Get JWT token

Exchange API key for a JWT access token.

Тело запроса (обязательно)

{
  "api_key": ""
}

Пример запроса

curl -X POST "https://union.api-centr.ru/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key":""}'

Ответ 200

{
  "access_token": "",
  "token_type": "bearer"
}

Ответ 422

{
  "detail": [
    null
  ]
}

Current user info

Return current user info from JWT.

Пример запроса

curl -X GET "https://union.api-centr.ru/auth/me" \
  -H "Authorization: Bearer $UNION_API_KEY"

Register Link

Ссылка на регистрацию в Telegram боте.

Пример запроса

curl -X GET "https://union.api-centr.ru/register-link"

Api Guide

Краткое руководство по API.

Пример запроса

curl -X GET "https://union.api-centr.ru/guide"

Search cars

Search vehicles with filters, sorting, pagination. Market parameter is required. Results are cached in Redis for 300 seconds.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars?market=che168&country=DE&fuel_type=gasoline&transmission=manual&sort=price_asc&page=1&limit=20" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{
  "data": [
    {
      "brand": "BMW",
      "city": "Berlin",
      "currency": "EUR",
      "fuel_type": "diesel",
      "id": "12345",
      "mileage": 35000,
      "model": "X5",
      "price": 45000.0,
      "transmission": "automatic",
      "year": 2020
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 20,
    "market": "encar",
    "page": 1,
    "took_ms": 42,
    "total": 1
  }
}

Ответ 422

{
  "detail": [
    null
  ]
}

Aggregations & stats

Returns statistics (price, year, fuel types) without detailed listings.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/aggregations?market=che168&country=DE&fuel_type=gasoline&transmission=manual" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Filter values

Returns available values for the given field with current filters. Параметр field обязателен.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/filters?market=che168&field=brand&fuel_type=gasoline&transmission=manual&country=DE" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Numeric field ranges

Min and max values for price, year, mileage, engine_cc given the current filters.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/range?market=<market>&fuel_type=gasoline&transmission=manual" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Autocomplete

Suggestions for text input. Params: field, query, limit.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/suggest?market=<market>&field=<field>&query=&limit=10" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

[
  {}
]

Ответ 422

{
  "detail": [
    null
  ]
}

Distinct field values

All distinct text field values (city, color, body_type, etc.) with pagination.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/distinct/{field}?market=<market>&limit=50&offset=0" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

[
  ""
]

Ответ 422

{
  "detail": [
    null
  ]
}

Attribute keys and values

List all unique JSON attribute keys with value counts. Comma-separated market codes. Empty = all markets.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/attributes?market=" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Market statistics

Overall stats: total listings, avg price, new today.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/stats?market=<market>" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Similar listings

Similar vehicles — same brand/model, closest price and year. Тариф: по одной записи за каждый отданный похожий автомобиль (per_unit). Безлимит на рынок покрывает. При недостаточном балансе — HTTP 402.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/{car_id}/similar?market=<market>&limit=6" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

[
  {}
]

Ответ 422

{
  "detail": [
    null
  ]
}

Get listing by ID

Full details for a single listing with all fields. Тариф: одна запись по тарифу аккаунта (per_unit). Безлимит на рынок покрывает. Если авто не найдено — запись не тарифицируется (возврат). При недостаточном балансе — HTTP 402.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/{car_id}?market=<market>" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Inspection report with body damages (encar)

Builds a car inspection report. Damage/inspection data is fetched from the external car-report service; only encar market is supported. Тариф: 1 ₽ за запись с заполненным отчётом (checkup/resume). Списание НЕ покрывается безлимитом на рынок и не входит в подписку — платный тариф применяется всегда, когда по car_id возвращён заполненный отчёт (has_checkup=true). Если отчёта по авто нет — запись не тарифицируется (возврат). При недостаточном балансе — HTTP 402.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/{car_id}/report?market=<market>&lang=ru" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Batch fetch by ID

Batch fetch: up to 100 vehicles by ID list. Тариф: по одной записи за каждый найденный автомобиль (per_unit). Ненайденные id не тарифицируются (возврат разницы). Безлимит на рынок покрывает. При недостаточном балансе — HTTP 402.

Тело запроса (обязательно)

{}

Пример запроса

curl -X POST "https://union.api-centr.ru/api/v2/cars/batch" \
  -H "Authorization: Bearer $UNION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответ 200

[
  {}
]

Ответ 422

{
  "detail": [
    null
  ]
}

Estimate and reserve export quote

Returns quote_id for export creation. Quote expires in 15 minutes.

Тело запроса (обязательно)

{
  "brand": "",
  "model": "",
  "variant": "",
  "model_group": "",
  "year_from": 0,
  "year_to": 0,
  "price_min": 0,
  "price_min_rub": 0,
  "price_max": 0,
  "price_max_rub": 0,
  "price_total_min_rub": 0,
  "price_total_max_rub": 0,
  "mileage_max": 0,
  "engine_cc_min": 0,
  "engine_cc_max": 0,
  "city": "",
  "country": "",
  "fuel_type": "",
  "transmission": "",
  "fields": "",
  "since": "",
  "include_new": false,
  "include_removed": false,
  "demo": false,
  "id": "",
  "attributes": "",
  "vin": "",
  "sort": "",
  "cursor": "",
  "page": 1,
  "limit": 20,
  "max_records": 0,
  "max_cost": 0,
  "market": "",
  "export_format": "csv",
  "archive_format": "zip",
  "delimiter": "auto",
  "header_lang": "ru",
  "chunk_size": 100000
}

Пример запроса

curl -X POST "https://union.api-centr.ru/api/v2/cars/export/count" \
  -H "Authorization: Bearer $UNION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand":"","model":"","variant":"","model_group":"","year_from":0,"year_to":0,"price_min":0,"price_min_rub":0,"price_max":0,"price_max_rub":0,"price_total_min_rub":0,"price_total_max_rub":0,"mileage_max":0,"engine_cc_min":0,"engine_cc_max":0,"city":"","country":"","fuel_type":"","transmission":"","fields":"","since":"","include_new":false,"include_removed":false,"demo":false,"id":"","attributes":"","vin":"","sort":"","cursor":"","page":1,"limit":20,"max_records":0,"max_cost":0,"market":"","export_format":"csv","archive_format":"zip","delimiter":"auto","header_lang":"ru","chunk_size":100000}'

Ответ 200

{
  "quote_id": "",
  "total": 0,
  "cost": 0,
  "per_unit": 0,
  "balance": 0,
  "balance_after": 0,
  "tariff": "",
  "chunks": 0,
  "chunk_size": 0,
  "can_export": false,
  "expires_at": "",
  "total_is_capped": false,
  "record_limit": 0,
  "include_removed_allowed": false
}

Ответ 422

{
  "detail": [
    null
  ]
}

Create export task

Creates export using quote_id from /cars/export/count. Параметры экспорта берутся из квоты, передавать их повторно не нужно.

Тело запроса (обязательно)

{
  "quote_id": ""
}

Пример запроса

curl -X POST "https://union.api-centr.ru/api/v2/cars/export" \
  -H "Authorization: Bearer $UNION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":""}'

Ответ 422

{
  "detail": [
    null
  ]
}

Export task status

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/export/{task_id}/status" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Download export result

If multi-part export, specify ?page=N.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/export/{task_id}/download?page=1" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 422

{
  "detail": [
    null
  ]
}

Cross-market search

Ищет автомобили одновременно на нескольких рынках. С каждого рынка возвращается до `limit` записей. Цена конвертируется в рубли (price_rub). Результаты объединяются, сортируются и возвращается одна страница. Недоступные рынки пропускаются. Если все запрошенные рынки пилотные (одна БД union_cars), сортировка и страница идут по всему корпусу, а `meta.total` точный (`meta.total_is_exact = true`). Пагинация. Два способа, взаимоисключающие: - `page` + `limit` — классическая страница по OFFSET (на глубине дороже); - `cursor` — keyset-пагинация: возьмите `meta.next_cursor` прошлого ответа и передайте его в `cursor` следующего запроса. Курсор привязан к набору фильтров, сортировке и рынкам: измените что-нибудь — получите 400 `cursor_query_mismatch` и начните заново с первой страницы. Инвариант: `meta.has_more = false` ⇔ `meta.next_cursor = null`. Передавать `cursor` вместе с `page` нельзя (400 `cursor_page_conflict`). Ключи `next_cursor` / `has_more` / `markets_total_listings` присутствуют в режиме всех-пилотных рынков. `meta.markets_total_listings` — это объём рынка: **все активные объявления рынка без учёта фильтров** запроса (удобно для «ещё столько-то на рынке»), а не число строк, попавших под фильтр (оно в `meta.total`). Квота на рынок: `diversify=true` ограничивает страницу `limit` записями **с каждого** рынка (мелкие рынки не тонут под крупными). Страница отсчитывается по рангу внутри рынка: `page=2, limit=5` — записи 6..10 каждого рынка. `meta.total` при этом остаётся полным итогом под фильтр (не урезается). `diversify` несовместим с `cursor` (400 `diversify_cursor_conflict`) и доступен только когда все рынки пилотные (иначе 400 `diversify_not_supported`). Биллинг: плата — за запись, `стоимость = число_записей × per_unit` (₽/запись тарифа). Списываются только записи рынков, **не покрытых безлимитом** («плата — за рынки, которые безлимит не покрывает»); если безлимит покрывает все запрошенные рынки, списания нет. Резерв берётся по верхней границе страницы, подтверждение — по факту отданных записей. Поля ответа: id, make, model, model_group, variant, price, price_rub, mileage, firstreg, year, fuel_type, displacement_cc, power_kw, power_hp, transmission, drive_train, color, body_type, seats, cover_image, images, vin, country, city, url, first_seen_at, last_seen_at, market, currency.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/cars/search/all?markets=&sort=price_asc&limit=20&page=1&diversify=False" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 422

{
  "detail": [
    null
  ]
}

Central Bank of Russia exchange rates

Current Central Bank of Russia exchange rates (RUB base). Cached for 6 hours.

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/currency/rates" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{}

Demo: search cars (public)

Public endpoint for the demo site. No JWT required. Only listings with demo_flag=TRUE. Max 15 oldest (by year + add date). Filters: market, brand, model, year_from/year_to, price_min/price_max, fuel_type, transmission, country, city.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/demo/cars?market=<market>"

Ответ 200

{}

Ответ 422

{
  "detail": [
    null
  ]
}

Выдача архива по коду Digiseller

Проверить код у Digiseller, отдать архив и отметить выдачу. Покупателя сюда приводит Digiseller после оплаты: он добавляет к адресу страницы (verify_url товара) параметры uniquecode и pay_uid. Порядок важен: проверка переводит код в состояние «проверен», затем отметка о выдаче разблокирует деньги продавцу, и только после этого отдаём файл.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/digiseller/{slug}"

Ответ 422

{
  "detail": [
    null
  ]
}

List available tariffs

Доступен без API-ключа. С ключом дополнительно помечает текущий тариф (`is_current`) и запланированный даунгрейд (`scheduled`).

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/billing/tariffs" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

[
  {
    "name": "",
    "label": "",
    "monthly_price": 0,
    "per_unit": 0,
    "period_days": 30,
    "is_current": false,
    "scheduled": false
  }
]

List market unlimited plans

Безлимиты на рынки: цена и срок. Доступен без API-ключа; с ключом дополнительно помечает уже активные (`is_active`, `expires_at`).

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/billing/unlimited" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{
  "unlimited": [
    null
  ]
}

Current balance and tariff info

Return current balance and active tariff.

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/billing/balance" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{
  "balance": 0,
  "tariff": "",
  "per_unit": 0.05,
  "is_active": true,
  "expires_at": "",
  "auto_renew": true,
  "scheduled_tariff": "",
  "unlimited_markets": [
    null
  ]
}

Купить безлимит на рынок на 30 дней

Buy (or extend) unlimited access to a market. Price is deducted from balance. Списание баланса, активация подписки и запись транзакции выполняются атомарно в одной транзакции (service.purchase_unlimited).

Тело запроса (обязательно)

{
  "market": ""
}

Пример запроса

curl -X POST "https://union.api-centr.ru/api/v2/billing/unlimited/buy" \
  -H "Authorization: Bearer $UNION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"market":""}'

Ответ 200

{
  "market": "",
  "expires_at": "",
  "cost": 0,
  "period_days": 30,
  "balance_before": 0,
  "balance_after": 0,
  "message": ""
}

Ответ 422

{
  "detail": [
    null
  ]
}

Select a tariff

Upgrade (на более дорогой) — сразу, списывается месячная плата. Downgrade (на более дешёвый) — в конце текущего периода. Даунгрейд до base — отключение платного тарифа по окончании. auto_renew=false — после окончания периода переход на base.

Тело запроса (обязательно)

{
  "tariff": "",
  "auto_renew": true
}

Пример запроса

curl -X POST "https://union.api-centr.ru/api/v2/billing/tariff/select" \
  -H "Authorization: Bearer $UNION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tariff":"","auto_renew":true}'

Ответ 200

{
  "tariff": "",
  "per_unit": 0,
  "message": "",
  "immediate": true,
  "balance_before": 0,
  "balance_after": 0
}

Ответ 422

{
  "detail": [
    null
  ]
}

Transaction history

Return paginated transaction history for current user.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/billing/transactions?page=1&limit=20" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{
  "items": [
    null
  ],
  "total": 0,
  "page": 0,
  "limit": 0
}

Ответ 422

{
  "detail": [
    null
  ]
}

Spending summary

Total spent all time, today, this month. Shows balance and tariff.

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/billing/spending" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 200

{
  "total_spent": 0,
  "tariff_spent": 0,
  "search_spent": 0,
  "spent_today": 0,
  "spent_this_month": 0,
  "requests_today": 0,
  "balance": 0,
  "tariff": "",
  "per_unit": 0.05
}

Export spending report as CSV

Download spending report. detail=summary — по дням, detail=full — каждая транзакция.

Параметры

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/billing/spending/export?date_from=<date_from>&date_to=<date_to>&detail=summary" \
  -H "Authorization: Bearer $UNION_API_KEY"

Ответ 422

{
  "detail": [
    null
  ]
}

List available markets

Returns the list of supported sources for the market parameter.

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/markets"

Ответ 200

{}

Support Contact

Контакт техподдержки — из ссылки клиент рисует кнопку. Путь под /api/v2: nginx пускает наружу только перечисленные location'ы (/api/, /auth/, /docs, /register-link, /guide, /health), поэтому голый /support снаружи недостижим — уходит на сайт-каталог и даёт 404.

Пример запроса

curl -X GET "https://union.api-centr.ru/api/v2/support"