ETR API

Что такое ETR?

ETR (Eblan Trouble Register) — это бан-реестр для игровых серверов, управляемый сообществом. Серверы регистрируются в системе, и когда достаточное количество серверов голосует за бан игрока, он автоматически добавляется в чёрный список ETR.

Все зарегистрированные серверы могут проверять игроков по базе ETR при подключении и голосовать за добавление проблемных игроков. Когда 10% всех верифицированных серверов проголосуют за игрока, он автоматически блокируется.

Быстрый старт

Регистрация сервера через API (для аддонов)

Аддоны игровых серверов могут регистрироваться автоматически с помощью setup-токена:

POST https://sellingvika.party/etr/v3/auth/setup-token
(требуется сессия браузера — авторизованный пользователь)

POST https://sellingvika.party/etr/v3/servers/register
Header: Content-Type: application/json
Body: {
  "setup_token": "YOUR_TOKEN_HERE",
  "name": "My Game Server",
  "ip": "123.45.67.89",
  "port": "27015",
  "app_id": "4020",
  "description": "Optional description"
}

{
  "status": "registered",
  "server": {"id": 42, "name": "My Game Server", "ip": "123.45.67.89", "port": "27015", "app_id": "4020", "verified": false},
  "api_key": "abc123...64chars...",
  "api_secret": "xyz789...64chars...",
  "message": "Server registered. Save your key and secret."
}

Setup token is valid for 1 hour and can be reused to register multiple servers (within your account limits). You can generate 1 token per hour. Server must be verified by admin before it can vote.

Аутентификация

Все API-запросы (кроме регистрации сервера) требуют API-ключ. Передайте его одним из двух способов:

X-API-Key: your_64_char_key_here

Authorization: Bearer your_64_char_key_here

POST-запросы с телом должны включать Content-Type: application/json.

Типы API-ключей

Автономные ключи не могут голосовать или отправлять heartbeat — для этого нужен серверный ключ. Добавление игроков (add, add-bulk) требует разрешения can_add_users от админа и работает с любым типом ключа.

Limits

• Daily requests: 5,000 per account (all keys combined). Admin can adjust.
• Standalone keys: Max 1 per account.
• Registered servers: Max 10 per account.
• Bulk status check: Up to 100 Steam IDs per request (counts as 1 request).
• Per-minute: 100 requests per key per minute.

Как работает голосование

ETR использует систему голосования на уровне серверов:

• Каждый **верифицированный** сервер может проголосовать **один раз** за игрока (Steam ID).
• Голос означает: «этот сервер хочет добавить этого игрока в ETR».
• Когда **10% всех верифицированных серверов** проголосуют за игрока, он **автоматически** добавляется в ETR.
• Минимальный порог — 2 сервера (даже если 10% составляет меньше).
• Когда игрок уже в ETR, за него нельзя голосовать повторно.

Лимиты запросов

Заголовки ответа

Каждый API-ответ включает эти заголовки:

X-API-Version: 3
X-Request-Id: unique-uuid-per-request
X-Server-Time: 1711929600         (unix timestamp — use to sync your clock)
X-Security-Policy: hmac-optional; nonce-if-hmac; body-hash-if-hmac; ua-recommended
X-RateLimit-Limit: 10000          (daily limit)
X-RateLimit-Remaining: 9999       (remaining today)
X-RateLimit-Reset: 1711929600     (unix timestamp, end of day)
X-RateLimit-Minute-Limit: 100     (per-minute limit)
X-RateLimit-Minute-Remaining: 99  (remaining this minute)
Cache-Control: no-store
X-Content-Type-Options: nosniff

Тайминг Heartbeat

Эндпоинт heartbeat возвращает точное время для следующего heartbeat. Ваш аддон должен следовать инструкциям сервера по таймингу:

// After receiving a heartbeat response:
local nextIn = response.next_heartbeat_in  // e.g. 11025 seconds
timer.Simple(nextIn, function()
    sendHeartbeat()  // send next heartbeat after exactly `nextIn` seconds
end)

Сервер добавляет случайный джиттер (0-5 минут) к базовому интервалу, чтобы предотвратить одновременные запросы. Всегда используйте next_heartbeat_in из ответа вместо захардкоженного интервала.

HMAC-подпись РЕКОМЕНДУЕТСЯ

HMAC-подпись необязательна, но настоятельно рекомендуется. Её можно включить или отключить для каждого API-ключа в Настройки → Серверы. При включении каждый запрос должен содержать следующие заголовки безопасности:

Формула подписи

Signature = HMAC-SHA256(
  key:     your_api_secret,
  message: "METHOD:path:body:timestamp"
)

-- METHOD  = uppercase HTTP method (GET, POST, etc.)
-- path    = request path without domain (e.g. "etr/v3/status/76561190000000001")
-- body    = raw request body (empty string "" for GET requests)
-- timestamp = same value as X-Timestamp header

Example:
  HMAC-SHA256(secret, "POST:etr/v3/vote/76561190000000001:{\"reason\":\"cheat\"}:1711929600")

For GET requests (no body):
  HMAC-SHA256(secret, "GET:etr/v3/status/76561190000000001::1711929600")

GET https://sellingvika.party/etr/v3/time

Response: {
  "timestamp": 1711929600,
  "iso": "2026-03-25T14:00:00+00:00",
  "timezone": "UTC"
}

X-Server-Time: 1711929600

Примеры кода

const crypto = require("crypto");  // Node.js built-in

const API_KEY    = "your_64_char_api_key";
const API_SECRET = "your_64_char_api_secret";
const BASE_URL   = "https://sellingvika.party";

// Step 1: sync clock on startup
let timeOffset = 0;
async function syncClock() {
  const res = await fetch(`${BASE_URL}/etr/v3/time`);
  const data = await res.json();
  timeOffset = data.timestamp - Math.floor(Date.now() / 1000);
}

// Step 2: make signed API request
async function etrRequest(method, path, body = null) {
  const timestamp = String(Math.floor(Date.now() / 1000) + timeOffset);
  const nonce     = crypto.randomBytes(32).toString("hex");
  const bodyStr   = body ? JSON.stringify(body) : "";

  const headers = {
    "X-API-Key":  API_KEY,
    "User-Agent": "MyApp/1.0",
  };

  // HMAC signing (skip if HMAC disabled on your key)
  const payload   = `${method.toUpperCase()}:${path}:${bodyStr}:${timestamp}`;
  const signature = crypto.createHmac("sha256", API_SECRET)
                          .update(payload).digest("hex");
  headers["X-Signature"] = signature;
  headers["X-Timestamp"] = timestamp;
  headers["X-Nonce"]     = nonce;

  if (bodyStr) {
    headers["X-Body-SHA256"] = crypto.createHash("sha256")
                                     .update(bodyStr).digest("hex");
    headers["Content-Type"]  = "application/json";
  }

  const res = await fetch(`${BASE_URL}/${path}`, {
    method,
    headers,
    body: bodyStr || undefined,
  });
  return res.json();
}

// Usage
await syncClock();
const status = await etrRequest("GET", "etr/v3/status/76561190000000001");
console.log("In ETR:", status.status);

-- Uses HTTP() function (Garry's Mod) or your HTTP library
-- HMAC requires a sha256/hmac module (e.g. gmsv_hmac, luaossl, or pure-Lua impl)

local API_KEY    = "your_64_char_api_key"
local API_SECRET = "your_64_char_api_secret"
local BASE_URL   = "https://sellingvika.party"
local timeOffset = 0

-- Sync clock on startup
function ETR_SyncTime()
    http.Fetch(BASE_URL .. "/etr/v3/time", function(body)
        local data = util.JSONToTable(body)
        if data and data.timestamp then
            timeOffset = data.timestamp - os.time()
        end
    end)
end

-- Make an API request (User-Agent is optional — GMod sends "Half-Life 2" automatically)
function ETR_CheckPlayer(steamId, callback)
    http.Fetch(BASE_URL .. "/etr/v3/status/" .. steamId .. "?api_key=" .. API_KEY,
        function(body)
            local data = util.JSONToTable(body)
            if callback then callback(data) end
        end)
end

-- Example: check player on connect
hook.Add("PlayerAuthed", "ETR_Check", function(ply, steamId)
    ETR_CheckPlayer(steamId, function(data)
        if data and data.status == true then
            ply:Kick("You are in the ETR ban list.")
        end
    end)
end)

import hashlib, hmac, json, secrets, time, requests

API_KEY    = "your_64_char_api_key"
API_SECRET = "your_64_char_api_secret"
BASE_URL   = "https://sellingvika.party"

# Sync clock once on startup
_srv = requests.get(f"{BASE_URL}/etr/v3/time").json()
_offset = _srv["timestamp"] - int(time.time())

def etr_request(method, path, body=None):
    ts       = str(int(time.time()) + _offset)
    body_str = json.dumps(body, separators=(",",":")) if body else ""
    payload  = f"{method.upper()}:{path}:{body_str}:{ts}"
    sig      = hmac.new(API_SECRET.encode(), payload.encode(),
                        hashlib.sha256).hexdigest()
    headers  = {
        "X-API-Key": API_KEY, "User-Agent": "MyBot/1.0",
        "X-Signature": sig, "X-Timestamp": ts,
        "X-Nonce": secrets.token_hex(32),
    }
    if body_str:
        headers["X-Body-SHA256"] = hashlib.sha256(body_str.encode()).hexdigest()
        headers["Content-Type"]  = "application/json"
    return requests.request(method, f"{BASE_URL}/{path}",
                            headers=headers, data=body_str or None).json()

# Check a player
print(etr_request("GET", "etr/v3/status/76561190000000001"))

# Simple status check (HMAC disabled on your key)
curl -s "https://sellingvika.party/etr/v3/status/76561190000000001" \
  -H "X-API-Key: your_api_key" \
  -H "User-Agent: curl/test"

# Get server time
curl -s "https://sellingvika.party/etr/v3/time"

Чек-лист безопасности

• Никогда не вставляйте секреты в клиентский код. Храните API-секреты в конфигурационных файлах сервера, а не в Lua-скриптах, доступных игрокам.
• Генерируйте новый nonce для каждого запроса. Используйте криптографическую случайность (16-128 символов). Повторно использованные nonce отклоняются с 409 nonce_reused.
• Синхронизируйте часы. Call GET /etr/v3/time при запуске. Запросы с временными метками, отличающимися более чем на 2 минуты, отклоняются.
• Используйте точную строку тела для подписи. Тело в HMAC-нагрузке должно совпадать с байтами, отправленными по сети. Не пересериализуйте JSON между подписью и отправкой.
• Привязка IP (опционально). Вы можете ограничить API-ключ конкретными IP в Настройки → Серверы для дополнительной безопасности.

Common Use Cases

Ответы с ошибками

Все ошибки возвращают JSON с полем error и необязательным message.

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

{
  "error": "server_not_verified",
  "message": "Server must be verified by admin before voting.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}