Desarrolladores · API

API de plugin: conecta tu servidor de juego

Conecta tu servidor de juego (Minecraft, Rust, ARK…) a tu campaña: el progreso se muestra en el juego y las recompensas se otorgan automáticamente.

GET/api/plugin/campaignGET/api/plugin/donations

1. Autenticación

Generar una clave

En tu panel: Campaña → pestaña Editar → «Plugin en el juego» → Generar una clave. La clave completa (ka_live_…) se muestra una sola vez: cópiala y pégala en la configuración de tu plugin.

Una clave está limitada a una sola campaña / un solo servidor.
Solo se almacena la huella SHA-256: nadie puede volver a leer tu clave. ¿La perdiste? Genera una nueva.
Puedes revocar una clave en cualquier momento; deja de funcionar de inmediato.

Usar la clave

Envía la clave en la cabecera Authorization de cada solicitud:

header

Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx

Seguridad: la clave es un secreto de servidor. Nunca la pongas en un cliente de juego, un repositorio público ni en nada accesible a los jugadores.

2. Generalidades

URL base	`https://keepalive.gg` · dev local `http://localhost:3100`
Formato	JSON para solicitudes y respuestas.
Límite de tasa	~120 solicitudes / minuto por clave. Más allá → `429`.
Polling	Un intervalo de 30 a 60 s es más que suficiente.

Los errores siguen un formato estándar: { "error": { "code", "message" } }

401Clave ausente, inválida o revocada.
404La campaña ya no existe.
429Demasiadas solicitudes, inténtalo de nuevo en un momento.

GET/api/plugin/campaign

Devuelve el progreso de la campaña vinculada a la clave; llámalo periódicamente para refrescar la vista en el juego.

cURL

curl https://keepalive.gg/api/plugin/campaign \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta 200

{
  "campaign": {
    "slug": "skycraft-survie",
    "title": "SkyCraft Survie",
    "game": "minecraft",
    "status": "published",
    "goalKind": "monthly",
    "goalCents": 2000,
    "currency": "EUR",
    "raisedCents": 1450,
    "pct": 73,
    "supporters": 12,
    "rewards": [
      { "minCents": 500, "title": "Role", "description": "…" }
    ]
  }
}

goalCents / raisedCents están en céntimos · pct ya limitado de 0 a 100 · goalKind es monthly u oneshot.

GET/api/plugin/donations

Lista las donaciones cobradas, de la más antigua a la más reciente, para otorgar recompensas. El cursor evita volver a descargar donaciones antiguas.

Parám.	Por defecto	Descripción
`after`	ninguno	Cursor opaco: el `nextCursor` de la página anterior. Omítelo en la primera llamada.
`limit`	50	Número máximo de donaciones (máximo 50).

cURL

curl "https://keepalive.gg/api/plugin/donations?after=CURSOR" \
  -H "Authorization: Bearer ka_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta 200

{
  "donations": [
    {
      "id": "don_9f2c…",
      "donorName": "Nova",
      "amountCents": 1000,
      "currency": "EUR",
      "message": "gg",
      "recurring": false,
      "rewardTitle": "Kit VIP",
      "createdAt": "2026-07-21T18:04:11.000Z"
    }
  ],
  "nextCursor": "2026-07-21T18:04:11.000Z|don_9f2c…"
}

Campos expuestos (solo públicos):

Campo	Descripción
`id`	Identificador único de la donación (sirve para deduplicar).
`donorName`	Nombre público introducido por el donante (`null` si es anónimo).
`amountCents`	Importe de la donación, en céntimos.
`message`	Mensaje público del donante (`null` si no hay).
`recurring`	`true` si es una donación mensual.
`rewardTitle`	Nivel desbloqueado a otorgar en el juego (`null` si no hay).
`createdAt`	Fecha ISO 8601.

Nunca un correo, un id de Stripe ni el importe neto: solo lo que ya es público en la página de la campaña.

Bucle de sondeo recomendado

pseudocódigo

cursor = cargar_cursor()             # vacío en el primer arranque
ids_tratados = cargar_ids()          # anti-duplicado

cada 30 a 60 s:
  page = GET /api/plugin/donations?after=cursor
  por cada donación en page.donations:
    si donación.id ya tratado: continuar
    si donación.rewardTitle y donación.donorName:
      jugador = buscar_jugador(donación.donorName)
      si jugador: otorgar_recompensa(jugador, donación.rewardTitle)
    marcar donación.id tratado
  si page.nextCursor:
    cursor = page.nextCursor ; guardar(cursor)

Siempre deduplica por id: nunca otorgues la misma recompensa dos veces, ni siquiera en el límite del cursor.

3. Otorgar la recompensa al jugador correcto

KeepAlive no conoce la cuenta de juego del donante, solo el nombre público que introdujo (donorName). La convención recomendada:

Pide a tus jugadores que donen usando su nombre en el juego como nombre público.

Tu plugin hace coincidir donorName con el jugador (sin distinguir mayúsculas). Si nadie coincide al momento de la donación, deja la recompensa pendiente y vuelve a aplicarla cuando se reconecte.

Próximamente: un flujo de «código a canjear» (/claim <code> en el juego) hará la atribución 100 % fiable, sin depender del nombre.

¿Todo listo para conectar tu servidor?

Genera una clave API desde el panel de tu campaña y sigue los ejemplos de arriba.

Abrir mi panel →