API бота

Что можно создать

API бота позволяет вашему сайту или инструментам читать актуальные данные вашего сервера Discord. Он только читает. Ничто из созданного вами не сможет изменить сервер или затронуть участников. Вот несколько идей, которые люди реализуют за один вечер.

• Виджет таблицы лидеровПокажите 10 лучших выживших по уровню на сайте вашего сообщества.
• Обратный отсчёт розыгрышаРазместите на главной странице текущий розыгрыш, его приз и время окончания.
• Число тикетовПоказывайте, сколько тикетов открыто и как быстро отвечает команда: для панели персонала или баннера «мы отвечаем примерно за 10 минут».
• Значок статусаПоказывайте, в сети ли ваш игровой сервер и сколько на нём игроков.
• Список товаров магазинаВыводите товары вашего магазина донатов с ценами на своём сайте и ведите прямо на оплату.

Пошагово: создайте токен

Токен это длинный секретный пароль, который позволяет одному сайту или инструменту читать данные вашего сервера. Вы создаёте его в панели.

1. 01

   Откройте страницу API бота

   Войдите на dayzhub.net, откройте панель, выберите свой сервер и нажмите API бота в разделе «Управление» бокового меню. Страница видна только тем, у кого есть право «Управление сервером». Участники с доступом команды её не видят.

2. 02

   Дайте ему имя

   Введите короткое имя, которое подскажет, для чего токен, например «Таблица лидеров на сайте». Используйте отдельный токен для каждого сайта или инструмента.

3. 03

   Выберите, что он может читать

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

4. 04

   Разрешённый сайт (только иногда)

   Оставьте пустым, если только веб-страница в браузере посетителей не будет вызывать API напрямую. Тогда укажите адрес сайта точно, например https://yoursite.com, без пути в конце.

5. 05

   Нажмите «Создать токен» и скопируйте его

   Появится окно с вашим токеном, он начинается с dhba_. Нажмите «Копировать» и сразу вставьте его в надёжное место. Он показывается только один раз. Если потеряете, создайте новый.

6. 06

   Храните его в секрете

   Относитесь к токену как к паролю. Не публикуйте его в Discord, не кладите в публичный проект на GitHub и не вставляйте на веб-страницу, которую могут читать посетители. Храните его на своём сервере или в менеджере паролей.

Ваш первый запрос

Давайте проверим, что токен работает. Нужны две вещи: только что скопированный токен и ID вашего сервера (в Discord включите режим разработчика в настройках, затем нажмите правой кнопкой на сервер и выберите «Копировать ID сервера»). Для первого вызова ниже нужен только токен.

В каждом примере замените dhba_YOUR_TOKEN своим настоящим токеном. Каждый пример отправляет токен в заголовке Authorization. Если указать его в веб-адресе, это не сработает.

Windows PowerShell (use curl.exe with the .exe, plain curl means something else in PowerShell)

curl.exe -H "Authorization: Bearer dhba_YOUR_TOKEN" https://dayzhub.net/api/v1/bot/me

curl (macOS, Linux and most hosting)

curl -H "Authorization: Bearer dhba_YOUR_TOKEN" https://dayzhub.net/api/v1/bot/me

JavaScript on your own server (Node 18 or newer). Keep the token in an environment variable.

const res = await fetch("https://dayzhub.net/api/v1/bot/guilds/YOUR_SERVER_ID/giveaways?status=active", {
  headers: { Authorization: "Bearer " + process.env.DAYZHUB_BOT_API_TOKEN }
});
const { ok, data } = await res.json();
console.log(data);

JavaScript in a visitor's browser (needs the Allowed website setting on the token, and shows the token to everyone, so use a token with the fewest boxes ticked)

fetch("https://dayzhub.net/api/v1/bot/guilds/YOUR_SERVER_ID/leaderboard/levels?limit=10", {
  headers: { Authorization: "Bearer dhba_YOUR_TOKEN" }
}).then(r => r.json()).then(j => console.log(j.data));

Что вы получите в ответ

Каждый ответ приходит в формате JSON. Успешные ответы содержат "ok": true и ваши данные. Списки приходят с частью "page": когда "hasMore" равно true, передайте значение "nextCursor" как ?cursor=, чтобы получить следующую страницу. Даты указаны в UTC.

GET /me: who the token belongs to

{
  "ok": true,
  "data": {
    "guildId": "123456789012345678",
    "name": "Website leaderboard",
    "prefix": "dhba_aB3dE",
    "scopes": ["leveling:read", "giveaways:read"],
    "allowedOrigin": null,
    "rateLimitPerMin": 60,
    "createdAt": "2026-10-01T12:00:00.000Z",
    "plan": "premium1",
    "limits": { "tokens": 2, "perMinute": 60 },
    "tokensUsed": 1
  }
}

GET /guilds/ID/leaderboard/levels?limit=2

{
  "ok": true,
  "data": [
    { "rank": 1, "member": { "id": "111111111111111111", "anonymous": false }, "xp": 18450, "level": 27 },
    { "rank": 2, "member": { "id": null, "anonymous": true }, "xp": 17020, "level": 26 }
  ],
  "page": { "limit": 2, "hasMore": true, "nextCursor": "eyJpZCI6IjY..." }
}

GET /guilds/ID/giveaways?status=active

{
  "ok": true,
  "data": [{
    "id": "6650f0c2a1b2c3d4e5f60718",
    "prize": "Premium VIP for 30 days",
    "status": "active",
    "type": "reaction",
    "winnerCount": 1,
    "entryCount": 86,
    "endsAt": "2026-10-08T18:00:00.000Z",
    "requirements": { "role": false, "verified": true, "minInvites": 0 },
    "host": { "id": "111111111111111111", "anonymous": false },
    "winners": []
  }],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

GET /guilds/ID/tickets/summary

{
  "ok": true,
  "data": {
    "open": 4,
    "closed": 212,
    "total": 216,
    "last30Days": { "created": 38, "closed": 41, "averageRating": 4.7, "ratingCount": 29, "averageFirstResponseMinutes": 9.5 },
    "byCategory": [ { "category": "Support", "open": 3, "closed": 150 } ]
  }
}

GET /guilds/ID/shop/products

{
  "ok": true,
  "shop": { "name": "Survivor HQ Shop", "description": "Support the server", "slug": "survivor-hq", "url": "https://dayzhub.net/shop/survivor-hq" },
  "data": [{
    "id": "6650f0c2a1b2c3d4e5f60999", "name": "VIP Role", "slug": "vip-role", "description": "Priority queue and a gold name",
    "price": 9.99, "compareAtPrice": null, "currency": "EUR", "type": "subscription", "interval": "monthly",
    "thumbnailUrl": null, "featured": true, "inStock": true, "url": "https://dayzhub.net/shop/survivor-hq/vip-role"
  }],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

GET /guilds/ID/server-status

{
  "ok": true,
  "data": {
    "listed": true,
    "servers": [{ "name": "Survivor HQ", "slug": "survivor-hq", "url": "https://dayzhub.net/s/survivor-hq", "online": true, "players": 42, "maxPlayers": 60, "address": "game.yourserver.gg:2302", "lastChangeAt": "2026-10-01T09:30:00.000Z" }]
  }
}

When something is wrong, for example a mixed-up server ID (HTTP 403)

{ "ok": false, "error": "guild_mismatch", "code": "guild_mismatch", "message": "This token belongs to another server", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

Полный список эндпоинтов и всех полей находится в машиночитаемом описании по адресу /api/v1/bot/openapi.json. Каждый ответ содержит заголовок X-Request-Id, а в ошибках он повторяется как requestId. Назовите его, когда обращаетесь в поддержку.

Лимиты, тарифы и приватность

• Только чтениеЗдесь нет кнопок, что-либо меняющих. Обрабатываются только запросы GET.
• ТарифыВашему серверу нужен платный тариф или активный бесплатный пробный период. Данные о розыгрышах требуют Premium 2. Для списка товаров нужен настоящий платный доступ, потому что бесплатный пробный период не включает магазин донатов.
• Сколько токенов можно иметьPremium 1 включает 2 активных токена, Premium 2 включает 5, а Premium 3 включает 10. Бесплатный пробный период и спонсируемый сервер считаются как Premium 1. Отзовите ненужные, чтобы освободить место. Если ваш тариф понизится, уже созданные токены продолжат работать. Просто нельзя создавать новые, пока вы не окажетесь ниже лимита.
• Ограничения скоростиКаждый токен может делать 60 запросов в минуту на Premium 1, 120 на Premium 2 и 300 на Premium 3, а один интернет-адрес 300 в минуту. При превышении вы получите ответ 429 с заголовком Retry-After, который подскажет, сколько секунд ждать.
• Бережные запросыОтветы содержат ETag. Отправьте его обратно в заголовке If-None-Match, и если ничего не изменилось, вы получите крошечный ответ 304 вместо полных данных. Опрашивать каждые 30-60 секунд вполне достаточно, а большинству виджетов хватит и реже.
• Что никогда не передаётсяПереписки и сообщения тикетов, заявки и ответы на них, платежи и заказы, адреса электронной почты, имена и аватары, а также участники розыгрыша. Вы получаете только числа и числовые ID Discord там, где функция и так публично показывает людей в Discord, например организатор розыгрыша или таблица уровней.
• Участники, отказавшиеся от обработки данныхЛюбой, кто использовал /privacy optout, всегда отображается как анонимный (id равен null). Его место и цифры при этом учитываются, поэтому итоги сходятся.

Решение проблем

Отзыв и замена токена

Сделайте это сразу, если токен был передан по ошибке, опубликован открыто или человек, который его знал, ушёл из вашей команды.

1. 01

   Сначала создайте новый токен

   На странице API бота создайте замену с теми же настройками и скопируйте её.

2. 02

   Переключите сайт или инструмент

   Вставьте новый токен везде, где использовался старый, и проверьте, что всё по-прежнему работает.

3. 03

   Отзовите старый

   В списке ваших токенов нажмите «Отозвать» у старого и подтвердите. Он перестанет работать сразу, а всё, что его ещё использует, получит 401. Создание и отзыв записываются в журнал аудита вашего сервера, но сам токен никогда.

Частые вопросы