Saltar al contenido
Nerion
Inicio

Explora la plataforma

JuegosJugar con amigosCreadores

Juegos destacados

Backrooms MODPo-KemonitoBackrooms Found FootageKasuSafio 1Todos los juegos

Para creadores

Cómo publicarDashboardMonetizaciónAPI y webhooksAcuerdo de creador
Quiénes somos Noticias
EN
EN Descargar

Para desarrolladores

API y webhooks

Actualizado el 12 de octubre de 2026

Empezar

Qué puedes hacerSin programar: avisos en Discord

API

Claves de APICómo llamar a la APIEndpointsErrores

Webhooks

Cómo funcionanQué recibe tu servidorVerificar la firmaReintentos y apagado automático

Eventos

Lista de eventos

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:

  1. En Discord: Editar canal › Integraciones › Webhooks › Nuevo webhook › Copiar URL del webhook.
  2. En el dashboard: Config › Desarrolladores › Nuevo webhook, elige Un canal de Discord, pega la URL y marca los eventos que quieres.
  3. 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.

PermisoQué permite
instance:readVer la instancia y sus servidores.
players:readVer quién está jugando ahora.
allowlist:readVer la lista de acceso.
allowlist:writeDar y quitar acceso.
activity:readVer 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" } }
HTTPcodeQué pasó
401DEVELOPER_KEY_INVALIDFalta la clave, no existe, está revocada o vencida, o quien la creó ya no tiene permiso.
403DEVELOPER_KEY_WRONG_INSTANCELa clave es de otra instancia.
403DEVELOPER_KEY_MISSING_SCOPELa clave no tiene ese permiso (params.scope).
429DEVELOPER_KEY_RATE_LIMITEDMás de 120 peticiones en un minuto.
400ALLOWLIST_TARGET_REQUIREDFalta accountId o minecraftUsername.
404ACCOUNT_NOT_FOUNDNo 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": { … }
}
  • id identifica el evento. Rara vez un evento puede llegar dos veces: si te importa, ignora los id que ya procesaste.
  • Los eventos no siempre llegan en orden; usa occurredAt si 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.test y 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=…&section=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." }
Nerion

La plataforma que conecta jugadores con experiencias de Minecraft.

Nerion

InicioQuiénes somosNoticias

Plataforma

JuegosJugar con amigosCreadores

Legal

TérminosPrivacidadAcuerdo de creador

Comunidad

Discord

© 2026 Nerion. Nerion no está afiliado a Mojang Studios ni a Microsoft. Minecraft es una marca de Mojang Studios.