Referencia de la API REST

Los SDK son clientes ligeros sobre esta API HTTPS + JSON, así que cualquier motor, herramienta o servidor puede usarla directamente.

Los comentarios del código y los nombres de la API se mantienen en inglés para que coincidan con los SDK.

En esta página

Conceptos básicos
Cabeceras
Respuestas
Ejemplo
Endpoints
Proyecto
Autenticación de jugadores
Tablas de clasificación
Configuración remota
Guardado en la nube
Recompensas y billetera

Conceptos básicos#

URL base: https://majacloud.majanite.com/v1. HTTPS es obligatorio salvo desde localhost. Los cuerpos de las solicitudes son JSON con Content-Type: application/json.

Descarga la descripción OpenAPI 3.1 para generar clientes o importarla en Postman o Insomnia.

Cabeceras#

Cabecera	Significado
`X-Project-ID`	ID de proyecto del panel (siempre).
`X-Client-Key`	Clave de cliente pública (siempre; se puede incluir sin riesgo en las builds).
`X-Secret-Key`	Clave secreta de servidor en lugar de la clave de cliente (solo de servidor a servidor).
`Authorization`	Bearer <access_token> para los endpoints de jugador.
`X-Device-ID`	ID de instalación opcional (se usa como etiqueta del dispositivo del invitado).
`X-Majacloud-SDK`	Cliente y versión opcionales, p. ej., unity/2.0.0.

Respuestas#

Todas las respuestas son JSON con ok. Los errores también incluyen un code estable, un message, el request_id y, a veces, details:

var top = await Majacloud.Leaderboards.GetTopAsync("coins", 10);
if (top.Ok)
{
    foreach (var entry in top.Value.Entries)
        Debug.Log($"#{entry.Rank} {entry.PlayerName} {entry.Score}");
}
else if (top.Error.IsRetryable)
{
    // Network, timeout, 5xx or rate limit: try again later
    Debug.Log("Retry in " + top.Error.RetryAfterSeconds + " s");
}
else
{
    Debug.LogWarning(top.Error.Code + ": " + top.Error.Message + " (" + top.Error.RequestId + ")");
}

GDScript

var top := await Majacloud.leaderboards.get_top("coins", 10)
if top.ok:
	for entry in top.value.entries:
		print("#%d %s %d" % [entry.rank, entry.player_name, entry.score])
elif top.is_retryable():
	# Network, timeout, 5xx or rate limit: try again later
	print("Retry in ", top.retry_after, " s")
else:
	push_warning("%s: %s (%s)" % [top.error, top.message, top.request_id])

JavaScript

const top = await mc.leaderboards.getTop('coins', { limit: 10 });
if (top.ok) {
  for (const entry of top.value.entries) {
    console.log(`#${entry.rank} ${entry.player_name} ${entry.score}`);
  }
} else if (top.error.retryable) {
  // Network, timeout, 5xx or rate limit: try again later
  console.log('Retry in', top.error.retryAfter, 's');
} else {
  console.warn(`${top.error.code}: ${top.error.message} (${top.error.requestId})`);
}

JSON

// Success
{ "ok": true, "entries": [ … ], "total": 42 }

// Error (HTTP 4xx/5xx)
{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Project rate limit reached. Try again in a minute.",
    "request_id": "6f1c2a9e-…",
    "details": { "limit": 120, "window": "minute" }
  }
}

Ejemplo#

bash

export PROJECT_ID="<project id>" CLIENT_KEY="pk_live_…"

curl https://majacloud.majanite.com/v1/project -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY"

curl -X POST https://majacloud.majanite.com/v1/auth/guest -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY" \
  -H "Content-Type: application/json" -d '{}'

Endpoints#

Proyecto#

GET/projectInformación del proyecto, plan y clave pública de configuración remotaClave de cliente

Respuesta 200

{
    "ok": true,
    "project": {
        "id": "8f3c…",
        "name": "Space Runner",
        "plan": "free",
        "config_version": 12,
        "config_public_key_xml": "<RSAKeyValue>…</RSAKeyValue>",
        "config_public_key_pem": "-----BEGIN PUBLIC KEY-----\n…\n-----END PUBLIC KEY-----\n",
        "services": {
            "player_auth": true,
            "leaderboards": true,
            "remote_config": true,
            "cloud_save": true,
            "rewards": true
        }
    }
}

Autenticación de jugadores#

POST/auth/guestCrear un jugador invitado y una sesiónClave de cliente

Cuerpo

{
    "device_id": "optional installation id"
}

Respuesta 201

{
    "ok": true,
    "auth_method": "guest",
    "access_token": "eyJ2IjoyLCJ0IjoiYWNjZXNz…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "2d0f…",
    "refresh_expires_in": 2592000,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

POST/auth/refreshRotar el token de actualización y obtener un nuevo token de accesoClave de cliente

Cuerpo

{
    "refresh_token": "…"
}

Respuesta 200

{
    "ok": true,
    "auth_method": "guest",
    "access_token": "eyJ2IjoyLCJ0IjoiYWNjZXNz…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "2d0f…",
    "refresh_expires_in": 2592000,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

Errores

unauthorized (reason: invalid | expired | revoked | reused)

POST/auth/logoutRevocar la sesiónClave de cliente

Cuerpo

{
    "refresh_token": "optional"
}

Respuesta 200

{
    "ok": true,
    "revoked": true
}

POST/auth/link/startIniciar el inicio de sesión web (vincular un invitado a correo o Google)Token de jugador

Cuerpo

{
    "code_challenge": "base64url(sha256(verifier))",
    "code_challenge_method": "S256",
    "return_url": "optional, https on this host or an allowlisted scheme"
}

Respuesta 201

{
    "ok": true,
    "flow_id": "uuid",
    "flow_token": "…",
    "auth_url": "https://majacloud.majanite.com/player-auth.php?flow_id=…&flow_token=…",
    "expires_at": "2026-10-09T08:27:00Z",
    "poll_interval_seconds": 3
}

GET/auth/link/statusConsultar el estado del flujo de inicio de sesiónClave de cliente

Parámetros de consulta

flow_id — uuid
flow_token — …

Respuesta 200

{
    "ok": true,
    "status": "pending | completed | consumed | expired",
    "exchange_code": "(only when completed)",
    "expires_at": "…"
}

POST/auth/link/exchangeCanjear un flujo completado por una sesiónClave de cliente

Cuerpo

{
    "flow_id": "uuid",
    "exchange_code": "…",
    "code_verifier": "the original verifier"
}

Respuesta 200

{
    "ok": true,
    "auth_method": "guest",
    "access_token": "eyJ2IjoyLCJ0IjoiYWNjZXNz…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "2d0f…",
    "refresh_expires_in": 2592000,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    },
    "merged_guest": true
}

GET/players/meEl jugador con sesión iniciadaToken de jugador

Respuesta 200

{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

PATCH/players/meCambiar el nombre visibleToken de jugador

Cuerpo

{
    "display_name": "Nova"
}

Respuesta 200

{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false
    }
}

GET/players/{player_id}Leer cualquier jugador (clave secreta)Clave secreta

Respuesta 200

{
    "ok": true,
    "player": {
        "id": "c7a1…",
        "player_id": "player_3f9c…",
        "display_name": "Guest 4821",
        "auth_type": "guest",
        "email_verified": false,
        "email": "nova@example.com",
        "wallets": [
            {
                "currency": "coins",
                "balance": 150
            }
        ]
    }
}

Tablas de clasificación#

POST/leaderboards/{slug}/scoresEnviar una puntuaciónToken de jugador

Cuerpo

{
    "score": 120
}

Respuesta 200

{
    "ok": true,
    "accepted": true,
    "entry": {
        "rank": 1,
        "player_id": "player_3f9c…",
        "player_name": "Nova",
        "score": 9840,
        "score_updated_at": "2026-10-09T08:12:00Z",
        "is_me": false
    },
    "period": {
        "key": "2026-W41",
        "ends_at": "2026-10-12T00:00:00Z"
    }
}

Errores

validation (bounds)
rate_limited (cooldown)
plan_limit (entry cap)

GET/leaderboards/{slug}/entriesPrimeras posicionesClave de cliente

Parámetros de consulta

limit — 1-100 (default 10)
offset — 0+
period — current | previous

Respuesta 200

{
    "ok": true,
    "leaderboard": {
        "slug": "coins",
        "name": "Coins",
        "sort_type": "DESC",
        "score_mode": "BEST",
        "reset_rule": "WEEKLY"
    },
    "period": {
        "key": "2026-W41",
        "ends_at": "2026-10-12T00:00:00Z"
    },
    "entries": [
        {
            "rank": 1,
            "player_id": "player_3f9c…",
            "player_name": "Nova",
            "score": 9840,
            "score_updated_at": "2026-10-09T08:12:00Z",
            "is_me": false
        }
    ],
    "total": 42,
    "limit": 10,
    "offset": 0,
    "max_entries": 10
}

GET/leaderboards/{slug}/meMi posición y puntuaciónToken de jugador

Parámetros de consulta

period — current | previous

Respuesta 200

{
    "ok": true,
    "entry": {
        "rank": 1,
        "player_id": "player_3f9c…",
        "player_name": "Nova",
        "score": 9840,
        "score_updated_at": "2026-10-09T08:12:00Z",
        "is_me": false
    },
    "total": 42
}

GET/leaderboards/{slug}/around-meEntradas alrededor de mi posiciónToken de jugador

Parámetros de consulta

radius — 1-25 (default 3)

Respuesta 200

{
    "ok": true,
    "entries": [
        {
            "rank": 1,
            "player_id": "player_3f9c…",
            "player_name": "Nova",
            "score": 9840,
            "score_updated_at": "2026-10-09T08:12:00Z",
            "is_me": false
        }
    ],
    "me": {
        "rank": 1,
        "player_id": "player_3f9c…",
        "player_name": "Nova",
        "score": 9840,
        "score_updated_at": "2026-10-09T08:12:00Z",
        "is_me": false
    },
    "total": 42
}

Configuración remota#

GET/configConfiguración publicada, firmada con RSA; envía If-None-Match para recibir 304Clave de cliente

Respuesta 200

{
    "ok": true,
    "project_id": "8f3c…",
    "version": 12,
    "checksum": "sha256 of data",
    "data": "base64url(JSON payload)",
    "signature": "base64 RSA-SHA256 over data",
    "signature_algorithm": "rsa-sha256",
    "signing_key_id": "config-v1",
    "configs": [
        {
            "key": "enemy_damage",
            "type": "number",
            "value": "25"
        }
    ]
}

Guardado en la nube#

GET/cloudListar las claves guardadasToken de jugador

Respuesta 200

{
    "ok": true,
    "keys": [
        {
            "key": "progress",
            "revision": 3,
            "size_bytes": 180,
            "updated_at": "…"
        }
    ],
    "total_bytes": 180
}

GET/cloud/{key}Cargar un documentoToken de jugador

Respuesta 200

{
    "ok": true,
    "key": "progress",
    "data": {
        "level": 3
    },
    "revision": 3,
    "size_bytes": 180,
    "updated_at": "…"
}

PUT/cloud/{key}Guardar un documento (revisión esperada opcional)Token de jugador

Cuerpo

{
    "data": {
        "level": 4
    },
    "revision": "optional: expected current revision (0 = create only)"
}

Respuesta 200

{
    "ok": true,
    "key": "progress",
    "revision": 4,
    "size_bytes": 190,
    "updated_at": "…",
    "created": false
}

Errores

revision_mismatch (details.current_revision)
plan_limit (storage)

DELETE/cloud/{key}Eliminar un documentoToken de jugador

Respuesta 200

{
    "ok": true,
    "key": "progress",
    "deleted": true
}

Recompensas y billetera#

GET/rewardsRecompensas activas (indicadores claimable con un token de jugador)Clave de cliente

Respuesta 200

{
    "ok": true,
    "rewards": [
        {
            "reward_key": "daily_coins",
            "name": "Daily coins",
            "amount": 50,
            "currency": "coins",
            "cooldown": "daily",
            "claimable": true,
            "next_claim_at": null
        }
    ]
}

POST/rewards/claimReclamar una recompensaToken de jugador

Cuerpo

{
    "reward_key": "daily_coins"
}

Respuesta 200

{
    "ok": true,
    "accepted": true,
    "reward_key": "daily_coins",
    "amount": 50,
    "currency": "coins",
    "balance": 150,
    "next_claim_at": "2026-10-10T00:00:00Z"
}

Errores

conflict (already claimed; details.next_claim_at)

GET/walletSaldos de la billeteraToken de jugador

Respuesta 200

{
    "ok": true,
    "wallets": [
        {
            "currency": "coins",
            "balance": 150,
            "updated_at": "…"
        }
    ]
}