Методы

Промокоды

В SailPlay реализован механизм промо-кодов для использования в рассылках, при совершении покупок, или для выполнения настраиваемых действий. Промо-коды делятся на два типа - простые и активационные, сценарий использования зависит от конкретного типа промо-кода.

Простые промо-коды

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

Активационные промо-коды

Активационные промо-коды используются в рассылках, а также позволяют реализовать настраиваимые действия при помощи механизма триггерных цепочек. Промо-коды загружаются в аккаунт партнера при помощи интерфейса SPanel. После завершения загрузки промо-коды из созданной группы возможно передать пользователям при помощи динамического параметра в рассылках. Выданный промо-код может быть применен для конкретного пользователя при помощи метода активации, либо через интерфейс SPanel. При активации промо-кода, пользователь получает тег "Использовал промокод [Название промо-кода]", который может вызывать триггерную цепочку для выполнения специальных действий.

Подарочные сертификаты

Подарочные сертификаты позволяют создавать группы сертификатов с разбивкой по магазинам и номиналу для последующей продажи этих сертификатов и их отоваривания (оплаты покупки или части покупки сертификатом). Основной бизнес-кейс — продажа сертификатов для их передачи в качестве подарка.

Состояния сертификатов

В течение цикла жизни сертификат меняет несколько состояний, каждое из которых является необратимым:

  • Созданный сертификат. Состояние сертификата, которое говорит о факте его наличия. Сертификат имеющий данное состояние невозможно использовать как средство оплаты в покупке.
  • Активированный сертификат. Данное состояние подразумевает, что сертификат был продан и может использован в покупке как средство оплаты.
  • Отоваренный (использованный) сертификат. Финальное состояние сертификата, которое говорит о том, что он был использован в покупке как средство оплаты.

Атрибуты сертификатов

Сертификат имеет несколько атрибутов/признаков:

  • Активация – был активирован сертификат или нет.
  • Использование – был отоварен (использован) сертификат в покупке или нет.
  • Группа – название группы, к которой принадлежит сертификат. Принимая во внимание то, что в одной загрузке может быть множество сертификатов, то даже при создании одного сертификата он будет иметь принадлежность к группе.
  • Отдел – отдел, к которому принадлежит сертификат. Указание принадлежности сертификата к тому или иному отделу обязательно. Логика работы сертификатов подразумевает то, что сертификат создается для конкретного отдела. Вследствие чего активация и использование сертификата доступны только в том отделе, для которого он был создан.
  • Номинал – денежный эквивалент сертификата. То есть, если номинал сертификата равен 5 000 рублей, то им можно оплатить покупку суммой <= 5 000 рублей.

/api/v2/promocodes/groups/list/ - Получение списка промо-кодов

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

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

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

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

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

https://sailplay.ru/api/v2/promocodes/groups/list/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9

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

Параметр (ключ)ОписаниеТип данныхПример
status статус запроса JSON String
"status":"ok"
  • groups
    • disabled
    • enabled
      • create_date
      • reserved_count
      • apply_items_once
      • receipted_count
      • applied_count
      • unused_count
      • id
      • update_date
      • name
      • total_count
      • group_type
  • Объект групп промо-кодов, включающий в себя следующие данные:
    • Массив,  содержащий в себе объекты отключенных в данный момент групп. Структуру объекта см. ниже.
    • Массив, содержащий в себе объекты включенных в данный момент групп. Содержимое объекта группы:
      • дата создания группы промо-кодов.
      • количество промо-кодов данной группы, доступное для выдачи.
      • уникальность промо-кодов данной группы.
      • количество выданных промо-кодов данной группы.
      • количество промо-кодов данной группы, примененное к покупке.
      • количество неиспользованных промо-кодов данной группы.
      • id группы в системе партнера.
      • дата обновления группы промо-кодов.
      • название данной группы промо-кодов.
      • общее количество промо-кодов, созданных в данной группе.
      • тип промо-кодов данной группы, принимает значение "1", если промо-коды в группе - простые, и "2" - если промо-коды в данной группе - активационные.
  • JSON Object
    • JSON Array
      • JSON Object
        • JSON String
        • JSON Number
        • JSON Boolean
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON String
        • JSON String
        • JSON Number
        • JSON Number
    • JSON Array
      • JSON Object
        • JSON String
        • JSON Number
        • JSON Boolean
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON Number
        • JSON String
        • JSON String
        • JSON Number
        • JSON Number
	"groups": {
	  "disabled": [],
	  "enabled": [
	  {
	    "create_date": "2016-09-29T23:14:50",
	    "reserved_count": 62,
	    "apply_items_once": true,
	    "receipted_count": 38,
	    "applied_count": 0,
	    "unused_count": 62,
	    "id": 470,
	    "update_date": "2016-09-29T23:14:50",
	    "name": "$5 voucher",
	    "total_count": 100,
	    "group_type": 2
	  },
	  {
	    "create_date": "2016-10-04T23:42:22",
	    "reserved_count": 79,
	    "apply_items_once": true,
	    "receipted_count": 21,
	    "applied_count": 0,
	    "unused_count": 79,
	    "id": 492,
	    "update_date": "2016-10-04T23:42:22",
	    "name": "$100 voucher",
	    "total_count": 100,
	    "group_type": 2
	  }
	  ]
	  }

placeholderplaceholderplacehold

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

{
	  "status": "ok",
	  "groups": {
	  "disabled": [],
	  "enabled": [
	  {
	    "create_date": "2016-09-29T23:14:50",
	    "reserved_count": 62,
	    "apply_items_once": true,
	    "receipted_count": 38,
	    "applied_count": 0,
	    "unused_count": 62,
	    "id": 470,
	    "update_date": "2016-09-29T23:14:50",
	    "name": "$5 voucher",
	    "total_count": 100,
	    "group_type": 2
	  },
	  {
	    "create_date": "2016-10-04T23:42:22",
	    "reserved_count": 79,
	    "apply_items_once": true,
	    "receipted_count": 21,
	    "applied_count": 0,
	    "unused_count": 79,
	    "id": 492,
	    "update_date": "2016-10-04T23:42:22",
	    "name": "$100 voucher",
	    "total_count": 100,
	    "group_type": 2
	  }
	  ]
	  }
}	 

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

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

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

/api/v2/promocodes/info/ - Получение информации о промо-коде

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

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

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да number Непосредственный номер промо-кода string (1-128 символов)
PROMO15

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

https://sailplay.ru/api/v2/promocodes/info/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=yfubf_mm400

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

Параметр (ключ)ОписаниеТип данныхПример
status статус запроса JSON String
"status":"ok"
  • numbers
    • applied_times
    • can_be_applied
    • group
      • apply_items_once
      • enabled
      • id
      • name
    • number
    • is_published
  • Массив, содержащий в себе объекты промо-кодов, найденные по номеру у данного партнера. Содержимое объекта промо-кода:
    • Количество раз, которое данный промо-код был применен к покупке.
    • Доступность данного промо-кода для применения к покупке.
    • Объект группы, к которой относится данный промо-код. Содержимое объекта группы:
      • уникальность промо-кодов данной группы.
      • флаг, хранящий информацию о том, включена ли в данный момент данная группа.
      • id группы в системе партнера.
      • название данной группы промо-кодов
    • Номер данного промо-кода.
    • Флаг, хранящий информацию о том, был ли выдан данный промо-код.
  • JSON Array
    • JSON Object
      • JSON Number
      • JSON Boolean
      • JSON Object
        • JSON Boolean
        • JSON Boolean
        • JSON Number
        • JSON String
      • JSON String
      • JSON Boolean
"numbers": [
	  {
	  "applied_times": 0,
	  "can_be_applied": true,
	  "group": {
	  "apply_items_once": true,
	  "enabled": true,
	  "id": 498,
	  "name": "$400 voucher"
	  },
	  "number": "yfubf_mm400",
	  "is_published": false
	  }
	  ]

placeholderplaceholderplacehold

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

{
	  "status": "ok",
	  "numbers": [
	  {
	  "applied_times": 0,
	  "can_be_applied": true,
	  "group": {
	  "apply_items_once": true,
	  "enabled": true,
	  "id": 498,
	  "name": "$400 voucher"
	  },
	  "number": "yfubf_mm400",
	  "is_published": false
	  }
	  ]
}

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

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

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

промо-код по данному номеру не найден для данного партнера.

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

placeholderplaceholderplacehold

/api/v2/promocodes/activate/ - Активация промо-кода

Данный метод API позволяет активировать указанный промо-код для указанного клиента. Данный метод работает только с промо-кодами с типом "активационный".

При успешном выполнении метода, пользователь получит тег "Использовал промокод [название промо-кода]".

Метод используется, например, в момент активации промо-кода пользователем на сайте партнера. Метод активирует промо-код (и запретит повторное использование, если промо-код одноразовый), а также запустит соответствующие триггерные цепочки, если они установлены в настройках партнера.

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

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

user_phone, email или origin_user_id

Идентификатор клиента. Более подробно см. здесь.

string

user_phone=79001234567
да group_name Название группы промо-кодов, которое было указано при их создании string (1-128 символов)
group_name=PROMO50
да number Непосредственный номер проко-кода для активации string (1-128 символов)
number=xyzt_2938

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

https://sailplay.ru/api/v2/promocodes/activate?&store_department_id=111&token=da32f321d2516c8e56142f2430bea4f72a80a6ae&phone=79251276676&group_name=PROMO25&number=NJ23Z

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

Параметр (ключ)ОписаниеТип данныхПример
status Статус запроса JSON String
"status":"ok"

promocode_status

Статус конкретного промо-кода. Принимает следующие значения:

1 - код доступен для распространения,

2 - код выслан пользователю (пользователь уведомлен о его существоовании),

3 - код участвует в условии хотя бы одной акции, применённой хотя бы к одной совершённой покупке

JSON Number

"promocode_status": 2

placeholderplaceholderplacehold

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

{
"status": "ok",
"promocode_status": 2
}

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

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

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

промо-код по данному номеру не найден для данного партнера

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

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

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

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

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

Пользователь не найден в системе партнера

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

/api/v2/promocodes/coupons/numbers/add - Создание сертификатов

Метод используется для создаения новых групп сертификатов. HTTP-метод: POST

Подготовка

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

  • .txt
  • .csv
  • .xls
  • .xlsx

При использовании .txt и .csv формата каждый номер сертификата должен будет указан с новой строки. В случае использования .xls или .xlsx формата номера должны быть указаны в одной колонке, где в каждой ячейке присутствует один номер сертификата.

Формат сертификата

  • Тип: строка
  • Ограничение по длине: от 2 до 255 символов
  • Кодировка: UTF-8
  • Допустимые символы: буквы из включенных в юникод алфавитов, цифры, знаки пунктуации, спецсимволы. Рекомендуется использование сочетаний цифр и/или букв.
  • Уникальность: номер сертификата должен быть строго уникальным

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345
да type Системный параметр SailPlay. Всегда должен иметь занчение 2 integer
type=2
да value Номинал сертификата integer
value=5000
да name Название группы сертификатов string
name=Новогодние сертификат на 5000 рублей
да target_dep_id Отдел, которому будут принадлежать сертификаты integer
target_dep_id=3487
да pin_code Пин-код приложения integer
pin_code=4455

Тело запроса

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да file файл с номерами сертификатов File

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

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

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

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

JSON String
"status":"ok"
status_code Цифровой идентификатор статуса. Параметр появляется только в случае возникновения ошибки в запросе JSON Number
"status_code": -4201
message Содержит описание ошибки в случае ее возникновения. JSON String
"message": "Invalid file"

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

{
"status":"ok"
}

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

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

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

Неподдерживаемый формат файла или файл отствует

{
    "status": "error",
    "status_code": -4201,
    "message": "Invalid file"
}

Не передан обязательный параметр запроса

{
    "status": "error",
    "status_code": -1000,
    "message": "Provide required {'field': 'name'}"
}

/api/v2/promocodes/coupons/groups/list/ - Список сертификатов

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

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

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

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

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

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

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

JSON String
"status":"ok"
  • groups
    • create_date
    • name
    • total_count
    • used_count
    • activated_count
    • id
  • Массив, содержащий следующую информацию по каждой группе сертификатов:
    • дата создания группы
    • название группы
    • кол-во сертификатов в группе
    • кол-во использованных сертификатов в группе
    • кол-во активированных сертификатов в группе
    • внутренний идентификатор группы
  • JSON Array
    • JSON String
    • JSON String
    • JSON Number
    • JSON Number
    • JSON Number
    • JSON Number
"groups":[
   {
      "create_date":"2017-11-30T14:37:42.853",
      "name":"TTTTTTTTT",
      "total_count":6,
      "used_count":0,
      "activated_count":0,
      "id":1649
   }

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

https://sailplay.ru/api/v2/promocodes/coupons/groups/list/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9

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

{
	  "status": "ok",
	  "groups": [
	  {
	  "create_date": "2016-12-15T20:36:23",
	  "name": "Test Certificate",
	  "total_count": 1,
	  "used_count": 0,
	  "activated_count": 0,
	  "id": 924
	  }
	  ]
}

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

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

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

/api/v2/promocodes/coupons/numbers/status/ - Проверка статусов сертификатов

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

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

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

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

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

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

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

JSON String
"status":"ok"
used Признак, информирующий о том, использован сертификат или нет. JSON Boolean
"used": false
value_type Системный параметр SailPlay. Всегда содержит значение 2. JSON Number
"value_type": 2
deleted

Признак, информирующий о том, удален сертификат или нет.

JSON Boolean
"deleted": false
  • group
    • id
    • name
  • Объект, содержащий информацию о группе, которой принадлежит сертификат:
    • внутренний идентификатор группы
    • название группы
  • JSON Object
    • JSON Number
    • JSON String
"group":{
   "id":1649,
   "name":"TTTTTTTTT"
}

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

https://sailplay.ru/api/v2/promocodes/coupons/numbers/status/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv

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

{
	  "status": "ok",
	  "used": false,
	  "value_type": 2,
	  "deleted": false,
	  "group": {
	  "id": 1132,
	  "name": "Test Certificate 2"
	  },
	  "dep_id": 3516,
	  "activated": false,
	  "number": "8m8iv",
	  "value": "50"
}

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

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

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

Не передан обязательный параметр

{
    "status": "error",
    "status_code": -1000,
    "message": "Provide required {'field': 'number'}"
}

/api/v2/promocodes/coupons/numbers/activate/ - Активация сертификата

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

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345
да number Номер сертификата string
number=testcert1
да target_dep_id Отдел, которому принадлежит сертификат integer
target_dep_id=3487

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

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

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

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

JSON String
"status":"ok"
activated Признак, информирующий о том, был ли активирован сертификат или нет в случае успешного запроса. JSON Boolean
"activated": true

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

https://sailplay.ru/api/v2/promocodes/coupons/numbers/activate/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv

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

{
  "status": "ok",
  "activated": true
}

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

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

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

Не передан обязательный параметр

{
    "status": "error",
    "status_code": -1000,
    "message": "Provide required {'field': 'number'}"
}

/api/v2/promocodes/coupons/numbers/use/ - Использовать сертификат

Метод предназначен для использования определенного сертификата.

Важно: сертификат должен быть активирован перед его использованием. Сертификат можно использовать один раз для списания суммы сертификата в счет скидки.

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

Обязательный параметр? Параметр Описание параметра Тип данных Пример
да token См. здесь см. пример запроса
token=qx6s4gsdvsdhsdsd
да store_department_id См. здесь integer
store_department_id=345 
да number Непосредственный номер сертификата string
jn321jns
да target_dep_id Отдел, которому принадлежит сертификат Integer
target_dep_id=3487

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

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

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

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

JSON String
"status":"ok"
used Признак, информирующий о том, был ли использован сертификат или нет в случае успешного запроса. JSON Boolean
"used": true

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

https://sailplay.ru/api/v2/promocodes/coupons/numbers/use/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=8m8iv

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

{
  "status": "ok",
  "used": true
}

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

{
  "status": "ok",
  "used": true
}

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

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

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

Не передан обязательный параметр

{
    "status": "error",
    "status_code": -1000,
    "message": "Provide required {'field': 'number'}"
}

/api/v2/promocodes/coupons/numbers/delete - Удаление сертификатов

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

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

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

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

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

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

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

JSON String
"status":"ok"
deleted Признак, инфомирующий о том, был ли удален сертификат или нет, в случае успешного запроса. JSON Boolean
"deleted": true
deleted_date Дата удаления JSON String
"deleted_date": "2017-11-30T17:17:18.071"
number Номер сертификата JSON String
"number": "testcert1"

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

{
    "deleted": true,
    "status": "ok",
    "deleted_date": "2017-11-30T17:17:18.071",
    "number": "йцв765йц7в65"
}

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

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

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

Не передан обязательный парметр запроса

{
    "status": "error",
    "status_code": -1000,
    "message": "Provide required {'field': 'name'}"
}