API del Bot

Qué puedes construir

La API del Bot permite que tu propia web o tus herramientas lean datos en vivo de tu servidor de Discord. Solo lee. Nada de lo que construyas con ella puede cambiar tu servidor ni tocar a tus miembros. Aquí tienes algunas ideas que la gente monta en una tarde.

• Un widget de clasificaciónMuestra a tus 10 mejores supervivientes por nivel en la web de tu comunidad.
• Una cuenta atrás de sorteoPon en tu página de inicio el sorteo en curso, su premio y cuándo termina.
• Recuento de ticketsMuestra cuántos tickets hay abiertos y qué tan rápido responde tu equipo, para un panel del staff o un banner de "respondemos en unos 10 minutos".
• Una insignia de estadoMuestra si tu servidor de juego está en línea y cuántos jugadores hay.
• Una lista de productos de la tiendaLista los productos de tu Tienda de donaciones con precios en tu propia web y enlaza directo al pago.

Paso a paso: crea tu token

Un token es una contraseña larga y secreta que permite a una web o herramienta leer tu servidor. Lo creas en tu panel.

1. 01

   Abre la página API del Bot

   Inicia sesión en dayzhub.net, abre tu panel, elige tu servidor y selecciona API del Bot en la sección Gestión del menú lateral. Solo la ven las personas con el permiso Gestionar servidor. Los miembros con Acceso del equipo no.

2. 02

   Ponle nombre

   Escribe un nombre corto que te diga para qué sirve, por ejemplo "Clasificación de la web". Usa un token por web o herramienta.

3. 03

   Elige lo que puede leer

   Marca las casillas de los datos que necesitas, como sorteos o la clasificación de niveles. Menos casillas es más seguro. Siempre puedes crear otro token más adelante.

4. 04

   Web permitida (solo a veces)

   Déjalo vacío, salvo que una página web llame a la API directamente desde los navegadores de tus visitantes. En ese caso escribe la dirección de tu web exactamente, como https://tuweb.com, sin ruta al final.

5. 05

   Pulsa Crear token y cópialo

   Aparece un cuadro con tu token, que empieza por dhba_. Pulsa Copiar y pégalo enseguida en un lugar seguro. Solo se muestra una vez. Si lo pierdes, creas uno nuevo.

6. 06

   Mantenlo en secreto

   Trata el token como una contraseña. No lo publiques en Discord, no lo pongas en un proyecto público de GitHub y no lo pegues en una página web que los visitantes puedan leer. Guárdalo en tu propio servidor o en un gestor de contraseñas.

Tu primera petición

Comprobemos que tu token funciona. Necesitas dos cosas: el token que acabas de copiar y el ID de tu servidor (en Discord, activa el Modo desarrollador en los ajustes, luego haz clic derecho en tu servidor y elige Copiar ID del servidor). La primera llamada de abajo solo necesita el token.

Sustituye dhba_YOUR_TOKEN por tu token real en cada ejemplo. Todos envían el token en una cabecera llamada Authorization. Ponerlo en la dirección web no 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));

Qué devuelve

Cada respuesta es JSON. Las respuestas correctas llevan "ok": true y tus datos. Las listas vienen con una parte "page": cuando "hasMore" es true, devuelve el valor de "nextCursor" como ?cursor= para obtener la página siguiente. Las fechas están en 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" }

La lista completa de endpoints y de todos los campos está en la descripción legible por máquinas en /api/v1/bot/openapi.json. Cada respuesta lleva la cabecera X-Request-Id, y los errores la repiten como requestId. Indícala cuando contactes con soporte.

Límites, planes y privacidad

• Solo lecturaNo hay botones que cambien nada. Solo se responden peticiones GET.
• PlanesTu servidor necesita un plan de pago o una prueba gratuita activa. Los datos de sorteos necesitan Premium 2. La lista de la tienda necesita acceso de pago real, porque la prueba gratuita no incluye la Tienda de donaciones.
• Cuántos tokens puedes tenerPremium 1 incluye 2 tokens activos, Premium 2 incluye 5 y Premium 3 incluye 10. Una prueba gratuita o un servidor patrocinado cuenta como Premium 1. Revoca los que ya no uses para liberar sitio. Si tu plan baja, los tokens que ya tienes siguen funcionando. Solo no puedes crear nuevos hasta que estés por debajo del límite.
• Límites de velocidadCada token puede hacer 60 peticiones por minuto en Premium 1, 120 en Premium 2 y 300 en Premium 3, y una dirección de internet 300 por minuto. Al superarlo recibes una respuesta 429 con una cabecera Retry-After que indica cuántos segundos esperar.
• Consultar con cuidadoLas respuestas incluyen un ETag. Devuélvelo en una cabecera If-None-Match y, si nada ha cambiado, recibes una respuesta 304 diminuta en vez de todos los datos. Preguntar cada 30 a 60 segundos es de sobra, y la mayoría de los widgets pueden preguntar con menos frecuencia.
• Lo que nunca se comparteTranscripciones y mensajes de tickets, solicitudes y sus respuestas, pagos y pedidos, direcciones de correo, nombres y avatares, y las personas que participaron en un sorteo. Solo recibes recuentos, más ID numéricos de Discord donde la función ya muestra a las personas públicamente en Discord, como el anfitrión de un sorteo o la clasificación de niveles.
• Miembros que se han negadoQuien haya usado /privacy optout aparece siempre como anónimo (un id de null). Su puesto y sus números siguen contando, así que los totales cuadran.

Solución de problemas

Revocar y renovar un token

Hazlo al instante si un token se compartió por error, se publicó o si una persona que lo conocía ha dejado tu equipo.

1. 01

   Crea primero el token nuevo

   En la página API del Bot crea un reemplazo con los mismos ajustes y cópialo.

2. 02

   Cambia tu web o herramienta

   Pon el token nuevo donde se usaba el antiguo y comprueba que todo sigue funcionando.

3. 03

   Revoca el antiguo

   En la lista de tus tokens, pulsa Revocar en el antiguo y confirma. Deja de funcionar al instante y todo lo que aún lo use recibirá un 401. La creación y la revocación se anotan en el registro de auditoría de tu servidor, nunca el token en sí.

Preguntas frecuentes