Rutas, autenticación y ejemplos de datos para el plugin de Minecraft: vinculación de cuentas y reporte de actividad. Con esto el plugin puede avanzar mientras implementamos nuestro lado.
El plugin solo informa: quién se vincula y quién está conectado y activo. El bot de economía es el que paga, en su ciclo de voice de cada minuto, a quien esté a la vez en Minecraft y en voice. La cantidad, cada cuánto se paga y el tope diario se configuran desde el panel web (apartado Minecraft).
Como el plugin nunca dispara pagos, reenviar un reporte o reintentar una petición no puede pagar dos veces.
| Entorno | URL base |
|---|---|
| Producción | https://api.latinos.gg/api (a confirmar) |
| Pruebas | Te la pasamos junto con la clave de pruebas. |
Todas las peticiones del plugin llevan estas cabeceras:
X-Minecraft-Key: mc_k7Hq2…(clave del servidor) Content-Type: application/json User-Agent: LatinosMC-Plugin/1.0
401.2026-10-21T19:00:00.000Z)./vincular en el juego.POST /minecraft/link-codes y le muestra el código (por ejemplo K7P2QX), que dura 10 minutos./minecraft vincular código:K7P2QX, o en su perfil de la web.linked en la respuesta de /minecraft/activity. El plugin puede avisarle «Cuenta vinculada» cuando lo detecte.
sequenceDiagram
participant J as Jugador
participant P as Plugin
participant A as API Latinos
participant B as Bot (Discord)
J->>P: /vincular
P->>A: POST /minecraft/link-codes {uuid, name}
A-->>P: 201 {code: "K7P2QX", expiresAt}
P-->>J: "Tu código es K7P2QX"
J->>B: /minecraft vincular código:K7P2QX
B->>A: confirma el código (ruta interna)
A-->>B: vinculado
P->>A: POST /minecraft/activity (cada 60 s)
A-->>P: 200 {linked: [uuid, …]}
P-->>J: "Cuenta vinculada"
Regla: una cuenta de Minecraft por usuario de Discord y un usuario por UUID. Para cambiar de cuenta, primero se desvincula desde Discord o la web.
Para comprobar al arrancar el plugin que la clave es válida y a qué servidor pertenece. Sin cuerpo.
{
"server": "skyblock",
"bonusEnabled": false,
"reportIntervalSeconds": 60,
"staleAfterSeconds": 180
}
Pide un código de vinculación para un jugador. Pedir uno nuevo anula el anterior de ese UUID.
{
"uuid": "3f8c1e2a-5b7d-4c9e-a1f0-6d2b8e4c7a90",
"name": "SparkMC"
}
| Campo | Tipo | Regla |
|---|---|---|
uuid | string | Obligatorio. UUID con guiones, el que usa el servidor para ese jugador. |
name | string | Obligatorio. Nick actual, 1–32 caracteres. Solo para mostrarlo en el panel y en Discord. |
{
"code": "K7P2QX",
"expiresAt": "2026-10-21T19:10:00.000Z",
"ttlSeconds": 600
}
El código tiene 6 caracteres de A–Z y 2–9, sin los que se confunden (0 O 1 I).
{
"error": "Esta cuenta de Minecraft ya está vinculada",
"code": "ALREADY_LINKED",
"discordUsername": "spark"
}
{
"error": "Demasiados códigos para este jugador",
"code": "TOO_MANY_CODES",
"retryAfterSeconds": 420
}
Máximo 5 códigos cada 10 minutos por UUID.
Estado de vinculación de un jugador, por ejemplo para un comando /vinculo en el juego o para avisar al entrar.
{
"linked": true,
"discordId": "123456789012345678",
"discordUsername": "spark",
"linkedAt": "2026-10-21T19:04:12.000Z"
}
{ "linked": false }
La foto de todos los jugadores conectados en este servidor, cada 60 segundos. Quien no viene en la lista se considera desconectado de este servidor.
{
"sentAt": "2026-10-21T19:05:00.000Z",
"players": [
{ "uuid": "3f8c1e2a-5b7d-4c9e-a1f0-6d2b8e4c7a90", "name": "SparkMC", "active": true },
{ "uuid": "b21d7f04-9a3e-4f6b-8c55-0e7a1d9c3f12", "name": "Blackk", "active": false },
{ "uuid": "e94a6c18-2f0b-4d7a-9e31-5c8b7a2d0f46", "name": "lia_mc", "active": true }
]
}
| Campo | Tipo | Regla |
|---|---|---|
sentAt | string ISO | Obligatorio. Hora en que el plugin armó la foto. Si llega una foto más vieja que la última aceptada de este servidor, se ignora. |
players | array | Obligatorio, 0–1000 elementos. Lista vacía = no hay nadie (úsala también al apagar el servidor). |
players[].uuid | string | Obligatorio. Solo jugadores con la sesión iniciada. |
players[].name | string | Obligatorio. Nick actual. |
players[].active | boolean | Obligatorio. false si está AFK según el criterio del plugin. |
{
"server": "skyblock",
"accepted": 3,
"ignored": 0,
"linked": [
"3f8c1e2a-5b7d-4c9e-a1f0-6d2b8e4c7a90",
"e94a6c18-2f0b-4d7a-9e31-5c8b7a2d0f46"
],
"staleAfterSeconds": 180
}
linked: de los jugadores enviados, los que tienen cuenta vinculada. Sirve para avisar «Cuenta vinculada» cuando un UUID aparece por primera vez.ignored: entradas con datos inválidos (UUID mal formado, repetidos). El resto se procesa igual.200 con "stale": true y no se procesa.Todos los errores tienen la forma { "error": "texto", "code": "CODIGO" }.
| HTTP | code | Qué hacer |
|---|---|---|
| 400 | VALIDATION_ERROR | Datos mal formados; el cuerpo trae details con el campo. No reintentar igual. |
| 401 | UNAUTHORIZED | Clave ausente, incorrecta o revocada. Avisar en consola y dejar de enviar hasta corregir la config. |
| 409 | ALREADY_LINKED | Decirle al jugador con qué Discord está vinculado. |
| 429 | RATE_LIMITED / TOO_MANY_CODES | Esperar lo que diga la cabecera Retry-After o retryAfterSeconds. |
| 5xx o timeout | — | activity: no reintentar, la foto del minuto siguiente la reemplaza. link-codes: un reintento tras 2 s; si falla, decir al jugador que pruebe más tarde. |
Timeout recomendado: 5 segundos. Las peticiones deben ir fuera del hilo principal del servidor (async) para no causar lag.
players ni puede usar /vincular hasta poner su contraseña. Si no, cualquiera podría entrar con el nick de otro y contar como él."players": []. Si no llega, caducan solos a los 3 minutos.