Referencia de la API

URL base y formato de respuesta

Todas las rutas se sirven con el prefijo /api. En local, la URL base es http://localhost:8000/api. En un servidor es la dirección de tu API seguida de /api, el mismo valor que ambos frontends leen de NEXT_PUBLIC_API_BASE_URL (Variables de entorno).

La API sirve a dos públicos que nunca comparten un token. Los estudiantes usan las rutas de /api/users/<area> y /api/shop, que se enumeran en las secciones para estudiantes más abajo. El panel de administración usa todas las demás rutas, incluidas /api/users y /api/users/<username>, que gestionan las cuentas de los estudiantes.

Los cuerpos de las solicitudes son JSON, excepto la subida de archivos. Cada respuesta llega en el mismo envoltorio:

{
  "success": true,
  "data": { },
  "message": ""
}

data contiene el resultado. message es una frase corta que rellenan algunas escrituras, traducida al idioma de la solicitud, y vacía en los demás casos. La comprobación de estado no necesita token y muestra el envoltorio:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok"},"message":""}

Responde 503 mientras no se puede acceder a la base de datos o esta no tiene tablas, así que un balanceador de carga puede usarla como sonda de disponibilidad.

Errores

Una solicitud fallida responde con el estado HTTP correspondiente y el mismo sobre, con success: false, data: null y, en la validación, los problemas por campo, con el nombre del campo como clave (un campo dentro de un objeto anidado, con su ruta separada por puntos):

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"not-an-email","password":"x"}'

{
  "success": false,
  "data": null,
  "message": "Enter a valid email address (example@domain.com).",
  "errors": {
    "email": ["Enter a valid email address (example@domain.com)."]
  }
}

Las escrituras correctas responden 201 para POST y 200 para los demás métodos.

Paginación y ordenación

Las listas llegan en dos formas, una por público. Las rutas de estudiantes responden con la forma que lee el sitio para estudiantes; las rutas de administración responden con la forma que lee el panel.

Una página tiene como máximo 100 filas: un tamaño mayor se lee como 100, y uno ausente o ilegible vuelve al valor por defecto de la lista. Lo mismo ocurre con page, que vuelve a 1.

sort solo acepta las columnas que permite cada lista. Una clave desconocida recurre al orden predeterminado en lugar de fallar, así que un marcador antiguo sigue cargando.

La lista pública de cursos se ordena por id, price, discount_percentage, rating, duration, level, language, created_at o updated_at, y se filtra por title, category_id, instructor_id y type (live o recorded).

Idioma

Envía el idioma del lector en la cabecera Accept-Language. La API habla los idiomas indicados en back-end/src/i18n/locales.ts, en y ar tal como viene. Lee la primera etiqueta, así que ar-SA es árabe, y una solicitud que no nombra ningún idioma admitido se responde en el idioma del ajuste default_locale. No hay parámetro de consulta para el idioma.

• Los mensajes de error y el message de una escritura correcta se traducen.
• El texto guardado en ambos idiomas, como los títulos y las descripciones de los cursos, vuelve como { "en": "...", "ar": "..." } y el cliente elige uno.
• Algunas rutas de estudiantes responden solo en el idioma solicitado: la lista de inscripciones, el contenido de un curso y la búsqueda.
• El pago toma el idioma de su cuerpo (locale, uno de los idiomas admitidos), para que el recibo coincida con la página en la que compró el estudiante.

Autenticación

Los estudiantes y los administradores inician sesión en endpoints distintos, contra tablas distintas, y reciben tokens que solo aceptan sus propias rutas.

• Ambos son JWT firmados con JWT_SECRET. Envíalos como Authorization: Bearer <token>.
• Un token dura JWT_EXPIRATION, 7d por defecto (Variables de entorno). El inicio de sesión de administrador indica el mismo valor en expires_in.
• No hay endpoint de renovación. Cuando un token caduca, la siguiente solicitud responde 401 y el cliente vuelve a iniciar sesión.
• Cerrar sesión (POST /api/users/auth/logout) solo le indica al cliente que descarte su token. No se revoca nada en el servidor, así que un token sigue siendo válido hasta que caduca.
• Un token de estudiante se rechaza en las rutas de administración y un token de administrador en las rutas de estudiantes, aunque ambos usan el mismo secreto.
• Un inicio de sesión fallido responde 401 con un único mensaje, tanto si el email no tiene cuenta como si la contraseña es incorrecta, así que el formulario no sirve para averiguar quién tiene cuenta.
• Las rutas de inicio de sesión, registro y contraseña aceptan 10 intentos por minuto desde una misma dirección, contados por ruta. Pasado eso responden 429 con una cabecera Retry-After. La cuenta se guarda en la memoria de la API, así que se reinicia al reiniciarla y cada instancia lleva la suya.

1. 01

   Inicia sesión como el Super Admin de los datos iniciales

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@learnio.com","password":"Admin@123"}'

   RespuestaCopiar

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@learnio.com",
         "instructor_id": null,
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "Signed in successfully."
   }
2. 02

   Llama a una ruta protegida con el token

   TerminalCopiar

   curl "http://localhost:8000/api/courses?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Resultado esperado: Los cinco primeros cursos, con la forma de lista de administración.
3. 03

   Inicia sesión como el estudiante de los datos iniciales

   Los datos de ejemplo también incluyen un estudiante, demo@learnio.com con la contraseña Demo@123:

   TerminalCopiar

   curl -X POST http://localhost:8000/api/users/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"demo@learnio.com","password":"Demo@123"}'

   Después pasa data.token de la misma forma, por ejemplo a GET /api/users/enrollments.

Permisos

Cada ruta de administración comprueba primero el token y luego el permiso que indica. Los permisos se llaman <module>.<action>, y un administrador tiene todos los permisos de todos sus roles. Cuando una ruta indica varios, basta con uno de ellos. En las tablas de administración de más abajo, un nombre de permiso en la columna Quién puede llamarla significa un administrador cuyos roles lo conceden.

Volver a ejecutar el seeder crea los roles que faltan y deja como están los permisos de los roles existentes, así que los cambios hechos en el panel se conservan. Super Admin es la excepción: recibe cualquier permiso que aún no tenga.

Todos los permisos de lectura terminan en .view y ningún otro lo hace: el rol Viewer de los datos iniciales se construye con esa regla. Los roles que crean los datos de ejemplo:

Una cuenta de administrador vinculada a un instructor lleva un instructor_id en su respuesta de inicio de sesión y, además de sus permisos, queda limitada a sus propios cursos: las listas solo muestran esos cursos y sus estudiantes, y una escritura fuera de ellos responde 403.

Cuando cambian los roles de un administrador, el panel recibe el aviso por el socket /auth (evento permissions-updated) para refrescar GET /api/auth/me. Ese socket solo acepta tokens de administrador.

Catálogo público

No se necesita token. Son las rutas que llaman las páginas públicas del sitio para estudiantes.

La I mayúscula de /api/users/Instructors es la ruta que llama el sitio para estudiantes; la coincidencia no distingue mayúsculas de minúsculas.

Registro e inicio de sesión de estudiantes

El sitio para estudiantes usa las rutas de /api/users/auth. El registro inicia la sesión del estudiante al momento y envía por correo un enlace de confirmación; una cuenta sin confirmar puede igualmente navegar y comprar.

resend y forgot-password responden igual tanto si la dirección tiene cuenta como si no, así que no sirven para averiguar quién está registrado. El inicio de sesión, el registro, resend, forgot-password y reset-password tienen límite de intentos (Autenticación).

Un segundo conjunto de rutas de estudiantes en /api/students/auth trabaja con las mismas cuentas y también responde token y user. El sitio para estudiantes no lo usa; usa preferiblemente /api/users/auth.

Perfil, cursos y progreso del estudiante

Todas estas rutas necesitan un token de estudiante. Los cursos y las lecciones se identifican por su code, no por su id numérico.

Las rutas de reseñas usan el id numérico del curso, y cada estudiante tiene una reseña por curso. Solo puede escribirla un estudiante inscrito en el curso; una inscripción cancelada responde 403.

• Una reseña queda published al instante, o pending hasta que un moderador la apruebe cuando el ajuste reviews_require_approval vale true. Editar una reseña que un moderador ocultó la devuelve a pending.
• Una reseña que eliminó un moderador vuelve con status: removed y ya no se puede editar ni retirar (403).
• Cada escritura recalcula la valoración y el número de reseñas del curso, y los de su instructor.
• Una reseña nueva, y una edición que espera aprobación, notifican al personal que tiene reviews.view.

Cuestionarios, tareas y calendario

Las rutas de clases en vivo del calendario se describen en Clases en vivo.

Mensajes y notificaciones del estudiante

Las notificaciones nuevas también se envían por Socket.IO, en el namespace /notifications en la dirección de la API sin /api. Pasa el token como auth.token en el handshake y escucha notification:created. Los administradores usan el mismo socket con su propio token.

Pago y cobros

Cuando el pago responde con redirect_url, envía allí al comprador y trata el pedido como pending: la plaza se concede cuando el webhook del procesador confirma el pago, no al volver. Cada webhook comprueba la firma del procesador y responde 401 cuando no coincide. Los eventos se aplican una sola vez, por mucho que el procesador reintente.

Un curso gratuito (precio 0) pasa por la misma ruta y nunca llega a un procesador, así que funciona sin ninguna clave de pago. El pedido se guarda como paid con gateway: "free" y redirect_url: null, la plaza se concede al momento y el estudiante recibe el email de inscripción sin recibo. Los pedidos gratuitos cuentan como inscripciones, no como ventas: quedan fuera del valor medio de pedido.

Configuración de los procesadores y sus suscripciones a webhooks: Pagos.

Inicio de sesión de administradores y cuentas del personal

Una dirección de email pertenece a un solo administrador, incluso a uno eliminado: crear un administrador, o cambiar un email por uno ya usado, responde 409.

Roles

Estudiantes

Las cuentas de estudiantes se identifican por username. Eliminar una es un borrado lógico que se puede restaurar.

Instructores

Una cuenta de instructor escribe a sus estudiantes mediante estas rutas, que responden 403 para un administrador no vinculado a un instructor:

Categorías

Las lecturas están abiertas a cualquiera y se enumeran en el Catálogo público. Las escrituras necesitan un permiso:

Cursos

Plan de estudios: secciones, lecciones y recursos

Cuestionarios y tareas

Inscripciones y pedidos

El status de un pedido es pending, paid, failed o refunded. Su gateway indica el procesador que cobró, demo para el simulador integrado o free para un curso que no costaba nada.

Reseñas

Los estudiantes escriben sus propias reseñas mediante las rutas de estudiante, y la página del curso lee las publicadas del Catálogo público. Cada cambio de moderación recalcula la valoración del curso y la del instructor.

Blog

Ajustes

Los ajustes de la plataforma se guardan como pares de clave y valor y se identifican por key.

El seeder crea estos seis, y cada uno lo lee la API o el panel del estudiante:

Un cambio se aplica en la siguiente solicitud o el siguiente email, sin reiniciar. Volver a ejecutar el seeder añade un ajuste que falte, pero nunca sobrescribe un valor ya guardado.

Subida de archivos multimedia

Envía multipart/form-data con el archivo en file, hasta 150 MB, y opcionalmente path (la carpeta, uploads por defecto), for (un tamaño de imagen predefinido) y type (video para omitir el procesamiento de imágenes). Las imágenes se redimensionan en varias versiones; los videos (mp4, webm, mov, m4v) se guardan tal cual. Necesita la configuración del bucket de Almacenamiento multimedia.

La ruta necesita un token de administrador o de estudiante, comprobado antes de leer el archivo. path debe ser una de las carpetas indicadas en back-end/src/modules/helpers/upload/upload-folders.constants.ts; cualquier otra responde 400. Un administrador puede subir a uploads, admins/profile, admins/profiles, users/profiles, blog, categories, courses, instructors, messages y ai-chat. Un estudiante solo puede subir a messages, para las imágenes que adjunta a una conversación. Una pantalla nueva que suba a una carpeta propia necesita añadir esa carpeta a la lista.

curl -X POST http://localhost:8000/api/helpers/upload \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@cover.jpg" -F "path=courses"

Notificaciones, búsqueda y estadísticas

Un administrador solo lee y cambia sus propias notificaciones: las rutas toman al administrador del token. La API escribe una por cada uno de estos eventos, para cada administrador que tenga el permiso que necesita la pantalla enlazada:

Una cuenta de administrador vinculada a un instructor solo recibe avisos de los cursos de ese instructor, y no de los registros nuevos. Cada una se envía además por el socket /notifications en cuanto se guarda.

Clases en vivo

Certificados

Asistente de IA

Historial de chat del asistente

Servidor MCP

Rutas del modo demostración

Pasarelas de pago personalizadas