Методы

/api/v2/marketing-actions/calc - расчет акций для чека (корзины)

Этот метод предназначен для формирования корзины (чека), расчета её стоимости, количества начисляемых баллов и применения акций с последующим пересчетом стоимости заказа (в случае если он изменился при применении акции).

При формировании запроса передаётся информация о количестве товарах, их SKU и цене.

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

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да
  • cart
    • 1, 2, 3 ... n
    • sku
    • price
    • quantity
    • discount_points
    • min_price
  • JSON, содержащий основную информацию о чеке (корзине)
    • Порядковый номер товара в корзине (позиция строки в чеке)
    • ID товара в вашей системе (артикул)
    • Суммарная стоимость позиции
    • Количество единиц товара в позиции чека.
    • Информация о размере желаемого списания баллов для каждой позиции в параметрею. Необязательный ключ. Значение по-умолчанию — 0
    • минимальная стоимость товара по которой товар может быть продан. Акции не могут снизить стоимость товара ниже min_price. Необязательный параметр.
  • JSON Objects
    • JSON String
    • JSON String
    • JSON Number
    • JSON Number
    • JSON Number
    • JSON Number
{"1":{"sku":"item1","price":1000,"quantity":1,"discount_points":0,"min_price":250}} 

qweasdzxcqweasdxcz

нет promocodes Массив со списком промокодов, примененных к корзине (заказу) JSON Array
["summer2017"]
нет card_numbers Массив, содержащий коды дисконтных карт, примененных к корзине (заказу). Возможно передать несколько карт в один заказ разделяя их запятой. JSON Array
["290000000236543"]
нет verbose Параметр verbose служит для отображения более детальной информации по расчету акции в ответе сервера. Изменение данных касается только массива marketing_actions_applied и вложенного в объект позиций массива marketing_actions. Принимает значения 1 (выводить дополнительные данные) или 0 (не выводить). integer
1

Примечения

  • Значение discount_points должно быть рассчитано на стороне кассового ПО или вашего сайта, в соответствии с желаемой бизнес-логикой.
  • Значение min_price также рассчитывается на стороне кассового ПО или сайта. В качестве min_price может выступать себестоимость товара или любой другой порог, ниже которого отпускать товар нельзя.
  • Если значение скидки, получаемой по позиции при переданном количестве баллов превышает квоту, то в ответ на запрос будет возвращена ошибка с указанием позиции, превысившей квоту:
{
    "status": "error",
    "status_code": -7042,
    "message": "Max discount. Position num = 1"
 }

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

https://sailplay.ru/api/v2/marketing-actions/calc/?token=qwuwq6e5546qwe6qrwe&store_department_id=456&cart={"1":{"sku":"123123","price":1500,"quantity":2,"discount_points":0,"min_price":300}}&user_phone=70001234567&card_numbers=["200000000981"]&promocodes=["summer2017"]&verbose=1

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

При успешном запросе сервер возвращает JSON со следующими параметрами:

Параметр (ключ)ОписаниеТип данныхПример
status статус запроса JSON String
"status":"ok"
  • marketing_actions_applied
    • client_msg
    • service_msg
    • name
    • alias
  • Массив с примененными к корзине акциями, содержащий объекты примененных акций со значениями:
    • сообщение для отображения покупателю
    • сообщение для отображения продавцу
    • наименование акции
    • идентификатор акции
  • JSON Array
    • JSON String или null
    • JSON String или null
    • JSON String
    • JSON String
"marketing_actions_applied":[
   {
      "client_msg":null,
      "service_msg":null,
      "name":"Bonus",
      "alias":"60 pre"
   }
]

------------------------------

possible_marketing_actions

Массив с акциями, которые могут быть применены к корзине, содержащий объекты возможных акции со значениями:

  • сообщение для отображения покупателю
  • сообщение для отображения продавцу
  • наименование акции
  • идентификатор акции
  • объект, содержащий информацию о вознаграждениях, которые возможно применить по данной акции. Добавляется
    только для вознаграждений с модификатором
    "Предлагать при выполнении условий
    акции", при выполнении всех условий акции:
    • Объект, содержащий следующую
      информацию о вознаграждении:
      • тип вознаграждения: "discount"
        для вознаграждения "Скидка на товар",
        "fixed" - для вознаграждения "Фиксированная цена"
      • массив, содержащий SKU товаров,
        попадающих под действие данного
        вознаграждения
      • в случае, если на вознаграждение
        установлен лимит использования -
        лимит использования вознаграждения
      • в случае, если на вознаграждение
        установлен лимит использования -
        оставшийся лимит использования
        вознаграждения (учитывая товары, уже
        добавленные в корзину, на которые это
        вознаграждение уже применилось)
      • в случае, если вознаграждение типа
        "Фиксированная цена" - стоимость
        товара после применения
        вознаграждения
см.marketing_actions_applied
"marketing_actions_applied":[
   {
      "client_msg":null,
      "service_msg":null,
      "name":"Bonus",
      "alias":"60 pre"
"rewards": [{
"type": "fixed",
"gift_sku": [
"sku1",
"sku2"
],
"quantity_limit": 2,
"quantity_left": 1,
"gift_price": 15
} ]
  • cart
    • total_price
    • total_discount_points_max
    • total_points
    • positions
      • category
        • sku
        • id
        • name
      • product
        • sku
        • id
        • name
      • discount_points_max
      • reverse_points_rate
      • price
      • expiry_info
      • new_price
      • min_price
      • num
      • marketing_actions
      • quantity
      • points_rate
      • discount_points
      • points
    • positions_count
    • id
  • Объект корзины, включающий в себя следующие данные:
    • стоимость корзины после применения акций
    • максимальное кол-во баллов, которое можно потратить в счет покупки. Значение определяется на стороне SailPlay.
    • кол-во баллов, которое получит пользователь за покупку, в соответствии с настройкой коэффициента в SailPlay. 
    • массив, содержащий в себе объекты каждой отдельной позиции. Содержимое объекта позиции:
      • объект содержащий следующую информацию о категории товара:
        • id категории в системе партнера
        • id категории в системе Sailplay
        • наименование категории
      • объект содержащий следующую информацию о товаре:
        • id товара в системе партнера
        • id товара в системе SailPlay
        • наименование товара
      • максимальное кол-во баллов, которое можно списать в счет покупки позиции. Значение рассчитывается на стороне SailPlay.
      • коэффициент списания баллов в счет покупки. Значение указывается в процессе настройки акций.
      • начальная стоимость товара
      • стоимость товара после применения акций
      • минимальная стоимость товара, ниже которой она не опустится невзирая на кол-во примененных акций. Значение определяется и передается с кассового ПО. В качестве минимальной стоимости может выступать себестоимость товара.
      • порядковый номер позиции в корзине. Может использоваться для сопоставления товаров в чеке и товаров в ответе от SailPlay.
      • массив, в котором находтся акции, котороеы были применены относительно этой позиции.
      • кол-во позиции в корзине
      • коэффициент для расчета кол-ва баллов, которое пользователь получит за покупку позиции. Коэффициент настраивается на стороне SailPlay.
      • кол-во баллов, которое будет списано с пользователья в счет скидки за покупку позиции. Указывается в параметре discount_points.
      • кол-во баллов, которое получит пользватель за покупку данной позиции.
    • кол-во позиций в корзине. Считается по порядковым номерам позиций, а не по их кол-ву (quantity).
    • id операции (расчета корзины).
  • JSON Object
    • JSON String
    • JSON Number
    • JSON Number
    • JSON Array
      • JSON Object
        • JSON String
        • JSON Number
        • JSON String
      • JSON Object
        • JSON String
        • JSON Number
        • JSON String
      • JSON Number
      • JSON Array
      • JSON String
      • JSON String
      • JSON String
      • JSON Number
      • JSON Array
      • JSON String
      • JSON String
      • JSON Number
      • JSON Number
    • JSON Number
    • JSON Number
"cart":{
   "total_price":"810.00",
   "total_discount_points_max":0,
   "total_points":0,
   "positions":[
      {
         "category":{
            "sku":"001105",
            "id":111540,
            "name":"Default cat"
         },
         "product":{
            "sku":"57681645",
            "id":14042,
            "name":"Item1"
         },
         "discount_points_max":0,
         "reverse_points_rate":[

         ],
         "price":"900.00",
         "new_price":"810.00",
         "min_price":"120.00",
         "num":1,
         "marketing_actions":[
            "Action 1"
         ],
         "quantity":"1",
         "points_rate":"0.0000",
         "discount_points":0,
         "points":"0.00"
      }
   ],
   "positions_count":1,
   "id":206410452
}

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

{
    "status": "ok",
    "marketing_actions_applied": [
        {
            "client_msg": null,
            "service_msg": null,
            "name": "Bonus",
            "alias": "60 pre"
        }
    ],
    "possible_marketing_actions": [
        {

            "client_msg": null,
            "service_msg": null,
            "name": "Bonus",
            "alias": "60 pre"
        }
    ],
    "cart": {
                "total_price": "890.00",
                "total_discount_points_max": 450,
                "total_points": 0,
                "positions": [
                    {
                        "category": {
                            "sku": "Default cat",
                            "id": 85548,
                            "name": "Default cat"
                        },
                        "product": {
                            "sku": "item_1_test",
                            "id": 3855267,
                            "name": "Item 1"
                        },
                        "discount_points_max": 450,
                        "reverse_points_rate": [],
                        "price": "900.00",
                        "new_price": "890.00",
                        "min_price": "400.00",
                        "num": 1,
                        "marketing_actions": [],
                        "quantity": "1",
                        "points_rate": "0.0000",
                        "discount_points": 10,
                        "points": 0
                    }
                ],
                "positions_count": 1,
                "id": 202558532
            }
    }

Возможные ошибки

Пара store_deprtment_id и token указаные неверно или отсутствуют.

{
    "status": "error",
    "message": "Permission denied. Provide auth token and store_department_id"
}

Невалидный JSON в параметре cart

{
    "status": "error",
    "status_code": -1211,
    "message": "Must be valid json string {'field': 'cart'}"
}

Значение скидки, получаемой по позиции при переданном количестве баллов превышает квоту

{
    "status": "error",
    "status_code": -7042,
    "message": "Max discount. Position num = 1"
 }

Неописанная ошибка

{
    "status": "error",
    "message": "server error"
}

При возникновение подобной ошибки просим обратиться в службу поддержки по адресу support@sailplay.ru

Пример отображения параметра marketing_actions_applied, при включенной опции verbose:

"marketing_actions_applied":[
        {
            "count":null,
            "total_quantity_applied":null,
            "service_msg":"6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
            "name":"Процентный прайс от 20.10.2017 (531)",
            "alias":"6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
            "client_msg":"6fcc3ebd-b57c-11e7-a265-000c29bf15f9",
            "till_date":null,
            "total_discount":null
        }
    ]   

Дополнительные ключи содержат значений отличные от null только в том случае, если в настройках акции выставлены ограничения "Лимит по количеству применений акции" или "Лимит для каждого клиента".

Описание дополнительных ключей:

Параметр (ключ)ОписаниеТип данныхПример
count Оставшееся кол-во применений акции для пользователя. JSON Number или null
"count":1
total_quantity_applied Оставшееся кол-во товаров на которое может примениться скидка по акции. JSON String или null
"total_quantity_applied":"10"
till_date Дата окончания действия ограничений для пользователя. JSON String или null
"till_date":"2017-11-19T19:44:58.489"
total_discount Оставшаяся сумма, которая может быть получена пользователем в виде скидки. JSON String или null
"total_discount":"207894.00"

/api/v2/marketing-actions/balance - запрос лимитов для пользователя по акциям

Метод предназначен для запроса лимитов пользователя по отношению к лимитированным акциям.

Лимиты в настройках акции позволяют указать ограничения: сколько раз и в каком объеме может сработать акция. Например - когда у маркетинговой кампании есть ограниченный бюджет, или мы хотим добавить ограничение для клиента - например, кратковременная акция, которая должна действовать для каждого клиента 1 раз в день.

Эта настройка может ориентироваться как на общее количество покупок по акции (имеется ввиду, что, например, акция должна перестать быть активной после первых N срабатываний), так и на количество покупок определенного клиента, учитывая для этого ограничение времени в днях (например, 1 раз в день, 2 раза в месяц и так далее). Подробный пример описан ниже, для каждого из параметров.

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

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

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

Параметр обязательный? Параметр Описание параметра Пример
да token См. здесь
token=dqgfsd66asdhgds87ssd
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см. здесь.
user_phone=79001234567
да store_department_id См. здесь
store_department_id=345

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

https://sailplay.ru/api/v2/marketing-actions/balance/?token=xxxxxxxxx&store_department_id=xxx&user_phone=70001234567

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

При успешном запросе сервер возвращает JSON со следующими параметрами:

Параметр (ключ)ОписаниеТип данныхПример
status статус запроса JSON String
"status":"ok"
  • marketing_actions_info
    • name
    • remaining_count
    • till_date
    • remaining_quantity
    • remaining_discount
    • id
  • Массив с информацией по лимитам пользователя, содержащий следующие данные:
    • Наименование акции
    • Оставшееся кол-во применений акций
    • Дата окончания
    • Оставшееся кол-во товаров
    • Оставшаяся скидка
    • id акции
  • JSON Array
    • JSON String
    • JSON Number
    • JSON String
    • JSON Number
    • JSON String
    • JSON Number
"marketing_actions_info":[
    {
        "name":"Limit action",
        "remaining_count":15,
        "till_date":"2017-11-24T19:44:58.489",
        "remaining_quantity":65,
        "remaining_discount":"1207894.00",
        "id":3596
     }
 ]

-------------------------------------

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

{
  "status":"ok",
  "marketing_actions_info":[
     {
        "name":"Limit action",
        "remaining_count":15,
        "till_date":"2017-11-24T19:44:58.489",
        "remaining_quantity":65,
        "remaining_discount":"1207894.00",
        "id":3596
     }
  ]
}


api/v2/marketing-actions/calc/bulk/

Метод используется для расчётов акций на витринах и ценниках в рамках отдела от которого производится запрос. 

Метод возвращает рассчитанную цену товара, исходя из акций, которые действуют на этот товар независимо от других условий. Например, промокодов, статусов клиента и комплектов. Если не передан идентификатор участника программы лояльности расчет производится только для акций с типом “все клиенты”. 

При передаче идентификатора участника программы лояльности расчёт производится для всех участников программы лояльности. Акции по специфичным сегментам клиента применены не будут.

 Полученный расчет сохраняется в кэш, и при последующих расчетах результат будет возвращен из кэша. Время хранения кэша 1 час.

Параметр Обязательный Описание
pin_code да см.Авторизация
store_department_id да см.Авторизация
store_department_key да см.Авторизация
token да см.Авторизация
positions да принимает:sku – идентификатор товара;price – первоначальная стоимость товара.
user_phone, origin_user_id, email нет идентификаторы клиента

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

https://sailplay.ru//api/v2/marketingactions/calc/bulk/?pin_code=1234&positions=[{"sku":"676939FD-D0BD-1B3F-AE05-3E30A030A162","price":200},{"sku":"095371AF-7B6C-4788-B4C795FD774171AB","price":200}]&store_department_id=2324&store_department_key=34434512&token=sgearr23Qdsw234234

 В случае успеха:

{
"status": "ok",
"positions": [
{
"product": {
"sku": "676939FD-D0BD-1B3F-AE05-3E30A030A162",
"id": 25015135,
"name": "Смекта суспензия для приема внутрь (карамель-какао) пак. 3г 8 шт._227902"
},
"new_price": "200.00",
"price": "200.00",
"possible_marketing_actions": [
{
"client_msg": "Применён сертификат",
"service_msg": null,
"name": "prc_m_hello5",
"alias": "prc_m_hello5"
},
{
"client_msg": "",
"service_msg": "",
"name": "prc_p_danti_15_20200718-20201231",
"alias": "prc_p_danti_15_20200718-20201231"
}
],
"marketing_actions": [
"Срок действия баллов - 6 месяцев"
]
},
{
"product": {
"sku": "095371AF-7B6C-4788-B4C795FD774171AB",
"id": 42308787,
"name": null
},
"price": "200.00",
"marketing_actions": [
"Срок действия баллов - 6 месяцев"
],
"possible_marketing_actions": [
{
"client_msg": "Применён сертификат",
"service_msg": null,
"name": "prc_m_hello5",
"alias": "prc_m_hello5"
},
{
"client_msg": "",
"service_msg": "",
"name": "prc_p_danti_15_20200718-20201231",
"alias": "prc_p_danti_15_20200718-20201231"
}
],
"new_price": "200.00"
}
]
}

, где:

status – состояние соединения;

product – объект товар;

sku – идентификатор товара;

id – id товара в системе;

name – наименование товара.

price – цена товара до расчёта акций ;

new_price – цена товара после расчёта акций;

possible_marketing_actions – возможные акции для этого товара;

marketing_actions – акции, примененные к товару.