# API — Руководство пользователя

## Схема работы

### Шаг 1 — Поиск автомобилей

```
POST /che168/search_car
```

Запрос: фильтры (бренд, цена, год, пробег, пагинация, сортировка).

Ответ: список автомобилей. Каждый объект содержит `infoid`, `specid` и основные поля.

```json
{
  "cars": [
    {
      "infoid": 58425637,
      "carname": "Audi A3 2022 A3l Limousine 35 Tfsi ...",
      "price_cny": 153800,
      "total_price_rub": 3854420,
      "specid": 62663,
      "mileage": 9,
      ...
    }
  ]
}
```

Поле `specid` — идентификатор спецификации/комплектации. Через него запрашиваются технические характеристики.

**Требуемый тариф:** `search`

---

### Шаг 2 — Детальная информация (до 100 за запрос)

```
POST /che168/batch_car_info
```

```json
{
  "infoids": [58425637, 58516696],
  "include_spec_params": false
}
```

Ответ: для каждого `infoid` — 5 категорий данных с переводом на английский:

| Категория | Содержание |
|-----------|-----------|
| `vehicle_info` | Название, бренд, модель, пробег, цвет, город, год |
| `technical_specs` | Двигатель, КПП, топливо, привод, мощность |
| `seller_info` | ID дилера, ID продавца |
| `history_condition` | Количество перепродаж, анализ remark на маркеры |
| `media_support` | Фотографии (основная + список) |

Дополнительно в каждый ответ автоматически включается `pricing_finance` — расчёт
таможенных платежей и итоговой цены (доступен на всех тарифах, без подключения опций).

**Требуемый тариф:** `car_info`

---

### Шаг 2b — Детальная информация + технические характеристики

```
POST /che168/batch_car_info
```

```json
{
  "infoids": [58425637, 58516696],
  "include_spec_params": true
}
```

Добавляет к ответу поле `spec_params` — технические характеристики по `specid` автомобиля (автоматически извлекается из данных). Набор секций зависит от наличия данных в БД (см. раздел **Типы specid**).

**Требуемый тариф:** `car_info` + `car_param`

---

### Шаг 3 — Получение specid для старых выгрузок

```
POST /che168/get_specid
```

Если у вас есть CSV-выгрузка, сделанная **до 21.05.2026** — в ней нет колонки `specid`. Этот эндпоинт позволяет дозаполнить:

```json
{
  "infoids": [58425637, 58516696]
}
```

Ответ:
```json
{
  "58425637": 62663,
  "58516696": 32017,
  "99999999": null
}
```

**Требуемый тариф:** `search`

---

### Шаг 4 — Технические характеристики по отобранным specid

```
POST /che168/get_spec_params
```

Если вы уже получили `batch_car_info` без `include_spec_params` и хотите дозапросить тех. характеристики для части автомобилей:

```json
{
  "specids": [62663, 32017]
}
```

**Требуемый тариф:** `car_param`

---

## Типы specid

### Новые specid (94% записей, ~29500 шт.)

Содержат полный набор секций — от 23 до 33, в зависимости от комплектации автомобиля. Каждая секция содержит массив `data` с полями `name` и `content` (переведены на английский).

#### Полный список секций

| № | Секция | Что содержит |
|---|--------|-------------|
| 1 | Basic parameters | Модель, производитель, уровень, мощность, крутящий момент, масса |
| 2 | engine | Объём, мощность, топливо, охлаждение, экология |
| 3 | gearbox | Тип КПП, число передач |
| 4 | chassis steering | Привод, тип руля, подвеска спереди/сзади |
| 5 | wheel brake | Тип тормозов, размер дисков, ABS |
| 6 | Body | Длина/ширина/высота, колёсная база, кол-во дверей/мест |
| 7 | active/passive safety equipment | Подушки безопасности, ремни, ISOFIX |
| 8 | passive safety | Пассивная безопасность |
| 9 | active safety | ABS, EBD, ESP, контроль тяги |
| 10 | Driving control | Круиз-контроль, парктроники, камеры |
| 11 | driving hardware | Радар, лидар, камеры |
| 12 | driving function | Автопилот, адаптивный круиз |
| 13 | 4WD/off-road | Тип полного привода, блокировки |
| 14 | Appearance/anti-theft | Колёса, люк, рейлинги, сигнализация |
| 15 | External/anti-theft configuration | Замки, иммобилайзер |
| 16 | exterior lights | Фары (тип, адаптив, омыватель), ДХО |
| 17 | lighting configuration | Дополнительное освещение |
| 18 | skylight/glass | Люк, стёкла, тонировка, зеркала |
| 19 | Glass/rearview mirror | Зеркала с электроприводом, обогрев |
| 20 | exterior rearview mirror | Обогрев, складывание, память |
| 21 | screen/system | Размер экрана, навигация, CarPlay |
| 22 | Intelligent configuration | Голосовое управление, OTA, Wi-Fi |
| 23 | Smart hardware | Чип, AI-процессор |
| 24 | Steering wheel/interior rearview mirror | Кожа, подогрев, регулировки, память |
| 25 | Interior configuration | Кожа, дерево, карбон в салоне |
| 26 | Charging in car | USB, розетки, беспроводная зарядка |
| 27 | Seat configuration | Материал, электрорегулировки, вентиляция |
| 28 | Audio/interior lighting | Колонки, сабвуфер, ambient light |
| 29 | Multimedia configuration | AUX, USB, Bluetooth, радио |
| 30 | Air conditioner/refrigerator | Климат-контроль, зоны, фильтр |
| 31 | License plate information | Дата регистрации, страховка |
| 32 | electric motor | Мощность, тип, батарея (только EV) |
| 33 | Auxiliary/control configuration | Парктроники, камера 360 |

> Не все секции заполнены у каждой машины. Среднее количество — 23-24 секции на автомобиль. Чем богаче комплектация, тем больше секций.

---

### Старые specid (6% записей, ~1800 шт.)

Содержат базовый набор из 7 секций с основными данными об автомобиле. Формат данных — тот же (структура `sections` с `title` и `data`), но количество полей ограничено.

| № | Секция | Поля |
|---|--------|------|
| 1 | Basic parameters | carname, levelname, engine, gearbox, displacement, drivingmode, fuelname, colorname, mileage, price |
| 2 | engine | engine, displacement, fuelname, environmental, fuel_consumption |
| 3 | gearbox | gearbox, driving_wheels |
| 4 | chassis steering | drivingmode |
| 5 | Body | colorname, levelname |
| 6 | License plate information | firstregdate, firstregyear, examine, insurance |
| 7 | electric motor | batterytype, batterypower, ev100power, evwarranty (только EV) |

> Старые specid не могут быть дополнены до полного набора — исходные данные (che168.com) не содержат детальной спецификации для этих автомобилей.

---

## Как отличить новый specid от старого

Через `get_spec_params` — по количеству секций:

- **23-33 секции** — новый specid, полные данные
- **7 секций** — старый specid, базовые данные
- **`null`** — данные отсутствуют

Либо через `search_car` — если specid найден, количество секций можно проверить через `get_spec_params`.

---

## Сводная таблица эндпоинтов

| Шаг | Эндпоинт | Что на выходе | Тариф |
|-----|----------|--------------|-------|
| 1 | `search_car` | Список авто + `specid` | `search` |
| 2 | `batch_car_info` | 5 категорий детально (перевод) + `pricing_finance` | `car_info` |
| 2b | `batch_car_info` (+флаг) | 5 категорий + тех. характеристики + `pricing_finance` | `car_info` + `car_param` |
| 3 | `get_specid` | infoid → specid | `search` |
| 4 | `get_spec_params` | specid → тех. характеристики | `car_param` |

---

## Описание тарифов

### Dev (0 ₽)

**Ознакомительный.** Поиск с фильтрами, расчёт таможенных платежей, но только каждый 50-й автомобиль в выдаче. Подходит для интеграции, тестирования, оценки формата данных. Для реального использования не предназначен.

### Базовый (3 000 ₽/мес)

**Витрина.** Поиск по всем автомобилям без семплирования + расчёт таможенных платежей. Базовая информация из поиска: марка, модель, год, пробег, цена, комплектация. Хватает для сбора статистики и поверхностного анализа рынка, но без погружения в детали.

### Базовый + Расширенная информация (5 000 ₽/мес)

**Детальная карточка.** Добавляет 5 категорий данных по каждому автомобилю: характеристики двигателя и КПП, историю и состояние, фотографии. Позволяет оценить автомобиль без перехода на che168.

### Базовый + Расширенная информация + Технические характеристики (7 000 ₽/мес)

**Полный справочник.** Добавляет 23–33 секции технических параметров с переводом на английский: от подушек безопасности и мультимедиа до электродвигателя и систем помощи водителю. Весь набор данных, который существует по автомобилю на китайском рынке.

---

## Формат авторизации

Все запросы требуют заголовок:

```
Authorization: Bearer <token>
```

Пример:
```
Authorization: Bearer che168-uwSaKqi7M9BHqwlmV
```

Получение токена: [https://t.me/api_centr_regbot](https://t.me/api_centr_regbot)