Documentação da API do Bot

Autenticação

Cria um token na página API do Bot do teu painel e envia-o no cabeçalho Authorization: Authorization: Bearer <token>. Um token pertence a um servidor e só lê esse servidor. É mostrado uma vez; o DayZ Hub guarda apenas a sua impressão digital.

curl -H "Authorization: Bearer dhba_..." \
  https://dayzhub.net/api/v1/bot/guilds/<guildId>

URL base: https://dayzhub.net/api/v1/bot

Endpoints

Cada resposta é JSON no mesmo formato. As listas são paginadas com limit (1 a 100) e o cursor de page.nextCursor.

{ "ok": true, "data": [ ... ], "page": { "limit": 25, "hasMore": true, "nextCursor": "eyJpZCI6Ij..." } }

Âmbitos

Cada token tem apenas os âmbitos que lhe deste. Todos são só de leitura; nada pode ser alterado através desta API.

Privacidade dos membros

Os membros só aparecem onde a funcionalidade já os mostra publicamente, como um id do Discord. Um membro que optou por não ter os dados tratados é sempre mostrado como anónimo, como abaixo. Nomes, mensagens, tickets e respostas de formulários nunca fazem parte da API.

{ "id": null, "anonymous": true }

Limites

Os limites seguem o plano do servidor. Premium 1: 2 tokens ativos, 60 pedidos por minuto por token. Premium 2: 5 tokens, 120 por minuto. Premium 3: 10 tokens, 300 por minuto. Um teste gratuito ou um servidor patrocinado conta como Premium 1. Cada endereço IP pode fazer 300 pedidos por minuto. Acima do limite recebes 429 com o cabeçalho Retry-After. Um plano que desce não revoga nenhum token: os que tens continuam a funcionar e só os novos ficam bloqueados até estares abaixo do limite. O servidor precisa de um plano pago ou de um teste ativo.

Cache

As respostas trazem um ETag e uma cache privada curta. Envia If-None-Match para receber 304 quando nada mudou. Consultar a cada 30 a 60 segundos chega bem.

Navegadores e CORS

Chama a API a partir do teu servidor. O CORS está desligado por omissão. Se uma página web tiver de a chamar no navegador de um visitante, define um site permitido no token; pedidos de qualquer outra origem são recusados. Tudo o que está numa página web é visível para os visitantes.

O teu token, plano e limites

GET /me não verifica o plano. Além do próprio token, devolve plan (premium1, premium2, premium3 ou none), limits (tokens e perMinute desse plano) e tokensUsed (tokens ativos do servidor). rateLimitPerMin é o ritmo que este token tem neste momento.

{ "ok": true, "data": { "guildId": "123456789012345678", "name": "Website", "prefix": "dhba_aB3dE", "scopes": ["guild:read"],
  "allowedOrigin": null, "rateLimitPerMin": 120, "createdAt": "2026-10-01T12:00:00.000Z",
  "plan": "premium2", "limits": { "tokens": 5, "perMinute": 120 }, "tokensUsed": 2 } }

Identificadores de pedido

Cada resposta traz o cabeçalho X-Request-Id. Se enviares o teu próprio X-Request-Id (até 64 letras, dígitos e . _ : -), ele é mantido; caso contrário, é gerado um. Os erros repetem-no como requestId. Indica-o quando contactares o suporte.

X-Request-Id: 3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c

{ "ok": false, "error": "rate_limited", "code": "rate_limited", "message": "Too many requests", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

Erros

Os erros são JSON com ok: false, um código estável em code (error tem o mesmo valor), uma mensagem curta e o requestId. Decide pelo código, nunca pelo texto da mensagem.