Para desarrolladores
API y webhooks
Actualizado el 12 de octubre de 2026
Empezar
Qué puedes hacer
Nerion te deja conectar tu instancia con tus propias herramientas: un bot de Discord, tu web, un panel o tu sistema de whitelist. Hay dos piezas:
- La API: tu código le pregunta cosas a Nerion (quién está jugando, quién tiene acceso, qué cambió) y puede dar o quitar acceso. Usa claves de API.
- Los webhooks: Nerion le avisa a tu código (o a un canal de Discord) cada vez que pasa algo: entra un jugador, alguien pide acceso, hay un crash…
Las dos se configuran en el dashboard, en tu instancia › Config › Desarrolladores. Para verla necesitas ser el dueño o tener el permiso de integraciones.
Sin programar: avisos en Discord
Si solo quieres que lo que pasa en tu instancia llegue a un canal de tu servidor de Discord, no necesitas nada de lo demás:
- En Discord: Editar canal › Integraciones › Webhooks › Nuevo webhook › Copiar URL del webhook.
- En el dashboard: Config › Desarrolladores › Nuevo webhook, elige Un canal de Discord, pega la URL y marca los eventos que quieres.
- Pulsa Probar: debería aparecer un mensaje en el canal.
Los mensajes salen en español o inglés, según elijas, por ejemplo «▶️ Pablo abrió la instancia» o «💥 Pablo tuvo un crash», con un enlace que abre ese crash en el dashboard.
API
Claves de API
Crea una clave en Config › Desarrolladores › Nueva clave. Le pones un nombre, eliges qué puede hacer y, si quieres, cuándo vence. La clave (empieza con nrn_) se muestra una sola vez: cópiala y guárdala en un lugar seguro, como una variable de entorno. Si la pierdes, revócala y crea otra.
| Permiso | Qué permite |
|---|---|
instance:read | Ver la instancia y sus servidores. |
players:read | Ver quién está jugando ahora. |
allowlist:read | Ver la lista de acceso. |
allowlist:write | Dar y quitar acceso. |
activity:read | Ver el registro de actividad. |
- Una clave actúa con los permisos de quien la creó. Si esa persona deja de tener el permiso de integraciones en la instancia, la clave deja de funcionar. Lo que haga la clave queda en la actividad a su nombre.
- Cada instancia puede tener hasta 10 claves activas. Revocar una corta su acceso al instante.
- Nunca pongas una clave en código que se ejecute en el navegador o en un mod: cualquiera podría leerla.
Cómo llamar a la API
Todas las rutas cuelgan de la URL de tu instancia, que aparece en Config › Desarrolladores:
https://launcherapi.onesimpledev.net/api/v1/instances/{instanceId}
Manda la clave en el encabezado Authorization de cada petición:
curl -H "Authorization: Bearer nrn_…" \
https://launcherapi.onesimpledev.net/api/v1/instances/{instanceId}
Las respuestas son JSON. Cada clave puede hacer hasta 120 peticiones por minuto; si te pasas, recibes 429 y debes esperar un poco. Los campos sin valor pueden venir como null, y en el futuro pueden aparecer campos nuevos: ignora los que no conozcas.
Endpoints
Ver la instancia
GET / · permiso instance:read
{
"id": "6f1c…",
"name": "Survival Nerion",
"minecraftVersion": "1.20.1",
"loader": "FABRIC",
"loaderVersion": "0.16.5",
"accessMode": "ALLOWLIST",
"status": "AVAILABLE",
"onlinePlayers": 12,
"onlineServers": 2
}
accessMode: PUBLIC, ACCESS_KEY o ALLOWLIST. status: AVAILABLE, SCHEDULED, MAINTENANCE, DISABLED o ERROR.
Ver los servidores
GET /servers · permiso instance:read. Son los servidores que registró el plugin de Nerion.
[
{
"id": "a41b…",
"name": "Survival",
"type": "SURVIVAL",
"status": "ONLINE",
"currentPlayers": 8,
"maxPlayers": 50,
"lastHeartbeat": "2026-10-12T20:00:00Z"
}
]
Ver quién está jugando
GET /players · permiso players:read. Solo incluye servidores en línea.
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Pablo",
"avatarUrl": "https://…",
"serverId": "a41b…",
"serverName": "Survival"
}
]
Ver la lista de acceso
GET /allowlist · permiso allowlist:read
[
{
"accountId": "2c9f…",
"displayName": "Pablo",
"source": "MANUAL",
"addedAt": "2026-10-01T18:30:00Z",
"expiresAt": null
}
]
source dice de dónde viene el acceso: MANUAL (dashboard o API), o automático por PATREON, DISCORD, TWITCH o KICK.
Dar acceso
POST /allowlist · permiso allowlist:write. Manda la cuenta de Nerion o un nombre de Minecraft premium:
{ "accountId": "2c9f…" }
{ "minecraftUsername": "Pablo_MC" }
Responde 201:
{ "accountId": "2c9f…", "minecraftUsername": null, "pending": false }
Con un nombre de Minecraft de alguien que todavía no usa Nerion, el acceso queda pendiente ("pending": true) y se le da solo cuando entre a Nerion con esa cuenta.
Quitar acceso
DELETE /allowlist/{accountId} · permiso allowlist:write. Responde 204.
Ver la actividad
GET /activity?page=0&size=20 · permiso activity:read. Lo más reciente primero; size llega hasta 100.
{
"items": [
{
"id": "e8d2…",
"action": "INSTANCE_ALLOWLIST_ACCOUNT_ADDED",
"details": "Added account 2c9f… to the ALLOWLIST",
"actor": "pablo",
"createdAt": "2026-10-12T19:58:00Z"
}
],
"page": 0,
"size": 20,
"totalPages": 4,
"totalItems": 71
}
Errores
Los errores responden con un código HTTP y, cuando aplica, un code que puedes usar en tu código:
{ "status": 403, "error": "Forbidden", "code": "DEVELOPER_KEY_MISSING_SCOPE", "params": { "scope": "allowlist:write" } }
| HTTP | code | Qué pasó |
|---|---|---|
| 401 | DEVELOPER_KEY_INVALID | Falta la clave, no existe, está revocada o vencida, o quien la creó ya no tiene permiso. |
| 403 | DEVELOPER_KEY_WRONG_INSTANCE | La clave es de otra instancia. |
| 403 | DEVELOPER_KEY_MISSING_SCOPE | La clave no tiene ese permiso (params.scope). |
| 429 | DEVELOPER_KEY_RATE_LIMITED | Más de 120 peticiones en un minuto. |
| 400 | ALLOWLIST_TARGET_REQUIRED | Falta accountId o minecraftUsername. |
| 404 | ACCOUNT_NOT_FOUND | No existe esa cuenta de Nerion. |
Webhooks
Cómo funcionan
Un webhook es una URL a la que Nerion le manda un POST cada vez que pasa uno de los eventos que elegiste. Los creas en Config › Desarrolladores › Nuevo webhook, en uno de dos formatos:
- Un canal de Discord: pegas la URL de un webhook de Discord y recibes mensajes legibles. No hay firma ni JSON que procesar.
- Tu servidor (JSON): recibes el evento completo en JSON, firmado. Es el que se documenta abajo.
Requisitos de la URL: https y accesible desde internet (no se aceptan direcciones privadas). Nerion no sigue redirecciones. Cada instancia puede tener hasta 10 webhooks.
Qué recibe tu servidor
POST /tu-ruta HTTP/1.1
Content-Type: application/json
User-Agent: Nerion-Webhooks/1
X-Nerion-Event: player.joined
X-Nerion-Delivery: 3f0d…
X-Nerion-Timestamp: 1760299200
X-Nerion-Signature: sha256=6a85cb11…
{
"id": "9b2e…",
"type": "player.joined",
"instanceId": "6f1c…",
"occurredAt": "2026-10-12T20:00:00Z",
"data": { … }
}
ididentifica el evento. Rara vez un evento puede llegar dos veces: si te importa, ignora losidque ya procesaste.- Los eventos no siempre llegan en orden; usa
occurredAtsi lo necesitas. - Responde con cualquier código 2xx en menos de 10 segundos. Si tienes trabajo largo, responde primero y hazlo después.
Verificar la firma
Al crear un webhook JSON te damos un secreto (empieza con whsec_, se muestra una sola vez; si lo pierdes, usa Nuevo secreto). Cada envío trae X-Nerion-Signature: sha256=…, un HMAC-SHA256 en hexadecimal de timestamp + "." + cuerpo, donde el timestamp es X-Nerion-Timestamp (segundos Unix) y el cuerpo son los bytes exactos que recibiste. Verifícala antes de confiar en el evento, y rechaza timestamps de hace más de 5 minutos.
Node.js
import crypto from 'node:crypto';
// rawBody: el cuerpo tal como llegó (string), antes de hacer JSON.parse.
function isFromNerion(headers, rawBody, secret) {
const timestamp = headers['x-nerion-timestamp'];
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`).digest('hex');
const given = headers['x-nerion-signature'] ?? '';
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
return fresh && given.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
Python
import hashlib, hmac, time
def is_from_nerion(headers, raw_body: bytes, secret: str) -> bool:
timestamp = headers.get("X-Nerion-Timestamp", "")
expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body,
hashlib.sha256).hexdigest()
fresh = timestamp.isdigit() and abs(time.time() - int(timestamp)) < 300
return fresh and hmac.compare_digest(headers.get("X-Nerion-Signature", ""), expected)
Reintentos y apagado automático
- Si tu servidor no responde 2xx (o tarda más de 10 segundos), reintentamos a los 1, 5 y 30 minutos. Después de eso, ese envío se da por perdido.
- Si se pierden 10 envíos seguidos, el webhook se apaga solo y el dashboard lo avisa. Arregla la URL y vuelve a encenderlo.
- En Historial ves los últimos envíos con su estado, el código que respondió tu servidor y el error. Se guardan 7 días.
- Probar manda al momento un evento
webhook.testy te muestra qué respondió tu servidor.
Eventos
Lista de eventos
En data solo vienen los campos que tienen valor.
player.started_playing · player.stopped_playing
Un jugador abre o cierra la instancia desde el launcher de Nerion. No hace falta tener un servidor con el plugin.
"data": {
"playerAccountId": "2c9f…",
"playerName": "Pablo", // su nombre en Nerion
"minecraftUsername": "Pablo_MC", // la cuenta de Minecraft con la que juega
"durationSeconds": 1520 // solo en stopped, si el launcher la sabe
}
player.joined · player.left
Un jugador entra o sale de un servidor que tiene el plugin de Nerion. Se detecta con el latido del plugin, así que puede tardar unos segundos.
"data": {
"serverId": "a41b…",
"serverName": "Survival",
"player": { "uuid": "069a79f4-…", "name": "Pablo", "avatarUrl": "https://…" }
}
allowlist.added · allowlist.removed
Una cuenta gana o pierde acceso a la instancia.
"data": { "accountId": "2c9f…", "source": "MANUAL" }
source: MANUAL (dashboard o API), INVITE (una invitación por nombre que se cumplió), o PATREON, DISCORD, TWITCH, KICK (membresías).
access_request.created · access_request.decided
Alguien pidió acceso con /join en tu servidor de Discord, y después el staff lo aprobó o rechazó.
"data": {
"requestId": "71ac…",
"discordUserId": "1234567890",
"discordUsername": "pablito",
"playerAccountId": "2c9f…", // si su Discord está vinculado a Nerion
"minecraftUsername": "Pablo_MC", // si pidió por nombre
"status": "APPROVED", // solo en decided: APPROVED o REJECTED
"decidedBy": "moderador" // solo en decided
}
crash.reported
El juego de un jugador se cerró con un error, o no llegó a abrir (phase: LAUNCH_FAILED).
"data": {
"crashId": "c0d3…",
"phase": "IN_GAME_CRASH",
"cause": "GPU_DRIVER",
"exitCode": 1,
"minecraftVersion": "1.20.1",
"launcherVersion": "0.1.77",
"playerAccountId": "2c9f…",
"playerName": "Pablo",
"minecraftUsername": "Pablo_MC",
"dashboardUrl": "https://…/instances?instance=…§ion=crashes&crash=c0d3…"
}
cause es la causa probable: GPU_DRIVER, JAVA_TOO_OLD, JAVA_UNAVAILABLE, JAVA_BLOCKED, JAVA_OPTIONS, OUT_OF_MEMORY, JVM_CRASH, DISK_SPACE, LAUNCH_FAILED, GAME_ERROR. dashboardUrl abre ese crash en el dashboard (hace falta tener el permiso de ver reportes). Los crashes se guardan 30 días.
feedback.created
Un jugador mandó un reporte desde el launcher. category: BUG o SUGGESTION.
"data": { "feedbackId": "f33d…", "category": "BUG", "body": "No carga el mapa…", "playerAccountId": "2c9f…" }
activity.logged
Cualquier cambio que entra en la actividad de la instancia. Es el más completo y también el que más eventos manda.
"data": { "action": "INSTANCE_MOD_ADDED", "actor": "pablo", "details": "sodium-0.5.11.jar" }
webhook.test
Solo cuando pulsas Probar.
"data": { "message": "This is a test event from Nerion." }