В SailPlay реализован механизм промо-кодов для использования в рассылках, при совершении покупок, или для выполнения настраиваемых действий. Промо-коды делятся на два типа - простые и активационные, сценарий использования зависит от конкретного типа промо-кода.
Простые промо-коды используются в рассылках и при совершении покупок. Промо-коды загружаются в аккаунт партнера при помощи интерфейса SPanel. После завершения загрузки промо-коды из созданной группы возможно передать пользователям при помощи динамического параметра в рассылках и триггерных цепочках. Выданный промо-код может быть использован в существующих системах партнера, а также может быть передан в корзину при создании покупки, на основании чего к покупке могут быть применены специально настроенные промо-акции.
Активационные промо-коды используются в рассылках, а также позволяют реализовать настраиваимые действия при помощи механизма триггерных цепочек. Промо-коды загружаются в аккаунт партнера при помощи интерфейса SPanel. После завершения загрузки промо-коды из созданной группы возможно передать пользователям при помощи динамического параметра в рассылках. Выданный промо-код может быть применен для конкретного пользователя при помощи метода активации, либо через интерфейс SPanel. При активации промо-кода, пользователь получает тег "Использовал промокод [Название промо-кода]", который может вызывать триггерную цепочку для выполнения специальных действий.
Подарочные сертификаты позволяют создавать группы сертификатов с разбивкой по магазинам и номиналу для последующей продажи этих сертификатов и их отоваривания (оплаты покупки или части покупки сертификатом). Основной бизнес-кейс — продажа сертификатов для их передачи в качестве подарка.
В течение цикла жизни сертификат меняет несколько состояний, каждое из которых является необратимым:
Сертификат имеет несколько атрибутов/признаков:
Данный метод 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": "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, "marketing_actions": [ 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, "marketing_actions": [
{
"status": 2,
"service_msg": null,
"name": "test2",
"client_msg": null,
"alias": "2",
"id": 109
},
{
"status": 2,
"service_msg": null,
"name": "test3",
"client_msg": null,
"alias": "3",
"id": 110
}
},
{
"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 используется для получения информации о конкретном промо-коде.
Используется, например, перед активацией промо-кода, предоставленного пользователем, для проверки его валидности, или определения группы, к которой принадлежит предоставленный промо-код.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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": 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 позволяет активировать указанный промо-код для указанного клиента. Данный метод работает только с промо-кодами с типом "активационный".
При успешном выполнении метода, пользователь получит тег "Использовал промокод [название промо-кода]".
Метод используется, например, в момент активации промо-кода пользователем на сайте партнера. Метод активирует промо-код (и запретит повторное использование, если промо-код одноразовый), а также запустит соответствующие триггерные цепочки, если они установлены в настройках партнера.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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=79000000000&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 используется для глобального поиска промок-кода врамках аккаунта. Также метод позводяет получить расширенную инфомацию о использовании промо-кода.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | token | См. здесь | см. пример запроса |
token=qx6s4gsdvsdhsdsd |
да | store_department_id | См. здесь | integer |
store_department_id=345 |
да | number | Непосредственный номер промо-кода | string (1-128 символов) |
PROMO15 |
нет | user_phone, email или origin_user_id | Идентификатор клиента, по отношению к которому необходимо искать промокод. Влияет на выдачу применимых маркетинговых акций (см. ниже) | string |
user_phone=79001234567 |
https://sailplay.ru/api/v2/promocodes/info/?store_department_id=3620&token=12b3278xcb23b2498vxvb230nrfv24erf9&number=yfubf_mm400
Параметр (ключ) | Описание | Тип данных | Пример |
---|---|---|---|
status | статус запроса | JSON String |
"status":"ok" |
|
|
|
"promocodes": [ { "issued_to": { "id": 40560461, "name": "Grigory Sidorov" }, "purchase_id": 187647692, "receipt_date": "2018-03-28T11:01:54.503", "group": { "status": 2, "type": 2, "name": "PromoGroup1" }, "issued_by": null, "date_of_use": "2018-03-28T11:24:55.565", "order_num": "2734672364723", "marketing_action": [ { "id": 7081, "name": "Test action" } ], placeholderplaceholderplacehold |
{ "status": "ok", "promocodes": [ { "issued_to": { "id": 40560461, "name": "Grigory Sidorov" }, "purchase_id": 187647692, "receipt_date": "2018-03-28T11:01:54.503", "group": { "status": 2, "type": 2, "name": "PromoGroup1" }, "issued_by": null, "date_of_use": "2018-03-28T11:24:55.565", "order_num": "2734672364723", "marketing_action": [ { "id": 7081, "name": "Test action" } ],
"possible_marketing_action": [
{
"status": 2,
"service_msg": null,
"name": "test2",
"alias": "2",
"client_msg": null,
"id": 109
},
{
"status": 2,
"service_msg": null,
"name": "test3",
"alias": "3",
"client_msg": null,
"id": 110
}
]
} ] }
placeholderplaceholderplacehold
Метод используется для создаения новых групп сертификатов. HTTP-метод: POST
Перед созданием сертификатов необходимо подготовить файл, в котором будут содержаться номера сертификатов. Допустимые форматы файлов:
При использовании .txt и .csv формата каждый номер сертификата должен будет указан с новой строки. В случае использования .xls или .xlsx формата номера должны быть указаны в одной колонке, где в каждой ячейке присутствует один номер сертификата.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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'}" }
Этот метод используется для получения списка доступных групп сертификатов у департамента.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | token | См. здесь | см. пример запроса |
token=qx6s4gsdvsdhsdsd |
да | store_department_id | См. здесь | integer |
store_department_id=345 |
Параметр | Описание параметра | Тип данных | Пример |
status |
Статус запроса: ok — если запрос успешен, error — если возникла ошибка. |
JSON String |
"status":"ok" |
|
|
|
"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" }
Метод используется для получения информации о статусе конкретного сертификата, например, для проверки валидности сертификата, предоставленного пользователем.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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":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'}" }
Этот метод используется для активации сертификата. Вызывается в момент передачи сертификата покупателю, который его приобрел, и является механизмом защиты от мошеннических действий. Таким образом, если, например, список номеров сертификатов стал доступен третьим лицам, утекшие сертификаты не смогут быть использованы, так как они еще не были активированы.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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'}" }
Метод предназначен для использования определенного сертификата.
Важно: сертификат должен быть активирован перед его использованием. Сертификат можно использовать один раз для списания суммы сертификата в счет скидки.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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'}" }
Метод используется для удаления отдельных номеров сертификтов. Возможно удаление сертификатов с любым статусом: активирован, использован и пр.
Обязательный параметр? | Параметр | Описание параметра | Тип данных | Пример |
да | 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'}" }