Documentación de la API del Bot

Autenticación

Crea un token en la página API del Bot de tu panel y envíalo en la cabecera Authorization: Authorization: Bearer <token>. Un token pertenece a un servidor y solo lee ese servidor. Se muestra una vez; DayZ Hub solo guarda su huella.

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

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

Endpoints

Cada respuesta es JSON con el mismo sobre. Las listas se paginan con limit (de 1 a 100) y el cursor de page.nextCursor.

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

Scopes

Cada token solo tiene los scopes que le diste. Todos son de solo lectura; nada se puede cambiar con esta API.

Privacidad de los miembros

Los miembros solo aparecen donde la función ya los muestra públicamente, como un id de Discord. Un miembro que se negó al tratamiento de datos se muestra siempre como anónimo, como abajo. Nombres, mensajes, tickets y respuestas de formularios nunca forman parte de la API.

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

Límites

Los límites dependen del plan del servidor. Premium 1: 2 tokens activos, 60 peticiones por minuto por token. Premium 2: 5 tokens, 120 por minuto. Premium 3: 10 tokens, 300 por minuto. Una prueba gratuita o un servidor patrocinado cuenta como Premium 1. Cada dirección IP puede hacer 300 peticiones por minuto. Al superarlo recibes 429 con la cabecera Retry-After. Bajar de plan no revoca ningún token: los que tienes siguen funcionando y solo se bloquean los nuevos hasta que estés por debajo del límite. El servidor necesita un plan de pago o una prueba activa.

Caché

Las respuestas llevan un ETag y una caché privada corta. Envía If-None-Match para recibir 304 cuando nada ha cambiado. Consultar cada 30 a 60 segundos es más que suficiente.

Navegadores y CORS

Llama a la API desde tu servidor. CORS está desactivado por defecto. Si una página web debe llamarla desde el navegador de un visitante, define una web permitida en el token; las peticiones de cualquier otro origen se rechazan. Todo lo que hay en una página web es visible para los visitantes.

Tu token, plan y límites

GET /me no comprueba el plan. Además del propio token devuelve plan (premium1, premium2, premium3 o none), limits (tokens y perMinute de ese plan) y tokensUsed (tokens activos del servidor). rateLimitPerMin es la tasa que tiene este token ahora mismo.

{ "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 petición

Cada respuesta lleva la cabecera X-Request-Id. Si envías tu propio X-Request-Id (hasta 64 letras, dígitos y . _ : -), se conserva; si no, se genera uno. Los errores lo repiten como requestId. Indícalo cuando contactes con soporte.

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" }

Errores

Los errores son JSON con ok: false, un código estable en code (error contiene el mismo valor), un mensaje corto y el requestId. Decide por el código, nunca por el texto del mensaje.