Каталог

Запрос к каталогу

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

Описание

Каталог обходится по указателям. Первый указатель приходит из /api/vin в поле vehicle.qMainGroup, дальше каждый ответ содержит указатели на следующий уровень: lists[].q, node.qGroup, part.q_partinfo и другие поля, начинающиеся с q.

Метод POST используется, когда в ответе пришли forms: значения полей отправляются на указатель формы тем же запросом, но с телом JSON.

Указатель — непрозрачная строка
Не разбирайте и не собирайте q вручную: его формат — внутреннее дело сервера и может измениться. Сохраняйте значение как есть и передавайте обратно.

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

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

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

Передаются в строке запроса и для GET, и для POST.

Параметр Тип Обязательный Описание
qstringдаУказатель на раздел каталога. Приходит в ответах сервера: vehicle.qMainGroup, lists[].q, node.qGroup, part.q_partinfo и другие поля с префиксом q.
catalogstringнетИдентификатор каталога из ответа /api/vin. Передавайте вместе с q, чтобы запрос выполнялся в нужном каталоге.

Тело запроса (POST)

Плоский объект: код поля формы — выбранное значение.

Параметр Тип Обязательный Описание
<код поля>string | number | booleanнетЗначение поля формы. Ключ — code или id поля из forms[].fields, значение — выбранный вариант. Состав полей задаёт сервер в предыдущем ответе.

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

Переход по указателю:

curl -G 'http://192.168.70.253:3102/api/q' \
  --data-urlencode 'q=<указатель из ответа>' \
  --data-urlencode 'catalog=lexus' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept-Language: ru'

Отправка формы:

curl -X POST 'http://192.168.70.253:3102/api/q?q=<указатель формы>&catalog=lexus' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: ru' \
  -d '{ "engine": "1UZ-FE", "transmission": "AT" }'

Ответ

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

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

Ответ — объединение вариантов: заполнены только поля, относящиеся к текущему разделу каталога.

Свойство Тип Обязательный Описание
lists_groupMainGroup[]нетГлавные группы узлов. Приходит в ответ на vehicle.qMainGroup.
listsListItem[]нетСписок узлов или подгрупп текущего уровня.
nodeNodeнетКарточка узла: схема, точки на схеме и детали.
servicePartsobject[]нетСервисные позиции, сгруппированные по разделам: { key, title, list[] } с таблицами внутри.
nodesBlockDataobjectнетБлок табличных данных вместо списка узлов: { tables }.
formsForm[]нетФормы фильтрации. Значения полей отправляются обратно методом POST.
tablesTable[]нетТабличные данные раздела.
partinfoPartInfoнетИнформация по детали. Может прийти объектом или массивом таблиц.
groupinfoPartInfoнетИнформация по группе деталей.
replacementPartInfoнетЗамены детали.
compatibilityPartInfoнетПрименимость детали.
listinfoPartInfoнетИнформация по строке списка.
imagesImage[]нетИзображения раздела.
htmlstringнетГотовый HTML-блок для показа в модальном окне.
modalobjectнетМодальное окно с данными: { title, tables, images }.
bread_crumbBreadCrumb[]нетХлебные крошки текущего уровня.
flagTranslatebooleanнетНазвания переведены машинным переводом.
typestringнетРежим работы каталога, из которого получены данные, например offline.
resultCodenumberнетВнутренний код результата каталога. При успехе — 200.
vinstringнетVIN автомобиля, в контексте которого выполняется обход каталога.
infoInfoнетСообщение для пользователя: подсказка или причина отказа.
200 OK
{
  "success": true,
  "result": {
    "bread_crumb": [
      { "q": "702c9916-428a-433d-8eac-2245d9a48834", "title": "JTJBERBZ602000192" }
    ],
    "type": "offline",
    "resultCode": 200,
    "vin": "JTJBERBZ602000192",
    "lists": [
      {
        "code": "2",
        "title": "ДВИГАТЕЛЬ",
        "q": "a4607a7d-5096-472b-a85c-2d6b71fcdc2a",
        "qImage": "d2386829-c388-4e4e-be8d-3f36826c418d"
      }
    ]
  }
}

Ошибки

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

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

  • Порядок обхода: qMainGrouplists_grouplists[].qnode с деталями.
  • Детали в node.parts связаны со схемой через hotspotId: подсветка области соответствует строке в списке.
  • Изображения отдаются указателями qImage, а не готовыми ссылками — файл забирается отдельным запросом по базовому адресу изображений.
  • При смене языка повторите последний запрос с новым Accept-Language: перевод выполняется на стороне сервера.