API bota

Co możesz zbudować

API bota pozwala Twojej stronie lub narzędziom czytać na żywo informacje o serwerze Discord. Tylko czyta. Nic, co z nim zbudujesz, nie może zmienić serwera ani dotknąć członków. Oto kilka pomysłów, które ludzie wdrażają w jedno popołudnie.

• Widżet rankinguPokaż 10 najlepszych ocalałych według poziomu na stronie swojej społeczności.
• Odliczanie do końca konkursuUmieść na stronie głównej trwający konkurs, jego nagrodę i czas zakończenia.
• Liczba ticketówPokaż, ile ticketów jest otwartych i jak szybko odpowiada Twoja ekipa, na panelu dla ekipy albo w banerze „odpowiadamy w około 10 minut”.
• Plakietka statusuWyświetl, czy serwer gry jest online i ilu graczy na nim jest.
• Lista produktów ze sklepuWylistuj produkty ze Sklepu z darowiznami z cenami na własnej stronie i połącz je prosto z płatnością.

Krok po kroku: utwórz swój token

Token to długie tajne hasło, dzięki któremu jedna strona lub narzędzie może czytać Twój serwer. Tworzysz go w panelu.

1. 01

   Otwórz stronę API bota

   Zaloguj się na dayzhub.net, otwórz panel, wybierz serwer i wybierz API bota w sekcji Zarządzanie w menu bocznym. Widzą ją tylko osoby z uprawnieniem Zarządzanie serwerem. Członkowie z dostępem dla ekipy jej nie widzą.

2. 02

   Nadaj nazwę

   Wpisz krótką nazwę mówiącą, do czego służy, na przykład „Ranking na stronie”. Używaj jednego tokenu na stronę lub narzędzie.

3. 03

   Wybierz, co może czytać

   Zaznacz pola z danymi, których potrzebujesz, np. konkursy albo ranking poziomów. Mniej zaznaczonych pól to większe bezpieczeństwo. Zawsze możesz później utworzyć kolejny token.

4. 04

   Dozwolona strona (tylko czasem)

   Zostaw puste, chyba że strona w przeglądarkach odwiedzających będzie wywoływać API bezpośrednio. Wtedy wpisz adres swojej strony dokładnie, np. https://twojastrona.com, bez ścieżki na końcu.

5. 05

   Naciśnij Utwórz token i skopiuj go

   Pojawi się okienko z Twoim tokenem, który zaczyna się od dhba_. Naciśnij Kopiuj i od razu wklej go w bezpiecznym miejscu. Wyświetla się tylko raz. Jeśli go zgubisz, tworzysz nowy.

6. 06

   Zachowaj go w tajemnicy

   Traktuj token jak hasło. Nie wrzucaj go na Discorda, nie umieszczaj w publicznym projekcie na GitHubie i nie wklejaj na stronę, którą mogą czytać odwiedzający. Trzymaj go na własnym serwerze lub w menedżerze haseł.

Twoje pierwsze żądanie

Sprawdźmy, czy token działa. Potrzebujesz dwóch rzeczy: tokenu, który właśnie skopiowałeś, i ID serwera (w Discordzie włącz Tryb programisty w ustawieniach, potem kliknij serwer prawym przyciskiem i wybierz Kopiuj ID serwera). Pierwsze wywołanie poniżej potrzebuje tylko tokenu.

We wszystkich przykładach zamień dhba_YOUR_TOKEN na swój prawdziwy token. Każdy z nich wysyła token w nagłówku o nazwie Authorization. Wpisanie go w adresie internetowym nie działa.

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));

Co dostajesz w odpowiedzi

Każda odpowiedź to JSON. Udane odpowiedzi mają "ok": true i Twoje dane. Listy mają część "page": gdy "hasMore" ma wartość true, przekaż wartość "nextCursor" jako ?cursor=, aby pobrać następną stronę. Daty są w 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" }

Pełna lista punktów końcowych i wszystkich pól jest w opisie czytelnym dla maszyn pod adresem /api/v1/bot/openapi.json. Każda odpowiedź niesie nagłówek X-Request-Id, a błędy powtarzają go jako requestId. Podaj go, kontaktując się z pomocą.

Limity, plany i prywatność

• Tylko odczytNie ma przycisków, które cokolwiek zmieniają. Odpowiadamy tylko na żądania GET.
• PlanyTwój serwer potrzebuje płatnego planu lub aktywnego darmowego okresu próbnego. Dane konkursów wymagają Premium 2. Lista sklepu wymaga prawdziwego płatnego dostępu, bo darmowy okres próbny nie obejmuje Sklepu z darowiznami.
• Ile tokenów możesz miećPremium 1 obejmuje 2 aktywne tokeny, Premium 2 obejmuje 5, a Premium 3 obejmuje 10. Darmowy okres próbny lub serwer sponsorowany liczy się jako Premium 1. Unieważnij te, których już nie używasz, aby zwolnić miejsce. Jeśli Twój plan się obniży, tokeny, które już masz, nadal działają. Po prostu nie możesz tworzyć nowych, dopóki nie będziesz poniżej limitu.
• Limity szybkościKażdy token może wykonać 60 żądań na minutę w Premium 1, 120 w Premium 2 i 300 w Premium 3, a jeden adres internetowy 300 na minutę. Po przekroczeniu dostaniesz odpowiedź 429 z nagłówkiem Retry-After, który mówi, ile sekund czekać.
• Uprzejme odpytywanieOdpowiedzi zawierają ETag. Odeślij go w nagłówku If-None-Match, a gdy nic się nie zmieniło, dostaniesz malutką odpowiedź 304 zamiast pełnych danych. Pytanie co 30 do 60 sekund w zupełności wystarcza, a większość widżetów może pytać rzadziej.
• Co nigdy nie jest udostępnianeTranskrypcje i wiadomości z ticketów, podania i ich odpowiedzi, płatności i zamówienia, adresy e-mail, nazwy i awatary oraz osoby, które wzięły udział w konkursie. Dostajesz tylko liczby oraz numeryczne ID Discorda tam, gdzie dana funkcja już publicznie pokazuje osoby na Discordzie, np. organizator konkursu lub ranking poziomów.
• Członkowie, którzy się sprzeciwiliKażdy, kto użył /privacy optout, zawsze pojawia się jako anonimowy (id równe null). Jego pozycja i liczby nadal się liczą, więc sumy się zgadzają.

Rozwiązywanie problemów

Unieważnianie i wymiana tokenu

Zrób to od razu, jeśli token został przez pomyłkę udostępniony, opublikowany lub osoba, która go znała, odeszła z Twojej ekipy.

1. 01

   Najpierw utwórz nowy token

   Na stronie API bota utwórz zamiennik z tymi samymi ustawieniami i skopiuj go.

2. 02

   Przełącz stronę lub narzędzie

   Wstaw nowy token wszędzie tam, gdzie używany był stary, i sprawdź, czy wszystko nadal działa.

3. 03

   Unieważnij stary

   Na liście tokenów naciśnij Unieważnij przy starym i potwierdź. Przestaje działać natychmiast, a wszystko, co go jeszcze używa, dostaje 401. Tworzenie i unieważnianie trafiają do dziennika audytu serwera, ale nigdy sam token.

Pytania, które zadają ludzie