Методы

/api/v1/purchases/confirm/ - подтверждение покупки

Назначение метода

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

Реализовано это следующим образом: устанавливается время жизни “неподтвержденных” бонусных баллов.  По прошествии этого срока, если оплата не была подтверждена, бонусные баллы будут списаны автоматически. В период, пока покупка не подтверждена и срок не истек, пользователь не сможет получить подарок.

Кроме этого, в методе purchases/new реализован механизм подтверждения платежей (см.  здесь 

Внимание

В запросе используется параметр order_num - номер заказа/платежа (это номер заказа в вашей системе, который был передан в запросе на начисление бонусных баллов). Вместо него может быть использован purchase_id - ID транзакции в системе SailPlay, который возвращается в ответе на запрос о начислении бонусных баллов. При этом, если переданы оба параметра, то приоритет отдается purchase_id. 

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

Параметр обязательный  Название параметра  Описание параметра 
да token   См. здесь 
да store_department_id   См. здесь 
да order_num (либо purchase_id)  Номер заказа в вашей системе (либо ID транзакции, который возвращается в ответ на запрос начисления бонусных баллов)
нет new_price  Актуальная цена (цена после подтверждения, если изменилась)
нет positions  Массив товаров внутри данной покупки (состав корзины). Имеет формат “positions=1899,200:101,379” - в группах, разделенных двоеточиями, парами идут ID-товаров в вашей системе и стоимость. Если покупок с данным ID товара несколько - передавать этот ID нужно несколько раз. Важно: суммы должны иметь тип int.

 

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


http://sailplay.ru/api/v1/purchases/confirm/?store_department_id=1&token=b301f9928dda6499a74755491767208f3b156867&order_num=12344&new_price=12344&positions=1899,200:101,379

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

Полностью идентичен ответу сервера при начислении бонусных баллов ( см. здесь )

 

/api/v1/purchases/delete/ - удаление покупки

Назначение метода

Служит для удаления покупки и отмены начисления бонусных баллов за совершенную покупку. 

Важно

Допустим пользователь совершил покупку и получил 1000 бонусных баллов, а затем получил подарок на 100 бонусных баллов. В этом случае запрос на удаление покупки вернет ошибку, потому что после его удаления у пользователя останется отрицательное количество бонусных баллов. Чтобы решить эту проблему, предварительно необходимо удалить транзакцию о выдаче подарка. 

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

Параметр обязательный  Название параметра  Описание параметра 
да order_num или purchase_id  Номер заказа, либо ID транзакции в системе SailPlay (более подробно см. п. 2.1)
да token   См. здесь 
да store_department_id   См. здесь 

 

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

Название параметра  Описание параметра 
status  
id  Уникальный ID удаленной транзакции
order_num  Номер удаленного заказа

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

http://sailplay.ru/api/v1/purchases/delete/?store_department_id=32&token=0e96be0867401601df4c6e8691476bfaaa73f3&order_num=12345

 

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

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

{

"order_num": "12345",
"status": "ok",
"id": 9676
}

 В случае неуспеха (если у пользователя не хватает бонусных баллов, т.е. если перед этим предварительно не был удален подарок): 

{

  "status":"error",
  "status_code": -3001,
  "message":"Impossible to delete purchase"
}

/api/v1/purchases/edit/ - редактирование покупки

Назначение метода

Служит для изменения пользователя, к которому привязана покупка.

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

Параметр обязательный  Название параметра  Описание параметра 
да order_num или purchase_id  Номер заказа, либо ID транзакции в системе SailPlay (более подробно см. п. 2.1)
да token   См. здесь 
да store_department_id   См. здесь 
да user_phone или email или origin_user_id  Идентификатор клиента. Более подробно см.  здесь .

 

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

Название параметра  Описание параметра 
status  
id  Уникальный ID измененной транзакции
order_num  Номер измененного заказа
user  Данные о пользователе, к которому теперь привязана покупка

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

http://sailplay.ru/api/v1/purchases/edit/?token=206f37f4fbf70db81b330d8187beed7a3b507a0f&store_department_id=*&order_num=9988&origin_user_id=12200247

 

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

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

{
"order_num": "9988",
"status": "ok",
"id": 68283629,
"user": {
"full_phone": "",
"phone": "+7 (916) 1***-05",
"origin_user_id": "12200244",
"last_name": "Тепцова",
"first_name": "Татьяна",
"points": 0,
"id": 36151702,
"email": "tteptsova@yandex.ru"
}
}

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

{
"status": "error",
"status_code": -3003,
"message": "Impossible to change purchase user"
}

/api/v1/purchases/get/ - получение информации о покупке

Назначение метода

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

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

Параметр обязательный  Название параметра  Описание параметра 
да order_num   Номер заказа
да token   См. здесь 
да store_department_id   См. здесь 

 

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

Название параметра  Описание параметра 
status  
purchase объект с инфомрацией о покупке
is_completed подтверждена ли покупка
store_department_id идентификатор департамента покупки
completed_date дата подтверждения
order_num идентификатор заказа
points_delta количество начисленных баллов
public_key ключ подтверждения покупки
user_id внутренний идентификатор клиента в системе SailPlay
purchase_date дата совершения покупки
clerk_pin пинкод клиента
price сумма покупки
cart объект описания корзины

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

http://sailplay.ru/api/v2/purchases/get/?store_department_id=435&token=b3c7ac443b9843bf4daa20f54292655b5f77bb4b&order_num=136

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

{
    "status": "ok",
    "purchase": {
        "is_completed": false,
        "store_department_id": 435,
        "completed_date": null,
        "order_num": "42260",
        "id": 11916548,
        "points_delta": 25,
        "public_key": "7d46d2b7c74c418c9559621e85f97afcc1eddbe2",
        "user_id": 6556846,
        "purchase_date": "2015-05-12T17:49:01",
        "clerk_pin": "1231",
        "price": 500
    },
    "cart": {
        "marketing_actions_applied": [
            {
                "client_msg": "Уведомление об успехе!",
                "service_msg": "Уведомление о возмоности!",
                "alias": "all"
            }
        ],
        "possible_marketing_actions": [],
        "cart": {
            "total_points": 25,
            "positions": [
                {
                    "category": {
                        "sku": "default",
                        "id": 707
                    },
                    "product": {
                        "sku": "ugly",
                        "id": 485226
                    },
                    "num": "1",
                    "points_rate": "0.05000",
                    "price": "600.00",
                    "quantity": "1.0000",
                    "new_price": "300.00",
                    "points": 15
                },
                {
                    "category": {
                        "sku": "default",
                        "id": 707
                    },
                    "product": {
                        "sku": "2",
                        "id": 485224
                    },
                    "num": "2",
                    "points_rate": "0.05000",
                    "price": "400.00",
                    "quantity": "1.0000",
                    "new_price": "200.00",
                    "points": 10
                }
            ],
            "positions_count": 2,
            "total_price": "500.00",
            "id": 1547
        }
    }
}

/api/v1/purchases/new/ - создание покупки

Назначение метода

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

Процесс выглядит следующим образом: 

  • Покупатель совершает покупку на вашем сайте
  • С вашего сервера (сайта, POS-терминала, мобильного приложения) отправляется HTTP(s)-запрос к SailPlay

 

В ответ вернется public_key, который необходимо подставить при отображении следующей страницы в JS.

Для случаев, когда

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

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

Работает это следующим образом: в запросе на  начисление подтверждение  бонусных баллов дополнительно передается параметр positions, имеющий следующий формат:

 

postion_id_1,[category_id_1,]sum_1[:...:postion_id_N,[category_id_N,]sum_N]

где

Параметр обязательный  Название параметра  Описание параметра 
да position_id  SKU товара в вашем каталоге (может содержать латинские символы и цифры)
да category_id  ID категории для данного товара в вашем каталоге
да sum  Сумма (стоимость для данного товара)

 

Как видно из формата, параметр категории является необязательным.

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

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

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

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

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

Параметр обязательный?  Имя параметра  Описание параметра 
да user_phone или email или origin_user_id  Идентификатор клиента. Более подробно см.  здесь .
да token  С м. здесь 
да store_department_id   см. здесь 
да pin_code   см. здесь 
да price Полная сумма покупки в местной валюте
нет fields Дополнительные поля, которые будут в JSON ответе. Дополнительные поля перечисляются через запятую и могут принимать следующие значения: public_key, order_num. Пример: &fields=public_key,order_num
нет points_rate Коэффициент конвертации рублей в баллы. Может принимать значение из полуинтервала (0,1]. При отсутствии данного параметра, используется значение, указанное в настройках. Формат points_rate=0.45
нет order_num Номер заказа в вашей системе (используется в случае, если выбран механизм с подтверждением факта оплаты. Подробнее  см. здесь )
нет force_complete Флаг. Если данный флаг установлен (force_complete=1), транзакция считается подтвержденной несмотря на флаг в настройках. Данный атрибут может быть использован, например, в случае когда часть оплат необходимо подтверждать, а про остальные известно что они уже подтверждены. Более подробно  см. здесь .
нет positions  Массив товаров внутри данной покупки (состав корзины). Имеет формат “positions=1899,13,200:101,10,379” - в группах, разделенных двоеточиями, передается ID-товаров в вашей системе, ID группы товара (опционально) и его стоимость Если покупок с данным ID товара несколько - передавать этот ID нужно несколько раз. Служит для возможности начисления бонусных баллов с разными коэффициентами (например, если есть необходимость за товары определенной категории начислять в 2 раза больше бонусных баллов). Более подробно  см. здесь . Важно: суммы должны иметь тип int.
нет user_category_name категория пользователя ( см. здесь )


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

Название параметра  Описание параметра 
status  
purchase Данные о транзакции
complete_date Дата и время окончания транзакции
price Переданная в запросе сумма
id Уникальный ID транзакции
points_delta Начисленные пользователю баллы за эту покупку
user Данные о пользователе, его баллах
phone Номер телефона пользователя в форматированном виде (если информация есть в системе SailPlay)
full_name Полное имя пользователя (если информация есть в системе SailPlay)
email Электронный адрес (если информация есть в системе SailPlay)
public_key Возвращается только, если был указан в запросе в параметре fields. Hash транзакции покупки. Используется для подставноки в JS-код popup'а для автоматического открытия попапа после покупки.
order_num Возвращается только, если был указан в запросе в параметре fields.Номер заказа в вашей системе.
attrs Атрибут покупки. Возможно указать любую информацию о покупке, которая понадобится в дальнейшем, например, тип платежа или время, которое заняла покупка.

 

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

http://sailplay.ru/api/v1/purchases/new/?store_department_id=219&cart={"1": {"sku": "1","price": "100","quantity": 3,"discount_points": 40},"2": {"sku": "2","price": "100", "quantity": 3,"discount_points": 30} }&order_num=327924&pin_code=1111&origin_user_id=25547&token=024e3bfbe50c8ef3d413caf19bf5380bbdd79df3&attrs={"processing_time":"249","payment_type":"card"}

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

{
    "status": "ok",
    "purchase": {
        "complete_date": "2013-01-25T00:31:42.642",
        "price": "10",
        "id": 8,
        "points_delta": 4,
        "public_key": ";ao08rj3tj09fu9jkwer20393urjflshg54h",
        "order_num": 132123
    },
    "user": {
        "phone": "79060054602",
        "points": 28,
        "full_name": "Кирилл Иванович Лавров"
    },
    "email": "sales@sailplay.ru"
}

/api/v2/purchases/confirm/ - подтверждение покупки

Назначение метода

Метод служит для подтверждения покупок в систему SailPlay.

Отличие от метода /api/v1/purchases/confirm/ в формате передачи состава корзины - в версии 2 это json объект, аналогично /api/v2/purchases/new/.

/api/v2/purchases/new/ - создание покупки с расчетом акций

Назначение метода

Метод служит для передачи информации о покупках в систему SailPlay.

В отличие от метода /api/v1/purchases/new/ в версии 2 производится рассчет акций, для чего состав корзины становится обязательным параметром. Также были убраны параметры модицифирующие количество начисляемых баллов (этот функциона перенесен в раздел акции) и немного поменялся формат корзины.

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone или email или origin_user_id  Идентификатор клиента. Более подробно см.  здесь .
да token  См. здесь
да store_department_id   см. здесь
да pin_code   см. здесь
да order_num   Номер заказа в вашей системе.
да cart    Json объект, содержащий в себе информацию о составе корзины. Для объекта каждоый позиции передаются параметры sku - идентификатор товара, price - суммарная стоимость товаров в позиции, количество товаров в позиции.
 нет cart_id   Идентификатор корзины, полученный на этапе предварительного рассчета (метод /api/v2/marketing-actions/calc/). Если передается cart_id состав корзины cart можно не передавать.
нет force_complete Флаг. Если данный флаг установлен (force_complete=1), транзакция считается подтвержденной несмотря на флаг в настройках. Данный атрибут может быть использован, например, в случае когда часть оплат необходимо подтверждать, а про остальные известно что они уже подтверждены. Более подробно  см. здесь .

 

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

http://sailplay.ru/api/v2/purchases/new/?store_department_id=219&token=024e3bfbe50c8ef3d413caf1erwf5380bbdd79df3&order_num=171&cart={"1":{"sku":"1","price":1000, "quantity":1},"2":{"sku":"2","price":300, "quantity":3}}&origin_user_id=cart1&pin_code=104443

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

{
    "status": "ok",
    "purchase": {
        "is_completed": false,
        "store_department_id": 219,
        "completed_date": null,
        "order_num": "171",
        "id": 23141,
        "points_delta": 410,
        "public_key": "a45939f44e6c6783ad8d38562e083a6fda233e29",
        "user_id": 340774,
        "purchase_date": "2015-06-02T15:00:16.129",
        "clerk_pin": "104443",
        "price": "1200.00"
    },
    "cart": {
        "marketing_actions_applied": [
            {
                "client_msg": "2",
                "service_msg": "1",
                "alias": "3"
            }
        ],
        "possible_marketing_actions": [],
        "cart": {
            "total_points": 410,
            "positions": [
                {
                    "category": {
                        "sku": "elphnt",
                        "id": 271
                    },
                    "product": {
                        "sku": "1",
                        "id": 203
                    },
                    "num": 1,
                    "marketing_actions": [],
                    "price": "1000.00",
                    "new_price": "1000.00",
                    "points": 400,
                    "points_rate": "0.4000",
                    "quantity": "1"
                },
                {
                    "category": {
                        "sku": "default",
                        "id": 196
                    },
                    "product": {
                        "sku": "2",
                        "id": 205
                    },
                    "num": 2,
                    "marketing_actions": [
                        "3"
                    ],
                    "price": "300.00",
                    "new_price": "200.00",
                    "points": 10,
                    "points_rate": "0.0500",
                    "quantity": "3"
                }
            ],
            "positions_count": 2,
            "total_price": "1200.00",
            "id": 1097
        }
    }
}