AG GAMEAPI слотов на ваших условиях.
Русский
Связаться

AG GAME · Slots API V5.0.0

Документация Game API для интеграции AG GAME Slots

Эта документация Slots API предоставляет публичную справку для AG GAME Slots API V5.0.0. Используйте справочник для проверки подписи, запуска игры, потоков кошелька, записей транзакций и обработки ошибок, затем следуйте процессу интеграции для подтверждения доступа и тестовых материалов конкретного проекта.

Обзор API и границы доступа

Публичная справка и контролируемые материалы проекта

Эта страница объясняет назначение текущего публичного протокола. Реальный Base URL, учётные данные, полные ограничения полей, окончательный список callback и производственная конфигурация подтверждаются для каждого проекта в контролируемом процессе интеграции.

Справочник Slots API

Подготовка к тестированию и production

Необходимые материалы и следующие шаги

Подготовьте объём проекта, архитектуру кошелька и тестовые материалы, затем используйте процесс интеграции для подтверждения сред, ответственности и проверяемых условий запуска.

Начать процесс интеграции · Обсудить тестовый доступ

Аутентификация и подпись

Общие заголовки

ЗаголовокТипОбязательноОписание
X-MERCHANT-CODEstringОбязательноКод мерчанта, назначенный платформой
X-TIMESTAMPstringОбязательноМетка времени на момент запроса
X-NONCEstringОбязательноСлучайная строка для каждого запроса
X-SIGNstringОбязательноПодпись запроса, сформированная с HmacSHA256
X-CONTENT-PROCESSING-TYPEstringОбязательноТип обработки контента, заданный конфигурацией интеграции

Строка подписи

Сериализуйте окончательное тело JSON. Объедините значения в указанном порядке без разделителей и вычислите HMAC-SHA256 с ключом подписи. Передайте результат в X-SIGN. Подписанные байты должны точно совпадать с отправленными: изменение форматирования JSON может вызвать C10004.

merchantCode + timestamp + nonce + signType + body
import { createHmac } from "node:crypto";
const signType = "HmacSHA256";
const body = JSON.stringify(requestBody);
const signingText = merchantCode + timestamp + nonce + signType + body;
const signature = createHmac("sha256", secretKey)
  .update(signingText, "utf8")
  .digest("hex");

Общий ответ

Бизнес-результат определяется полем code. Один HTTP-статус не подтверждает результат транзакции.

ПолеТипОписание
codestringКод бизнес-результата
msgstringСообщение о результате
successbooleanПризнак успеха в примере
dataobjectДанные ответа операции
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {}
}

Каталог 17 публичных возможностей

Каталог игр и сессии

  • POST /game/v5/providers

    Получить список поставщиков игр

  • POST /game/v5/categories

    Получить список категорий игр

  • POST /game/v5/games

    Получить постраничный список игр

  • POST /game/v5/game/url

    Создать игровую сессию игрока и получить URL запуска

  • POST /game/v5/player/force/logout

    Принудительно завершить игровую сессию игрока

Обратные вызовы единого кошелька

  • POST {MERCHANT-URL}/wallet/balance

    Запросить баланс кошелька игрока

  • POST {MERCHANT-URL}/player/info

    Запросить сведения об игроке

  • POST {MERCHANT-URL}/wallet/bet

    Получить уведомление о ставке

  • POST {MERCHANT-URL}/wallet/win

    Получить уведомление о расчёте или расчёте ставки

  • POST {MERCHANT-URL}/wallet/cancel

    Получить уведомление об отмене операции

Переводной кошелёк

  • POST /game/v5/cash/deposit

    Перевести средства в игровой кошелёк игрока

  • POST /game/v5/cash/withdraw

    Перевести средства из игрового кошелька игрока

  • POST /game/v5/cash/balance

    Запросить баланс игрового кошелька игрока

  • POST /game/v5/cash/transaction

    Получить постраничный список записей операций кошелька

  • POST {CONTROLLED-PATH:FUND-RECOVERY}

    Вернуть все средства из игрового кошелька игрока через контролируемую операцию

Записи и мерчант

  • POST /game/v5/game/record

    Получить постраничный список игровых записей

  • POST {CONTROLLED-PATH:MERCHANT-CONFIGURATION}

    Запросить конфигурацию мерчанта и сведения о кошельке через контролируемую операцию

POST/game/v5/game/urlСоздать игровую сессию

Создаёт игровую сессию для указанного игрока и возвращает URL, по которому можно запустить игру.

Аутентификация: общие заголовки запросаContent-Type: application/json

Поля запроса

ПолеТипОбязательноОписание
reqTraceIdstringОбязательноУникальный идентификатор запроса; его нельзя использовать повторно
gameCodestringОбязательноКод игры
playerIdstringОбязательноУникальный идентификатор игрока на стороне мерчанта
currencyCodestringОбязательноКод валюты кошелька
languagestringОбязательноЯзык игрового интерфейса
terminalTypestringНеобязательноТип терминала: PHONE или PC; по умолчанию PHONE
returnUrlstringНеобязательноURL возврата после выхода игрока из игры
ipAddressstringОбязательноIPv4- или IPv6-адрес игрока
subMerchantCodestringНеобязательноКод субмерчанта; не может содержать символ подчёркивания
nickNamestringНеобязательноПсевдоним игрока
avatarUrlstringНеобязательноURL аватара игрока
Запрос
{
  "reqTraceId": "trace-demo-001",
  "gameCode": "{game-code}",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "language": "en",
  "terminalType": "PC",
  "returnUrl": "https://{merchant-host}/lobby",
  "ipAddress": "192.0.2.10"
}
Ответ
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameCode": "{game-code}",
    "playerId": "player-demo-001",
    "gameUrl": "https://{game-launch-host}/session/{token}",
    "expireTime": "2026-08-08T10:30:00Z"
  }
}

Поля ответа

ПолеТипВозвращаетсяОписание
data.gameCodestringОбязательноКод игры
data.playerIdstringОбязательноИдентификатор игрока
data.gameUrlstringОбязательноURL запуска игры
data.expireTimestringНеобязательноВремя истечения сессии

POST{MERCHANT-URL}/wallet/winОбратный вызов расчёта кошелька

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

Направление: платформа → мерчантТип: win / bet_win

Поля запроса

ПолеТипОбязательноОписание
reqTraceIdstringОбязательноУникальный идентификатор запроса
playerIdstringОбязательноУникальный идентификатор игрока на стороне мерчанта
currencyCodestringОбязательноКод валюты кошелька
gameCodestringОбязательноКод игры
transactionIdstringОбязательноУникальный идентификатор операции платформы
roundIdstringОбязательноУникальный идентификатор игрового раунда
betIdstringОбязательноИдентификатор связанной ставки
betAmountstringОбязательноСумма ставки по этой операции
winAmountstringОбязательноСумма выплаты по этой операции
isFreebooleanОбязательноСоздана ли запись бесплатной игрой
isEndbooleanОбязательноЗавершён ли текущий игровой раунд
betTimestringОбязательноВремя ставки
settledTimestringОбязательноВремя расчёта
typestringОбязательноТип уведомления: win или bet_win
Запрос обратного вызова
{
  "reqTraceId": "trace-demo-002",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "gameCode": "{game-code}",
  "transactionId": "txn-demo-002",
  "roundId": "round-demo-001",
  "betId": "bet-demo-001",
  "betAmount": "10.00",
  "winAmount": "18.50",
  "isFree": false,
  "isEnd": true,
  "betTime": "2026-08-08T10:00:00Z",
  "settledTime": "2026-08-08T10:00:08Z",
  "type": "bet_win"
}
Ответ мерчанта
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "merchantBetId": "merchant-bet-demo-001",
    "balance": "108.50"
  }
}

POST/game/v5/cash/depositПеревести средства в игровой кошелёк

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

Модель кошелька: переводной кошелёкКлюч операции: merchantTransactionId

Поля запроса

ПолеТипОбязательноОписание
reqTraceIdstringОбязательноУникальный идентификатор запроса для трассировки
playerIdstringОбязательноУникальный идентификатор игрока на стороне мерчанта
currencyCodestringОбязательноКод валюты кошелька
amountstringОбязательноСумма перевода
merchantTransactionIdstringОбязательноУникальный идентификатор операции мерчанта для сверки операций
Запрос
{
  "reqTraceId": "trace-demo-003",
  "playerId": "player-demo-001",
  "currencyCode": "{currency-code}",
  "amount": "100.00",
  "merchantTransactionId": "merchant-txn-demo-001"
}
Ответ
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "balance": "100.00"
  }
}
Сверка операций

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

POST/game/v5/game/recordЗапросить игровые записи

Запрашивает записи ставок и выплат игрока по диапазону времени с постраничной выдачей.

Поля запроса

ПолеТипОбязательноОписание
reqTraceIdstringОбязательноУникальный идентификатор запроса
pageNumintegerОбязательноНомер страницы
pageSizeintegerОбязательноКоличество записей на странице
reqData.startTimestringОбязательноВремя начала запроса
reqData.endTimestringОбязательноВремя окончания запроса
sortstringНеобязательноПорядок сортировки
Запрос
{
  "reqTraceId": "trace-demo-004",
  "pageNum": 1,
  "pageSize": 50,
  "reqData": {
    "startTime": "2026-08-08T00:00:00Z",
    "endTime": "2026-08-08T23:59:59Z"
  },
  "sort": "DESC"
}
Ответ
{
  "code": "C10000",
  "msg": "Request succeeded",
  "success": true,
  "data": {
    "gameRecordList": [{
      "orderNo": "order-demo-001",
      "playerId": "player-demo-001",
      "betAmount": "10.00",
      "winAmount": "18.50",
      "betTime": "2026-08-08T10:00:00Z",
      "winTime": "2026-08-08T10:00:08Z",
      "gameCode": "{game-code}",
      "currencyCode": "{currency-code}",
      "roundId": "round-demo-001"
    }]
  }
}

Коды ошибок

КодСообщениеДействие
C10000Запрос выполнен успешноЗапрос выполнен успешно
C10001Исключение базового сервисаИсключение базового сервиса
C10002Ошибка параметров запросаПроверьте поля запроса и типы данных
C10003Недопустимый заголовок запросаПроверьте пять общих заголовков запроса
C10004Ошибка подписиПроверьте порядок подписи, ключ и исходное тело запроса
C20001Отсутствует код мерчантаПроверьте код мерчанта
G10001Исключение игрового сервисаИсключение игрового сервиса
G20001Пустой ID игрокаУкажите playerId
G20002Отсутствует ID игрыПроверьте код игры
G20003Игра отключенаИгра отключена или недоступна
G30001Сессия игрового пользователя истеклаСоздайте новую игровую сессию
G30002Недостаточный баланс мерчантаБаланс мерчанта недостаточен
G30003Недостаточный баланс игрокаБаланс игрока недостаточен
G40001Исключение стороннего сервисаИсключение стороннего сервиса

Технические вопросы

Как AG API формирует подпись запроса?

Сериализуйте окончательное тело запроса как body, затем без разделителей соедините merchantCode + timestamp + nonce + signType + body именно в таком порядке. signType фиксирован как HmacSHA256. Вычислите HMAC-SHA256 с ключом подписи и поместите результат в X-SIGN. Тело, использованное для подписи, должно в точности совпадать с отправленным телом.

Почему возвращается C10004?

C10004 означает ошибку проверки подписи. Сначала проверьте код мерчанта, метку времени, nonce, ключ подписи и фиксированный тип HmacSHA256. Затем убедитесь, что промежуточное ПО не сериализовало подписанную JSON-строку повторно, не изменило порядок полей или пробелы. Для диагностики сохраняйте reqTraceId и время запроса, но никогда не записывайте ключ подписи.

Чем отличается единый кошелёк от переводного?

В режиме единого кошелька мерчант ведёт баланс игрока, а платформа взаимодействует с кошельком мерчанта через обратные вызовы баланса, ставки и расчёта. В режиме переводного кошелька мерчант вызывает такие конечные точки, как /game/v5/cash/deposit и /game/v5/cash/withdraw, чтобы переводить средства между системой мерчанта и игровым кошельком игрока. Используемая модель зависит от конфигурации интеграции мерчанта; их нельзя смешивать в одном потоке операций.

Как обрабатывать повторные обратные вызовы кошелька?

Мерчант должен использовать transactionId как основу идемпотентности для операций обратного вызова. При повторном поступлении той же операции верните ранее подтверждённый результат обработки и баланс; не списывайте и не зачисляйте сумму повторно. Сохраняйте запрос, бизнес-результат и окончательный баланс для сверки. Необходимость /wallet/bet и /wallet/cancel по-прежнему определяется окончательным списком обратных вызовов мерчанта.

Можно ли сразу повторить перевод после тайм-аута?

Не создавайте новую операцию и не повторяйте перевод, пока результат неизвестен. Сначала используйте исходный merchantTransactionId для вызова /game/v5/cash/transaction и запроса результата, затем решайте об отправке повторно согласно окончательному техническому соглашению. Это предотвращает двойной учёт, если первый запрос был успешен, но его ответ потерялся в сети.

Для чего нужны reqTraceId и merchantTransactionId?

reqTraceId — уникальный идентификатор трассировки каждого запроса. Он связывает журналы вызовов и помогает диагностировать один запрос; его следует генерировать и записывать для каждого запроса, включая повторные. merchantTransactionId — уникальный идентификатор операции на стороне мерчанта, используемый для сверки переводов, запросов результата и предотвращения повторной обработки одной бизнес-операции. У них разные назначения, и они не заменяют друг друга.

Как создаётся игровая сессия игрока?

Получите доступный gameCode из каталога игр, подготовьте идентификатор игрока, валюту, язык и IP-адрес, затем вызовите /game/v5/game/url с общими заголовками запроса. Успешный ответ возвращает gameUrl и может вернуть expireTime; клиент должен открыть URL, пока сессия действительна.

Как запрашиваются игровые записи игрока?

Вызовите /game/v5/game/record с pageNum, pageSize и диапазоном reqData.startTime и reqData.endTime; при необходимости можно передать sort. Из gameRecordList в ответе считывайте записи заказа, игрока, суммы ставки, выплаты, кода игры и раунда и продолжайте запросы по страницам.

Проверки перед запуском

Разделяйте тестовую и рабочую среды. Храните ключи на сервере, не передавайте их в браузер, журналы или чат. Проверяйте тайм-ауты, повторы, отмены и сверку по идентификаторам транзакций. Согласуйте рабочую конфигурацию и контролируемые операции с командой интеграции.

Начать процесс интеграции

AG GAME

Обсудим ваш проект

Связаться с нами
TelegramWhatsApp