Desarrolladores

Documentación De Integraciones

API REST v1, webhooks entrantes y salientes, y servidor MCP para Claude.

Autenticación Con Claves De API

Crea una clave en Mi Panel → Integraciones → Claves API (solo administradores). Se muestra una sola vez. Envíala en cada petición con la cabecera Authorization: Bearer. Las claves de solo lectura permiten GET; las de escritura permiten POST, PATCH y PUT.

Probar la clave

curl https://tu-app.lovable.app/api/v1 \
  -H "Authorization: Bearer cj10k_TU_CLAVE"

Endpoints REST v1

Todas las respuestas son JSON. Las listas aceptan ?page=1&per_page=20 (máx. 100) y devuelven { data, pagination: { page, per_page, total } }.

Referencia

GET    /api/v1/games                 ?public=true&template=snake
POST   /api/v1/games                 { title, template, description?, config?, is_public? }
GET    /api/v1/games/:id
PATCH  /api/v1/games/:id             { title?, description?, config?, is_public? }
GET    /api/v1/games/:id/levels
POST   /api/v1/games/:id/levels      { rows: ["WWWW","WP.G","WWWW"] }
PATCH  /api/v1/games/:id/levels/:n   { rows: [...] }
PUT    /api/v1/games/:id/rules       { rules: [{ event, action, value?, condition? }] }
GET    /api/v1/games/:id/ranking
GET    /api/v1/games/:id/plays
POST   /api/v1/games/:id/plays       { player_name, score }
GET    /api/v1/templates   ·   GET /api/v1/templates/:id
GET    /api/v1/assets      ·   POST /api/v1/assets { name, value, kind? }
GET    /api/v1/assets/:id  ·   PATCH /api/v1/assets/:id
GET    /api/v1/scores                ?game_id=…
GET    /api/v1/users       ·   POST /api/v1/users { email, password, display_name? }
GET    /api/v1/users/:id   ·   PATCH /api/v1/users/:id { display_name }

Crear un juego

curl -X POST https://tu-app.lovable.app/api/v1/games \
  -H "Authorization: Bearer cj10k_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"title":"Volcán Arenal Runner","template":"runner","is_public":true,"config":{"player":"🦥","enemy":"🌋","speed":6}}'

Ranking de un juego

curl "https://tu-app.lovable.app/api/v1/games/ID_DEL_JUEGO/ranking?per_page=10" \
  -H "Authorization: Bearer cj10k_TU_CLAVE"

Registrar una partida

curl -X POST https://tu-app.lovable.app/api/v1/games/ID_DEL_JUEGO/plays \
  -H "Authorization: Bearer cj10k_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"player_name":"Tica","score":420}'

Errores

Los errores devuelven { error: { code, message } } con el código HTTP correspondiente: 400 json_invalido, 401 no_autorizado / clave_invalida, 403 sin_permiso, 404 no_encontrado / ruta_desconocida, 422 validacion, 500 interno.

Ejemplo

{ "error": { "code": "validacion", "message": "El campo 'title' es obligatorio" } }

Webhooks Entrantes

Envía eventos externos a POST /api/v1/webhooks/in con una clave de escritura. Cada evento queda registrado y visible en el panel (pestaña Eventos Entrantes). Usa las cabeceras opcionales X-Event y X-Source.

Enviar un evento

curl -X POST https://tu-app.lovable.app/api/v1/webhooks/in \
  -H "Authorization: Bearer cj10k_TU_CLAVE" \
  -H "X-Event: torneo.creado" -H "X-Source: crm" \
  -H "Content-Type: application/json" \
  -d '{"torneo":"Copa San José","premio":"Plan Pro"}'

Webhooks Salientes

Registra URLs en el panel y elige eventos: juego.publicado, partida.terminada, record.nuevo y usuario.registrado. Cada envío es un POST JSON firmado con HMAC-SHA256 del cuerpo usando el secreto del endpoint, en la cabecera X-Signature: sha256=<hex>. Se reintenta hasta 3 veces con espera exponencial y cada entrega queda registrada.

Payload de ejemplo

{
  "id": "6f1c…",
  "evento": "record.nuevo",
  "creado": "2026-10-05T04:50:00.000Z",
  "datos": { "juego_id": "…", "juego": "Volcán Arenal Runner", "jugador": "Tica", "puntaje": 420, "fecha": "…" }
}

Verificar la firma (Node.js)

import crypto from "node:crypto";

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", process.env.WEBHOOK_SECRET).update(req.body).digest("hex");
  const got = req.get("X-Signature") || "";
  const ok = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!ok) return res.status(401).send("firma inválida");
  const evento = JSON.parse(req.body);
  console.log(evento.evento, evento.datos);
  res.sendStatus(200);
});

Verificar la firma (Python)

import hmac, hashlib
def firma_valida(cuerpo: bytes, cabecera: str, secreto: str) -> bool:
    esperado = "sha256=" + hmac.new(secreto.encode(), cuerpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, cabecera)

Servidor MCP Para Claude

El endpoint /mcp habla MCP por HTTP (JSON-RPC) y usa la misma clave de API. Herramientas: listar_juegos, ver_juego, crear_juego, agregar_nivel, editar_reglas, publicar_juego y ver_ranking. Las herramientas que modifican datos requieren una clave de escritura.

Claude Desktop · claude_desktop_config.json

{
  "mcpServers": {
    "creador-de-juegos-10k": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://tu-app.lovable.app/mcp",
        "--header", "Authorization: Bearer ${CJ10K_API_KEY}"
      ],
      "env": { "CJ10K_API_KEY": "cj10k_TU_CLAVE" }
    }
  }
}

Claude Code (CLI)

claude mcp add --transport http creador-de-juegos-10k https://tu-app.lovable.app/mcp \
  --header "Authorization: Bearer cj10k_TU_CLAVE"

Probar con curl

curl -X POST https://tu-app.lovable.app/mcp \
  -H "Authorization: Bearer cj10k_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"crear_juego","arguments":{"titulo":"Quiz De Costa Rica","plantilla":"quiz"}}}'

Crear Mi Clave De API