Интеграция цен в Parts-Catalogs

1. Введение
2. Общий процесс получения и отображения цен
3. Требования к серверу
4. Обработка ошибок и ответы сервера
5. Локализация и формат цен
6. Требования к производительности
7. Шаги по интеграции
8. Конфигурация приложения
9. Примеры ответов и отображения

Введение

Данное руководство предназначено для разработчиков и интеграторов, желающих интегрировать актуальные цены на автозапчасти в приложении Parts-Catalogs. Здесь вы найдёте информацию о требованиях к вашему серверу, формате ответа и примеры интеграции. Реализовав описанный функционал, вы сможете отображать цены на автозапчасти непосредственно на странице выбора деталей.

Основная идея интеграции заключается в том, что приложение Parts-Catalogs будет выполнять фоновый запрос к вашему серверу, передавая параметры детали (например, артикул и бренд), а затем использовать полученный JSON-ответ для отображения актуальных цен на экране.

Общий процесс получения и отображения цен

1. Пользователь в приложении Parts-Catalogs переходит к выбору деталей.
2. Приложение отправляет запрос к вашему серверу по указанному URL, передавая параметры code и brand.
3. Ваш сервер возвращает JSON-ответ с ценовыми предложениями.
4. Приложение отображает полученные цены на экране.

При отсутствии цен приложение отображает ссылку на проценку с надписью "Расширенный поиск".

Требования к серверу

Сервер должен:

• Обрабатывать запросы по протоколу HTTP или HTTPS.
• Принимать параметры code и brand (обязательные), а также опционально name.
• Возвращать данные в формате JSON.

Ответ сервера — это массив объектов, каждый из которых описывает одну ценовую позицию. В минимальном варианте объект должен содержать:

• title — название детали (строка)
• code — артикул детали (строка)
• brand — бренд детали (строка)
• price — цена детали (строка с указанием валюты)

Ниже приведён пример типичного ответа сервера:

[
  {
    "title": "Фильтр воздушный",
    "code": "8W0133843A",
    "brand": "Audi",
    "price": "1930 ₽"
  }
]

Обработка ошибок и ответы сервера

Рекомендуется поддержать следующие сценарии:

• Отсутствие результата: Если по переданным параметрам code и brand нет предложений, сервер может вернуть пустой массив [] или специальный объект с полем message.
• Ошибки в запросе: При неправильных параметрах запроса или внутренних ошибках возвращайте понятный ответ, например:

  {
     "error": "Invalid parameters",
     "message": "Parameter 'code' is missing"
  }
  

При этом следует использовать соответствующие HTTP-коды: 400 для некорректных запросов, 500 для внутренних ошибок.

Локализация и формат цен

Для удобства пользователей цены необходимо отображать в понятном и привычном формате.

• Валюта. Указывайте знак или код валюты рядом с числовым значением, например: "1930 ₽", "1930 RUB" или "1930 $".
• Разделители разрядов. Используйте пробелы или запятые для улучшения восприятия больших чисел: "1 930" или "1,930".
• Локализация. Если приложение будет использоваться в разных странах, убедитесь, что формат чисел и валюты легко адаптируется к региональным стандартам. Это позволит отображать цены корректно в зависимости от местоположения пользователя.

Требования к производительности

Сервер должен обеспечивать время ответа не более 300–500 мс, а при большом объёме обращений рекомендуется использовать кэширование для улучшения производительности и снижения нагрузки. Лимит на получение цен от сервера составляет 30 секунд. Если за это время ответ не получен, пользователь видит уведомление об ошибке.

Шаги по интеграции

1. Реализуйте на своем сервере эндпоинт (например /price) который принимает параметры code и brand и возвращает JSON.
2. Убедитесь, что ваш сервер корректно отвечает на тестовые запросы. Для проверки можно обратиться к вашему эндпоинту напрямую в браузере: https://yourdomain.com/price/

Конфигурация приложения

После реализации эндпоинта вы можете указать источник цен для вашего приложения. Для этого в инициализации приложения укажите параметр data-price-url и его значение с вашим адресом:

<div id="parts-catalog"
  data-key=""
  data-back-url="/search/?code={code}&brand={brand}"
  data-price-url="/price"
></div>

Пример сценария работы:

1. Пользователь выбирает нужную позицию детали в приложении Parts-Catalogs.
2. Приложение отправляет фоновый запрос к https://yourdomain.com/price/?code={article}&brand={brand}.
3. Возвращаются предложения с ценой.
4. Отображается таблица с ценами.
5. При нажатии на иконку корзины происходит переход по адресу https://yourdomain.com/search/?code={code}&brand={brand}, где подставляются реальные значения артикула и бренда.

Примеры ответов и отображения

Приеры ответов на запрос и как это будет выглядеть

1. Ответ одной искомой позицией

В данном примере сервер возвращает только одну искомую поизицию

Demo 1

2. Несколько ценовых предложений

В данном примере сервер возвращает несколько вариантов цен

Demo 2

3. Данные с аналогами

В данном примере сервер возвращает на искомую деталь разные варианты деталей включая аналоги а также примерные цены

Demo 3