Каталог

Запрос по VIN

Определяет автомобиль по VIN и возвращает точку входа в каталог запчастей.
GET
http://192.168.70.253:3102/api/vin
АвторизацияBearer-токен в заголовке Authorization
Язык ответаЗаголовок Accept-Language, по умолчанию ru
Формат ответаJSON: { success, result }, полезная нагрузка в поле result
Следующий шагУказатель vehicle.qMainGroup передаётся в /api/q

Описание

Метод принимает VIN и ищет автомобиль по доступным каталогам. Дальнейшая работа с каталогом идёт через непрозрачные указатели: из ответа берётся vehicle.qMainGroup и передаётся в /api/q. Формировать такие указатели вручную нельзя — они возвращаются сервером.

Возможны три исхода: автомобиль определён (vehicle), подошло несколько (vehicles — покажите таблицу и повторите запрос с vehicle_id), VIN не распознан (valid_catalogs — предложите выбрать каталог вручную).

Заголовки запроса

Заголовок Тип Обязательный По умолчанию Описание
AuthorizationstringдаBearer <access_token>.
Accept-LanguagestringнетruЯзык названий узлов и деталей: ru, en, de, fr, es, it, pl, tr, ko, zh.

Параметры запроса

Передаются в строке запроса.

Параметр Тип Обязательный Описание
vinstringнетVIN автомобиля, 17 символов. Обязателен, если не передан vehicle_id.
vehicle_idstringнетИдентификатор автомобиля из таблицы vehicles. Используется, когда по VIN нашлось несколько машин.
catalogstringнетИдентификатор каталога. Ограничивает поиск одним каталогом; при поиске по vehicle_id обязателен.

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

curl 'http://192.168.70.253:3102/api/vin?vin=JTJBERBZ602000192' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept-Language: ru'

Ответ

Поле Тип Обязательный Описание
successbooleanдаПризнак успешного ответа.
resultResultдаПолезная нагрузка. Набор полей зависит от того, чем закончилось определение автомобиля.

Вложенные объекты

Заполняется один из трёх блоков: vehicle, vehicles или valid_catalogs.

Свойство Тип Обязательный Описание
vehicleVehicleнетАвтомобиль определён однозначно.
vehiclesTableнетПо VIN подошло несколько автомобилей — таблица для выбора. Строки содержат vehicle_id для повторного запроса.
valid_catalogsValidCatalog[]нетАвтомобиль не определён, но VIN относится к этим каталогам — выбор за пользователем.
catalogIdstringнетИдентификатор каталога, в котором найден автомобиль.
getCatalogDataCatalogData[]нетНастройки каталога. Если пришли здесь, отдельный запрос /api/catalog-data не нужен.
bread_crumbBreadCrumb[]нетХлебные крошки для навигации по каталогу.
flagTranslatebooleanнетНазвания в ответе переведены машинным переводом.
typestringнетРежим работы каталога, из которого получены данные, например offline.
resultCodenumberнетВнутренний код результата каталога. При успехе — 200.
vinstringнетVIN, по которому выполнен запрос. Возвращается на всех шагах работы с каталогом.
infoInfoнетСообщение для пользователя: подсказка или причина отказа.
200 OK
{
  "success": true,
  "result": {
    "bread_crumb": [],
    "type": "offline",
    "resultCode": 200,
    "vin": "JTJBERBZ602000192",
    "catalogId": "lexus",
    "vehicle": {
      "vin": "JTJBERBZ602000192",
      "brandId": "lexus",
      "brandName": "Lexus",
      "modelName": "LEXUS NX SERIES",
      "name": "Lexus, серия NX, 10.2014.",
      "nameFull": "LEXUS NX, выпущено в 10.2014.",
      "nameShort": "СЕРИЯ LEXUS NX",
      "qMainGroup": "702c9916-428a-433d-8eac-2245d9a48834",
      "attributesMain": [
        { "id": "vin", "label": "VIN-номер", "value": "JTJBERBZ602000192" },
        { "id": "model_code", "label": "Код модели", "value": "ZGZ15L-AWXLPW" }
      ]
    },
    "getCatalogData": [
      { "name": "models", "value": true }
    ]
  }
}

Ошибки

HTTP Код ошибки Когда возникает
401UnauthorizedТокен не передан или истёк. Обновите пару через /auth/refresh и повторите запрос.
200result.infoVIN не распознан или каталог недоступен. Ответ приходит с кодом 200, причина — в result.info, поля vehicle и vehicles при этом пустые.
Остальные коды в разработке
Здесь описано поведение, которое реализовано на клиенте: 401 и логический отказ в result.info. Полный список статусов будет добавлен позже.

Дополнительная информация

Ошибка приходит с кодом 200
Проверяйте не только HTTP-статус: причина отказа или подсказка лежит в result.info с типом error. Виджет показывает её пользователю модальным окном.
  • Выбор автомобиля из таблицы vehicles: повторите запрос с параметрами vehicle_id и catalog, VIN при этом не нужен.
  • Смена языка требует повторного запроса — названия приходят уже переведёнными под Accept-Language.
  • Если в ответе пришёл getCatalogData, отдельный запрос настроек каталога делать не нужно.