Перейти к содержанию

API методы

Платформа предоставляет REST API для работы с играми. Все запросы должны быть подписаны согласно разделу Авторизация.

Базовый URL

URL для доступа к API будет предоставлен менеджером платформы.

Общий формат запросов

Метод

Все запросы используют метод POST.

Заголовки

Все запросы должны содержать следующие заголовки:

  • Content-Type: application/json
  • X-Signature: {подпись_запроса} - подпись запроса, сгенерированная согласно разделу Авторизация

Формат тела запроса

Все данные передаются в JSON формате в теле запроса. Обязательные поля для всех запросов:

  • agent_id (integer) - ID агента
  • timestamp (integer) - Unix timestamp запроса

Формат ответа

Все успешные ответы имеют унифицированную структуру и возвращаются с HTTP статусом 200 OK:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "unique-request-id",
  "content": {
    // Данные ответа
  }
}

Ответы с ошибками возвращаются с соответствующими HTTP кодами ошибок (4xx, 5xx):

{
  "status": "error",
  "error": "error_code",
  "message": "Описание ошибки",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "unique-request-id"
}

Важно

Считайте все HTTP ответы, кроме статуса 200 OK, как ошибки. Даже если в теле ответа есть данные, при статусе отличном от 200, запрос следует обрабатывать как неуспешный.

Методы API

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

Генерирует уникальную ссылку для запуска игры с указанными параметрами.

Endpoint: POST /api/games/get_game_link

Параметры запроса:

Параметр Тип Обязательный Описание
agent_id integer Да ID агента
timestamp integer Да Unix timestamp запроса
game_id integer Да ID игры
player_id string Да Уникальный ID игрока в системе агента. Должен быть уникальным для каждого игрока
player_username string Да Имя пользователя игрока. Может быть неуникальным
language string Да Код языка (ru, en, и т.д.)
currency string Да Код валюты (RUB, USD, EUR, и т.д.)
home_url string Да URL возврата для игрока. Используется в некоторых играх для кнопки "Home"
agent_session_id string Да ID сессии агента
ip string Да IP адрес игрока

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

{
  "agent_id": 1,
  "timestamp": 1640995200,
  "game_id": 123,
  "player_id": "player_123",
  "player_username": "john_doe",
  "language": "ru",
  "currency": "RUB",
  "home_url": "https://example.com",
  "agent_session_id": "session_abc123",
  "ip": "192.168.1.1"
}

Пример успешного ответа:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "content": {
    "url": "https://game.example.com/play?token=abc123&gameId=123&playerId=player_123"
  }
}

Возможные ошибки:

  • invalid_signature (403) - неверная подпись запроса
  • agent_not_found (404) - агент не найден
  • game_not_found (404) - игра не найдена
  • game_not_available (403) - игра недоступна для данного агента
  • validation_error (422) - ошибка валидации параметров

Пример ответа с ошибкой:

{
  "status": "error",
  "error": "game_not_found",
  "message": "Game not found",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da"
}

Получить ссылку на демо-игру

Генерирует ссылку для запуска демо-версии игры без создания игровой сессии. Демо-версия позволяет игроку попробовать игру без использования реальных денег.

Endpoint: POST /api/games/get_game_link_demo

Параметры запроса:

Параметр Тип Обязательный Описание
agent_id integer Да ID агента
timestamp integer Да Unix timestamp запроса
game_id integer Да ID игры
player_id string Да Уникальный ID игрока в системе агента. Должен быть уникальным для каждого игрока
player_username string Да Имя пользователя игрока. Может быть неуникальным
language string Да Код языка (ru, en, и т.д.)
currency string Да Код валюты (RUB, USD, EUR, и т.д.)
home_url string Да URL возврата для игрока. Используется в некоторых играх для кнопки "Home"
ip string Да IP адрес игрока

Отличия от обычной ссылки

  • Не требуется параметр agent_session_id (сессия не создается)
  • Игрок получает виртуальный баланс для демо-игры
  • Результаты игры не сохраняются

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

{
  "agent_id": 1,
  "timestamp": 1640995200,
  "game_id": 123,
  "player_id": "player_123",
  "player_username": "john_doe",
  "language": "ru",
  "currency": "RUB",
  "home_url": "https://example.com",
  "ip": "192.168.1.1"
}

Пример успешного ответа:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "content": {
    "url": "https://game.example.com/demo?token=abc123&gameId=123&playerId=player_123"
  }
}

Возможные ошибки:

  • invalid_signature (403) - неверная подпись запроса
  • agent_not_found (404) - агент не найден
  • game_not_found (404) - игра не найдена
  • game_not_available (403) - игра недоступна для данного агента
  • game_provider_not_found (404) - нет провайдера с поддержкой демо для данной игры
  • validation_error (422) - ошибка валидации параметров

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

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

Endpoint: POST /api/games/list

Параметры запроса:

Параметр Тип Обязательный Описание
agent_id integer Да ID агента
timestamp integer Да Unix timestamp запроса

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

{
  "agent_id": 1,
  "timestamp": 1640995200
}

Пример успешного ответа:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "content": {
    "games": [
      {
        "id": 1,
        "title": "Champagne Party",
        "brand": "Mega",
        "image_url": "https://cdn.example.com/images/games/champagne_party.jpg",
        "demo": true
      },
      {
        "id": 2,
        "title": "Book of Fortune",
        "brand": "Mega",
        "image_url": "https://cdn.example.com/images/games/book_of_fortune.jpg",
        "demo": false
      }
    ],
    "total": 2
  }
}

Описание полей ответа:

Поле Тип Описание
games array Массив объектов игр
games[].id integer Уникальный ID игры
games[].title string Отображаемое название игры
games[].brand string Бренд игры
games[].image_url string URL изображения игры
games[].demo boolean Доступность демо-версии игры. true если игра поддерживает демо-режим, false если демо недоступно
total integer Общее количество игр в списке

Возможные ошибки:

  • invalid_signature (403) - неверная подпись запроса
  • agent_not_found (404) - агент не найден
  • validation_error (422) - ошибка валидации параметров

Обработка ошибок

Платформа возвращает HTTP коды статусов для индикации результата запроса:

  • 200 OK - запрос успешно обработан
  • 4xx - ошибки клиента (неверный запрос, неавторизован, не найдено и т.д.)
  • 5xx - ошибки сервера (внутренние ошибки платформы)

Важно

Считайте все HTTP ответы, кроме статуса 200 OK, как ошибки. При получении любого статуса отличного от 200, обрабатывайте запрос как неуспешный, даже если в теле ответа присутствуют данные.

Коды ошибок

Код ошибки HTTP статус Описание
signature_required 401 Отсутствует заголовок X-Signature
invalid_signature 403 Неверная подпись запроса
agent_not_found 404 Агент с указанным ID не найден
api_token_not_found 404 У агента не настроен API токен
game_not_found 404 Игра с указанным ID не найдена
game_not_available 403 Игра недоступна для данного агента
method_not_allowed 405 Использован неподдерживаемый HTTP метод
validation_error 422 Ошибка валидации входных данных
request_expired 400 Запрос устарел (timestamp слишком старый)

Рекомендации по использованию

Кэширование списка игр

  • Список игр не меняется часто, рекомендуется кэшировать его на стороне агента
  • Обновляйте кэш раз в несколько часов или при необходимости

Обработка ошибок

  • Всегда проверяйте HTTP статус ответа. Считайте все ответы, кроме 200 OK, как ошибки
  • При ошибке invalid_signature проверьте правильность генерации подписи
  • При ошибке request_expired убедитесь, что используете актуальное время сервера