API do Bot

O que podes construir

A API do Bot permite que o teu site ou as tuas ferramentas leiam informação em direto sobre o teu servidor Discord. Só lê. Nada do que construíres com ela pode alterar o teu servidor nem mexer nos teus membros. Aqui ficam algumas ideias que as pessoas montam numa tarde.

• Um widget de classificaçãoMostra os teus 10 melhores sobreviventes por nível no site da tua comunidade.
• Uma contagem decrescente de sorteioPõe o sorteio a decorrer, o prémio e a hora de fim na tua página inicial.
• Número de ticketsMostra quantos tickets estão abertos e a rapidez com que a tua equipa responde, num painel para a equipa ou num banner "respondemos em cerca de 10 minutos".
• Um selo de estadoMostra se o teu servidor de jogo está online e quantos jogadores tem.
• Uma lista de produtos da lojaLista os produtos da tua Loja de Donativos com preços no teu próprio site e liga diretamente ao pagamento.

Passo a passo: cria o teu token

Um token é uma palavra-passe secreta e comprida que permite a um site ou ferramenta ler o teu servidor. Crias no teu painel.

1. 01

   Abre a página da API do Bot

   Inicia sessão em dayzhub.net, abre o teu painel, escolhe o teu servidor e escolhe API do Bot na secção Gestão do menu lateral. Só quem tem a permissão Gerir Servidor a vê. Os membros com acesso da equipa não.

2. 02

   Dá-lhe um nome

   Escreve um nome curto que diga para que serve, por exemplo "Classificação do site". Usa um token por site ou ferramenta.

3. 03

   Escolhe o que pode ler

   Marca as caixas dos dados de que precisas, como sorteios ou a classificação de níveis. Menos caixas é mais seguro. Podes sempre criar outro token mais tarde.

4. 04

   Site permitido (só às vezes)

   Deixa vazio, a não ser que uma página web nos navegadores dos teus visitantes chame a API diretamente. Nesse caso escreve o endereço do teu site exatamente, como https://oteusite.com, sem caminho no fim.

5. 05

   Carrega em Criar token e copia-o

   Aparece uma caixa com o teu token, que começa por dhba_. Carrega em Copiar e cola-o logo num sítio seguro. É mostrado apenas uma vez. Se o perderes, crias um novo.

6. 06

   Mantém-no secreto

   Trata o token como uma palavra-passe. Não o publiques no Discord, não o ponhas num projeto público do GitHub e não o colles numa página web que os visitantes possam ler. Guarda-o no teu próprio servidor ou num gestor de palavras-passe.

O teu primeiro pedido

Vamos verificar se o teu token funciona. Precisas de duas coisas: o token que acabaste de copiar e o ID do teu servidor (no Discord, ativa o Modo de Programador nas definições, depois clica com o botão direito no servidor e escolhe Copiar ID do Servidor). A primeira chamada abaixo só precisa do token.

Substitui dhba_YOUR_TOKEN pelo teu token verdadeiro em todos os exemplos. Cada um envia o token num cabeçalho chamado Authorization. Pô-lo no endereço web não funciona.

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

O que recebes de volta

Cada resposta é JSON. As respostas bem-sucedidas têm "ok": true e os teus dados. As listas vêm com uma parte "page": quando "hasMore" é true, passa o valor de "nextCursor" como ?cursor= para obter a página seguinte. As datas estão em 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" }

A lista completa de endpoints e de todos os campos está na descrição legível por máquinas em /api/v1/bot/openapi.json. Cada resposta traz o cabeçalho X-Request-Id, e os erros repetem-no como requestId. Indica-o quando contactares o suporte.

Limites, planos e privacidade

• Só de leituraNão há botões que alterem nada. Só respondemos a pedidos GET.
• PlanosO teu servidor precisa de um plano pago ou de um teste gratuito ativo. Os dados de sorteios precisam do Premium 2. A lista da loja precisa de acesso pago a sério, porque o teste gratuito não inclui a Loja de Donativos.
• Quantos tokens podes terO Premium 1 inclui 2 tokens ativos, o Premium 2 inclui 5 e o Premium 3 inclui 10. Um teste gratuito ou um servidor patrocinado conta como Premium 1. Revoga os que já não usas para libertar um lugar. Se o teu plano descer, os tokens que já tens continuam a funcionar. Apenas não podes criar novos até estares abaixo do limite.
• Limites de velocidadeCada token pode fazer 60 pedidos por minuto no Premium 1, 120 no Premium 2 e 300 no Premium 3, e um endereço de internet 300 por minuto. Acima do limite recebes uma resposta 429 com um cabeçalho Retry-After que indica quantos segundos esperar.
• Consultar com cuidadoAs respostas incluem um ETag. Envia-o de volta num cabeçalho If-None-Match e, quando nada mudou, recebes uma pequenina resposta 304 em vez de todos os dados. Perguntar de 30 em 30 ou de 60 em 60 segundos chega bem, e a maioria dos widgets pode perguntar com menos frequência.
• O que nunca é partilhadoTranscrições e mensagens de tickets, candidaturas e respetivas respostas, pagamentos e encomendas, endereços de e-mail, nomes e avatares, e as pessoas que participaram num sorteio. Só recebes contagens, mais IDs numéricos do Discord onde a funcionalidade já mostra pessoas publicamente no Discord, como o anfitrião de um sorteio ou a classificação de níveis.
• Membros que optaram por sairQuem usou /privacy optout aparece sempre como anónimo (um id null). A posição e os números continuam a contar, por isso os totais batem certo.

Resolução de problemas

Revogar e trocar um token

Faz isto logo se um token foi partilhado por engano, publicado em público ou se alguém que o conhecia saiu da tua equipa.

1. 01

   Cria primeiro o novo token

   Na página da API do Bot cria um substituto com as mesmas definições e copia-o.

2. 02

   Muda o teu site ou ferramenta

   Põe o novo token em todo o lado onde o antigo era usado e verifica se tudo continua a funcionar.

3. 03

   Revoga o antigo

   Na lista dos teus tokens, carrega em Revogar no antigo e confirma. Deixa de funcionar de imediato, e tudo o que ainda o use recebe um 401. A criação e a revogação ficam registadas no registo de auditoria do teu servidor, nunca o token em si.

Perguntas frequentes