API del servidor | Documentación de Noxyr

Qué expone la API

La API es de solo lectura y está limitada a un servidor. Está pensada para páginas de estado, hojas de cálculo y herramientas internas que quieran las cifras del panel sin iniciar sesión. No puede cambiar ajustes, cerrar tickets ni crear facturas.

Todos los endpoints viven bajo https://noxyrbot.com/api/v1 y devuelven JSON. La clave identifica el servidor, así que ningún endpoint pide un ID de servidor.

GET /api/v1/: Qué ámbitos están activos para esta clave y los endpoints a los que puede acceder.
GET /api/v1/server: Nombre, icono, número de miembros, número de conectados, mejoras y fecha de creación.
GET /api/v1/tickets: Totales, recuentos de abiertos y cerrados, volumen de los últimos 7 y 30 días, valoración media.
GET /api/v1/activity?days=30: Mensajes diarios, altas y bajas, hasta 90 días.
GET /api/v1/invoices: Recuentos de facturas, ingresos por moneda y estado de pago. Con el ámbito de enlaces de facturas, ?limit= añade las facturas recientes con una URL descargable de la imagen.
GET /api/v1/reviews: Valoración media, desglose de estrellas y las cinco reseñas públicas más recientes.
GET /api/v1/giveaways: Recuentos de sorteos activos y finalizados, participaciones totales y los sorteos actuales.

Crear una clave

Cada servidor tiene una clave. Se genera en la página de API del servidor y se muestra una sola vez: solo se guarda un hash, así que si pierdes la clave hay que regenerarla, lo que invalida la anterior.

Abre el servidor en el panel y ve a API.
Pulsa Generar y copia la clave que empieza por nxr_. No se volverá a mostrar.
Desactiva los ámbitos que no necesites. Los enlaces de facturas están desactivados por defecto porque exponen imágenes de facturas de clientes.
Opcional: pulsa Configurar canal para que el bot cree en el servidor una categoría y un canal de API con la lista de endpoints.

La página también muestra cuándo se usó la clave por última vez y cuántas peticiones ha hecho, que es la forma más rápida de detectar una clave filtrada. Desactívala con el interruptor, o revócala para eliminarla por completo.

Ámbitos

Los ámbitos controlan endpoints, no campos. Una petición a un endpoint cuyo ámbito está desactivado recibe un 403 con un mensaje que indica el ámbito.

overview: /server
tickets: /tickets
activity: /activity
invoices: /invoices
invoiceLinks: Añade la lista de facturas recientes con enlaces de imagen. Desactivado por defecto.
reviews: /reviews
giveaways: /giveaways

Autenticación y petición de ejemplo

Envía la clave como token Bearer en la cabecera Authorization. Las llamadas desde el navegador están permitidas (CORS está abierto), pero una clave en código de front-end es una clave pública, así que llama a la API desde un servidor que controles.

curl -H "Authorization: Bearer nxr_your_key" https://noxyrbot.com/api/v1/tickets
Respuesta: {"total":128,"open":4,"closed":124,"opened7d":9,"opened30d":41,"closed7d":8,"averageRating":4.6,"ratingsCount":37}

Límites de peticiones

Cada clave puede hacer 60 peticiones por minuto. El límite se devuelve en las cabeceras RateLimit estándar de cada respuesta, y superarlo devuelve HTTP 429 con el error "rate_limited". No consultes más rápido de lo que cambian los datos: los totales de tickets y ventas se pueden leer una vez por minuto.

Errores

Cada error es JSON con un código de error legible por máquinas y un mensaje para personas.

401 no autorizado: Falta la cabecera Authorization, no es un token Bearer o la clave no existe.
403 key_disabled: La clave se desactivó en el panel.
403 scope_disabled: Ese ámbito está desactivado para esta clave.
404 not_found: Endpoint desconocido. El mensaje lista los válidos.
404 guild_unavailable: El bot ya no está en el servidor.
429 rate_limited: Más de 60 peticiones en un minuto.
500 internal_error: Algo falló en el lado de Noxyr. Vuelve a intentarlo más tarde.