> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edtools.co/llms.txt
> Use this file to discover all available pages before exploring further.

# La API de EdTools

> Cuatro superficies, una sola app. Cuál te sirve depende de quién llama.

EdTools es una plataforma multi-tenant de gestión educativa: admisiones, académico, comunicaciones, pagos, agenda, portal de familias y documentos. Todo vive en una sola aplicación Next.js con una API Hono embebida en `/api`.

Esa API no es una sola cosa. Son cuatro superficies, con contratos distintos, y confundirlas es el error más caro que puedes cometer al integrar.

<CardGroup cols={2}>
  <Card title="Client API" icon="plug" href="/client-api/inicio-rapido">
    **Para integrar sistemas externos.** Server-to-server, token de servicio, scopes, idempotencia y webhooks firmados. Es la única con contrato estable y la única con playground.
  </Card>

  <Card title="Superficies internas" icon="map" href="/superficies/panorama">
    **Para entender la plataforma.** El dashboard, el portal, lo público y lo interno. Documentadas como mapa, no como contrato: cambian con el producto.
  </Card>
</CardGroup>

## Si vienes a integrar

Vas al [Client API](/client-api/inicio-rapido). Pide una API key en **Ajustes → API e integraciones**, y con eso tienes estudiantes, admisiones, pagos, programas, cursos, formularios y Vault.

```bash theme={null}
curl https://app.edtools.co/api/client/v1/me \
  -H "Authorization: Bearer $EDTOOLS_API_KEY"
```

<Warning>
  No integres contra `/api/v1/*`. Esos endpoints son los del dashboard: piden sesión de navegador, cambian sin aviso y no tienen versionado. Existen en esta documentación para que el equipo sepa qué hay, no para que los consumas.
</Warning>

## Las cuatro superficies de un vistazo

| Superficie | Prefijo          | Quién llama                                 | Cómo se autentica                       | Contrato                             |
| ---------- | ---------------- | ------------------------------------------- | --------------------------------------- | ------------------------------------ |
| Client API | `/api/client/v1` | Sistemas externos del cliente               | Token de servicio (Bearer) + scopes     | **Estable**, versionado, con OpenAPI |
| Dashboard  | `/api/v1`        | El frontend administrativo                  | Sesión Better Auth + tenant             | Interno, sin garantías               |
| Portal     | `/api/v1/portal` | El portal de familias y estudiantes         | Sesión + `portalMiddleware`             | Interno, sin garantías               |
| Pública    | `/api/public`    | Internet: widget, formularios, PQRS, firmas | Ninguna; cada endpoint se defiende solo | Semi-estable (hay embebidos vivos)   |
| Interna    | `/api/internal`  | Tareas de Trigger.dev                       | `INTERNAL_API_SHARED_SECRET`            | Interno                              |

## Qué esperar de cada página

La pestaña **Referencia** se genera desde el OpenAPI 3.1 real del Client API: lo que ves ahí es lo que responde el servidor, con sus esquemas de Zod. Si el código cambia y alguien corre el generador, la página cambia.

Los **catálogos** de superficies internas se extraen de `apps/web/src/server/app.ts` y dicen contra qué commit se generaron. Son inventarios honestos: método, ruta y archivo. No prometen el cuerpo de la respuesta, porque esa capa no tiene esquema declarado.

## Antes de empezar

<Steps>
  <Step title="Confirma que el Client API está encendido">
    Requiere `EDTOOLS_CLIENT_API_ENABLED=1` en el entorno y el módulo `platform_integrations` activo en la institución.
  </Step>

  <Step title="Crea una API key">
    En **Ajustes → API e integraciones → API Keys**. El token completo se muestra una sola vez.
  </Step>

  <Step title="Llama a /me">
    Te devuelve el tenant, los scopes del token, los módulos habilitados y el Source of Record por dominio. Es la forma más rápida de saber qué puedes hacer.
  </Step>
</Steps>