Para Desarrolladores

Documentación de la API

Conecta Bloques Lógicos con tus herramientas. Cada clave solo accede a los datos de su propia familia; nunca se exponen datos personales de los niños (solo apodos y avatares).

Autenticación

Crea una clave en el Panel de Padres (necesitas una cuenta familiar). La clave completa se muestra una sola vez. Envíala en cada petición:

Authorization: Bearer bl_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Las claves pueden ser de solo lectura o de lectura y escritura, y se pueden revocar en cualquier momento.

API REST v1

Base: https://tu-app.lovable.app/api/v1. Las listas aceptan ?page=1&limit=20 (máx. 100) y ?q= para buscar.

GET /summary — Métricas de la familia.
GET /kids · POST /kids · GET /kids/:id · PATCH /kids/:id
GET /kids/:id/progress — Retos completados.
GET /projects (?kid_id=) · POST /projects · GET /projects/:id · PATCH /projects/:id
POST /webhooks/in — Registrar un evento entrante.

curl https://tu-app.lovable.app/api/v1/kids?page=1&limit=20 \
  -H "Authorization: Bearer $BL_KEY"

curl -X POST https://tu-app.lovable.app/api/v1/projects \
  -H "Authorization: Bearer $BL_KEY" -H "Content-Type: application/json" \
  -d '{"kid_id":"<uuid>","name":"Mi Cuadrado","program":[]}'

curl -X PATCH https://tu-app.lovable.app/api/v1/kids/<uuid> \
  -H "Authorization: Bearer $BL_KEY" -H "Content-Type: application/json" \
  -d '{"avatar":"🦊"}'

Respuesta de lista:

{ "data": [ { "id": "…", "nickname": "Lupita", "avatar": "🦊", "streak_best": 4 } ],
  "pagination": { "page": 1, "limit": 20, "total": 1 } }

Errores

{ "error": { "code": "unauthorized", "message": "Clave de API inválida o revocada." } }

401 clave ausente o inválida · 403 sin permiso · 404 no encontrado · 422 cuerpo inválido · 500 error del servidor.

Webhooks

Salientes: registra una URL https en el panel y elige eventos: kid.created, kid.updated, project.created, project.updated, level.completed, webhook.received. Reintentamos hasta 3 veces (0 s, 0,5 s, 1,5 s) y cada entrega queda en el registro del panel.

POST https://tu-servidor.com/webhook
X-Signature: sha256=5f2b…
X-Event: level.completed

{ "id": "c1d2…", "event": "level.completed", "created_at": "2026-10-05T04:38:00Z",
  "data": { "kid_id": "…", "level_id": 12, "stars": 3, "blocks": 5 } }

Entrantes: envía eventos externos con una clave de escritura; quedan registrados en el panel.

curl -X POST https://tu-app.lovable.app/api/v1/webhooks/in \
  -H "Authorization: Bearer $BL_KEY" -H "Content-Type: application/json" \
  -d '{"event":"clase.terminada","data":{"grupo":"A"}}'

Verificar la Firma

Calcula HMAC-SHA256 del cuerpo crudo con el secreto del webhook (whsec_…) y compáralo en tiempo constante.

// Node.js
import crypto from "crypto";
function verificar(cuerpoCrudo, cabecera, secreto) {
  const esperada = "sha256=" + crypto.createHmac("sha256", secreto).update(cuerpoCrudo).digest("hex");
  return cabecera.length === esperada.length &&
    crypto.timingSafeEqual(Buffer.from(cabecera), Buffer.from(esperada));
}

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

Conectar MCP a Claude

Servidor MCP por HTTP en https://tu-app.lovable.app/mcp con la misma clave de API. Herramientas: resumen_metricas, listar_perfiles, ver_progreso, crear_perfil, buscar_proyectos, ver_proyecto, crear_proyecto, actualizar_proyecto.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "bloques-logicos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tu-app.lovable.app/mcp",
               "--header", "Authorization: Bearer ${BL_KEY}"],
      "env": { "BL_KEY": "bl_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  }
}

Claude Code:

claude mcp add --transport http bloques-logicos https://tu-app.lovable.app/mcp \
  --header "Authorization: Bearer bl_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Prueba rápida:

curl -X POST https://tu-app.lovable.app/mcp -H "Authorization: Bearer $BL_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'