Корзина товаров и категории товаров

В SailPlay реализован механизм для работы с составом корзины. Работа с корзиной и категориями товаров может быть необходима в следующих случаях: 

  1. Когда необходимо реализовать логику для разных правил начисления бонусных баллов для разных товаров или разных категорий. 
  2. Для ведения аналитики и статистики, связанных с составомом корзины. 

Принцип работы

Каждому товару в системе SailPlay присваивается идентификатор этого товара в вашей системе (SKU). Аналогично, каждой категории в системе SailPlay присваивается некоторый идентификатор в вашей системе. 

Для каждого товара, категории можно указать: 

  1. Наименование
  2. Идентификатор
  3. Коэффициент конвертации рублей в баллы за покупку этого товара / покупку товара из данной категории
  4. Изображение

Соответственно, при передаче информации о покупке, необходимо дополнительно передавать состав корзины (см. здесь). 

При разборе состава корзины, применяются следующие правила:

  1. Если товара с данным SKU или группы с данным ID нет в базе данных SailPlay - они создаются автоматически (без названия и отсальных аттрибутов). 

  2. Если для данного товара нет специального коэффициента конвертации, проверяется есть ли коэффициент конвертации для данной категории, если и его нет - используется стандартный.

  3. Если в массиве передан один и тот же товар несколько раз - их суммы предварительно складываются.

 

Методы

  • /api/v2/basket/categories/add/ - добавление категории
  • /api/v2/basket/categories/edit/ - редактирование информации о категории
  • /api/v2/basket/categories/list/ - список категорий

  • /api/v2/basket/attributes/add/ - создание справочника (атрибута)
  • /api/v2/basket/attributes/edit/ - редактирование справочника
  • /api/v2/basket/attributes/list/ - список справочников

  • /api/v2/basket/attributes/values/add - добавление значения справочника (атрибута)
  • /api/v2/basket/attributes/values/edit - редактирование значения справочника
  • /api/v2/basket/attributes/values/list - список значений справочника
  • /api/v2/basket/attributes/values/delete - удаление значения справочника 

  • /api/v2/basket/products/add/ - добавление информации о товаре
  • /api/v2/basket/products/edit/ - редактирование информации о товаре
  • /api/v2/basket/products/list/ - список всех товаров

  • /api/v2/basket/products/attributes/add/ - присвоение товару атрибута и значения
  • /api/v2/basket/products/attributes/edit/ - изменение значея атрибута
  • /api/v2/basket/products/attributes/delete/ - удаление атрибута товара

 

/api/v2/basket/categories/add/ - добавление категории

Данный метод служит для добавления категорий товаров. Стоит помнить, что если категория была создана ранее непосредственно  при передаче очередной покупки (см. здесь), то при добавлении категории с данным SKU через данный метод, новая запись в базе данных создана не будет, будут только обновлены соответвующие параметры (наименование, картинка и т.д.).

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  ID данной категории в вашей системе
нет parent_sku  Родительская категория (sku). Если не указан - проставляется корневая категория
нет name  Наименование данной категории
нет pic  Изображение для данной категории
нет points_rate  Коэффициент конвертации рублей в баллы. При отсутствии данного параметра, используется значение, указанное в настройках. Формат points_rate=0.45


Ответ сервера

Название параметра Описание параметра
status  Статус операции
sku  Идентификатор категории
create_date  Дата создания категории
parent_sku  Родительская категория
points_rate  Коэффициент бонусных баллов созданной категории
pic  URL изображения категории

 

Пример ответа сервера:

{
status: 'ok',
sku: 'sku_1',
name: 'category name',
parent_sku: 'sku_2'
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.004',
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg'
}

 

Коды ошибок

Код Описание
-7000  Название категории или sku уже используется другой категорией

/api/v2/basket/categories/edit/ - редактирование информации о категории

Данный метод предназначен для редактирования информации о категории. Стоит отметить, что если в запросе не были переданы некоторые поля, то соответвующие аттрибуты не будут изменены для данной категории.
Чтобы удалить значение параметра, нужно передать пустую строку.   

Метод

POST /api/v2/basket/categories/edit/

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  ID данной категории в вашей системе
нет parent_sku  Родительская категория (sku)
нет name  Наименование данной категории
нет pic  Изображение для данной категории
нет points_rate  Коэффициент конвертации рублей в баллы. При отсутствии данного параметра, используется значение, указанное в настройках. Формат points_rate=0.45

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

https://sailplay.ru/api/v2/basket/categories/edit/?token=*&store_department_id=*&sku=ТЕСТ-140&parent_sku=test&name=тестовый&points_rate=0.01

Ответ сервера

Название параметра Описание параметра
status  Статус операции
sku  Идентификатор категории
create_date  Дата создания категории
points_rate  Коэффициент бонусных баллов созданной категории
pic  URL изображения категории

 

Пример ответа сервера:

{
status: 'ok',
sku: 'sku_1',
name: 'category name',
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.004',
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg'
}

 

Коды ошибок

Код Описание
-7001  Название категории уже используется другой категорией
-7002  Категория по переданному sku не существует

 

/api/v2/basket/categories/list/ - список категорий

Данный метод предназначен для получения списка категорий товаров, которые были добавлены через соответвующие методы (см. здесь и здесь).

Метод

GET /api/v2/basket/categories/list/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
нет sku  Если указан, отображается информация только по категории с данным sku. Является взаимоисключающим параметром с parent_sku
нет parent_sku  Ограаничивает список получаемых категорий указанной и дочерними по отношении к указанной. Если не указан, отображаются все категории

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
categories  Массив объектов со следующими аттрибутами:
sku  SKU (ID) категории в вашей системе.
parent_sku  Родительская категория (sku)
name  Наименование категории
points_rate  Коэффициент конвертации категории
create_date  Дата создания

 

Пример ответа сервера: 

{
status: 'ok',
categories: [
{
sku: 'c_1',
parent_sku: 'sku_3'
name: 'electronics',
points_rate: '0.1000',
pic: '//d39c94cu632zjz.cloudfront.net/static/e.jpg'
},
{
sku: 'c_2',
parent_sku: 'sku_4'
name: 'food',
points_rate: '0.2500',
pic: '//d39c94cu632zjz.cloudfront.net/static/food.jpg'
},
....
]
}

 

/api/v2/basket/attributes/add/ - создание справочника (атрибута)

Этот метод необходим для создания какого-либо атрибута для товара и услуги. Товары с установленным атрибутом могут формировать определнный справочник и служить для группировки товаров в системе SailPlay.
Следует отметить, что атрибут может иметь различные типы: такие как bool (булево), date (дата), float и текст.

Метод

POST /api/v2/basket/attributes/add/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного атрибута в вашей системе
да data_type  Тип данных, хранящийся в атрибуте. Имеет значения bool, date, float и text
нет name  Название. Если не указан - сохраняется пустое значение
нет pic  Файл изображения товара. (не ссылка) 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
sku  Идентификатор товара
parent_sku  SKU (ID) родительского справочника
name  Название справочника 
data_type  Тип данных
values  Массив доступных значений

 

Пример ответа сервера: 

{
status: 'ok',
sku: 'attribute_1',
parent_sku: 'attribute_2'
name: 'attribute name',
data_type: 'bool'
values: [sku: 'product_01', ‘value’: 'true'})]
}

/api/v2/basket/attributes/edit/ - редактирование справочника

Этот метод необходим для изменения какого-либо созданного ранее справочника (атрибута). 
Все параметры кроме sku не обязательны. Изменяются только те, которые указаны в запросе.
Чтобы удалить значение параметра, нужно передать пустую строку.

Следует отметить, что атрибут 'data_type' не может быть изменен.

Метод

POST /api/v2/basket/attributes/edit/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного атрибута в вашей системе
нет name  Название. Если не указан - сохраняется пустое значение
нет parent_sku  SKU (ID) родительского справочника. если не указан - сохраняется пустое значение

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
sku  Идентификатор атрибута
parent_sku  SKU (ID) родительского справочника
name  Название справочника 
data_type  Тип данных

 

Пример ответа сервера: 

{
status: 'ok',
sku: 'attribute_1',
parent_sku: 'attribute_4'
name: 'attribute name2',
data_type: 'bool'
values: [sku: 'product_01', ‘value’: 'true'})]
}

 

/api/v2/basket/attributes/list/ - список справочников

Данный метод предназначен для получения списка справочников (атрибутов), которые были добавлены через соответвующие методы, а так же массив значений sku, для которых присвоен тот или иной атрибут и его значение.

Метод

POST /api/v2/basket/attributes/list/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
нет sku  Если указан, отображается информация только по одному справочнику. Является взаимоисключающим параметром с parent_sku
нет parent_sku  Ограничивает список получаемых справочников указанным и дочерними по отношении к указанному. если не указан, отображаются все справочники 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
attributes  Массив объектов с описанием справочников и массивом их значений:
sku  Идентификатор атрибута
parent_sku  SKU (ID) родительского справочника
name  Название справочника 
values  Массив доступных значений (массив объектов вида {‘sku’: <sku>, ‘value’: <value>})

 

Пример ответа сервера: 

{
status: 'ok',
"attributes": [
{
sku: 'attribute_1',
parent_sku: 'attribute_4'
name: 'attribute name1',
values: [sku: 'product_01', ‘value’: 'true'}
{
sku: 'attribute_2',
parent_sku: 'attribute_4'
name: 'attribute name2',
values: [sku: 'product_02', ‘value’: 'null'}
]
}

За один запрос метод возвращает по 100 товаров на странице.

Если передан sku, будет отображена информация только по одному справочнику. Если будет передан parent_sku будет ограничен список получаемых справочников указанным и дочерними по отношении к указанному parent_sku

/api/v2/basket/attributes/values/add/ - добавление значения справочника (атрибута)

Данный метод предназначен для добавления значений различным, ранее созданным, справочникам (атрибутам). Для каждого атрибута могут быть добавлены какие-либо значения с их наименованием. Количество значений для атрибута не ограничено

Метод

POST /api/v2/basket/attributes/values/add/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного атрибута в вашей системе
нет value_sku  Наименование значения
нет value  Значение атрибута, в соответствии с data_type атрибута

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
values  Массив значений для указанного справочника (атрибута) с наименованиями

 

Пример ответа сервера: 

{
status: 'ok',
values: [sku: 'is_jnvls', ‘value’: 'true'})]

}

В случае, если sku уже имеет соответствующий атрибут будет возвращена ошибка:

{"status": "error", "message": "Value with such sku already exists for this attribute"}

/api/v2/basket/attributes/values/edit/ - редактирование значения справочника

Этот метод необходим для изменения какого-либо созданного ранее значения справочника (атрибута). 
Все параметры кроме sku не обязательны. Изменяются только те, которые указаны в запросе.
Чтобы удалить значение параметра, нужно передать пустую строку.

Следует отметить, что атрибут 'data_type' не может быть изменен.

Метод

POST /api/v2/basket/attributes/values/edit/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного атрибута в вашей системе
да value_sku  Наименование значения. Не может быть изменено
да value  Значение атрибута, в соответствии с data_type атрибута. Может быть изменено

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции

 

Пример ответа сервера: 

{
status: 'ok'
}

 

/api/v2/basket/attributes/values/list/ - список значений справочников

Этот метод позволяет получить массив допустимых значений с их наименованиями для какого-либо из атрибутов.

 

Метод

POST /api/v2/basket/attributes/values/list/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного атрибута в вашей системе

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
values  Массив допустимых значений для указанного справочника (атрибута)

 

Пример ответа сервера: 

{ status: 'ok',
"values": [
{
sku: 'product_1'
value: state_1}
{
sku: 'product_2'
value: state_2}
]
}

 

/api/v2/basket/attributes/values/delete/ - удаление значения справочника 

Этот метод позволяет удалить какое либо значения из определенного справочника (атрибута).

 

Метод

POST /api/v2/basket/attributes/values/delete/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного атрибута в вашей системе
да value_sku  Наименование значения к удалению

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции

 

Пример ответа сервера: 

{
status: 'ok'
}

 

/api/v2/basket/products/add/ - добавить информацию о товаре

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

Метод

POST /api/v2/basket/products/add/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного товара в вашей системе
нет name  Наименование данного товара
нет price  Цена товара
нет category_sku  SKU (ID) категории
нет points_rate  Коэффициент конвертации рублей в баллы для данного товара.
нет points_rate  Коэффициент конвертации рублей в баллы для данного товара.

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
sku  Идентификатор товара
create_date  Дата создания товара
points_rate  Коэффициент бонусных баллов созданного товара
price  Цена товара
pic  URL изображения товара
category_sku  sku категории
attributes  Атрибуты номенклатуры

 

Пример ответа сервера: 

{
status: 'ok',
sku: 'product_sku_1',
name: 'product name',
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.05',
price: '100.0000'
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg',
category_sku: 'category sku'
attributes: []
}

 

Коды ошибок

Код Описание
-7002  Категории по переданному sku не существует
-7003  Товар по переданному sku или name уже существует

 

/api/v2/basket/products/edit/ - редактировать информацию о товаре

Данный метод предназначен для редактирования информации о товаре. 
Все параметры кроме sku не обязательны. Изменяются только те, которые указаны.
Чтобы удалить значение параметра, нужно передать пустую строку.

Метод

POST /api/v2/basket/products/edit/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU (ID) данного товара в вашей системе
нет name  Наименование данного товара
нет price  Цена товара
нет category_sku  SKU (ID) категории
нет points_rate  Коэффициент конвертации рублей в баллы для данного товара.

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
sku  Идентификатор товара
create_date  Дата создания товара
points_rate  Коэффициент бонусных баллов созданного товара
price  Цена товара
pic  URL изображения товара
category_sku  sku категории
attributes  Атрибуты номенклатуры

 

Пример ответа сервера: 

{
status: 'ok',
sku: 'product_sku_1',
name: 'product name',
create_date: '2014-03-05T16:30:30.513',
points_rate: '0.05',
price: '100.0000'
pic: '//d39c94cu632zjz.cloudfront.net/static/absolute_url.jpg',
category_sku: 'category sku'
attributes: []
}

 

Коды ошибок

Код Описание
-7002  Категории по переданному sku не существует
-7004  Переданный name уже используется другим товаром
-7005  Продукт с переданным sku не существует

 

/api/v2/basket/products/list/ - список всех товаров

Данный метод предназначен для получения списка товаров, которые были добавлены через соответвующие методы (см. здесь и здесь).

Метод

GET /api/v2/basket/products/list/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
нет sku  sku товара. Если указан, отображается информация только по одному товару
нет category_sku  sku категории товаров. Ограничивает список товаров указанной и дочерними по отнонею к указанной категориями. Если не указан - отображаются все товары
нет page  номер страницы

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции
num_pages  Количество страниц
products  Массив объектов со следующими аттрибутами:
sku  SKU (ID) товара в вашей системе.
attributes  Объект, содержащий список и значения атрибутов товара.
name  Наименование данного товара
category_sku  Категория, в которой находится данный товар
points_rate  Коэффициент конвертации для данного товара
create_date  Дата создания

 

Пример ответа сервера: 

{
status: 'ok',
num_pages: 3,
products: [
{
sku: 'a_1',
name: 'notebook',
points_rate: '0.1000',
pic: '//d39c94cu632zjz.cloudfront.net/static/notebook.jpg',
      category_sku: 'e_1'
"attributes": [
               {
                   "sku": "attr1",
                   "values": [
                       {
                           "sku": null,
                           "value": "va3"
                       }
                   ],
                   "name": "first"
               }
           ],
},
{
sku: 'a_2',
name: 'tablet pc',
points_rate: '0.2500',
pic: '//d39c94cu632zjz.cloudfront.net/static/tablet.jpg',
category_sku: 'e_1'
"attributes": [
               {
                   "sku": "attr2",
                   "values": [
                       {
                           "sku": null,
                           "value": "va4"
                       }
                   ],
                   "name": "first"
               }
           ],
},
....
]
}

 

/api/v2/basket/products/attributes/add/ - присвоение товару атрибута и значения

Данный метод предназначен для добавления справочников (атрибутов), ранее созданным, товарам. Для каждого товара могут быть добавлены различные атрибуты с различными значениями. Количество атрибутов не ограничено.

Метод

POST /api/v2/basket/products/attributes/add/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  Идентификатор товара
да attribute_sku  SKU ранее созданного справочника (атрибута)
да value_sku  Значение атрибута, в соответствии с data_type атрибута

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции

 

Пример ответа сервера: 

{
status: 'ok'
}

/api/v2/basket/products/attributes/edit/ - изменение значея атрибута

Этот метод необходим для изменения значения какого-либо атрибута для товара.
Для того чтобы изменить значение атрибута необходимо передать как новое так и старое значение.

Следует отметить, что новое значение должно быть введено в соответствии с 'data_type' справочника (атрибута).

Метод

POST /api/v2/basket/product/attributes/edit/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU товара
да attribute_sku  SKU (ID) данного атрибута в вашей системе
да value_sku_from  Значение атрибута до изменения
да value_sku_to  Желаемое (новое) значение атрибута

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции

 

Пример ответа сервера: 

{
status: 'ok'
}

/api/v2/basket/products/attributes/delete/ - удаление атрибута товара

Этот метод позволяет удалить какое либо значения из определенного справочника (атрибута).

 

Метод

POST /api/v2/basket/products/attributes/delete/

 

Формат запроса

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да sku  SKU товара
да attribute_sku  SKU (ID) данного атрибута в вашей системе

 

Ответ сервера

Название параметра Описание параметра
status  Статус операции

 

Пример ответа сервера: 

{
status: 'ok'
}