API нагород за голоси

Видавайте гравцям ігрову нагороду за голосування. Є два способи отримувати голоси, обидва працюють з одним ключем і обидва розраховані на сервер за NAT або такий, що перезапускається двічі на день.

1. Отримайте ключ

Відкрийте свій сервер у розділі Мої сервери → Нагороди за голоси, увімкніть нагороди й скопіюйте API-ключ. Передавайте його в заголовку кожного запиту:

Authorization: Bearer YOUR_API_KEY

Ніколи не передавайте ключ в URL. Він потрапить у журнали доступу, журнали проксі та історію браузера.

2. Дізнайтеся, що ви маєте видати

POST /api/v1/rewards/pending повертає неотримані нагороди, починаючи з найстаріших.

curl -X POST https://xtremetop300.com/api/v1/rewards/pending \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

{
  "server":  { "id": 1234, "name": "My Server" },
  "count":   2,
  "more":    false,
  "rewards": [
    { "token": "8f2c...", "player": "Steve",  "server_id": 1234, "voted_at": "2026-08-25T09:14:02+00:00" },
    { "token": "1a90...", "player": "Alexia", "server_id": 1234, "voted_at": "2026-08-25T09:31:44+00:00" }
  ]
}

Читання нічого не списує. Видайте нагороди, а потім підтвердьте їх:

curl -X POST https://xtremetop300.com/api/v1/rewards/claim \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tokens": ["8f2c...", "1a90..."]}'

{ "claimed": ["8f2c...", "1a90..."], "already_claimed": [], "unknown": [] }

3. Або просто поставте питання «так/ні»

Більшості плагінів потрібно лише знати, чи нагадувати гравцеві про голосування під час входу. GET /api/v1/rewards/check відповідає за ім’ям гравця або за IP-адресою.

curl "https://xtremetop300.com/api/v1/rewards/check?player=Steve&hours=24" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "voted": true, "voted_at": "2026-08-25T09:14:02+00:00", "window_hours": 24 }

4. Push, якщо потрібно миттєво

Вкажіть callback URL у налаштуваннях нагород, і щойно надходитиме голос, ми надсилатимемо на нього POST такого вигляду:

POST /your-callback HTTP/1.1
Content-Type: application/json
X-Xtreme300-Signature: sha256=4f1e...
X-Xtreme300-Timestamp: 1787654321
X-Xtreme300-Delivery: 8f2c...

{
  "event":   "vote.reward",
  "sent_at": 1787654321,
  "reward":  { "token": "8f2c...", "player": "Steve", "server_id": 1234, "voted_at": "..." }
}

Відповідайте будь-яким статусом 2xx. На будь-яку іншу відповідь ми повторюємо надсилання (кількість спроб: 5) протягом наступної години, а після цього нагорода просто чекає, поки її заберуть через pull. Статус 4xx вважається відмовою й не повторюється, тож не повертайте його у разі тимчасової проблеми.

5. Перевіряйте підпис

Надіслати POST на ваш callback URL може будь-хто. Саме підпис відрізняє справжній голос від незнайомця, який видає собі алмази. Обчисліть HMAC-SHA256(timestamp + "." + rawBody) за допомогою свого API-ключа й порівняйте результат із заголовком.

// PHP
$body      = file_get_contents('php://input');   // the raw body, before json_decode
$timestamp = (int) $_SERVER['HTTP_X_XTREME300_TIMESTAMP'];
$signature = $_SERVER['HTTP_X_XTREME300_SIGNATURE'];

// Reject old requests first. A valid signature on a captured request replayed
// a thousand times is the whole attack.
if (abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $apiKey);

// hash_equals, not ==. A normal comparison returns faster the earlier it finds
// a difference, which is enough to guess the signature one byte at a time.
if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

// Java (Bukkit / Paper / Spigot)
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));

byte[] digest = mac.doFinal((timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8));

StringBuilder hex = new StringBuilder("sha256=");
for (byte b : digest) hex.append(String.format("%02x", b));

if (!MessageDigest.isEqual(hex.toString().getBytes(), signatureHeader.getBytes())) {
    return; // not from us
}

6. Давайте гравцям посилання, яке вже їх знає

Додайте ім’я гравця до посилання на голосування, і поле буде заповнене заздалегідь, тож гравцеві залишиться лише натиснути кнопку. Підходить будь-який із параметрів player, pingUsername, username або nick — додаткові варіанти потрібні для того, щоб кнопку, яку ви вже зробили для іншого топу, можна було без змін перенаправити сюди.

https://xtremetop300.com/vote/1234?player=Steve

Правила, які варто знати

• Нагорода створюється лише за голос, який зараховано. Голоси, позначені нашими перевірками на шахрайство, нічого не дають, тож ферма ботів не зможе викачувати вашу ігрову валюту, не впливаючи на рейтинг.
• Один голос від гравця раз на 24 год. — той самий ліміт, що й у самому топі.
• Вважайте, що кожен токен може надійти більше одного разу. Зберігайте ті, за які вже видали нагороду, і ігноруйте повтори. Це єдине, що плагін зобов’язаний зробити правильно.
• Ніколи не підставляйте ім’я гравця напряму в консольну команду. Ми обмежуємо імена літерами, цифрами, пробілами, крапками, дефісами та підкресленнями, але ваш сервер усе одно має перевірити, що ім’я належить справжньому акаунту, перш ніж видавати нагороду.
• За замовчуванням ліміт нагород на один pull-запит — 50, максимум — 200. Стежте за полем more і, якщо воно true, робіть ще один запит.
• 60 запитів на хвилину для одного сервера. Опитування раз на хвилину витрачає лише один із них.
• Незабрані нагороди видаляються через 14 дн.

Ваш сервер уже в топі? Відкрийте налаштування сервера, щоб увімкнути нагороди. Ще не додали? Додайте свій сервер.