Интеграция

Соглашения

Запросы и ответы#

Серверные вызовы — POST с Content-Type: application/json и JSON-объектом в теле.
Успешные ответы содержат "status": "ok" и поля результата.
Ошибки — {"status":"error","message":"<CODE>"}; HTTP-статус зависит от кода. message всегда код в верхнем регистре; см. справочник ошибок. Сбой без публичного кода — REQUEST_FAILED.
Ответы отправляются с Cache-Control: no-store.
Публичные GET-методы тоже возвращают JSON: /games/health, /capabilities, /health, /docs/openapi.json.

HTTP	Типичный смысл
200	Успех
400	Ошибка валидации или бизнес-правила (`INVALID_REQUEST`, `PROJECT_BET_LIMIT`, …)
401	`UNAUTHORIZED`
403	`IP_NOT_ALLOWED` (или `FORBIDDEN`)
404	Неизвестная игра или запись (`UNSUPPORTED_GAME`, `GAME_NOT_FOUND`, `GRANT_NOT_FOUND`, `OUTCOME_NOT_FOUND`)
409	`IDEMPOTENCY_CONFLICT`, `DUPLICATE_EXTERNAL_ID`

Идемпотентность#

POST /playGame.do и POST /gameActions.do принимают необязательный заголовок Idempotency-Key: от 1 до 128 печатных ASCII-символов (без пробелов).

Ключ действует в рамках вашего проекта и метода.
Повтор запроса с тем же ключом и тем же телом возвращает первый ответ без повторного выполнения.
Тот же ключ с другим телом даёт HTTP 409 IDEMPOTENCY_CONFLICT.
Поле api_key в сравнении не участвует.
Некорректный ключ даёт HTTP 400 INVALID_IDEMPOTENCY_KEY.
Без заголовка вызов выполняется каждый раз. Для freespins_create и outcome_schedule от дублей защищает ещё и поле external_id (DUPLICATE_EXTERNAL_ID).

Суммы#

Контекст	Формат
Callbacks кошелька	число JSON не более чем с 2 знаками после запятой (`12.5`, `100`)
`bet`, `total_win` фриспинов	десятичная строка, до 2 знаков (`"1.00"`)
`min_minor`, `max_minor`	строка из цифр, минорные единицы

Принимается не более двух знаков после запятой и не более 13 цифр до неё; ведущие нули недопустимы. Суммы точные — разбирайте их десятичным типом, а не числом с плавающей точкой.

Даты и время#

Поля expires_at, created_at, finished_at и подобные — ISO 8601. Когда вы отправляете expires_at, в нём обязателен часовой пояс (Z или +02:00), например 2026-11-01T12:00:00Z.
Callbacks кошелька несут Unix-время в секундах (meta.time, timestamp).

Идентификаторы#

Id	Откуда берётся
`player_id`	Задаёте вы (1–128 символов)
`session_id`	Возвращается методом запуска
`round_id`	Создаёт платформа; есть в callbacks кошелька и в админ-панели (Game History)
`meta.transaction`	Уникальный id каждой операции кошелька (`bet`, `win`)
`grant_id`, `outcome_id`	UUID, создаёт платформа
`external_id`	Необязательный ваш id выдач и исходов, уникален в проекте (1–128 печатных символов без пробелов)

Неизвестные поля#

Метод запуска отклоняет неизвестные поля с INVALID_REQUEST. Отправляйте только описанные поля.

Тайм-ауты и повторы с вашей стороны#

Используйте клиентский тайм-аут около 10 секунд; при тайм-ауте или 5xx повторите вызов с тем же Idempotency-Key.