📘

Documentación de la API

REST v1, Webhooks y Servidor MCP

Autenticación

Envía tu clave en la cabecera Authorization: Bearer <clave>. Crea claves en el Panel de Integraciones (solo administradores); la clave completa se muestra una sola vez y se guarda solo su huella SHA-256.

Modo demostración: usa pk_demo_poliglota para leer datos de ejemplo de Costa Rica. Las escrituras con esa clave se simulan y no se guardan.

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

Endpoints Principales

Base: https://tu-app.lovable.app/api/v1. Listados con ?page=1&per_page=20 (máx. 100) y búsqueda ?q=.

GET /languages · GET /languages/:code
GET /groups · POST /groups · GET /groups/:id · PATCH /groups/:id
GET /groups/:id/members · GET /members?group_id=&q=
GET /members/:id · PATCH /members/:id
GET /metrics

# Listar grupos (paginado)
curl "https://tu-app.lovable.app/api/v1/groups?page=1&per_page=10" \
  -H "Authorization: Bearer pk_demo_poliglota"

# Crear un grupo (requiere permiso de escritura)
curl -X POST https://tu-app.lovable.app/api/v1/groups \
  -H "Authorization: Bearer pk_demo_poliglota" \
  -H "Content-Type: application/json" \
  -d '{"name":"Escuela de Heredia — Inglés"}'

# Cambiar el apodo de un alumno
curl -X PATCH https://tu-app.lovable.app/api/v1/members/demo-m1 \
  -H "Authorization: Bearer pk_demo_poliglota" \
  -H "Content-Type: application/json" \
  -d '{"nickname":"Perezoso Sabio"}'

Respuesta de listado:

{
  "data": [{ "id": "demo-g1", "name": "Escuela República de Chile — San José", "code": "CRSJ01", "member_count": 4 }],
  "pagination": { "page": 1, "per_page": 10, "total": 3, "total_pages": 1 }
}

Errores Claros

{ "error": { "code": "invalid_key", "message": "La clave de API no es válida o fue revocada." } }

Códigos: 400 invalid_json · 401 unauthorized / invalid_key / invalid_signature · 403 forbidden · 404 not_found · 422 validation_error · 500 server_error.

Webhooks Salientes

Registra una URL https en el panel y elige eventos: group.created, group.updated, member.joined, member.updated (y webhook.test). Cada envío lleva X-Signature: sha256=<hmac> y X-Webhook-Event. Se reintenta hasta 3 veces y cada entrega queda registrada con estado, respuesta y fecha.

{
  "id": "evt_3f9a1c2b7d4e5f60",
  "event": "member.joined",
  "created_at": "2026-10-05T14:00:00.000Z",
  "data": {
    "id": "8c1e…",
    "group_id": "51ab…",
    "group_name": "Liceo de Cartago — Séptimo Año",
    "nickname": "Mono Aullador"
  }
}

Cómo Verificar la Firma

Calcula HMAC-SHA256 del cuerpo crudo con el secreto del endpoint y compáralo en tiempo constante.

// Node.js
import crypto from "node:crypto";
export function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return header.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

# Python
import hmac, hashlib
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header, expected)

Webhooks Entrantes

Envía eventos a POST /api/v1/webhooks/in con cuerpo {"event": "...", "data": {...}} firmado con un secreto de entrada del panel. Para probar usa el secreto demo whin_demo_secret (responde sin guardar).

BODY='{"event":"pago.recibido","data":{"colegio":"Escuela de Alajuela","monto":25000,"moneda":"CRC"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "whin_demo_secret" | sed 's/^.* //')
curl -X POST https://tu-app.lovable.app/api/v1/webhooks/in \
  -H "Content-Type: application/json" \
  -H "X-Signature: sha256=$SIG" \
  -d "$BODY"

Conectar el MCP a Claude

Servidor MCP por HTTP en https://tu-app.lovable.app/mcp, con la misma clave de API. Herramientas: list_languages, get_language, list_groups, get_group, search_members, create_group, update_group, update_member y summarize_metrics.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "poliglota-ia": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://tu-app.lovable.app/mcp",
        "--header", "Authorization: Bearer pk_demo_poliglota"
      ]
    }
  }
}

Claude Code u otros clientes con HTTP directo:

claude mcp add --transport http poliglota-ia https://tu-app.lovable.app/mcp \
  --header "Authorization: Bearer pk_demo_poliglota"

curl -X POST https://tu-app.lovable.app/mcp \
  -H "Authorization: Bearer pk_demo_poliglota" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"summarize_metrics","arguments":{}}}'