📚 Docs para Desarrolladores

API REST, webhooks y MCP de AI QUEST. Por privacidad infantil solo se comparten apodos e IDs internos, nunca nombres reales.

1. API REST v1

Crea una llave en Panel → 🔌 Integraciones (se muestra una sola vez; elige Solo Lectura o Lectura y Escritura). Envíala en cada petición:

Authorization: Bearer nsk_tu_llave

URL base: https://tu-app.lovable.app/api/public/v1 · Paginación: ?pagina=1&limite=25 (máx. 100). Las respuestas paginadas incluyen "paginacion": { "pagina", "limite", "total" }.

GET /clases

Lista tus clases (paginado).

POST /clases

Crea una clase. { "nombre": "6°A Arenal" }

GET /clases/{id}

Ver una clase.

PATCH /clases/{id}

Editar: { "nombre": "…", "activa": false }

GET /clases/{id}/alumnos

Alumnos de la clase por XP (paginado).

GET /alumnos/{id}

Ver un alumno (apodo, avatar, XP, nivel, coins).

GET /alumnos/{id}/progreso

XP reciente, logros y misiones completadas.

POST /alumnos/{id}/premiar

{ "xp": 50, "coins": 10, "motivo": "Gran idea" }

GET /misiones

Misiones activas: volcanes, selva, océano… (paginado).

curl "https://tu-app.lovable.app/api/public/v1/clases?pagina=1&limite=10" \
  -H "Authorization: Bearer nsk_tu_llave"

curl -X PATCH https://tu-app.lovable.app/api/public/v1/clases/ID_CLASE \
  -H "Authorization: Bearer nsk_tu_llave" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"6°A Volcán Poás"}'

curl -X POST https://tu-app.lovable.app/api/public/v1/alumnos/ID_ALUMNO/premiar \
  -H "Authorization: Bearer nsk_tu_llave" \
  -H "Content-Type: application/json" \
  -d '{"xp":50,"coins":10,"motivo":"Mejor prompt del Arenal"}'

Errores, siempre { "error": "mensaje" }: 400 datos inválidos · 401 llave inválida o revocada · 403 llave de solo lectura · 404 no existe o no es de tus clases.

2. Webhooks

Salientes (AI QUEST → tu Servidor)

Registra una URL https:// en Integraciones y elige eventos: mision.completada, logro.obtenido, progreso.actualizado. Reintentos a los 1, 5, 15, 60 y 240 minutos; cada entrega queda registrada (estado, respuesta, fecha).

POST https://tu-servidor.com/webhook
Content-Type: application/json
X-Nova-Evento: logro.obtenido
X-Nova-Entrega: 7b1c…
X-Signature: sha256=5f2a…   (HMAC-SHA256 del cuerpo crudo)

{ "id": "7b1c…", "evento": "logro.obtenido", "fecha": "2026-10-04T15:00:00Z",
  "alumno": { "id": "…", "apodo": "LavaFox", "clase_id": "…", "xp": 340, "nivel": 2, "coins": 80 },
  "datos": { "insignia": "FIRST_PROMPT", "nombre": "Primer prompt" } }

Verificar la firma (usa el secreto que ves en Integraciones):

// Node.js
import crypto from "node:crypto";
const esperado = "sha256=" + crypto.createHmac("sha256", SECRETO).update(cuerpoCrudo).digest("hex");
const valido = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(req.headers["x-signature"]));

Entrantes (tu Servidor → AI QUEST)

Envía JSON a https://tu-app.lovable.app/api/public/v1/webhooks/in firmado con el secreto de entrada del proyecto (X-Signature: sha256=… o X-Webhook-Secret). Cada evento queda registrado en Admin → Integraciones.

BODY='{"evento":"asistencia.registrada","origen":"colegio-cr","datos":{"clase":"6°A"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRETO_ENTRADA" | sed 's/^.* //')
curl -X POST https://tu-app.lovable.app/api/public/v1/webhooks/in \
  -H "Content-Type: application/json" \
  -H "X-Signature: sha256=$SIG" -d "$BODY"

3. Servidor MCP

Dirección: https://tu-app.lovable.app/mcp. Herramientas: listar_clases, listar_alumnos, buscar_alumnos, progreso_alumno, listar_misiones, resumen_metricas, crear_clase, actualizar_clase, premiar_alumno. El acceso es con tu inicio de sesión de profe (OAuth), sin pegar llaves.

Claude (web/escritorio): Configuración → Conectores → Agregar conector personalizado → pega la dirección. Claude Desktop por archivo (claude_desktop_config.json):

{
  "mcpServers": {
    "ai-quest": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tu-app.lovable.app/mcp"
      ]
    }
  }
}

Al conectar se abre AI QUEST: entra con tu cuenta de profe y toca Autorizar. Más detalles en la guía MCP.