API

Пример тела Product API запроса

Описание

Если интернет-магазин не содержит групповых товаров, то на страницах карточек товара нужно вызывать запрос productAPI, и передавать в него всю информацию о товаре.

В случае, если интеграция требует поддержки групповых товаров, нужно вызывать запрос productsGroupAPI

Важно: Если веб-сайт/мобильное приложение содержит функционал окна быстрого просмотра товара, то запрос нужно отправлять также при открытии этого окна.

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

{
  "id": <product ID>,
  "name": "Example product name",
  "price": 777,
  "pictureUrl": "http://example.com/path/to/Photo.jpg",
  "url": "http://www.example.com/path/to/productPage",
  "isAvailable": true,
  "categoryPaths": ["Women/Clothes/Skirts","Women/New Arrivals"],
  "description": "Some text description",
  "vendor": "Brand name",
  "model": "Model name",
  "typePrefix": "Product type",
  "oldPrice": 999,
  "params": {
    "<custom parameter 1 name>":  "<custom parameter 1 value>",
    "<custom parameter 2 name>":  "<custom parameter 2 value>",
    "<custom parameter N name>":  "<custom parameter N value>"
  }
 }

{
  "groupId": <group ID>,
  "name": "<string>",
  "price": 777,
  "pictureUrl": "http://example.com/path/to/Photo.jpg",
  "url": "http://www.example.com/path/to/productPage",
  "isAvailable": true,			
  "categoryPaths": ["Example/Category/Path","Another/Category"],
  "description": "Some text description",
  "products": {
		"<product id>": {
      "isAvailable": <bool>,
      "name": "<string>",
      "color": "<string>",
      "size": "<string>",
      "url": "<string>",
      "pictureUrl": "<string>",
      "price": <decimal>,
      "oldPrice": <decimal>,
      "description": "<string>",
      "params": {
        "<custom parameter 1 name>": "<custom parameter 1 value>",
        "<custom parameter 2 name>": "<custom parameter 2 value>",
        "<custom parameter N name>": "<custom parameter N value>"
      }	
  	},
	  "<product id>": {
      "isAvailable": <bool>,
      "name": "<string>",
      "color": "<string>",
      "size": "<string>",
      "url": "<string>",
      "pictureUrl": "<string>",
      "price": <decimal>,
      "oldPrice": <decimal>,
      "description": "<string>",
      "params": {
        "<custom parameter 1 name>": "<custom parameter 1 value>",
        "<custom parameter 2 name>": "<custom parameter 2 value>",
        "<custom parameter N name>": "<custom parameter N value>"
      }	
    }
  },
  "vendor": "Brand name",
  "model": "Model name",
  "typePrefix": "Product type",
  "oldPrice": 999		
}

Обязательные параметры Product API без использования групповых товаров

ПараметрТипОписание
idintegerУникальный идентификатор продукта. Этот атрибут может содержать только числа. Максимальная длина идентификатора - 16 символов. Значение id не должно превышать 9 007 199 254 740 991.
namestringИмя продукта (не более 120 символов). В качестве названия продукта мы рекомендуем указать полное уникальное имя продукта.
pricenumberЦена за единицу товара, не должна быть равна нулю.
urlstringАбсолютная ссылка на страницу продукта. Максимальная длина URL-адреса - 512 символов.
pictureUrlstringАбсолютная ссылка на изображение предложения продукта. Изображения, расположенные на этих URL-адресах, должны быть jpeg, gif или png. Чтобы гарантировать правильную обработку изображений, рекомендуемый размер составляет 400x400 пикселей или менее 1 МБ. Максимальная длина URL-адреса - 512 символов.
isAvailableboolСтатус доступности продукта:
true - Предложение на складе. Магазин готов организовать доставку / покупку продукта.
false - Предложение продукта отсутствует и / или недоступно.
Обратите внимание, данный параметр чувствителен к регистру. true и True являются разными значениями. Правильно указывать значение параметра с маленькой буквы.
categoryPathsstringМассив, состоящий из путей до товарных категорий. В качестве разделителя между категориями используется косая черта (слэш).
Путь до категории должен точно отражать структуру меню сайта и вложенность категорий (должны использоваться только статичные названия категорий, лучше не использовать URL путей, фильтров из боковой панели или динамических хлебных крошек).
Нужно передавать пути только до самых низкоуровневых категорий: если товар находится в категориях "Женщинам/Одежда/Юбки" и "Женщинам/Одежда", необходимо передать только один путь - "Женщинам/Одежда/Юбки". Если товар находится в нескольких категориях, то нужно передать их через запятую, например ["Женщинам/Одежда/Юбки","Женщинам/Одежда/Велюр"]. Обязательно должен быть одинаковым для одного товара

Обязательные параметры Product API с использованием групповых товаров

ПараметрТипОписание
productsJSON objectДанный параметр должен содержать все товары группы, объявленные отдельными объектами.
Обязательным параметром для продукта является лишь isAvailable. По умолчанию остальные параметры, такие как имя/URL/изображение, будут подтягиваться из общего объявления параметров группы.
groupIdintegerИдентификатор группы товаров. Объединяет все предложения, которые являются вариациями одной модели. Должен иметь одинаковое значение. Значение должно быть целым числом. Если товар не является групповым предложением, то в параметр нужно передавать идентификатор товарного предложения.

Дополнительные параметры

ПараметрТипОписание
vendorstringПроизводитель или бренд. Используется для формирования рекомендаций по производителю (popular by vendor).
oldPricenumberCтарая цена для продукта, по желанию можно отобразить в рекомендациях, использовать для расчёта и отображения скидки.
paramsJSON objectЭтот параметр предназначен для определения характеристик продукта. Каждый параметр описывается с помощью отдельного элемента в объекте params.
Params может содержать 40 элементов, включенных в него.
Элемент определяется как "" : "" , где:

- имя параметра.
- значение параметра, может содержать объект.Значения, переданные в элементе params, можно использовать для дополнительной фильтрации товарной выдачи.
Дополнительные параметры участвуют в формировании рекомендаций и их можно выводить как дополнительную информацию в карточке товара.

Параметр для поддержки региональности

ПараметрТипОписание
stockIdstringРегион, склад или языковой идентификатор пользователя для обработки нескольких складов, которые могут иметь разные цены и доступность товаров в разных регионах, или стран (в случае различающихся языков, валют и т.д.). В каждом регионе / stockId должно быть как минимум в 5 раз больше уникальных посетителей в месяц, чем число товаров в регионе / stockId. Например, если в регионе 10000 товаров, то посещаемость в этом регионе должна быть как минимум 50000 уникальных пользователей в месяц.

Поддержка мультиязычности и мультивалютности

Если на сайте для пользователей доступен выбор из нескольких языков из валют, то с помощью дополнительных параметров можно реализовать поддержку такого же функционала в продуктах Retail Rocket.

{
  "id": <product ID>,
  "name": "Example product name",
  "price": 777,
  "pictureUrl": "http://example.com/path/to/Photo.jpg",
  "url": "http://www.example.com/path/to/productPage",
  "isAvailable": true,
  "categoryPaths": ["Women/Clothes/Skirts","Women/New Arrivals"],
  "description": "Some text description",
  "vendor": "Brand name",
  "model": "Model name",
  "typePrefix": "Product type",
  "oldPrice": 999,
  "params": {
     "<custom parameter 1 name>": "<custom parameter 1 value>",
     "<custom parameter 2 name>": "<custom parameter 2 value>",
     "<custom parameter N name>": "<custom parameter N value>",
     "languages": {
       "<language1>": {
         "description": "description in language1",
         "name": "name in language1",
         "url": "url to product in specific language",
         "<custom parameter 1 name in language1>": "<custom parameter 1 value>",
         "<custom parameter 2 name in language1>": "<custom parameter 2 value>",
         "<custom parameter N name in language1>": "<custom parameter N value>"
       },
       "<language2>": {
         "description": "description in language2",
         "name": "name in language2",
         "url": "url to product in specific language",
         "<custom parameter 1 name in language2>": "<custom parameter 1 value>",
         "<custom parameter 2 name in language2>": "<custom parameter 2 value>",
         "<custom parameter N name in language2>": "<custom parameter N value>"
       }
     },
     "currencies": {
       "EUR": <price in EUR>,
       "USD": <price in USD>
     }
   }
}