API del Bot

Cosa puoi creare

L'API del Bot permette al tuo sito o ai tuoi strumenti di leggere informazioni in tempo reale sul tuo server Discord. Legge soltanto. Niente di ciò che costruisci può modificare il tuo server o toccare i tuoi membri. Ecco alcune idee che si mettono in piedi in un pomeriggio.

• Un widget con la classificaMostra i tuoi 10 migliori sopravvissuti per livello sul sito della tua community.
• Un conto alla rovescia per i giveawayMetti il giveaway in corso, il suo premio e l'ora di fine sulla tua homepage.
• Il numero di ticketMostra quanti ticket sono aperti e quanto velocemente risponde il tuo team, per una dashboard dello staff o un banner "rispondiamo in circa 10 minuti".
• Un badge di statoIndica se il tuo server di gioco è online e quanti giocatori ci sono.
• Un elenco dei prodotti del negozioElenca i prodotti del tuo Negozio donazioni con i prezzi sul tuo sito e rimanda direttamente al pagamento.

Passo dopo passo: crea il tuo token

Un token è una lunga password segreta che permette a un sito o a uno strumento di leggere il tuo server. Lo crei nella tua dashboard.

1. 01

   Apri la pagina API del Bot

   Accedi a dayzhub.net, apri la tua dashboard, scegli il tuo server e seleziona API del Bot nella sezione Gestione del menu laterale. Solo chi ha il permesso Gestisci server può vederla. I membri dell'accesso team no.

2. 02

   Dagli un nome

   Scrivi un nome breve che ti ricordi a cosa serve, per esempio "Classifica del sito". Usa un token per ogni sito o strumento.

3. 03

   Scegli cosa può leggere

   Spunta le caselle dei dati che ti servono, come i giveaway o la classifica dei livelli. Meno caselle, più sicurezza. Potrai sempre creare un altro token più avanti.

4. 04

   Sito consentito (solo a volte)

   Lascia vuoto, a meno che una pagina web chiami l'API direttamente dal browser dei tuoi visitatori. In quel caso scrivi esattamente l'indirizzo del tuo sito, come https://yoursite.com, senza percorso alla fine.

5. 05

   Premi Crea token e copialo

   Compare un riquadro con il tuo token, che inizia con dhba_. Premi Copia e incollalo subito in un posto sicuro. Viene mostrato una sola volta. Se lo perdi, ne crei uno nuovo.

6. 06

   Tienilo segreto

   Tratta il token come una password. Non pubblicarlo su Discord, non metterlo in un progetto GitHub pubblico e non incollarlo in una pagina web che i visitatori possono leggere. Conservalo sul tuo server o in un gestore di password.

La tua prima richiesta

Verifichiamo che il token funzioni. Ti servono due cose: il token che hai appena copiato e l'ID del tuo server (in Discord attiva la Modalità sviluppatore nelle impostazioni, poi clic destro sul tuo server e scegli Copia ID server). La prima chiamata qui sotto richiede solo il token.

Sostituisci dhba_YOUR_TOKEN con il tuo vero token in ogni esempio. Ognuno invia il token in un header chiamato Authorization. Metterlo nell'indirizzo web non funziona.

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

Cosa torna indietro

Ogni risposta è JSON. Le risposte riuscite contengono "ok": true e i tuoi dati. Le liste hanno una parte "page": quando "hasMore" è true, rimanda il valore "nextCursor" come ?cursor= per ottenere la pagina successiva. Le date sono in 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" }

L'elenco completo degli endpoint e di ogni campo si trova nella descrizione leggibile da macchina su /api/v1/bot/openapi.json. Ogni risposta porta l'header X-Request-Id e gli errori lo ripetono come requestId. Indicalo quando contatti il supporto.

Limiti, piani e privacy

• Sola letturaNon ci sono pulsanti che cambiano qualcosa. Vengono gestite solo le richieste GET.
• PianiIl tuo server ha bisogno di un piano a pagamento o di una prova gratuita attiva. I dati dei giveaway richiedono Premium 2. L'elenco del negozio richiede un vero accesso a pagamento, perché la prova gratuita non include il Negozio donazioni.
• Quanti token puoi averePremium 1 include 2 token attivi, Premium 2 ne include 5 e Premium 3 ne include 10. Una prova gratuita o un server sponsorizzato conta come Premium 1. Revoca quelli che non usi più per liberare un posto. Se il tuo piano scende, i token che hai già continuano a funzionare. Semplicemente non puoi crearne di nuovi finché non sei sotto il limite.
• Limiti di velocitàOgni token può fare 60 richieste al minuto con Premium 1, 120 con Premium 2 e 300 con Premium 3, e un indirizzo internet 300 al minuto. Oltre il limite ricevi una risposta 429 con un header Retry-After che indica quanti secondi aspettare.
• Interrogare con garboLe risposte includono un ETag. Rimandalo in un header If-None-Match e, se nulla è cambiato, ricevi una minuscola risposta 304 invece di tutti i dati. Chiedere ogni 30-60 secondi è più che sufficiente, e la maggior parte dei widget può chiedere più di rado.
• Cosa non viene mai condivisoTrascrizioni e messaggi dei ticket, candidature e relative risposte, pagamenti e ordini, indirizzi e-mail, nomi e avatar, e le persone che hanno partecipato a un giveaway. Ottieni solo conteggi, più ID Discord numerici dove la funzione mostra già le persone pubblicamente su Discord, come l'organizzatore di un giveaway o la classifica dei livelli.
• Membri che si sono opposti al trattamento dei datiChiunque abbia usato /privacy optout compare sempre come anonimo (un id pari a null). La sua posizione e i suoi numeri contano comunque, quindi i totali tornano.

Risoluzione dei problemi

Revocare e sostituire un token

Fallo subito se un token è stato condiviso per errore, pubblicato in pubblico, o se una persona che lo conosceva ha lasciato il tuo team.

1. 01

   Crea prima il nuovo token

   Nella pagina API del Bot crea un sostituto con le stesse impostazioni e copialo.

2. 02

   Passa al nuovo token sul tuo sito o strumento

   Metti il nuovo token ovunque venisse usato il vecchio e controlla che tutto funzioni ancora.

3. 03

   Revoca il vecchio

   Nell'elenco dei tuoi token, premi Revoca su quello vecchio e conferma. Smette di funzionare subito, e tutto ciò che lo usa ancora riceve un 401. Creazione e revoca vengono scritte nel registro di audit del tuo server, mai il token stesso.

Domande frequenti