API Документация

Обзор

Наш API позволяет администраторам игровых серверов интегрировать систему поощрения за голосование на нашем топе. Игроки, проголосовавшие за ваш сервер, могут получить награду на вашем сайте.

Базовый URL API: https://mmorating.top/api/v1

Как привязать голос к игроку на вашем сайте

pingback (рекомендуется) — игрок жмёт «Голосовать» у вас, вы добавляете в ссылку токен своего аккаунта. MMORating не знает ваших персонажей и не обязан совпадать по email: после голоса токен вернётся в callback как есть.
Callback после голоса — как платёжка: мы сами POST-им на ваш URL. Работает и если игрок проголосовал прямо на mmorating.top (тогда ищите по email / нику, если pingback не было).
check-flexible — запасной опрос API, если callback не дошёл.

Получение API ключа

Войдите в свой аккаунт на mmorating.top
Перейдите в раздел "Мои сервера"
Найдите ваш сервер (должен быть одобрен администрацией)
В разделе "API для поощрения за голосование" нажмите "Создать API ключ"
Скопируйте полученный API ключ (он начинается с mmr_)

⚠️ Важно: Храните ваш API ключ в безопасности! Не публикуйте его в открытом доступе.

Рекомендуемая схема: pingback + callback

У MMORating нет базы персонажей ваших миров. Почта аккаунта на топе тоже может отличаться от почты на сайте сервера. Поэтому не стоит рассчитывать, что мы «узнаем» вашего игрока. Вы сами помечаете переход на голосование токеном — мы его сохраняем и возвращаем.

1. Ссылка на голосование с pingback

Когда игрок на вашем сайте нажимает «Голосовать», откройте страницу вашего сервера и добавьте параметр pingback (до 255 символов: латиница, цифры, ._~+=/-:):

https://mmorating.top/server/123?pingback=ВАШ_ТОКЕН

Токен — это идентификатор вашего игрока. Мы его не разбираем. Рекомендуется HMAC, чтобы чужой не подставил чужой id:

$userId = (int) $player['id'];
$pingback = $userId . '.' . hash_hmac('sha256', (string) $userId, $apiKey);
$voteUrl = 'https://mmorating.top/server/123?pingback=' . rawurlencode($pingback);

Токен попадает в сессию на странице сервера: игрок может сначала войти / зарегистрироваться на MMORating — pingback не потеряется.
После голоса (обычного или премиум) поле pingback уходит в callback и доступно в /vote/check-flexible.
Если игрок зашёл на топ сам, без вашей ссылки, pingback будет null. Тогда можно сопоставить по email / нику, если они у вас совпадают — это запасной путь, не основной.

2. Callback после голоса

В «Мои сервера» укажите URL уведомления, например https://your-game-site.com/api/votes/mmorating. После голоса MMORating отправит POST (как платёжная система).

Подпись: HMAC-SHA256 от строки {timestamp}.{raw_json_body} вашим API-ключом
Заголовки: X-MMR-Signature, X-MMR-Timestamp (окно 5 минут)
Сначала начислите по pingback. Email / username / character_name — только если pingback нет

{
  "event": "vote.created",
  "id": 12345,
  "server_id": 1,
  "world_id": 2,
  "voted_at": "2026-09-04T10:00:00+00:00",
  "vote_type": "normal",
  "character_name": "Thrall",
  "pingback": "42.a1b2c3...",
  "username": "PlayerNick",
  "email": "player@example.com",
  "ip_address": "1.2.3.4",
  "user_id": 99
}

user_id и email в payload — это аккаунт на mmorating.top, не на вашем сайте. Ответ 200 с {"ok":true} — повторно слать не нужно. 5xx — будет повтор.

$raw = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_MMR_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_MMR_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $timestamp . '.' . $raw, $apiKey);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
$payload = json_decode($raw, true);
$pingback = $payload['pingback'] ?? '';
if ($pingback) {
    [$userId, $hmac] = array_pad(explode('.', $pingback, 2), 2, '');
    if (hash_equals(hash_hmac('sha256', $userId, $apiKey), $hmac)) {
        creditVoteReward((int) $userId); // ваш игрок
    }
}
echo json_encode(['ok' => true]);

API Endpoints

POST `/api/v1/vote/check` (Legacy - для обратной совместимости)

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

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

Параметр	Тип	Обязательный	Описание
`api_key`	string	Да	Ваш API ключ
`ip_address`	string (IP)	Да	IP адрес игрока, для которого проверяется голосование

Пример запроса (cURL):

curl -X POST "https://mmorating.top/api/v1/vote/check" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "mmr_your_api_key_here",
    "ip_address": "192.168.1.1"
  }'

Пример запроса (PHP):

$apiKey = 'mmr_your_api_key_here';
$ipAddress = $_SERVER['REMOTE_ADDR']; // IP адрес игрока

$data = [
    'api_key' => $apiKey,
    'ip_address' => $ipAddress
];

$ch = curl_init('https://mmorating.top/api/v1/vote/check');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($result['success'] && $result['has_voted']) {
    // Игрок проголосовал - выдайте награду
    echo "Игрок проголосовал! Выдайте награду.";
} else {
    // Игрок не голосовал сегодня
    echo "Игрок еще не голосовал сегодня.";
}

Пример ответа (успех):

{
  "success": true,
  "has_voted": true,
  "server_id": 1,
  "server_name": "Название сервера",
  "checked_at": "2026-02-05T12:00:00+00:00"
}

Пример ответа (не голосовал):

{
  "success": true,
  "has_voted": false,
  "server_id": 1,
  "server_name": "Название сервера",
  "checked_at": "2026-02-05T12:00:00+00:00"
}

Пример ответа (ошибка):

{
  "success": false,
  "error": "Invalid API key"
}

GET `/api/v1/server/info`

Получает информацию о сервере по API ключу.

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

Параметр	Тип	Обязательный	Описание
`api_key`	string	Да	Ваш API ключ

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

curl -X GET "https://mmorating.top/api/v1/server/info?api_key=mmr_your_api_key_here" \
  -H "Accept: application/json"

Пример ответа:

{
  "success": true,
  "server": {
    "id": 1,
    "name": "Название сервера",
    "game_type": "l2",
    "website": "https://example.com",
    "worlds": [
      {
        "id": 1,
        "name": "Название мира",
        "type": "pvp",
        "version": "Interlude"
      }
    ]
  }
}

POST `/api/v1/vote/check-flexible` (Рекомендуется)

Запасной метод, если callback не дошёл. Можно проверить голос по pingback (токен с вашей ссылки), имени персонажа, email, user_id MMORating или IP. У MMORating нет вашей базы персонажей: character_name сработает только если игрок сам ввёл этот текст в форму голоса.

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

Параметр	Тип	Обязательный	Описание
`api_key`	string	Да	Ваш API ключ
`pingback`	string	Нет*	Токен, который вы передали в ссылке `?pingback=`. Искать нужно тем же значением, что отправляли.
`character_name`	string	Нет*	Текст, который игрок указал в форме голоса (ник/логин/email поля награды). Это не поиск по вашей игровой БД.
`user_id`	integer	Нет*	ID пользователя на mmorating.top
`email`	string (email)	Нет*	Email адрес пользователя
`ip_address`	string (IP)	Нет*	IP адрес игрока (для обратной совместимости)

* Нужен хотя бы один из: pingback, character_name, user_id, email, ip_address

** Несколько параметров сразу — логика AND (все должны совпасть). Для pingback передавайте только его.

Пример запроса (по pingback):

curl -X POST "https://mmorating.top/api/v1/vote/check-flexible" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "mmr_your_api_key_here",
    "pingback": "42.a1b2c3..."
  }'

Пример запроса (по имени персонажа):

curl -X POST "https://mmorating.top/api/v1/vote/check-flexible" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "mmr_your_api_key_here",
    "character_name": "PlayerName"
  }'

Пример запроса (по email):

curl -X POST "https://mmorating.top/api/v1/vote/check-flexible" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "mmr_your_api_key_here",
    "email": "player@example.com"
  }'

Пример запроса (комбинированная проверка):

curl -X POST "https://mmorating.top/api/v1/vote/check-flexible" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "mmr_your_api_key_here",
    "character_name": "PlayerName",
    "email": "player@example.com"
  }'

Пример ответа (успех - голосовал):

{
  "success": true,
  "has_voted": true,
  "server_id": 1,
  "server_name": "Название сервера",
  "checked_at": "2026-02-05T12:00:00+00:00",
  "checked_by": ["character_name", "email"],
  "vote_info": {
    "voted_at": "2026-02-05T10:30:00+00:00",
    "character_name": "PlayerName",
    "vote_type": "normal"
  }
}

Пример ответа (не голосовал):

{
  "success": true,
  "has_voted": false,
  "server_id": 1,
  "server_name": "Название сервера",
  "checked_at": "2026-02-05T12:00:00+00:00",
  "checked_by": ["character_name"],
  "vote_info": null
}

Пример интеграции PHP (по имени персонажа):

<?php
// config.php
define('MMORATING_API_KEY', 'mmr_your_api_key_here');
define('MMORATING_API_URL', 'https://mmorating.top/api/v1/vote/check-flexible');

// vote_check.php
function checkVoteOnMMORating($characterName) {
    $data = [
        'api_key' => MMORATING_API_KEY,
        'character_name' => $characterName
    ];
    
    $ch = curl_init(MMORATING_API_URL);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Accept: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        return false;
    }
    
    $result = json_decode($response, true);
    
    return isset($result['success']) && $result['success'] && $result['has_voted'];
}

// Использование в игре
$playerName = $_GET['player_name']; // Имя персонажа из игры
if (checkVoteOnMMORating($playerName)) {
    // Игрок проголосовал - выдайте награду по имени персонажа
    giveRewardToPlayer($playerName);
    echo "Спасибо за голос! Награда выдана.";
} else {
    echo "Пожалуйста, проголосуйте за наш сервер на https://mmorating.top";
}
?>

Пример интеграции PHP (по email):

<?php
function checkVoteByEmail($email) {
    $data = [
        'api_key' => MMORATING_API_KEY,
        'email' => $email
    ];
    
    $ch = curl_init(MMORATING_API_URL);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Accept: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        return false;
    }
    
    $result = json_decode($response, true);
    return isset($result['success']) && $result['success'] && $result['has_voted'];
}

// Использование
$userEmail = $_SESSION['user_email']; // Email из вашей системы
if (checkVoteByEmail($userEmail)) {
    giveRewardToUser($userEmail);
}
?>

Важные замечания

Рекомендуемый метод: ссылка с ?pingback= + callback URL. /api/v1/vote/check-flexible — запасной опрос, в том числе по тому же pingback.
pingback: единственный надёжный способ, если почта на топе другая и персонажи живут только в вашей игре. Токен должен быть подписан (HMAC), иначе любой сможет подставить чужой id.
Проверка по имени персонажа: сработает, только если игрок ввёл этот текст в форму на MMORating. Мы не ходим в вашу игровую базу.
Проверка по email: email аккаунта MMORating, не вашего сайта — используйте как запас, если игрок голосовал прямо на топе без вашей ссылки.
Проверка по IP (legacy): старый метод /api/v1/vote/check. IP часто меняется (мобильный интернет).
Комбинированная проверка: несколько параметров в check-flexible — логика AND (все должны совпасть).
Время обновления: Возможность голосовать обновляется каждый день в 00:01 по серверному времени.
Безопасность: Никогда не передавайте API ключ на клиентскую сторону. Все запросы должны выполняться с вашего сервера.
Rate Limiting: Рекомендуется кэшировать результаты проверки на вашей стороне, чтобы не делать лишние запросы.
Обратная совместимость: Старый метод /api/v1/vote/check продолжает работать для существующих интеграций. Нет необходимости обновлять код, если текущая система работает нормально.
Ошибки: При ошибке API возвращает HTTP статус 400/401 и JSON с полем error.

Примеры интеграции

Пример 1: Проверка по pingback

<?php
define('MMORATING_API_KEY', 'mmr_your_api_key_here');
define('MMORATING_API_URL', 'https://mmorating.top/api/v1/vote/check-flexible');

function checkVoteByPingback($pingback) {
    $data = [
        'api_key' => MMORATING_API_KEY,
        'pingback' => $pingback,
    ];

    $ch = curl_init(MMORATING_API_URL);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Accept: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        return false;
    }

    $result = json_decode($response, true);
    return !empty($result['success']) && !empty($result['has_voted']);
}
?>

Пример 2: Проверка по имени персонажа (если игрок ввёл ник в форме на топе)

<?php
// config.php
define('MMORATING_API_KEY', 'mmr_your_api_key_here');
define('MMORATING_API_URL', 'https://mmorating.top/api/v1/vote/check-flexible');

// vote_check.php
function checkVoteByCharacterName($characterName) {
    $data = [
        'api_key' => MMORATING_API_KEY,
        'character_name' => $characterName
    ];
    
    $ch = curl_init(MMORATING_API_URL);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Accept: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        return false;
    }
    
    $result = json_decode($response, true);
    return isset($result['success']) && $result['success'] && $result['has_voted'];
}

// Использование в игре
$playerName = $_GET['player_name']; // Имя персонажа из игры
if (checkVoteByCharacterName($playerName)) {
    // Игрок проголосовал - выдайте награду по имени персонажа
    giveRewardToPlayer($playerName);
    echo "Спасибо за голос! Награда выдана.";
} else {
    echo "Пожалуйста, проголосуйте за наш сервер на https://mmorating.top";
}
?>

Пример 2: Проверка по IP (legacy - для обратной совместимости)

<?php
// config.php
define('MMORATING_API_KEY', 'mmr_your_api_key_here');
define('MMORATING_API_URL', 'https://mmorating.top/api/v1/vote/check');

// vote_check.php
function checkVoteOnMMORating($playerIp) {
    $data = [
        'api_key' => MMORATING_API_KEY,
        'ip_address' => $playerIp
    ];
    
    $ch = curl_init(MMORATING_API_URL);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Accept: application/json'
    ]);
    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        return false;
    }
    
    $result = json_decode($response, true);
    return isset($result['success']) && $result['success'] && $result['has_voted'];
}

// Использование
$playerIp = $_SERVER['REMOTE_ADDR'];
if (checkVoteOnMMORating($playerIp)) {
    giveRewardToPlayer($playerName);
    echo "Спасибо за голос! Награда выдана.";
} else {
    echo "Пожалуйста, проголосуйте за наш сервер на https://mmorating.top";
}
?>

Поддержка

Если у вас возникли вопросы по использованию API, свяжитесь с нами через форму обратной связи или напишите на email администрации.

Обзор

Получение API ключа

Рекомендуемая схема: pingback + callback

1. Ссылка на голосование с pingback

2. Callback после голоса

API Endpoints

POST /api/v1/vote/check (Legacy - для обратной совместимости)

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

Пример запроса (cURL):

Пример запроса (PHP):

Пример ответа (успех):

Пример ответа (не голосовал):

Пример ответа (ошибка):

GET /api/v1/server/info

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

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

Пример ответа:

POST /api/v1/vote/check-flexible (Рекомендуется)

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

Пример запроса (по pingback):

Пример запроса (по имени персонажа):

Пример запроса (по email):

Пример запроса (комбинированная проверка):

Пример ответа (успех - голосовал):

Пример ответа (не голосовал):

Пример интеграции PHP (по имени персонажа):

Пример интеграции PHP (по email):

Важные замечания

Примеры интеграции

Пример 1: Проверка по pingback

Пример 2: Проверка по имени персонажа (если игрок ввёл ник в форме на топе)

Пример 2: Проверка по IP (legacy - для обратной совместимости)

Поддержка

Сервер отправлен на модерацию

POST `/api/v1/vote/check` (Legacy - для обратной совместимости)

GET `/api/v1/server/info`

POST `/api/v1/vote/check-flexible` (Рекомендуется)