Методы:

  • /api/v1/gifts/offer/
  • /api/v1/gifts/offer/available/
  • /api/v1/ecommerce/gifts/commit-transaction - подтверждение выдачи подарка
  • /api/v2/gifts/coupons/status/ - статус купона
  • /api/v2/gifts/coupons/delete/ - удаление купона
  • /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": "79000000000"
}
}

/api/v2/gifts/coupons/status - Проверка статуса купона

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

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

/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
"id" : 9293212929
},
"status": "ok",
"user":
{
"phone": null,
"origin_user_id": null,
"id": null
}
}

 

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

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

 

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

action=<confirm | confirm_cancel>

/api/v2/gifts/coupons/delete - Удаление купонов

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

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345
да coupon_id Внутренний идентификатор купона integer
coupon_id=180841

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

sailplay.ru/api/v2/gifts/coupons/delete/?store_department_id=345&token=qx6s4gsdvsdhsdsd&coupon_id=180841

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

Параметр Описание параметра Тип данных Пример
status

Статус запроса:

ok — если запрос успешен, error — если возникла ошибка.

JSON String
"status":"ok"

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

{
    "status": "ok"
}

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

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

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

Купон не найден

{
    "status": "error",
    "message": "Coupon not found"
}

Купон уже выдан и не может быть удален

{
    "status": "error",
    "message": "Coupon is already redeemed"
}

 

/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 - номер заказа, в который был включен данный подарок. Если подарок уже был выдан в рамках данного заказа - вернется ошибка.
[необязательный параметр] purchase_dep_id - идентификатор отдела (store_department_id), в котором был выдан подарок. Если параметр не передается, отдел будет определен из параметра store_department_id запроса.

 

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

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&purchase_dep_id=1241

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


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