Методы:

  • /api/v1/gifts/offer/
  • /api/v1/gifts/offer/available/
  • /api/v1/ecommerce/gifts/commit-transaction - подтверждение выдачи подарка
  • /api/v2/gifts/coupons/status/ - статус купона
  • /api/v2/gifts/manage/categories/ - список категорий подарков
  • /api/v2/gifts/manage/create/ - создание подарка
  • /api/v2/gifts/manage/edit/ - редакртирование подарка
  • /api/v2/gifts/list/ - список подарков
  • /api/v2/gifts/offer/ - 
  • /api/v2/gifts/purchases/delete/ - отмена выдачи подарка
  • /api/v2/gifts/purchases/edit/ - изменение выданного подарка
  • /api/v2/gifts/purchases/new/ - выдача подарка
  • /api/v2/gifts/samples/ - список типовых подарков SailPlay

Подтверждение выдачи подарка

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

http://sailplay.ru/api/v1/ecommerce/gifts/commit-transaction/?token=7ce324861c4a5de5bfe931c04d96073f9b72bfec&store_department_id=122&gift_public_key=09kdhh472idgh785920kfa

 Формат ответа

{
"status": "ok",
"purchase_gift": {
"id": 166,                   //id транзакции
"already_completed": false,  //была ли уже проведена транзакция
"gift": 20,                  //id подарка в системе SailPlay.ru
"gift_sku": "123",           //идентификатор подарка в системе партнера
"purchase_date": "2013-03-26T10:18:41",       
"complete_date": "2013-03-26T10:19:04.118",
"points_delta": 800,
"is_completed": true,
"user": "79149004432"
}
}

/api/v2/gifts/coupons/status/ - cтатус купона

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

Для получения информации о статусе получения купона используйте метод

/api/v2/gifts/coupons/status.

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

sailplay.ru/api/v2/gifts/coupons/status/?store_department_id=15&token=a81f9aaa212fa92a4ea2d8f05f350995002f761d08b0&coupon_number=adsf332hkak

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

{
"coupon":
{
"receipt_date": null,
"is_confirmed": false,
"number": "adsf332hkak",
"points": 400,
"confirm_date": null,
"is_purchased": false
},
"status": "ok",
"user":
{
"phone": null,
"origin_user_id": null,
"id": null
}
}

 

В ответе используются следующие переменные:

receipt_date - дата и время получения купона пользователем
is_confirmed - используется для подтверждения учета вашей системой данного купона. Методы для работы с данным параметром описаны ниже.

 

Для работы с полем is_confirmed используйте этот же запрос, дополнительно указав параметр

action=<confirm | confirm_cancel>

/api/v2/gifts/manage/categories/ - список категорий подарков

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

Каждый подарок должен принадлежать определенной категории. Категория подарка задается либо при создании подарка в личном кабинете на сайте SailPlay.ru в процессе созадния подарка, либо через API. 

Данный метод возвращает список всех категорий.

 

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

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

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

Название параметра Описание параметра
status  

массив

categories

 Массив объектов, содержащих два поля: id, name


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

http://sailplay.ru/api/v2/gifts/manage/categories/?token=45d1a2c8777532f140dfbd42706a5382540c8cdb&store_department_id=131

 

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

{
status: "ok",
categories:
[
{
id: 1,
name: "Одежда и обувь"
},
{
id: 2,
name: "Спортивные аксессуары и товары"
}
]

/api/v2/gifts/manage/create/ - создание подарка

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

Используйте этот метод для автоматического создания подарков, используя SailPlay API. 

Параметры

Параметр обязательный? Имя параметра Описание параметра
да token  См. здесь
да store_department_id  См. здесь
да name  Наименование подарка. Будет отображаться в popup'е на главной странице и на странице конкретного подарка.
да description  Текст описания подарка. Будет отображаться в popup'е на странице конкретного подарка.
да enabled  Флаг "Активен ли подарок?". Если равно “1” - подарок после создания будет доступен, любое другое значение - подарок будет недоступен.
да points  Стоимость подарка в баллах.
да pic  Изображение подарка (файл в POST). Это изображение будет использовано в попапе и личном кабинете. Оно обязательно должно быть квадратным. Оно будет автоматически масштабировано под размер 250х250
да pic_full  Изображение подарка (файл в POST). Это изображение не будет автоматически обрабатываться и будет возвращено в исходном виде. Требований к пропорциям нет.
нет quantity  Количество подарков (в случае если параметр не передан - подарков неограниченное количество, если передан - указанное количество
нет category  Категория подарка
Нет type  Тип подарка (если передан, то должен иметь значение “coupon”).
нет Coupons  Номера купонов через запятую.
Нет sku  Идентификатор подарка в вашей системе (см. также здесь.)
нет partner_url  URL страницы подарка на вашем сайте (если таковой имеется). Будет использован при генерации ссылок при шарингах пользователей. Если значение этого параметра пустое, будет использоваться адрес вашего сайта, если и он пустой - страница подарка на сайте SailPlay.
нет help_text  Текст, который будет отображаться пользователю в popup’е после получения подарка (подробнее см. здесь).
нет share_msg  Текст, который будет подставляться при шаринге пользователем информации в социальной сети. Информацию о переменных, которые можно использовать, можно узнать в вашем личном кабинете на SailPlay, либо обратившись в службу поддержки.
нет sms_msg  Текст SMS-сообщения, которое будет отправляться пользователю после получения подарка. Информацию о переменных, которые можно использовать, можно узнать в вашем личном кабинете на SailPlay, либо обратившись в службу поддержки.

 

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

В ответ вернутся все переданные параметры в виде json-массива. 

Важно!

При создании подарка проходит валидация параметров на соответствие типу. Кроме этого, отдельно проверяется:

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

 

/api/v2/gifts/manage/edit/ - редактирование подарка

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

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

Описание метода

Для редактирования подарка используется метод

/api/v2/gifts/manage/edit

По структуре запроса/ответа и передаваемых параметров он такой же как и метод для создания подарка, но со следующими отличиями:

  1. при редактировании подарка обязательно необходимо передать параметр gift_id - ID подарка

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

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

  4. если у подарка тип купон, в случае если передаются параметры coupons - все новые неповторяющиеся будут добавлены к списку предыдущих купонов

/api/v1/gifts/list/ - полуение списка подарков

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

Метод позволяет получить список всех активных подарков.

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

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

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

Название параметра Описание параметра
status  

массив

gifts

 Массив объектов, содержащих в себе описание подарков.


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

http://sailplay.ru/api/v1/gifts/list/?token=c5c7c184b656d1166a2d512d19a945ae2a263858&store_department_id=441

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

{
"gifts": [
{
"sku": "even1",
"update_date": "2014-02-21T10:41:11",
"name": "Подарок",
"pic": "gifts/gift/b7fbeb7581fe4bafb408362b9d0c53d4.jpg",
"pic_full":"https://d3vr33qml1umu3.cloudfront.net/media/gifts/gift/b3a1a4faf2ebbaff7094a10e.jpg",
"points": 100,
"id": 583,
"description": "Отличный подарок за вашу преданность!"
}
],
"status": "ok",
"media_url": "//d3257v5wstjx8h.cloudfront.net/media/"
}

Где:

sku - идентификатор подарка на стороне партнера
update_date - дата последнего обновления
name - название подарка
pic - ссылка на изображение подарка
pic_full - ссылка на альтернативное изображение подарка в оригинальном размере
points - стоимость подарка в баллах
id - идентификатор подарка на стороне SailPlay
description - описание подарка
media_url - префикс ссылки на изображение подарка

 

/api/v2/gifts/purchases/new/ - выдача подарка

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

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

Параметры

[обязательный параметр] token
[обязательный параметр] store_department_id
[обязательный параметр] user_phone или origin_user_id
[обязательный параметр] gift_id или sku_id
[необязательный параметр] order_num - номер заказа, в который был включен данный подарок. Если подарок уже был выдан в рамках данного заказа - вернется ошибка.

 

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

sku  - SKU выданного подарка
status - статус транзакции
gift_id - ID подарка в системе SailPlay
user
phone
origin_user_id
order_num
points_delta - списанные баллы



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

http://sailplay.ru/api/v2/gifts/purchases/new/?store_department_id=37&token=0a5f9516698a3c9c2d34394fa8da9474307193c8&user_phone=79236054672&sku=U12312

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


{
"sku": "U12312",
"status": "ok",
"gift_id": 11,
"user": {
"phone": "79266054672",
"origin_user_id": "asdf23heiuhi2lhiuehiu23eh23ihi2e23e23"
},
"order_num": null,
"points_delta": 100
}