Документация по интеграции веб игр

Документация по интеграции партнера с игровым сервисом веб-игр.

Изменения

Дата	Версия	Описание
18.05.17	0.1	Создание документации
20.04.26	0.2	Документация обновлена: удалены неподдерживаемые методы, убран `live_slot`, обновлен `GetListGames`, уточнен `language`, добавлены поддерживаемые валюты
27.04.26	0.3	Уточнены запуск на реальные деньги, `partner_api_url`, работа с токеном и диагностика
13.05.26	0.4	Схема взаимодействия (Web Games API / iframe / Partner API); описаны партнёрские `Credit` и `Debit`; добавлена ссылка на расширенный каталог игр

Введение

В этом документе описан процесс интеграции партнера с сервисом веб-игр.

Интеграция состоит из двух частей:

Web Games API — публичные методы сервиса: получить список игр и открыть игру
Partner API — методы на стороне партнёра, которые сервис вызывает для авторизации и операций с балансом игрока

В demo-режиме игра открывается без вызовов кошелька партнёра. В real-money режиме сервис перед запуском игры вызывает Authorization, а во время игры — Credit для списания ставки и Debit для начисления выигрыша.

Общее

Протокол: HTTPS
Публичные методы сервиса вызываются через GET
Методы API партнера вызываются через POST
Формат тела POST-запросов: application/json
Успешный ответ: code = 0

Базовый сценарий интеграции

Partner API партнёра запрашивает каталог игр через GET /GetListGames.
Игрок выбирает игру на платформе партнёра. Платформа открывает игровое окно: на десктопе обычно iframe со страницей Web Games API GET /game, на мобильных — прямую ссылку на ту же страницу.
Если currency=DMO, игра запускается в demo-режиме. Partner API для кошелька не вызывается.
Если это real-money запуск, партнёр передаёт player_id и token. Сервис вызывает POST /Authorization на Partner API.
Во время real-money игры сервис вызывает POST /Credit для ставки и POST /Debit для выигрыша.

Участники

Участник	Роль
Partner API	Взаимодействует с сервисом со стороны партнёра: запрашивает каталог, формирует запуск игры и принимает `Authorization`, `Credit`, `Debit`
Web Games API	Отдаёт каталог, страницу игры и управляет игровой сессией
Iframe игрока	Клиент игры в браузере игрока

Получение каталога

Каталог обычно запрашивает Partner API партнёра до показа игры пользователю.

Запуск real-money игры

При запуске на реальные деньги сервис проверяет игрока через Partner API до того, как отдаст страницу игры.

Операции во время игры

Credit списывает ставку с кошелька игрока у партнёра. Debit начисляет выигрыш. Если выигрыша нет, Debit может не вызываться.

Имена полей JSON

Ответ Partner API должен возвращать ключи только в нижнем регистре: code, message, balance и т.д. Ключи вида Code, CODE или Balance не принимаются нашим API.

Подпись запросов

Все подписи считаются через md5.

Строка для подписи собирается по правилу:

text

<MethodName>/ + <value1> + <value2> + ... + <api_key>

Важно:

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

Пример для Authorization:

const crypto = require('crypto');

function calcSignature(method, values, apiKey) {
  const source = `${method}/${values.join('')}${apiKey}`;

  return crypto.createHash('md5').update(source).digest('hex');
}

const method = 'Authorization';
const values = [42, 2, 'Aj4BAnMZBepwoYqavIjwg3m3'];
const apiKey = 'secret';

const source = `${method}/${values.join('')}${apiKey}`;
const hash = calcSignature(method, values, apiKey);

console.log(source);
// Authorization/422Aj4BAnMZBepwoYqavIjwg3m3secret

console.log(hash);
// bac2df62b8873884dea9b0a918733554

1. GetListGames

Возвращает список игр, доступных партнеру.

Запрос

GET /GetListGames

Параметры:

Поле	Тип	Обязательно	Описание
`partner_id`	`int`	Да	Идентификатор партнера
`type`	`string`	Да	Тип игр. Поддерживаемое значение: `web_slot`
`hash`	`string`	Да	`md5("GetListGames/" + partner_id + type + api_key)`

Пример:

text

GET /GetListGames?partner_id=<partner_id>&type=web_slot&hash=<md5_signature>

Успешный ответ

json

{
  "code": 0,
  "message": "Ok",
  "games": [
    {
      "id": 11,
      "title": "Chicago Deluxe",
      "url": "/game",
      "icon": "/icon/novomatic-deluxe/206x206/chicago_deluxe.jpg",
      "class": "Novomatic Deluxe"
    }
  ]
}

Поля ответа:

Поле	Тип	Описание
`code`	`int`	Код результата
`message`	`string`	Описание результата
`games`	`array`	Список игр
`games[].id`	`int`	Идентификатор игры
`games[].title`	`string`	Название игры
`games[].url`	`string`	URL запуска игры
`games[].icon`	`string`	URL иконки игры
`games[].class`	`string`	Категория или класс игры

Дополнительный каталог игр доступен в Google Sheets. В нём есть ID игр, провайдеры, RTP, игровые фичи и ссылки на иконки 206x206 и 287x193.

Коды ответа

Код	Описание
`0`	Успешно
`10`	Hash mismatch
`15`	Unavailable type
`101`	Partner is not found
`1`	Internal Error

2. Запуск игры

Для запуска игры используется метод GET /game.

Запрос

GET /game

Параметры:

Поле	Тип	Обязательно	Описание
`partner_id`	`int`	Да	Идентификатор партнера
`game_id`	`int`	Да	Идентификатор игры
`language`	`string`	Нет	Язык игры. Параметр опционален
`currency`	`string`	Да	Валюта игрока
`player_id`	`int или string`	Для игры на реальные деньги	Идентификатор игрока у партнера
`token`	`string`	Для игры на реальные деньги	Одноразовый токен игрока

Имена параметров чувствительны к регистру. Используйте имена ровно в таком виде: partner_id, game_id, language, currency, player_id, token.

Значение currency — это код валюты, например USD или EUR, а не внутренний идентификатор валюты.

Запуск в браузере и на мобильных устройствах

В браузерной версии игра обычно открывается внутри iframe.

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

Демо-режим

Для запуска demo-версии используйте валюту DMO.

В демо-режиме метод Authorization на стороне партнера не вызывается, поэтому демо-режим не подходит для проверки работы токена в real-money сценарии.

Пример:

text

GET /game?partner_id=<partner_id>&game_id=<game_id>&language=eng&currency=DMO

Игра на реальные деньги

Пример:

text

GET /game?partner_id=<partner_id>&player_id=<player_id>&game_id=<game_id>&language=eng&currency=<currency>&token=<token>

Для запуска игры на реальные деньги партнер должен передавать player_id и token.

token генерируется на стороне партнера. Тот же token должен быть передан в GET /game и будет отправлен сервисом в партнерский метод Authorization.

Результат

При успешном запросе сервис возвращает HTML страницы игры.

Коды ответа

Код	Описание
`12`	Game is not found
`13`	Partner API return null
`101`	Partner is not found
`102`	Currency is not found
`1`	Internal Error

3. Authorization

Метод должен быть реализован на стороне партнера для запуска игры на реальные деньги.

Запрос

POST <partner_api_url>/Authorization

partner_api_url — это базовый URL, который предоставляет партнер. Он не должен включать финальную часть /Authorization и не должен заканчиваться слешем.

Пример:

Полный endpoint Authorization	Значение для `partner_api_url`
`https://example.com/callbacks/Authorization`	`https://example.com/callbacks`

Тело запроса:

json

{
  "player_id": "<player_id>",
  "game_id": "<game_id>",
  "token": "<token>",
  "hash": "<md5_signature>"
}

Подпись:

text

md5("Authorization/" + player_id + game_id + token + api_key)

Успешный ответ

Ответ должен быть валидным JSON. Пустой ответ, HTML-страница ошибки или другой не-JSON ответ не могут быть обработаны как успешный результат авторизации.

json

{
  "code": 0,
  "message": "Ok",
  "player_id": 42,
  "currency": "RUB",
  "nick": "Player42",
  "balance": 10000.12,
  "external_session": "session-123"
}

Поля ответа:

Поле	Тип	Описание
`code`	`int`	Код результата
`message`	`string`	Описание результата
`player_id`	`int или string`	Идентификатор игрока
`currency`	`string`	Валюта игрока
`nick`	`string`	Ник игрока
`balance`	`number`	Баланс игрока
`external_session`	`string`	Необязательный идентификатор внешней сессии

Коды ответа

Код	Описание
`0`	Успешно
`10`	Hash mismatch
`11`	Player not found
`14`	Non-valid token
`1`	Internal Error

4. Credit (Partner API)

Вызывается Web Games API во время спина в real-money, чтобы списать ставку с кошелька игрока у партнёра.

Запрос

POST <partner_api_url>/Credit

Тело запроса:

Поле	Тип	Описание
`token`	`string`	Тот же одноразовый токен, что и для `/Authorization`
`player_id`	`int`	Идентификатор игрока у партнёра
`round_id`	`int`	Идентификатор раунда на стороне партнёра
`game_id`	`int`	Идентификатор игры
`transaction_id`	`long`	Уникальный идентификатор операции
`amount`	`number`	Сумма ставки (десятичная, в той же шкале, что и `balance` из Authorization)
`is_close`	`bool`	Если `true`, по раунду не должно быть дальнейших операций
`hash`	`string`	Подпись `md5`

Пример тела запроса:

json

{
  "transaction_id": 2234,
  "player_id": 1223,
  "round_id": 12,
  "token": "Aj4BAnMZBepwoYqavIjwg3m3",
  "is_close": false,
  "game_id": 3,
  "amount": 42.6,
  "hash": "556c56d640c622659d001b4f344a2814"
}

Подпись:

text

md5("Credit/" + player_id + round_id + game_id + transaction_id + token + api_key)

Успешный ответ

Поле	Тип	Описание
`code`	`int`	`0` — успех
`message`	`string`	Описание
`balance`	`number`	Баланс после списания
`external_session_id`	`int`	Ссылка на операцию у партнёра

Повторный запрос с тем же сочетанием player_id, round_id, transaction_id должен вернуть тот же результат без повторного списания (идемпотентность).

Типовые коды ответа

Код	Описание
`0`	Успешно
`2`	Недостаточно средств
`4`	Игрок заблокирован
`5`	Раунд закрыт
`8`	Раунд не найден
`10`	Hash mismatch
`11`	Игрок не найден
`14`	Невалидный токен
`1`	Internal Error

5. Debit (Partner API)

Вызывается Web Games API, когда нужно начислить выигрыш на кошелёк у партнёра.

Запрос

POST <partner_api_url>/Debit

Тело запроса:

Поле	Тип	Описание
`token`	`string`	Токен сессии
`player_id`	`int`	Идентификатор игрока у партнёра
`round_id`	`int`	Идентификатор раунда на стороне партнёра
`game_id`	`int`	Идентификатор игры
`transaction_id`	`long`	Уникальный идентификатор операции
`amount`	`number`	Сумма выигрыша
`bet_amount`	`number`	Сумма связанной ставки (передаёт Web Games API)
`is_close`	`bool`	Если `true`, по раунду не должно быть дальнейших операций
`hash`	`string`	Подпись `md5`

Пример тела запроса:

json

{
  "transaction_id": 2235,
  "player_id": 1223,
  "round_id": 12,
  "token": "Aj4BAnMZBepwoYqavIjwg3m3",
  "is_close": true,
  "game_id": 3,
  "bet_amount": 42.6,
  "amount": 20,
  "hash": "82a9d01a912b3562b5496c74d7f9fcc8"
}

Подпись:

text

md5("Debit/" + player_id + round_id + game_id + transaction_id + token + api_key)

Успешный ответ

Формат как у Credit: code, message, balance, external_session_id.

Те же правила идемпотентности, что и для Credit (player_id, round_id, transaction_id).

Типовые коды ответа

Код	Описание
`0`	Успешно
`4`	Игрок заблокирован
`5`	Раунд закрыт
`8`	Раунд не найден
`10`	Hash mismatch
`11`	Игрок не найден
`14`	Невалидный токен
`1`	Internal Error

6. Диагностика запуска на реальные деньги

Если игра на реальные деньги не открывается корректно, сначала проверьте партнерский endpoint Authorization.

Что обычно нужно проверить:

partner_api_url является базовым URL и не включает финальную часть /Authorization или слеш в конце
endpoint доступен из публичного интернета
firewall или IP allowlist пропускают входящие запросы от сервиса
endpoint принимает POST запросы с application/json
endpoint возвращает JSON и для успешной авторизации, и для ошибок
player_id и token переданы в GET /game для запуска на реальные деньги

Partner API return null обычно означает, что сервис не получил валидный JSON-ответ от партнерского endpoint Authorization.

При обращении с проблемой запуска в интеграционный чат отправляйте полный URL, которым открывается iframe, включая все query-параметры. Это позволяет обеим сторонам воспроизвести тот же запрос и проверить те же параметры.

7. Поддерживаемые валюты

Сейчас поддерживается 122 валютных кода:

AED, ALL, AMD, AOA, ARS, AUD, AZN, BAM, BDT, BGN, BHD, BOB, BRL, BSX, BTC, BYN, CAD, CDF, CFA, CHF, CLP, CNY, COP, CZK, DASH, DEEX, DKK, DMO, DOP, DTC, DZD, EGP, ETB, ETH, EUR, FAU, FBu, GAME, GBP, GEL, GHS, GMC, GMD, GNF, HC, HKD, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JOD, JPY, KES, KGS, KM, KRW, KWD, KZT, LBP, LTC, MAD, MDL, MKD, MMK, MNT, MVR, MXN, MYR, MZN, NGN, NIS, NOK, NZD, OMR, PEN, PHP, PICK, PKR, PLN, PRB, PYG, QAR, RON, RSD, RUB, RUR, SAR, SDG, SEK, SGD, THB, TJS, TMT, TND, TRY, TWD, TZS, UAH, UGX, USD, USDC, USDT, UYU, UZS, VEF, VND, XAF, XEM, XMR, XOF, ZAR, ZEC, ZMW, ZWL, mBT, mETH, uBTC

Примечания:

DMO используется для запуска демо-режима
при необходимости можно добавить дополнительные валюты по запросу

Документация по интеграции веб игр ​

Изменения ​

Введение ​

Общее ​

Базовый сценарий интеграции ​

Участники ​

Получение каталога ​

Запуск real-money игры ​

Операции во время игры ​

Имена полей JSON ​

Подпись запросов ​

1. GetListGames ​

Запрос ​

Успешный ответ ​

Коды ответа ​

2. Запуск игры ​

Запрос ​

Запуск в браузере и на мобильных устройствах ​

Демо-режим ​

Игра на реальные деньги ​

Результат ​

Коды ответа ​

3. Authorization ​

Запрос ​

Успешный ответ ​

Коды ответа ​

4. Credit (Partner API) ​

Запрос ​

Успешный ответ ​

Типовые коды ответа ​

5. Debit (Partner API) ​

Запрос ​

Успешный ответ ​

Типовые коды ответа ​

6. Диагностика запуска на реальные деньги ​

7. Поддерживаемые валюты ​

Документация по интеграции веб игр

Изменения

Введение

Общее

Базовый сценарий интеграции

Участники

Получение каталога

Запуск real-money игры

Операции во время игры

Имена полей JSON

Подпись запросов

1. GetListGames

Запрос

Успешный ответ

Коды ответа

2. Запуск игры

Запрос

Запуск в браузере и на мобильных устройствах

Демо-режим

Игра на реальные деньги

Результат

Коды ответа

3. Authorization

Запрос

Успешный ответ

Коды ответа

4. Credit (Partner API)

Запрос

Успешный ответ

Типовые коды ответа

5. Debit (Partner API)

Запрос

Успешный ответ

Типовые коды ответа

6. Диагностика запуска на реальные деньги

7. Поддерживаемые валюты