API Партнера
API.URI - не забудьте указать в личном кабинете адрес, по которому Вы будете обрабатывать запросы.URI запроса формируется по схеме
API.URI + '/' + serviceName + '.' + methodName
Все запросы Платформы к Партнеру выполняются методом POST(HTTP) и содержат заголовок
Content-type: application/json
Все ответы от Партнера на запросы от Платформы должны отправляться в формате JSON в следующем виде:{ "method" : "имя_метода", "status" : 200, "response" : {тело ответа в JSON формате, в некоторых методах отсутсвует} }Любой ответ отличный от приведенного выше воспринимается Платформой как ошибочный и запускает алгоритм описанный у каждого метода в секции "Обработка ошибок"
Общая информация:
- Connect timeout
1s - Read timeout
3s - В случае любых ошибок(неполадок) при общении с сервером партнера клиенту в игру отправляется ошибка. Игра требует перезагрузки для продолжения.
- Все несущественные запросы останавливаются при ошибке. Все запросы с семантикой "запрос на совершение действия" - при ошибках отменяются(с попытками сообщить об этом партнеру). Все запросы с семантикой "сообщить исход" - будут выполняться до однозначной безошибочной обработки.
Формирование Подписи
- Подпись в запросе передается как именованный параметр
sign - В формировании подписи участвуют ВСЕ параметры, которые передаются в
теле POST запроса (GET параметры, являющиеся query частью url-адреса, не учитываются),
кроме параметров
meta,signи тех, чьи имена начинаются сpartner. - Формирование:
-
Формируем набор параметров из тела POST запроса
-
Отфильтровываем параметры
meta,signи имена которых начинаются сpartner. -
Сортируем оставшиеся параметры в лексикографическом порядке
-
Объединяем все имена параметров и значения параметров в единую строку
-
Добавляем к полученной строке имя метода, Идентификатор Партнера и Секретный ключ
-
Производим хеширование итоговой строки алгоритмом MD5
-
Полный алгоритм по формированию подписи(pseudo code):
val params = Map[Name,Value]
val joined = names
.filter( name => !(name.startsWith("partner.") || name === "meta" || name === "sign") )
.sorted
.map( name => name + "=" + params(name))
.join("&")
// Соединительная частица "&" между 'joined' и 'serviceName' проставляется в любом случае, даже при отсутствии параметров.
val sign = md5(joined + "&" + serviceName + "." + methodName + "&" + "Идентификатор Партнера" + "&" + "Секретный ключ")
Полный пример формирования подписи
METHOD: /games.list
PARAMS:
paramA = paramValueA
paramC = paramValueC
paramZ = paramValueZ
paramB = paramValueB
partner.alias = test
meta.param1 = someValue
meta.paramEtc = etcValue
SIGN:
// URL-encode - НЕ применяется
joined = "paramA=paramValueA¶mB=paramValueB¶mC=paramValueC¶mZ=paramValueZ"
stringToSign = joined + "&games.list&test&testsecret"
//stringToSign = "paramA=paramValueA¶mB=paramValueB¶mC=paramValueC¶mZ=paramValueZ&games.list&test&testsecret"
sign = md5(stringToSign)
//sign = "8cb94a439f507c1a6f9cede4982380a1"
FULL REQUEST BODY:
paramA=paramValueA¶mB=paramValueB¶mC=paramValueC¶mZ=paramValueZ&games.list&test&testsecret&partner.alias=test&partner.sign=8cb94a439f507c1a6f9cede4982380a1&meta.param1=someValue&meta.paramEtc=etcValue
Методы на стороне Партнера
/trx.cancel - Отмена транзакции
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@amount- Сумма в копейках/центах -
@trx_id- уникальный идентификатор транзакции на стороне Платформы. Партнер должен обеспечить проверку на уникальность на своей стороне и не списывать повторно при наличии повторных запросов с указанным идентификатором. -
@sign- подпись запроса -
@turn_id- номер хода в сессии на стороне Платформы (справочно) -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "trx.cancel",
"status" : 200,
"response" : {
currency: String // запрошенная валюта
balance:Long // баланс игрока в указанной валюте после отмены (для отображения в играх)
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1b905c92daf4052f06e9d18303d83322",
"currency": "RUB",
"amount": 7500,
"trx_id": "LOCAL-50-0",
"turn_id": 1,
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"RUB\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/trx.cancel
RESPONSE:
{
"method" : "trx.cancel",
"status" : 200,
"response" : {
"currency" : "RUB",
"balance" : 500000
}
}
Обработка ошибок
- В случае получения Платформой любого ответа отличного от ожидаемого делается несколько автоматических попыток(текущие установки 2 попытки через 5 и 15 секунд) уведомить Партнера об отмене транзакции.
- В случае исчерпания попыток Партнер должен после устранения неисправности инициировать запрос на отмену транзакции в ручную из Личного кабинета
Подробнее об отмене транзакций смотрите в разделе "Процедура отмены транзакции"
/trx.complete - Завершение транзакции
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@amount- Сумма в копейках/центах -
@trx_id- уникальный идентификатор транзакции на стороне Платформы. Партнер должен обеспечить проверку на уникальность на своей стороне и не списывать повторно при наличии повторных запросов с указанным идентификатором. -
@sign- подпись запроса -
@turn_id- номер хода в сессии на стороне Платформы (справочно) -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "trx.complete,
"status" : 200,
"response" : {
currency: String // запрошенная валюта
balance:Long // баланс игрока в указанной валюте после отмены (для отображения в играх)
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1b905c92daf4052f06e9d18303d83322",
"currency": "RUB",
"amount": 7500,
"trx_id": "LOCAL-50-0",
"turn_id": 1,
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"RUB\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/trx.complete
RESPONSE:
{
"method" : "trx.complete",
"status" : 200,
"response" : {
"currency" : "RUB",
"balance" : 500000
}
}
Обработка ошибок
- В случае получения Платформой любого ответа отличного от ожидаемого делается несколько автоматических попыток(текущие установки 2 попытки через 5 и 15 секунд) уведомить Партнера об отмене транзакции.
- В случае исчерпания попыток Партнер должен после устранения неисправности инициировать запрос на отмену транзакции в ручную из Личного кабинета
Подробнее об отмене транзакций смотрите в разделе "Процедура отмены транзакции"
/check.session - Получение(проверка) информации о сессии на
стороне Партнера.
id_player - это уникальный номер игрока.
Все игры для игрока с его id_player запускаются только в одном экземпляре.Обратите внимание, что важно указывать корректный id_player при создании сессии, если сесиия должна сохраняться за конкретным игроком.
Для анонимизации игроков на стороне Платформы id_player можно слать всегда уникальный.
Если же для всех сессий слать одно и тоже значение id_player, то работа платформы будет не корректна: будут смешиваться игры, других игроков будет разлогинивать и игровые данные будут смешиваться
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@sign- подпись запроса -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "check.session",
"status" : 200,
"response" : {
"id_player": Long|String // неизменяемый идентификатор игрока на стороне партнера. Требуется для восстановления игр, полных логов по игроку и другого.
"game_id": Int // идентификатор игры
"currency": String // запрошенная валюта
"balance": Long // баланс игрока в указанной валюте на момент запроса (для отображения в играх)
"denomination": Int // деноминатор в сотых долях(при значении 100 деноминация 1.00) используемый для игровой сессии
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1",
"currency": "RUB",
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"RUB\"}" http://example.com/check.session
RESPONSE:
{
"method" : "check.session",
"status" : 200,
"response" : {
"id_player" : "1",
"game_id" : 1,
"currency" : "RUB",
"balance" : 500000,
"denomination" : 500000
}
}
Обработка ошибок
- Остановка выполнения
/check.balance - Получение информации о балансе на стороне
партнера.
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@sign- подпись запроса -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "check.balance",
"status" : 200
"response" : {
currency: String // запрошенная валюта
balance:Long // баланс игрока в указанной валюте на момент запроса (для отображения в играх)
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1",
"currency": "RUB",
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"RUB\"}" http://example.com/check.balance
RESPONSE:
{
"method" : "check.balance",
"status" : 200,
"response" : {
"currency" : "RUB",
"balance" : 500000
}
}
Обработка ошибок
- Остановка выполнения
/withdraw.bet - Списание с баланса за совершение ставки.
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@amount- Сумма в копейках/центах -
@trx_id- уникальный идентификатор транзакции на стороне Платформы. Партнер должен обеспечить проверку на уникальность на своей стороне и не списывать повторно при наличии повторных запросов с указанным идентификатором. -
@sign- подпись запроса -
@turn_id- номер хода в сессии на стороне Платформы (справочно) -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "withdraw.bet",
"status" : 200
"response" : {
currency: String // запрошенная валюта
balance:Long // баланс игрока в указанной валюте после списания (для отображения в играх)
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1b905c92daf4052f06e9d18303d83322",
"currency": "RUB",
"amount": 7500,
"trx_id": "LOCAL-50-0",
"turn_id": 1,
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"RUB\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/withdraw.bet
RESPONSE:
{
"method" : "withdraw.bet",
"status" : 200,
"response" : {
"currency" : "RUB",
"balance" : 500000
}
}
Обработка ошибок
- В случае ответа от Партнера на запрос Платформы, где
@statusв диапазоне от 500 до 599 игровой сервер считает, что сервер партнера ответил отказом на проведение транзакционно значимого действия. Транзакция помечается как завершенная отказная. - В остальных случаях, когда ответ отличается от ожидаемого запускается "Процедура отмены транзакции"
/deposit.win - Зачисление выигрыша на баланс.
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@amount- Сумма в копейках/центах -
@trx_id- уникальный идентификатор транзакции на стороне Платформы. Партнер должен обеспечить проверку на уникальность на своей стороне и не начислять повторно выигрыш при наличии повторных запросов с указанным идентификатором. -
@sign- подпись запроса -
@turn_id- номер хода в сессии на стороне Платформы (справочно) -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "deposit.win",
"status" : 200,
"response" : {
currency: String // запрошенная валюта
balance:Long // баланс игрока в указанной валюте после зачисления выигрыша (для отображения в играх)
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1",
"currency": "RUB",
"amount": "7500",
"trx_id": "LOCAL-50-0",
"turn_id":"1",
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"sign\" : \"1b110f548f5b3baf21bd37e722020285\", \"session\" : \"5b3baf21bd37-5b3baf21bd37-5b3baf21bd37\", \"currency\" : \"RUB\", \"amount\" : 7500, \"trx_id\" : \"LOCAL-50-0\", \"turn_id\" : 1}" http://example.com/deposit.win
RESPONSE:
{
"method" : "deposit.win",
"status" : 200,
"response" : {
"currency" : "RUB",
"balance" : 500000
}
}
Обработка ошибок
Freerounds
- Каждый @freerounds.id должен быть уникальным в рамках партнера
- Партнеру необходимо осуществить проверку того, чтобы каждый @freerounds.id нельзя было активировать и завершить более одного раза.
- Если у игрока в игре, для которой активируются фрираунды, есть игровая сесиия, то она будет принудительно завершена. Подробнее о принудительном завершении сессий
Ставки и выигрыши на фрираундах:
- Изменить ставку на протяжении фрираундов нельзя
- Игра запускается всегда по минимальной для игры ставке и максимальному числу линий
- Размер потенциального выигрыша для Игрока регулируется Партнером путем указания количества выдаваемых фрираундов и деноминации
Почему нельзя изменить ставку и число линий на фрираундах?
Платформа содержит сотни игр из десятков различных серий. Многие игры имеют очень специфичные наборы ставок по линиям. В некоторых играх количество линий фиксировано или их нет совсем и обсчет идет по барабанам. Увеличение ставки крайне неравномерно распределит потенциальные выигрыши между играми с малым и большим количеством линий, а уменьшение количества линий резко сказывается на интересности игры для Игрока.Таким образом минимальная ставка с максимальным количеством линий позволяет получить максимальную вовлеченность Игрока благодаря большой вероятности небольших выигрышей. И при этом Партнеру не требуется учитывать специфику математики игры.
Порядок действий:
- Партнер запускает игру как обычно + параметр @freerounds.id
- Платформа активирует фрираунды на сервере Партнера
- Игрок отыгрывает фрираунды (в процессе фрираундов выигрыши не зачисляются на сервер партнера)
- Платформа завершает фрираунды на сервере Партнера с указанием общего выигрыша за фрираунды.
/freerounds.activate - Активация фрираундов.
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@game_id- идентификатор игры (партнер может осуществить дополнительную проверку, чтобы ограничить игры в которых можно использовать конкретные фрираунды) -
@freerounds_id- String - уникальный идентификатор фрираундов. -
@sign- подпись запроса -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "freerounds.activate",
"status" : 200,
"response" : {
"total": Int
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"session": "1",
"currency": "RUB",
"freerounds_id": "09fafb5e3794c3e07f585a790898b0e1",
"game_id": 1,
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"session\":\"1b6a31e8d65bbf17fcf7c5b09a2302fe\",\"sign\":\"20e455b3bd7e6c5e89dbe7db062f5c0a\",\"currency\":\"EUR\",\"freerounds_id\":\"09fafb5e3794c3e07f585a790898b0e1\",\"game_id\":1}" http://example.com/freerounds.activate
RESPONSE:
{
"method" : "freerounds.activate",
"status" : 200,
"response" : {
"total" : 10
}
}
Обработка ошибок
- Остановка выполнения
/freerounds.complete - Завершение фрираундов.
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@freerounds_id- String - уникальный идентификатор фрираундов. -
@trx_id- уникальный идентификатор транзакции на стороне Платформы. -
@amount- Long (в копейках/центах конкретной валюты) -
@turn_id- номер хода в сессии на стороне Платформы (справочно) -
@sign- подпись запроса -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "freerounds.complete",
"status" : 200,
"response" : {
currency: String // запрошенная валюта
balance:Long // баланс игрока в указанной валюте после зачисления выигрыша (для отображения в играх)
}
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"freerounds_id": "09fafb5e3794c3e07f585a790898b0e1",
"session": "1",
"currency": "RUB",
"amount": "7500",
"trx_id": "LOCAL-50-0",
"turn_id":"1",
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"trx_id\":\"347\",\"amount\":2200,\"session\":\"1b6a31e8d65bbf17fcf7c5b09a2302fe\",\"sign\":\"f2afb1d7095cce85819556493053bf50\",\"currency\":\"EUR\",\"freerounds_id\":\"09fafb5e3794c3e07f585a790898b0e1\",\"turn_id\":\"5\"}" http://example.com/freerounds.complete
RESPONSE:
{
"method" : "freerounds.complete",
"status" : 200,
"response" : {
"currency" : "RUB",
"balance" : 500000
}
}
Обработка ошибок
/freerounds.step - Уведомление о завершении шага фрираунда. НЕ
транзакционное действие. Не использовать для изменения баланса игрока! Запросы в случае ошибок не
дублируются.
- Параметры
-
@session- идентификатор сессии игрока, который Партнер указал при старте игры -
@currency- 3-Latin код валюты, который Партнер указал при старте игры -
@freerounds_id- String - уникальный идентификатор фрираундов в рамках партнера. -
@step- Int - Номер шага. Значение >= 1 -
@step_win- Long (в копейках) - Выигрыш на конкретном шаге -
@total_win- Long (в копейках конкретной валюты) - Аккумулированный выигрыш с учетом предыдущих шагов. -
@sign- подпись запроса -
@meta- мета-данные
-
Ожидаемый ответ
{
"method" : "freerounds.step",
"status" : 200,
"response" : true
}
Пример запроса, который отправляет Платформа
JSON:
{
"sign": "85520955afda57b28905181593440dbb",
"freerounds_id": "09fafb5e3794c3e07f585a790898b0e1",
"session": "1",
"currency": "RUB",
"step_win": 500,
"total_win": 7500,
"step": 1,
"meta": {
"game": "slot"
}
}
Пример запроса/ответа в формате CURL
CURL:
curl -X POST -d "{\"step_win\":2200,\"session\":\"1b6a31e8d65bbf17fcf7c5b09a2302fe\",\"sign\":\"fc1ab09e67798052c8e3f959b8b313f7\",\"currency\":\"EUR\",\"step\":\"2\",\"freerounds_id\":\"09fafb5e3794c3e07f585a790898b0e1\",\"total_win\":2200}" http://example.com/freerounds.step
RESPONSE:
{
"method" : "freerounds.step",
"status" : 200,
"response" : true
}
Обработка ошибок
- Ошибки по данному запросу игнорируются
Обработка ошибок
Перечень политик:
-
Stop on fail
Перечень методов:
- check.session
- check.balance
Поведение:
- При любой ошибке - остановка.
-
Cancel on undefined behavior
Перечень методов:
- withdraw.bet
- freerounds.activate
Поведение в случае получение ответа в зависимости от поля
@status(НЕ http status code):- 200 - штатное поведение. Транзакция помечается как успешная и завершенная.
- 500-599 - игровой сервер считает, что сервер партнера ответил отказом на проведение транзакционно значимого действия. Транзакция помечается как завершенная отказная.
- Любой другой код - несмотря на то, что игровой сервер получил тело ответа от партнера в согласованном формате, он считает что на сервере партнера произошла внештатная ситуация, которая не позволяет определить статус транзакции. Запускается процедура отмены транзакции.
Поведение в случае, когда игровой сервер не получил ответа(таймаут, сбой связи или любая другая - не имеет значения):
- Запускается процедура отмены транзакции.
Процедура отмены транзакции:
- Транзакция помечается как отмененная и не завершенная.
- Игровой сервер с некоторой задержкой осуществляет несколько
попыток(текущие установки 2 попытки через 5 и 15 секунд) сообщить партнеру, что транзакция
отменена путем вызова метода
/trx.cancel. - В случае если партнер отвечает статусом 200, транзакция помечается как завершенная.
- В случае если партнер отвечает статусом отличным от 200 попытки продолжаются.
- После исчерпания лимита попыток, они останавливаются.
- Все отмененные транзакции и их статусы можно просмотреть в ЛК
- В случае исчерпания попыток для того, чтобы завершить транзакцию
партнер может в ЛК в ручном режиме инициировать запрос с сообщением об отмене транзакции. В
этом случае игровой сервер незамедлительно попытается отправить
/trx.cancelи в случае успешного подтверждения пометит тразнакцию как завершенную.
-
Proceed on fail.
Перечень методов:
- deposit.win
- freerounds.complete
Поведение в случае получение ответа в зависимости от поля
@status(НЕ http status code):- 200 - штатное поведение. Транзакция помечается как успешная и завершенная.
- Любой другой код - несмотря на то, что игровой сервер получил тело ответа от партнера в согласованном формате, он считает что на сервере партнера произошла внештатная ситуация, которая не позволяет определить статус транзакции. Запускается процедура отложенного завершения транзакции.
Поведение в случае, когда игровой сервер не получил ответа(таймаут, сбой связи или любая другая - не имеет значения):
- Запускается процедура отложенного завершения транзакции.
Процедура отложенного завершения транзакции:
- Транзакция помечается как не завершенная.
- Игровой сервер с некоторой задержкой осуществляет несколько
попыток(текущие установки 2 попытки через 5 и 15 секунд) сообщить партнеру о завершении
тразнакции путем вызова метода
/trx.complete. - В случае если партнер отвечает статусом 200, транзакция помечается как завершенная.
- В случае если партнер отвечает статусом отличным от 200 попытки продолжаются.
- После исчерпания лимита попыток, они останавливаются.
- Все не завершенные транзакции и их статусы можно просмотреть в ЛК
- В случае исчерпания попыток для того, чтобы завершить
транзакцию партнер может в ЛК в ручном режиме инициировать запрос с сообщением о завершении
транзакции. В этом случае игровой сервер незамедлительно попытается отправить
/trx.completeи в случае успешного подтверждения пометит тразнакцию как завершенную.