Методы

/api/v2/users/add/ - создание записи клиента

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

В SailPlay реализован механизм регистрации клиента партнера. Основной сценарий использования - это ведение статистики по клиенту (время регистрации, первая покупка, первое полезное действие и т.д.). Кроме этого, в зависимости от настроек, при регистрации клиента может быть начислено некоторое количество бонусных баллов за факт регистрации, а так же баллы могут быть начислены человеку, по приглашению которого был зарегистрирован данные клиент.

 

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
нет user_category_name Категория пользователя. Подробнее см.здесь.
нет first_name Имя
нет last_name Фамилия
нет middle_name Отчество
нет birth_date Дата рождения в формате гггг-мм-дд. Минимальное значение года – 1900. Максимальное - текущий год. Если передан год меньше минимального, то значение года автоматически будет установлено в 1900. Если год больше текущего - будет установлен текущий год. При этом месяц и день рождения будут соотвествовать переданному параметру.
нет sex Пол. 1- мужской, 2 - женский.
нет extra_fields Дополнительные поля, которые будут в JSON ответе. Дополнительные поля перечисляются через запятую и могут принимать следующие значения: auth_hash. Пример: &extra_fields=auth_hash
нет referrer_origin_user_id, referrer_phone или referrer_email Позволяет установвить реферальную связь между создаваемой записью клиента (приглашенный) и какой-либо созданной ранее (пригласивший). Если referrer_* запись не обнаружена - новая запись клиента без создана без реферальной связи. Принимает на вход идентификаторы клиента.
нет referrer_promocode Позволяет установвить реферальную связь между создаваемой записью клиента (приглашенный) и какой-либо созданной ранее (пригласивший). Если referrer_* запись не обнаружена - новая запись клиента без создана без реферальной связи. Принимает на вход уникальный реферальный код клиента.

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

Название параметра Описание параметра
status  
message Текстовый ответ сервера. Состоит из двух частей: был ли пользователь уже зарегистрирован на сервере, был ли пользователь уже зарегистрирован у вас как у партнера. Пример: "message": "User is already registered.New client."
auth_hash Уникальный hash (auth_hash), который возвращается только если в запросе был передан параметр auth_hash в extra_fields (более подробно см.здесь).

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

https://sailplay.ru/api/v2/users/add/?phone=79000000000&token=3187e3c727e6d94f04e54acae75b1de157f103b0&store_department_id=435&first_name=Виталий&last_name=Нестеров&middle_name=Сергеевич&birth_date=1987-09-03&sex=1&extra_fields=auth_hash

 

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

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

{
"status": "ok",
"phone": "79000000000",
"first_name": "Виталий",
"last_name": "Нестеров",
"middle_name": "Сергеевич",
"birth_date": "1987-09-03",
"origin_user_id": null,
"id": 487997,
"sex": 1
}

В случае неуспеха (пользователь уже зарегистрирован в системе и является клиентом):

{
"status": "error",
"message": "User is already registered.User is already client."
}

/api/v2/users/custom-vars/add/ - добавление переменной

Данный метод API используется для добавления не системных переменных. Подробнее о типах переменных и их применении можно узнать здесь. Все переменные обрабатываются сервером как строки.

При передаче в значении переменной длинной строки (например, HTML код) рекомендуется передавать параметр vars в POST части запроса.

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь. string
type=2
да

vars

Объект добавляемых пользователю переменных

Ключ: Название 

Значение: Данные переменной, существует два варианта подобной структуры -

  1. Строка, содержащая значение не системной переменной
  2. Объект не системной переменной, содержащий следующие данные:
    • Значение переменной

    • Название переменной, отображаемое в личном кабинете

JSON Object

Key: JSON String(1-70 символов)

Value:

  1. JSON String
  2. JSON Object
    • JSON String

    • JSON String(1-128 символов)
vars={
"param_name1":{"value":"value1","verbose":"param_name"},
"param_name2":"value"
}

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

https://sailplay.ru/api/v2/users/custom-vars/add/?user_phone=79000000000&token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435&vars={"param_name1":"value1","param_name2":"value2"}

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

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

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

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

JSON String
"status":"ok"
updated_count Количество не системных переменных, уже присутствующих у пользователя, которые поменяли свое значение в результате запроса. JSON Integer
"updated_count":2
created_count Количество не системных переменных, которые были добавлены пользователю в результате запроса. JSON Integer
"created_count":0
  • user
    • phone
    • origin_user_id
    • email
  • Объект, содержащий информацию о пользователе, обладающем данной переменной:
    • Телефон (если имеется, иначе - null)
    • Идентификатор пользователя (если имеется, иначе - null)
    • E-mail (если имеется, иначе - null)
  • JSON Object
    • JSON String
    • JSON String
    • JSON String
 "user":{
"phone":"71111111111",
"origin_user_id":"a1",
"email":null
 }

 

 

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

{
 "updated_count":2,
 "created_count":0,
 "status":"ok",
 "user":{
"phone":"79000000000",
"origin_user_id":null,
"email":null
 }
}

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

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

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

Неверный формат телефона, указанного в запросе

{
    "status": "error",
    "message": "Phone is not valid"
}

Неверный формат E-mail, указанного в запросе

{
    "status": "error",
    "message": "Invalid value of email"
}

Неверный формат объекта не системных переменных

{
     "status": "error",
     "status_code": -5105,
     "message": "vars must be json object, {\"var_name\": \"var_value\", ...}, max items = 20. name max length = 70, value max length = 255"
}

/api/v2/users/custom-vars/get/ - получение значния не системной переменной

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

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь. string
email=test@test.com
да name Название переменной, которая будет получено в результате исполнения запроса string(1-128 символов)
name=var1

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

https://sailplay.ru/api/v2/users/custom-vars/get/?user_phone=79000000000&token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435&name=visit_date

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

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

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

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

JSON String
"status":"ok"
name Название переменной, полученной в результате запроса JSON String
"name": "var1"
value Значение переменной по имени, указанному в запросе JSON Number
"value": "Var value"
  • user
    • phone
    • origin_user_id
    • email
  • Объект, содержащий информацию о пользователе, обладающем данной переменной:
    • Телефон (если имеется, иначе - null)
    • Идентификатор пользователя (если имеется, иначе - null)
    • E-mail (если имеется, иначе - null)
  • JSON Object
    • JSON String
    • JSON String
    • JSON String
 "user":{
"phone":"71111111111",
"origin_user_id":"a1",
"email":null
 }

 

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

{
 "status":"ok",
 "name":"html",
 "value":"03/05/2015",
 "user":{
"phone":"71111111111",
"origin_user_id":"a1",
"email":null
 }
}

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

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

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

Неверный формат телефона, указанного в запросе

{
    "status": "error",
    "message": "Phone is not valid"
}

Неверный формат E-mail, указанного в запросе

{
    "status": "error",
    "message": "Invalid value of email"
}


Указанный пользователь не обладает данной переменной

 {
     "status": "error",
     "status_code": -5111,
     "message": "Custom variable for user does not exist"
 }

/api/v2/users/custom-vars/get/batch/ - получение значния не системной переменной

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

Если у клиента не будет указанных переменных - они не будут возвращены в объекте "vars".

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь. string
email=test@test.com
да names Массив с названием переменных, по которым будут полученые значения в результате исполнения запроса JSON Object
names=["var1","var2"]

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

https://sailplay.ru//api/v2/users/custom-vars/get/batch/?user_phone=79000000000&token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435&names=["var1","var2"]

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

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

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

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

JSON String
"status":"ok"
name Название переменной, полученной в результате запроса JSON String
"name": "var1"
vars
  • Объект, содержащий информацию о значениях переменных для выбранного пользователя:
    • name (имя переменной)
    • value (значение переменной)

Информация возвращается только по тем переменным, значения которых указаны у выбранного клиента.

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

  • JSON Object
    • JSON Object
    • JSON Object
"vars": [{"name": "var1","value": "val1"},{"name": "var2","value": "val2"}]
  • user
    • phone
    • origin_user_id
    • email
  • Объект, содержащий информацию о пользователе, обладающем данной переменной:
    • Телефон (если имеется, иначе - null)
    • Идентификатор пользователя (если имеется, иначе - null)
    • E-mail (если имеется, иначе - null)
  • JSON Object
    • JSON String
    • JSON String
    • JSON String
 "user":{
"phone":"71111111111",
"origin_user_id":"a1",
"email":null
 }

 

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

{"status": "ok","user": {"phone": null,"origin_user_id": "test_user","email": "ivan@sailplay.ru"},"vars":[{"name": "var1","value": "val1"},{"name": "var2","value": "val2"}]}

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

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

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

Неверный формат телефона, указанного в запросе

{
    "status": "error",
    "message": "Phone is not valid"
}

Неверный формат E-mail, указанного в запросе

{
    "status": "error",
    "message": "Invalid value of email"
}

/api/v2/users/custom-vars/delete/ - удаление не системной переменной

Данный метод API используется для удаления конкретной не системной переменной у конкретного клиента. В случае, если клиент - последний обладатель данной переменной, переменная так же перестанет присутствовать в выводе запроса /api/v2/users/custom-vars/list/.

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь. string
email=test@test.com
да name Название переменной, которая будет удалена в результате исполнения запроса string(1-128 символов)
name=var1

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

https://sailplay.ru/api/v2/users/custom-vars/delete/?user_phone=79000000000&token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435&name=visit_date

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

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

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

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

JSON String
"status":"ok"
name Название переменной, полученной в результате запроса JSON String
"name": "var1"
values Значение переменной по имени, указанному в запросе, которое было удалено JSON Number
"value": "Var value"
  • user
    • phone
    • origin_user_id
    • email
  • Объект, содержащий информацию о пользователе, обладающем данной переменной:
    • Телефон (если имеется, иначе - null)
    • Идентификатор пользователя (если имеется, иначе - null)
    • E-mail (если имеется, иначе - null)
  • JSON Object
    • JSON String
    • JSON String
    • JSON String
 "user":{
"phone":"71111111111",
"origin_user_id":"a1",
"email":null
 }

 

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

{
 "status":"ok",
 "name":"html",
 "values":"03/05/2015",
 "user":{
"phone":"71111111111",
"origin_user_id":"a1",
"email":null
 }
}

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

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

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

Неверный формат телефона, указанного в запросе

{
    "status": "error",
    "message": "Phone is not valid"
}

Неверный формат E-mail, указанного в запросе

{
    "status": "error",
    "message": "Invalid value of email"
}


Указанный пользователь не обладает данной переменной

 {
     "status": "error",
     "status_code": -5111,
     "message": "Custom variable for user does not exist"
 }

/api/v2/users/custom-vars/list/ - получение списка не системных переменных партнера

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

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

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

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

http://sailplay.ru/api/v2/users/custom-vars/list/?token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435

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

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

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

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

JSON String
"status":"ok"
custom_vars Список названий переменных, используемых партнером

JSON Array

  • JSON String
"custom_vars": 
["var1", "var2", "var3"]

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

{"status": "ok", "custom_vars": ["var1", "var2", "var3"]}

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

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

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

/api/v2/users/info/ - информация о клиенте

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

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
нет history Для получения истории начислений и списаний бонусных баллов клиента значение параметр должно равляться 1 (history=1)
нет subscriptions Для получения статуса подписок клиента (email или sms) необходимо передавать со значением 1. По умолчанию обрабатывается как 0. В JSON ответ будет добавлен соответствующий массив.
нет extra_fields Дополнительные поля, которые будут в JSON ответе. Дополнительные поля перечисляются через запятую и могут принимать следующие значения: auth_hash. Пример: &extra_fields=auth_hash

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

Название параметра Описание параметра
category Категория пользователя (если есть, см.здесь).
status Статус ответа.
origin_user_id Идентификатор клента в системе партнера
last_name Фамилия
middle_name Отчество
first_name Имя
sex Пол (1-М, 2-Ж)
phone Номер телефона клиента
points

Массив сводных данных о баллах клиента:

-confirmed - начисленные и подтвержденные

-unconfirmed - начсленные не подтвержденные

-spent - сумма потраченных клиентом баллов

-total - сумма всех начисленных баллов (подтвержденных и не подтвержденных)

email Электронная почта клиента
birth_date Дата рождения в формате гггг-мм-дд
id Идентификатор клиента в нашей системе.
user_points Количество бонусных баллов, доступных данному пользователю
message Текстовый ответ сервера. Состоит из двух частей: был ли пользователь уже зарегистрирован на сервере, был ли пользователь уже зарегистрирован у вас как у партнера. Пример: "message": "User is already registered.New client.
media_url Префикс для формирования URI адресов изображений подарков
available_gifts Массив доступных подарков пользователю
over_user_points_gifts Массив пока недоступных пользователю подарков
auth_hash Уникальный hash, который возвращается только если в запросе был передан параметр auth_hash в extra_fields (более подробно см.здесь).
history Объект с инфорацией о всех действиях пользователя (список покупок, список получений подарков и т.д.).
subscriptions Массив подписок клиента (email или sms).

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

https://sailplay.ru/api/v2/users/info/?user_phone=79223260840&token=6b186c1072e1670a93fa8d20bd605193c890a587&store_department_id=1&history=1&extra_fields=auth_hash&subscriptions=1

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

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

{"category":null,
"status":"ok",
"origin_user_id":null,
"last_name":"Нестеров",
"middle_name":"Сергеевич",
"first_name":"Виталий",
"sex":1,
"phone":"79223260848",
points: {
spent_extra: 20,# все списанные, и потраченные баллы в покупку
confirmed: 0,# все подтвержденные баллы на балансе
total: 0, # Величина транзакции в баллах подтвержденных + неподтвержденных
spent: 1, # Потраченных на подарки
unconfirmed: 0 # Сколько сейчас у клиента неподтвержденных бонусов
},
avatar: null,
email: "gmail@gmail.com",
auth_hash: "6395f07c34cf8dcbcfb07c85431cdc02222f7cf8",
birth_date: null,
id: 129144346,
history: [
{
action: "extra",# Тип транзакции
action_date: "2020-10-21T15:10:22.665",# Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: -13, # Величина транзакции в баллах
name: "триггер списание всех баллов"# Комментарий транзакции
},
{
action: "extra",# Тип транзакции
action_date: "2020-10-21T15:07:58.899",# Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: -1,# Величина транзакции в баллах
name: "триггер списание части баллов" # Комментарий транзакции
},
{
action: "expiration", # Тип транзакции
action_date: "2020-10-21T15:04:58.250",# Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: -1,# Величина транзакции в баллах
name: "Списание неиспользованных бонусов от "Начисление баллов (триггер с начислением с ограничением)""# Комментарий транзакции
},
{
name: "триггер с начислением с ограничением", # Комментарий транзакции
is_completed: true,# Статус состояния баллов
expiry_info: [{"points_expirable_remain": 200, "expire_date": "2020-11-22T15:40:58.454"}],
action_date: "2020-10-21T15:01:18.834",# Дата начисления
action: "extra",# Тип транзакции
points_delta: 1 # Величина транзакции в баллах
},
{
action: "extra",# Тип транзакции
action_date: "2020-10-21T14:59:42.454",# Дата начисления
is_completed: true, # Статус состояния баллов
points_delta: 1,# Величина транзакции в баллах
name: "триггер начисление без ограничения"# Комментарий транзакции
},
###
{# выдача подарка
name: "test", # Комментарий транзакции
is_completed: true,# Статус состояния баллов
pic: "//sailplays3.cdnvideo.ru/media/gifts/gift/0df8163798faba66dd10e3b8c7607d33.100x100.jpg",# Изображение подарка
action_date: "2020-10-21T14:54:01.242",# Дата начисления
coupon_number: null, # номер купона, связанный с подарком
action: "gift_purchase",# Тип транзакции
points_delta: -1 Величина транзакции в баллах списания
},
{#баллы в покупке
order_num: "add_and_spent_points_test_noconf",# Номер покупки
action_date: "2020-10-21T14:51:49.656",# Дата начисления
name: "Покупка",# Комментарий транзакции
debited_points_delta: 1,# Величина транзакции в баллах списания
action: "purchase",# Тип транзакции
is_completed: true,# Статус состояния начисленных за покупку баллов
store_department_id: 3489,# id отдела покупки
price: 79, # Сумма покупки
points_delta: 7,# Величина транзакции в баллах начисленных за покупку
id: 488528428 # id покупки
},
{#баллы в покупке
order_num: "add_and_spent_points_test_conf",# Номер покупки
action_date: "2020-10-21T14:50:43.579", # Дата начисления
name: "Покупка", # Комментарий транзакции
debited_points_delta: 1,# Величина транзакции в баллах списания
action: "purchase",# Тип транзакции
is_completed: true,# Статус состояния баллов
store_department_id: 3489,# id отдела покупки
price: 79,# Стоимость покупки
points_delta: 7,# Величина транзакции в баллах начисления
id: 488528206 # id покупки
},
{#простое начисление
action: "extra",# Тип транзакции
action_date: "2020-10-21T14:50:34.761", # Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: 2,# Величина транзакции в баллах
name: "простое"# Комментарий транзакции
},
{# перенос баллов между пользователями
user_id: 130344896,# user_id получателя или передающего
name: "Перевод баллов на счёт [[user]] с комментарием "передача"", # Комментарий транзакции
is_completed: true,# Статус состояния баллов
action_date: "2020-10-21T14:48:33.089", # Дата начисления
action: "points_transfer",# Тип транзакции
user_name: "ТЕСТОВЫЙ",# Имя получатели или отправителя
points_delta: -1# Величина транзакции в баллах
},
{# простое начисление
name: "простое", # Комментарий транзакции
is_completed: true, # Статус состояния баллов
expiry_info: [ ],
action_date: "2020-10-21T14:48:03.205",# Дата начисления
action: "extra", # Тип транзакции
points_delta: 1 # Величина транзакции в баллах
},
{# полное списание баллов с баланса
action: "extra", # Тип транзакции
action_date: "2020-10-21T14:47:36.167",# Дата начисления
is_completed: true, # Статус состояния баллов
points_delta: -1, # Величина транзакции в баллах
name: "списание полностью" # Комментарий транзакции
},
{# простое списание баллов
action: "extra", # Тип транзакции
action_date: "2020-10-21T14:47:20.408", # Дата начисления
is_completed: true, # Статус состояния баллов
points_delta: -1, # Величина транзакции в баллах
name: "списание простое" # Комментарий транзакции
},
{# начисление баллов со сгоранием в будущем
name: "со сгоранием", # Комментарий транзакции
is_completed: true, # Статус состояния баллов
expiry_info: [ ],
action_date: "2020-10-21T14:47:04.300", # Дата начисления
action: "extra", # Тип транзакции
points_delta: 1 # Величина транзакции в баллах
},
{# простое начисление баллов
action: "extra", # Тип транзакции
action_date: "2020-10-21T14:46:31.824",# Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: 1,# Величина транзакции в баллах
name: "простой" # Комментарий транзакции
},
{
action: "registration",# Тип транзакции
action_date: "2020-10-10T18:13:24.758",# Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: 100,# Величина транзакции в баллах
name: "Баллы за регистрацию"# Комментарий транзакции
},
{
action: "badge",# Тип транзакции
action_date: "2020-10-10T18:14:12.160",# Дата начисления
pic: "//sailplays3.cdnvideo.ru/media/badges/badge/d1387fdb435b01a5a291d3a49b5d3a16.100x100.png",#Изображение бейджика
is_completed: true,# Статус состояния баллов
points_delta: 100,# Величина транзакции в баллах
name: "Игрок"# Название бейджа
},
{action: "manual_change_referred",# Тип транзакции
user_name: "a a a", # Имя пригласившего
action_date: "2020-10-21T16:57:34.556",# Дата начисления
user_id: 156616158,# user_id пригласившего
name: "За приглашение друга"# Комментарий транзакции
is_completed: true,# Статус состояния баллов
points_delta: 1,# Величина транзакции в баллах
},
{action: "referral",# Тип транзакции
action_date: "2020-10-21T16:57:34.561",# Дата начисления
is_completed: true,# Статус состояния баллов
points_delta: 1,# Величина транзакции в баллах
name: "За регистрацию по приглашению"# Комментарий транзакции
},
{action: "manual_change_referrer",# Тип транзакции
user_name: "ТЕСТОВЫЙ1", # Имя приглашенного
action_date: "2020-10-21T16:57:34.556",# Дата начисления
user_id: 129013483,# user_id приглашенного
name: "Покупка приглашенного"# Комментарий транзакции
},
]
}
{
"status":"error",
"message":"User does not exist."
}

     action

     Описание действия

extra

ручные и триггерные начисления

points_transfer

передача баллов между пользователями

purchase

покупка

gift_purchase

выдача подарка

expiration

списание сгораемых баллов из триггера

registration

регистрация в программе лояльности

badge

бейджик, за действия на сайте

manual_change_referred

баллы за приглашение

referral

баллы за регистрацию приглашенного

manual_change_referrer

баллы за покупку приглашенного

 

 

/api/v2/users/merge/ - объединение клиентов

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

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

 

Параметр обязательный? Имя параметра Описание параметра
да from_phone, from_email или from_oid Идентификатор клиента, данные которого будут перенесены. После переноса этот клиент будет удален.
да token см. здесь
да store_department_id см. здесь
да to_phone,to_email илиto_oid Идентификатор клиента, которому будут добавлены данные второго клиента.

Пример объединения с использование параметров from_phone и to_phone

Запрос:

https://sailplay.ru/api/v2/users/merge/?from_phone=71111111111&token=024e3bfbe50c8ef3d413caf19bf5380bbdd79df3&store_department_id=435&to_phone=72222222222

Ответ:

{
 "status":"ok",
 "phone":"72222222222",
 "origin_user_id":null,
 "email":null
}

Рассмотрим пример с двумя пользователями, данные о которых представлены в таблице:

Имя Фамилия origin_user_id phone email
AAA BBB 123456789 +79123456789 aaa@yandex.ru
CCC DDD 000000001 +79010000001 ccc@gmail.com

 

Существует 9 вариантов объединения через этот метод. Важно учитывать, что, несмотря на одинаковый результат, различаются значения параметров в запросе.

Параметр 1 Параметр 2 Запрос Результат: Имя и Фамилия Результат: origin_user_id Результат: phone Результат: email
from_phone to_phone

/api/v2/users/merge/?from_phone=79123456789&token=*

&store_department_id=435&to_phone=79010000001

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_phone to_oid

/api/v2/users/merge/?from_phone=79123456789&token=*

&store_department_id=435&to_oid=000000001

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_phone to_email

/api/v2/users/merge/?from_phone=79123456789&token=*

&store_department_id=435&to_email=ccc@gmail.com

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_oid to_oid

/api/v2/users/merge/?from_oid=123456789&token=*

&store_department_id=435&to_oid=000000001

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_oid to_phone

/api/v2/users/merge/?from_oid=123456789&token=*

&store_department_id=435&to_phone=79010000001

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_oid to_email

/api/v2/users/merge/?from_oid=123456789&token=*

&store_department_id=435&to_email=ccc@gmail.com

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_email to_email

/api/v2/users/merge/?from_email=aaa@yandex.ru&token=*

&store_department_id=435&to_email=ccc@gmail.com

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_email to_oid

/api/v2/users/merge/?from_email=aaa@yandex.ru&token=*

&store_department_id=435&to_oid=000000001

AAA BBB 123456789 +79010000001 ccc@gmail.com
from_email to_phone

/api/v2/users/merge/?from_email=aaa@yandex.ru&token=*

&store_department_id=435&to_phone=79010000001

AAA BBB 123456789 +79010000001 ccc@gmail.com

/api/v2/users/sms-code/ - отправка смс сообщения клиенту

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

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

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

  1. На сервере SailPlay генерируется уникальный код

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

  3. В ответе на запрос
Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
нет text Кастомный текст сообщения. Если он не указан, используется текст по умолчанию.
нет priority Канал передачи сообщения. 1 - быстрый канал, 2 - обычный

Пример сообщение без кода

Запрос:

https://sailplay.ru/api/v2/users/sms-code/?phone=79000000000&token=6b186c1072e1670a93fa8d20bd605193c890a587&store_department_id=171&text=Пример
сообщения без кода

Ответ:

{
 "status":"ok",
 "sms_code":"7568"
}

SMS:

Пример сообщения без кода

 

Пример сообщение с кодом

Запрос:

https://sailplay.ru/api/v2/users/sms-code/?phone=79000000000&token=6b186c1072e1670a93fa8d20bd605193c890a587&store_department_id=171&text=Пример
сообщения с кодом. Код-$[sms_code]

Ответ:

{
 "status":"ok",
 "sms_code":"2172"
}

SMS:

Пример сообщения с кодом. Код-2172

Пример сообщение с тектом по умолчанию

Запрос:

https://sailplay.ru/api/v2/users/sms-code/?phone=79000000000&token=6b186c1072e1670a93fa8d20bd605193c890a587&store_department_id=171

Ответ:

{
 "status":"ok",
 "sms_code":"3082"
}

SMS:

Код для списания бонусов3082

 

/api/v2/users/sync-social/ - сбор данных через соцсети

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

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

Прежде чем использовать метод необходимо передатьSailPlay авторизационные данные приложений соцсетей . Сделать это можно через вашего менеджера или просто описав желаемую логику работы с данными из соцсетей в письме на support@sailplay.ru.

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

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

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
да type Идентификатор соцсети из которой будут получены данные. Может принимать значение vk, fb, ok.
да account_id Идентификатор клиента в соцсети, из которой будут получены данные.
да access_token Авторизационный токен клиента в соцсети. Методы получения этого токена уточните в документации к соцсети.
да session_secret_key Дополнительный токен авторизации клиента в сети Одноклассники. Для работы с другими соцсетями не требуется.

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

https://sailplay.ru/api/v2/users/sync-social?type=fb&access_token=CAALZCNDiO1tkBAF2QG46ealvQH2K0x54nKFQDtAofbLrNBEMoKhbtygUjhiwdUR2tKxLWbB5zC4iDFmzT6xrQGb0XZAWtgTCD4oamA1ZAZAWZAEiFZBjBj4uwyhcWMtcDXbuoX7xZB5BNFHPMSS8dHUVcS8z6EcoRflqim8F413Jn9UWngpDd1zimRrSA1V618ZCd2sMpZAYyUpwiXBNUyYMWfZASBZCDd7yxwZD&phone=79999999945&account_id=2679591&store_department_id=219&token=024e5bfbe50c8ef3d413caf19bf5380bbdd79df3

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

{"status": "ok"}

/api/v2/users/tags/add/ - добавление тега

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
да tags перечисленные через запятую присваиваемые теги.

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

https://sailplay.ru/api/v2/users/tags/add/?user_phone=79251276112&token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435&tags=Регистрация,A/B-тест#11,A/B-тест #11 вар. А

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

{
 "status":"ok",
 "added_tags_count":3
}

/api/v2/users/tags/delete/ - удаление тега

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
да tags перечисленные через запятую удаляемые теги.

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

https://sailplay.ru/api/v2/users/tags/delete/?phone=79000000000&token=024e3bfbe50c8ef3d413caf19bf5380bbdd79df3&store_department_id=219&tags=mytag

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

{
 "status":"ok",
 "deleted_count":1
}

/api/v2/users/tags/list/ -список присвоенных клиенту тегов

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
нет tags Дополнительные поля, которые будут в JSON ответе. Дополнительные поля перечисляются через запятую. Данный параметр нужен, чтобы выбрать определенные теги из общего списка. Пример: tags=['Покупка', 'Регистрация', 'Отзыв']

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

https://sailplay.ru/api/v2/users/tags/list/?store_department_id=219&token=024e3bfbe50c8ef3d413caf19bf5380bbdd79df3&origin_user_id=origin1

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

{
 "status":"ok",
 "events":[
{
 "update_date":"2014-07-07T14:50:38",
 "kind":"flag",
 "create_date":"2014-07-07T14:50:38",
 "name":"Tagging",
 "is_chains_event":true,
 "sender_name":null,
 "is_campaigns_event":true,
 "sender_templates_vars_help":null,
 "key":"62b80a71ddb37f22d5929e22312438c81024e7b1",
 "group":4,
 "is_future":false,
 "id":10000866
}
 ]
}

/api/v2/users/update/ - изменение данных клиента

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

Метод позволяет дополнить или изменить информацию о пользователе.

Параметры, указанные в методе будут перезаписаны, остальыне будут оставлены без изменений.

Чтобы удалить значение параметра у пользователя нужно отпарвить в значении параметра null.

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

Будте осторожны в использовании этих параметров! Если к e-mail или телефону, указанным в этих параметрах привязан пользователь, то история покупок и начислений будет утеряна.

Чтобы объединить истории несколькоих пользователей используйте метод /api/v2/users/merge/

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
нет user_category_name Категория пользователя. Подробнее см.здесь.
нет first_name Имя
нет last_name Фамилия
нет middle_name Отчество
нет birth_date Дата рождения в формате гггг-мм-дд. Минимальное значение года – 1900. Максимальное - текущий год. Если передан год меньше минимального, то значение года автоматически будет установлено в 1900. Если год больше текущего - будет установлен текущий год. При этом месяц и день рождения будут соотвествовать переданному параметру.
нет sex Пол. 1 - мужской, 2 - женский.
нет add_phone Если у клиента не указан телефон, привязывает переданный номер. Выдает ошибку, если телефон имеет неверный формат, клиент уже указал телефон или переданный номер привязан к другому клиенту.
нет add_email Если у клиента не указан адрес электронной почты, привязывает переданный адрес. Выдает ошибку, если адрес имеет неверный формат, клиент уже указал адрес или указанный адрес привязан к другому клиенту.
нет new_phone Контактный телефонклиента, которому будет перепривязана история. Нельзя передавать вместе с параметром new_email.
нет new_email E-mail адрес клиента, которому будет перепривязана история. Нельзя передавать вместе с параметром new_phone.
нет extra_fields Дополнительные поля, которые будут в JSON ответе. Дополнительные поля перечисляются через запятую и могут принимать следующие значения: auth_hash. Пример: &extra_fields=auth_hash
нет referrer_origin_user_id, referrer_phone или referrer_email= Позволяет установвить реферальную связь между редактируемой записью клиента (приглашенный) и какой-либо созданной ранее (пригласивший). Если referrer_* запись не обнаружена - новая запись клиента без изменена без установки реферальной связи.

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

Название параметра Описание параметра
status  
message Текстовый ответ сервера. Состоит из двух частей: был ли пользователь уже зарегистрирован на сервере, был ли пользователь уже зарегистрирован у вас как у партнера. Пример: "message": "User is already registered.New client."
complete_date Уникальный hash (auth_hash), который возвращается только если в запросе был передан параметр auth_hash в extra_fields (более подробно см.здесь).

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

https://sailplay.ru/api/v2/users/update/?phone=79000000000&token=3187e3c727e6d94f04e54acae75b1de157f103b0&store_department_id=435&first_name=Виталий&last_name=Нестеров&middle_name=Сергеевич&birth_date=1987-09-03&sex=1&extra_fields=auth_hash

 

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

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

{
"status": "ok",
"phone": "79251276676",
"first_name": "Виталий",
"last_name": "Нестеров",
"middle_name": "Сергеевич",
"birth_date": "1987-09-03",
"origin_user_id": null,
"id": 487997,
"sex": 1
}

/api/v2/users/unsubscribe/ - отписка клиента от рассылки

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

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
да unsubscribe_list список рассылок. от которых следует отписать клиента, через запятую

Возможные значения unsubscribe_list

  • email_all- все цепочки и рассылки, отправляемые по почте, за исключением цепочек, необходимых для совершения покупки или для получения подарка
  • sms_all- все цепочки и рассылки, отправляемые по sms, за исключением цепочек, необходимых для совершения покупки и получения подарка.

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

https://sailplay.ru/api/v2/users/unsubscribe/?user_phone=79000000000&token=6b186c1072e1670a93fa8d20bd605193c890a587&store_department_id=1&unsubscribe_list=email_all,sms_all

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

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

{
 "status":"ok",
 "user":{
"phone":"79000000000",
"origin_user_id":null,
"email":null
 },
 "unsubscribed":[
"email_all",
"sms_all"
 ]
}

/api/v2/users/subscribe/ - подписка клиента на рассылки

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

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

Параметр обязательный? Имя параметра Описание параметра
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь.
да token см. здесь
да store_department_id см. здесь
да subscribe_list список рассылок, на которые следует подписать клиента, через запятую

Возможные значения subscribe_list

  • email_all- все цепочки и рассылки, отправляемые по почте, за исключением цепочек, необходимых для совершения покупки или для получения подарка
  • sms_all- все цепочки и рассылки, отправляемые по sms, за исключением цепочек, необходимых для совершения покупки и получения подарка.

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

https://sailplay.ru/api/v2/users/subscribe/?user_phone=79000000000&token=6b186c1072e1670a93fa8d20bd605193c890a587&store_department_id=1&subscribe_list=email_all,sms_all

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

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

{
"status": "ok",
"user": {
"phone": "79000000000",
"origin_user_id": null,
"email": null
},
"subscribed": [
"email_all",
"sms_all"
]
}

/api/v2/users/update-feed/ - Получение списка пользователей с изменениями в профиле

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

Данный метод позволяет получить список последних изменений в записях клиентов за выбранный период. Период не может превышать 5 дней.

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

Параметр обязательный? Имя параметра Описание параметра
да token см. здесь
да store_department_id см. здесь
да datetime_from Начальная дата периода
нет datetime_to Дата конца преиода.Если не указан - устанавливается дата из datetime_from + 5 дней.

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

Название параметра Описание параметра
status Статус ответа.
datetime_from Начальная дата периода из запроса
datetime_to Дата конца периода из запроса
result Возвращает массивы данных “user_data” и “actions”
user_data Возвращает текущую информацию о покупателе (включая измененные)
actions Возвращает дату последнего изменения и его тип

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

https://sailplay.ru/api/v2/users/update-feed/?token=264bdf78f8479a243e23fdf798ee84086d832a64&store_department_id=1596&datetime_from=2015-02-10&datetime_to=2015-02-14

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

 

{
 "status":"ok",
 "datetime_to":"2015-02-14T00:00:00",
 "datetime_from":"2015-02-10T00:00:00",
 "result":{
"user_data":{
 "origin_user_id":null,
 "first_name":"Vasiliy",
 "middle_name":null,
 "user_data_updated":"2015-02-13T10:49:52",
 "vk_id":null,
 "sex":null,
 "phone":"70000055555",
 "last_name":"Pupkin",
 "facebook_id":null,
 "birth_date":null,
 "email":null
},
"actions":[
 {
"action_date":"2015-02-13T10:49:52",
"type":"user_data_change"
 }
]
 }
}

/api/v2/users/email-registration/complete/ - подтверждение регистрации

Данный метод API используется для автоматизации подтверждения регистрации пользователя. При регистрации пользователя через форму авторизации SailPlay, при обычном процессе регистрация считается завершенной в момент, когда пользователь подтвердил свой E-mail перейдя по ссылке в письме после регистрации, либо введя код из соответствующего E-mail/SMS в окне авторизации. В случае, если данные коммуникационные цепочки отключены, либо требуется подтвердить регистрацию со стороны партнера, следует использовать данный метод.

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

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да user_phone, email или origin_user_id Идентификатор клиента. Более подробно см.здесь. string
email=test@test.com

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

https://sailplay.ru/api/v2/users/email-registration/complete?email=test@test.com&token=b3c7ac443b9b93bf4daa20f5429a655b5f77bb4b&store_department_id=435

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

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

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

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

JSON String
"status":"ok"
warnings

Объект, содержащий объекты предупреждений. Предупреждения предоставляют дополнительную информацию при успешном исполнении запроса. Объект не будет возвращен в случае, если предупреждений при обработке запроса не возникло. Доступны следующие предупреждения:

  • user_already_registered - возвращается при попытке подтверждения уже зарегистрированного пользователя
JSON Object
warnings: { "user_already_registered" : "true" }

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

{"wargins": {"user_already_registered": true}, "status": "ok"}

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

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

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

Неверный формат телефона, указанного в запросе

{
    "status": "error",
    "message": "Phone is not valid"
}

Неверный формат E-mail, указанного в запросе

{
    "status": "error",
    "message": "Invalid value of email"
}


Указанный пользователь не подавал запрос на регистрацию

 {
     "status": "error",
     "message": "User is not autorized"
 }