Guía de integración

Conecta tus sistemas (un LMS como Moodle, Canvas o Google Classroom, un SaaS propio o una aplicación móvil) con el motor pedagógico de Eduplanner para generar contenido educativo con inteligencia artificial y consultar los recursos guardados.

Consola interactiva (Scalar)·Especificación OpenAPI

1. Autenticación

Todas las peticiones deben autenticarse con uno de estos dos métodos. Ambos son válidos en cualquier endpoint.

Bearer JWT (usuarios finales)

Token JWT de Supabase. Se obtiene iniciando sesión con POST /auth/login.

curl -X POST https://edu.planners.com.mx/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "docente@escuela.mx", "password": "••••••••"}'

# → { "token": "eyJ...", "user": { "id": "…", "email": "…", "name": "…" } }

Inclúyelo en cada petición como Authorization: Bearer <TOKEN>.

API key (server-to-server)

Clave estática emitida por un administrador desde el panel /admin/api-keys. La clave actúa en nombre de una cuenta: consume sus créditos y accede a sus recursos.

Authorization: <omitido>
x-api-key: epk_...

La clave se muestra una sola vez al crearla. Trátala como un secreto: no la expongas en código cliente ni la subas a repositorios.

2. Base URL

Entorno	URL
Producción	https://edu.planners.com.mx/api
Desarrollo	http://localhost:3000/api

3. Endpoints

Método	Ruta	Descripción
POST	/auth/login	Iniciar sesión y obtener un token JWT
GET	/v1/credits	Saldo de créditos del usuario
POST	/v1/planeaciones	Generar una planeación didáctica (NEM / CIME / Tutoría)
GET/PUT/DELETE	/v1/planeaciones/{id}	Consultar, actualizar o eliminar una planeación
POST	/v1/examenes	Generar un examen estructurado
GET/PUT/DELETE	/v1/examenes/{id}	Consultar, actualizar o eliminar un examen
POST	/v1/rubricas	Generar una rúbrica analítica de evaluación
GET/PUT/DELETE	/v1/rubricas/{id}	Consultar, actualizar o eliminar una rúbrica
POST	/v1/kahoot	Generar reactivos compatibles con Kahoot
GET/PUT/DELETE	/v1/kahoot/{id}	Consultar, actualizar o eliminar un cuestionario
POST	/v1/fichas-descriptivas	Generar una ficha descriptiva del alumno
GET/PUT/DELETE	/v1/fichas-descriptivas/{id}	Consultar, actualizar o eliminar una ficha
POST	/v1/seguimiento	Generar un seguimiento de alumno
GET/PUT/DELETE	/v1/seguimiento/{id}	Consultar, actualizar o eliminar un seguimiento
POST	/v1/ai/execute	Pasarela genérica al motor de IA

4. Generar una planeación didáctica

El endpoint POST /v1/planeaciones genera una planeación estructurada y, además, la guarda en la cuenta del usuario.

Campos aceptados

Campo	Requerido	Descripción
prompt	Sí	Tema o descripción del contenido a planificar
metodologia	No	NEM, CIME o Tutoría (por defecto NEM)
grado	No	Grado escolar; activa la búsqueda de referencias en libros SEP
materia	No	Campo formativo o asignatura
nivelDetalle	No	estándar o avanzado
numSesiones	No	Número de sesiones en la secuencia didáctica
contenidos_relacionados	No	IDs de contenidos curriculares relacionados

Petición

curl -X POST https://edu.planners.com.mx/api/v1/planeaciones \
  -H "Authorization: Bearer <TU_JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fracciones equivalentes para tercer grado de primaria",
    "metodologia": "NEM",
    "grado": "3",
    "materia": "Matemáticas",
    "nivelDetalle": "estándar",
    "numSesiones": 2
  }'

Respuesta

{
  "data": {
    "id": "…", "titulo": "…", "metodologia": "NEM",
    "estado": "borrador", "origen": "api"
  },
  "generated": {
    "titulo": "Explorando las fracciones equivalentes",
    "informacionGeneral": { "materia": "…", "grado": "3", "problemática": "…" },
    "elementosCurriculares": { "camposFormativos": [], "ejesArticuladores": [], "pda": "…", "proposito": "…" },
    "secuenciaDidactica": [
      { "numero": 1, "titulo": "…", "inicio": "…", "desarrollo": "…", "cierre": "…" }
    ],
    "recursos": [],
    "evaluacionFormativa": [],
    "adecuacionesCurriculares": "…"
  },
  "usage": { "inputTokens": 0, "outputTokens": 0 }
}

Si la petición incluye grado, Eduplanner enriquece la generación con referencias de los libros de texto SEP mediante búsqueda semántica.

5. Créditos

Cada generación con IA consume créditos de la cuenta. El costo depende del contenido: una planeación base cuesta 15 créditos, con un cargo adicional por sesiones extra o por nivel de detalle avanzado.

curl https://edu.planners.com.mx/api/v1/credits \
  -H "x-api-key: epk_..."

# → { "data": { "monthly_credits": 100, "purchased_credits": 0,
#              "total": 100, "subscription_plan": "pro" } }

6. Códigos de error

HTTP	code	Descripción
400	VALIDATION_ERROR	Falta un campo requerido o es inválido
401	UNAUTHORIZED	Token o API key ausente o inválida
402	INSUFFICIENT_CREDITS	Créditos insuficientes para la operación
404	NOT_FOUND	Recurso no encontrado
500	INTERNAL_ERROR	Error interno del servidor

7. Consideraciones

Latencia: la generación con IA puede tardar varios segundos (hasta 300 s). Algunos endpoints soportan streaming.
Concurrencia: los créditos actúan como control natural de consumo; evita paralelizar generaciones sin control.
Persistencia: los POST de generación ya guardan el resultado; usa los GET para leerlo.