API bota

Co můžeš postavit

API bota umožňuje tvému webu nebo nástrojům číst aktuální údaje o tvém serveru Discord. Jen čte. Nic, co s ním postavíš, nemůže změnit tvůj server ani se dotknout tvých členů. Tady je pár nápadů, které lidé zvládnou za odpoledne.

• Widget se žebříčkemZobraz na webu komunity svých 10 nejlepších přeživších podle úrovně.
• Odpočet giveawayDej na úvodní stránku probíhající giveaway, jeho cenu a čas ukončení.
• Počty ticketůUkaž, kolik ticketů je otevřených a jak rychle tým odpovídá, pro panel pro personál nebo banner „odpovídáme zhruba do 10 minut“.
• Odznak stavuZobraz, jestli je herní server online a kolik hráčů na něm je.
• Seznam produktů obchoduVypiš produkty svého obchodu s dary s cenami na vlastním webu a odkaž rovnou na platbu.

Krok za krokem: vytvoř svůj token

Token je dlouhé tajné heslo, které umožní jednomu webu nebo nástroji číst tvůj server. Vytvoříš ho ve svém panelu.

1. 01

   Otevři stránku API bota

   Přihlas se na dayzhub.net, otevři panel, vyber svůj server a v postranním menu v sekci Správa zvol API bota. Vidí ji jen lidé s oprávněním Spravovat server. Členové s Přístupem týmu ji nevidí.

2. 02

   Pojmenuj ho

   Napiš krátký název, který ti napoví, k čemu slouží, například „Žebříček na webu“. Pro každý web nebo nástroj použij samostatný token.

3. 03

   Vyber, co smí číst

   Zaškrtni políčka u dat, která potřebuješ, například giveaway nebo žebříček úrovní. Méně políček je bezpečnější. Další token můžeš vytvořit kdykoli později.

4. 04

   Povolený web (jen někdy)

   Nech prázdné, pokud webová stránka v prohlížečích návštěvníků nebude volat API přímo. V takovém případě napiš adresu svého webu přesně, například https://tvujweb.com, bez cesty na konci.

5. 05

   Stiskni Vytvořit token a zkopíruj ho

   Objeví se okno s tvým tokenem, který začíná dhba_. Stiskni Kopírovat a hned ho vlož na bezpečné místo. Zobrazí se jen jednou. Pokud ho ztratíš, vytvoříš nový.

6. 06

   Drž ho v tajnosti

   Zacházej s tokenem jako s heslem. Nepublikuj ho na Discordu, nedávej ho do veřejného projektu na GitHubu a nevkládej ho do webové stránky, kterou mohou návštěvníci číst. Měj ho na vlastním serveru nebo ve správci hesel.

Tvůj první požadavek

Ověřme, že token funguje. Potřebuješ dvě věci: token, který jsi právě zkopíroval, a ID svého serveru (na Discordu zapni v nastavení Vývojářský režim, pak na server klikni pravým tlačítkem a zvol Kopírovat ID serveru). První volání níže potřebuje jen token.

V každém příkladu nahraď dhba_YOUR_TOKEN svým skutečným tokenem. Každý příklad posílá token v hlavičce Authorization. Vložit ho do webové adresy nefunguje.

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 se vrací

Každá odpověď je JSON. Úspěšné odpovědi mají "ok": true a tvá data. Seznamy mají část "page": když je "hasMore" true, pošli hodnotu "nextCursor" zpět jako ?cursor= a dostaneš další stránku. Data jsou v 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" }

Úplný seznam koncových bodů a všech polí je ve strojově čitelném popisu na /api/v1/bot/openapi.json. Každá odpověď nese hlavičku X-Request-Id a chyby ji opakují jako requestId. Uveď ji, když kontaktuješ podporu.

Limity, tarify a soukromí

• Jen pro čteníNejsou tu žádná tlačítka, která by cokoli měnila. Odpovídá se jen na požadavky GET.
• TarifyTvůj server potřebuje placený tarif nebo aktivní bezplatnou zkušební dobu. Data o giveaway vyžadují Premium 2. Seznam obchodu vyžaduje skutečný placený přístup, protože zkušební doba Obchod s dary neobsahuje.
• Kolik tokenů můžeš mítPremium 1 zahrnuje 2 aktivní tokeny, Premium 2 zahrnuje 5 a Premium 3 zahrnuje 10. Zkušební doba zdarma nebo sponzorovaný server se počítá jako Premium 1. Zruš ty, které už nepoužíváš, a uvolníš místo. Když tvůj tarif klesne, tokeny, které už máš, dál fungují. Jen nemůžeš vytvářet nové, dokud nejsi pod limitem.
• Omezení rychlostiKaždý token může provést 60 požadavků za minutu na Premium 1, 120 na Premium 2 a 300 na Premium 3 a jedna internetová adresa 300 za minutu. Při překročení dostaneš odpověď 429 s hlavičkou Retry-After, která říká, kolik sekund počkat.
• Šetrné dotazováníOdpovědi obsahují ETag. Pošli ho zpět v hlavičce If-None-Match a když se nic nezměnilo, dostaneš drobnou odpověď 304 místo celých dat. Ptát se každých 30 až 60 sekund stačí a většina widgetů se může ptát méně často.
• Co se nikdy nesdílíPřepisy a zprávy ticketů, žádosti a jejich odpovědi, platby a objednávky, e-mailové adresy, jména a avatary a lidé, kteří se do giveaway zapojili. Dostaneš vždy jen počty, plus číselná ID Discordu tam, kde funkce už lidi veřejně ukazuje na Discordu, například hostitele giveaway nebo žebříček úrovní.
• Členové, kteří vznesli námitkuKaždý, kdo použil /privacy optout, se vždy zobrazí jako anonymní (id null). Jeho pořadí a čísla se stále počítají, takže součty sedí.

Řešení potíží

Zrušení a výměna tokenu

Udělej to hned, pokud byl token omylem sdílen, zveřejněn, nebo pokud odešel z týmu někdo, kdo ho znal.

1. 01

   Nejdřív vytvoř nový token

   Na stránce API bota vytvoř náhradu se stejným nastavením a zkopíruj ji.

2. 02

   Přepni svůj web nebo nástroj

   Vlož nový token všude, kde se používal starý, a ověř, že vše stále funguje.

3. 03

   Zruš ten starý

   V seznamu svých tokenů stiskni u starého Zrušit a potvrď. Okamžitě přestane fungovat a vše, co ho ještě používá, dostane 401. Vytvoření i zrušení se zapisují do auditního logu serveru, nikdy ne samotný token.

Časté otázky