API для разработчиков

Показывайте данные своего сервера на своём сайте, добавляйте серверы из панели и выдавайте игрокам награду за голос. Ключ создаёт владелец сервера в личном кабинете.

Перейти к ключу

Нажмите на метод, чтобы увидеть запрос и ответ. Метка справа показывает, чьи данные доступны. В примерах ключ лежит в переменной $HSZN_KEY.

Серверы

GET/serversВаши серверываши серверы

Серверы, где вы владелец, и добавленные, но ещё не подтверждённые: у них есть код для названия.

Запрос

curl "https://hszn.ru/api/v1/servers" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "servers": [
    { "id": 1042, "address": "play.example.ru:27015", "game": "cs2",
      "status": "online", "verified": true },
    { "id": 1077, "address": "surf.example.ru:27016", "game": "csgo",
      "status": "unknown", "verified": false, "verificationCode": "HSZN-4K7Q2M" }
  ]
}

GET/catalogРежимы и моды для нового сервералюбой ключ

Что можно указать при добавлении сервера: режим один, модов до 3. Список ведёт администратор платформы, он может меняться.

Запрос

curl "https://hszn.ru/api/v1/catalog" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "modes": ["Competitive", "Casual", "Wingman", "Deathmatch", "Retake"],
  "mods": ["Surf", "Bhop", "KZ", "Zombie", "Skins", "Ranks"]
}

POST/serversДобавить ещё один серверваши серверы

Первый сервер добавляется на сайте: ключ появляется после подтверждения владения. Этим методом можно добавить следующие.

Параметры тела

Поле	Значения	Описание
`address`	—	IP или домен с портом игры. Закрытые адреса не принимаются.
`mode`	—	Режим сервера из списка метода /catalog. Обязателен.
`mods`	до 3	Значения: до 3. Необязательно: моды из того же списка.
`game`	cs2, csgo	Значения: cs2, csgo. Необязательно: по умолчанию игра определяется по ответу сервера.

Запрос

curl -X POST "https://hszn.ru/api/v1/servers" \
  -H "Authorization: Bearer $HSZN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address": "play.example.ru:27017", "mode": "Retake", "mods": ["Surf"]}'

Ответ201

{
  "id": 1043,
  "status": "unknown",
  "verification": { "code": "HSZN-4K7Q2M", "expiresAt": "2026-11-08T10:00:00Z" }
}

Ответ409Адрес уже есть на сайте

{ "ok": false, "errors": { "address": "duplicate" }, "existingServerId": "1020" }

Сервер должен ответить на проверку, иначе вернётся 422 с кодом no_response. Если он ответил, но игра не поддерживается, придёт unsupported_game, а если режим или моды не из списка, ошибка будет в полях mode и mods. Остальное (описание, ссылки, баннер) владелец настроит в кабинете. Добавлять можно до 10 серверов в час.

POST/servers/{id}/verificationПодтвердить владениеваши серверы

Впишите код в начало названия сервера и вызовите метод: тот, чей это ключ, становится владельцем. Проверять можно раз в 10 секунд.

Запрос

curl "https://hszn.ru/api/v1/servers/1043/verification" -X POST \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200Код найден

{ "status": "verified" }

Ответ200Кода в названии пока нет

{ "status": "pending", "checkedAt": "2026-11-07T10:02:11Z", "reason": "code_not_found" }

Ответ429Проверяли слишком недавно

{ "status": "rate_limited", "retryAfterSeconds": 7 }

Ещё возможны expired (код истёк, на сайте выпускается новый) и owned (у сервера уже другой владелец).

GET/servers/{id}Данные сервералюбой сервер

Название, карта, онлайн, рейтинг и голоса: то же, что видно на странице сервера.

Запрос

curl "https://hszn.ru/api/v1/servers/1042" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "id": 1042,
  "name": "ZONE Surf | Retake",
  "address": "play.example.ru:27015",
  "game": "cs2",
  "status": "online",
  "map": "surf_kitsune",
  "mode": "Surf",
  "mods": ["Skins", "VIP"],
  "players": 38,
  "maxPlayers": 64,
  "rating": 87,
  "votes": { "total": 1840, "week": 96, "month": 410 },
  "uptimePct": 99.2,
  "peakPlayers": 61,
  "avgPlayers": 34,
  "country": "RU",
  "city": "Москва",
  "lastCheckAt": "2026-11-07T09:12:03Z"
}

rating — итоговый балл от 0 до 100. uptimePct — доля удачных опросов за 30 дней, peakPlayers и avgPlayers — за последние сутки. Пока сервер не опрашивался (status: unknown), данные опроса равны null.

GET/servers/{id}/playersИгроки сейчаслюбой сервер

По последнему опросу, не больше 64 строк.

Запрос

curl "https://hszn.ru/api/v1/servers/1042/players" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "total": 38,
  "updatedAt": "2026-11-07T09:12:03Z",
  "players": [
    { "name": "Alina", "score": 24, "minutes": 41 },
    { "name": "Max", "score": 17, "minutes": 12 }
  ]
}

Статистика

GET/servers/{id}/statsОнлайн по временилюбой сервер

Параметры

Поле	Значения	Описание
`days`	1, 7, 14, 30	Значения: 1, 7, 14, 30. Период, по умолчанию 7. За 1 и 7 дней точки по часу, за 14 и 30 дней по 6 часов.

Запрос

curl "https://hszn.ru/api/v1/servers/1042/stats?days=14" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "days": 14,
  "summary": { "avgPlayers": 34, "peakPlayers": 61, "uptimePct": 99.2 },
  "points": [
    { "t": "2026-10-24T00:00:00Z", "avgPlayers": 29, "peakPlayers": 44, "uptimePct": 100 },
    { "t": "2026-10-24T06:00:00Z", "avgPlayers": 17, "peakPlayers": 25, "uptimePct": 100 }
  ]
}

У нового сервера точек может не быть совсем: тогда points пуст, а в summary нули.

Отзывы

GET/servers/{id}/reviewsОтзывы о серверелюбой сервер

Параметры

Поле	Значения	Описание
`limit`	1–50	Значения: 1–50. Сколько отзывов вернуть, по умолчанию 10.

Запрос

curl "https://hszn.ru/api/v1/servers/1042/reviews?limit=2" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "summary": {
    "count": 128,
    "avg": 4.6,
    "distribution": { "1": 2, "2": 3, "3": 8, "4": 25, "5": 90 }
  },
  "items": [
    { "id": 9120, "author": "Alina", "rating": 5,
      "text": "Стабильный пинг и адекватные админы", "createdAt": "2026-11-06T19:20:41Z" },
    { "id": 9087, "author": "Max", "rating": 4,
      "text": "Хороший сервер, иногда не хватает слотов вечером", "createdAt": "2026-11-04T08:02:10Z" }
  ]
}

Отзывы идут от новых к старым, только опубликованные. Автор показывается ником. Оставить отзыв можно только на сайте.

Голоса

GET/servers/{id}/votesКто голосовалтолько владелец

Параметры

Поле	Значения	Описание
`since`	—	Номер последнего голоса, который вы уже обработали: вернутся только более новые. По умолчанию 0.
`limit`	1–100	Значения: 1–100. Сколько записей вернуть, по умолчанию 50.

Запрос

curl "https://hszn.ru/api/v1/servers/1042/votes?since=58212&limit=50" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200

{
  "total": 1840, "week": 96, "month": 410,
  "votes": [
    { "id": 58213, "steamId": "76561198000000001", "votedAt": "2026-11-07T08:40:12Z" },
    { "id": 58214, "steamId": null, "votedAt": "2026-11-07T08:55:47Z" }
  ]
}

steamId заполнен, если игрок привязал Steam к аккаунту HSZN. Голоса идут по возрастанию номера, номер не повторяется: по нему удобно не выдавать награду дважды. Новый голос появляется в списке через 5 секунд, чтобы номер последнего обработанного голоса ничего не пропустил. Если награда нужна сразу, спросите метод проверки игрока: он видит голос без паузы.

GET/servers/{id}/votes/checkПроголосовал ли игроктолько владелец

Голос ставится кнопкой «Проголосовать» на странице сервера, с одного аккаунта раз в 24 часа. Метод отвечает, был ли голос игрока за последние 24 часа.

Параметры

Поле	Значения	Описание
`steamid`	—	SteamID64 игрока, 17 цифр.

Запрос

curl "https://hszn.ru/api/v1/servers/1042/votes/check?steamid=76561198000000001" \
  -H "Authorization: Bearer $HSZN_KEY"

Ответ200Игрок голосовал

{
  "voted": true,
  "voteId": 58213,
  "votedAt": "2026-11-07T08:40:12Z",
  "nextVoteAt": "2026-11-08T08:40:12Z",
  "steamLinked": true
}

Ответ200Игрок не голосовал

{
  "voted": false,
  "voteId": null,
  "votedAt": null,
  "nextVoteAt": null,
  "steamLinked": true
}

Если steamLinked равно false, у игрока не привязан Steam и узнать его нельзя: подскажите ему привязать Steam в профиле HSZN.