API Documentation - Mayeutica

Introducción

Esta API proporciona endpoints para gestionar cursos, sesiones, interacciones con IA, datos de usuario y más para la plataforma Mayeutica.

Base URL: La URL base para todas las llamadas a la API es: https://api.mayeutica.school/api (Producción) ohttps://apimayeutica.test/api (Desarrollo Local)

Autenticación: La mayoría de los endpoints requieren autenticación. Hay dos tipos de tokens:

  1. Token API (token_api): Para operaciones generales de la API (como login inicial sin usuario). Se obtiene con la función login usando credenciales de API predefinidas. Se envía en el header: Authorization: Bearer {token_api}. El interceptor de Axios (main.js) intenta añadirlo automáticamente si no hay otro token de autorización presente.
  2. Token Usuario (token_user): Para operaciones específicas del usuario autenticado (como getUser, getPreferences, etc.). Se obtiene con las funciones signIn o signUp. Se envía en el header: Authorization: Bearer {token_user}.

Formato de Datos: Todas las solicitudes (a menos que se indique lo contrario) deben tener un Content-Type de application/json. Las respuestas también serán en formato JSON, excepto generateSpeech que devuelve audio/mpeg.

Manejo de Errores: La API utiliza códigos de estado HTTP estándar:

  • 200 OK: Solicitud exitosa.
  • 201 Created: Recurso creado exitosamente.
  • 400 Bad Request: Solicitud mal formada o datos inválidos (posiblemente error de Factory).
  • 401 Unauthorized: Token inválido o expirado. El interceptor del frontend redirige a /login.
  • 403 Forbidden: Permisos insuficientes.
  • 404 Not Found: Recurso no encontrado (usuario, curso, etc.).
  • 422 Unprocessable Entity: Errores de validación. La respuesta incluirá un objeto details o errors con los campos fallidos.
  • 500 Internal Server Error: Error inesperado en el servidor.
  • 503 Service Unavailable: Error de comunicación con servicios externos (como la API de IA).

Endpoints de Autenticación y Usuario

Estos endpoints gestionan el inicio/cierre de sesión y los datos del usuario.

POST /login (Inicio de Sesión API)

Inicia una sesión general para la API usando credenciales predefinidas (variables de entorno).

  • Descripción: Obtiene un token (token_api) para interactuar con endpoints que no requieren un usuario específico logueado.
  • Request Body:
    {
    "email": "tu_api_user@ejemplo.com", // Desde import.meta.env.VITE_MAYEUTICA_API_USER
    "password": "tu_api_key"           // Desde import.meta.env.VITE_MAYEUTICA_API_KEY
}
  • Successful Response (200 OK):
    {
    "accessToken": "..." // token_api
}
  • Notas: El frontend almacena este token en sessionStorage como token_api.

POST /login (Inicio de Sesión Usuario)

Autentica a un usuario existente con email y contraseña.

  • Descripción: Inicia la sesión para un usuario registrado.
  • Request Body:
    {
    "email": "usuario@ejemplo.com", // Requerido | string
    "password": "password_del_usuario" // Requerido | string
}
  • Successful Response (200 OK):
    {
    "accessToken": "...", // token_user
    "user": {
        "id": 1,
        "name": "Nombre Usuario",
        "email": "usuario@ejemplo.com",
        // ... otros datos del usuario
    }
}
  • Error Response (401 Unauthorized): Credenciales inválidas.
  • Notas: El frontend almacena accessToken como token_user y los datos de user en sessionStorage. Recarga la página después del login exitoso.

POST /register (Registro de Usuario)

Registra un nuevo usuario. Requiere obtener primero una cookie CSRF.

  • Descripción: Crea una nueva cuenta de usuario.
  • Prerrequisito: El frontend primero hace una llamada GET /sanctum/csrf-cookie para obtener la cookie CSRF necesaria para la protección de Laravel Sanctum.
  • Request Body:
    {
    "name": "Nuevo Usuario",    // Requerido | string
    "email": "nuevo@ejemplo.com", // Requerido | string | unique
    "password": "password_seguro" // Requerido | string | (Laravel suele requerir confirmación: password_confirmation)
}
  • Successful Response (201 Created):
    {
    // Datos del usuario recién creado o mensaje de éxito
    "id": 2,
    "name": "Nuevo Usuario",
    "email": "nuevo@ejemplo.com",
    // ...
}
  • Error Response (422 Unprocessable Entity): Fallos de validación (email ya existe, contraseña débil, etc.).

GET /user (Obtener Datos del Usuario Autenticado)

Obtiene los datos del usuario actualmente autenticado mediante token_user.

  • Descripción: Devuelve la información del usuario asociado al token Bearer enviado.
  • Headers:
    • Authorization: Bearer {token_user} (Requerido)
  • Successful Response (200 OK):
    {
    "id": 1,
    "name": "Nombre Usuario",
    "email": "usuario@ejemplo.com",
    "user_preferences": { "language": "es", "aiprovider": "openai" },
    // ... otros datos del usuario
}
  • Error Response (401 Unauthorized): Si el token no es válido o ha expirado.

POST /logout (Cierre de Sesión API/Usuario)

Invalida el token de autenticación proporcionado (puede ser token_api o token_user).

  • Descripción: Cierra la sesión asociada al token Bearer enviado.
  • Headers:
    • Authorization: Bearer {token} (Requerido: token_api o token_user)
  • Request Body: Objeto vacío {}
  • Successful Response (200 OK):
    {
    "message": "Successfully logged out" // o similar
}
  • Notas: El frontend elimina el token correspondiente (token_api o token_user) de sessionStorage.

Endpoints Principales (Orden Alfabético)

POST /countInteracciones

Cuenta las interacciones de tipo 'assistant' para una sesión específica.

  • Descripción: Devuelve el número total de mensajes enviados por el asistente en una sesión, útil para determinar si se alcanzó el límite o cuándo mostrar un cuestionario.
  • Request Body:
    {
    "id_user": 1,       // Requerido | integer
    "id_curso": 10,     // Requerido | integer
    "id_sesion": 55     // Requerido | integer
}
  • Successful Response (200 OK):
    // Devuelve directamente el número (integer)
3
  • Error Response (422 Unprocessable Entity): Si faltan parámetros requeridos.

POST /cupones

Obtiene una lista de todos los cupones disponibles.

  • Descripción: Devuelve un array con todos los registros de la tabla Cupon.
  • Request Body: (Aunque el backend no lo usa, el frontend envía requestData. Puede ser un objeto vacío {}).
  • Successful Response (200 OK):
    [
    { "id": 1, "codigo": "DESC10", "descuento": 10, ... },
    { "id": 2, "codigo": "PROMO20", "descuento": 20, ... }
]

POST /cursos

Obtiene información sobre los cursos.

  • Descripción: Devuelve una lista de todos los cursos o la información de un curso específico si se proporciona cursold.
  • Request Body:
    {
    "cursold": 10 // Opcional | integer - ID del curso a obtener
}
  • Successful Response (200 OK):
    • Si cursold se omite: Array de todos los objetos Curso.
    • Si cursold se proporciona: Array con un único objeto Curso.
    [
    { "id": 10, "nombre": "Introducción a Vue.js", "descripcion": "...", ... }
]

POST /engineInteraction

Procesa la interacción principal entre el usuario y la IA.

  • Descripción: Recibe el historial de chat, el contexto del curso y el proveedor de IA seleccionado, genera una respuesta de la IA y la devuelve. Es el endpoint central del chat.
  • Request Body:
    {
    "chatHistory": [ // Requerido | array
        { "role": "system", "content": "..." },
        { "role": "user", "content": "Hola" },
        { "role": "assistant", "content": "¿En qué puedo ayudarte?" }
    ],
    "data_curso": { // Requerido | object
        "id_user": 1,
        "curso_name": "Introducción a Vue.js",
        "session_name": "Componentes",
        "tema_name": "Conceptos Básicos",
        "name_user": "Nombre Usuario"
        // Se añaden id_curso, id_sesion, id_matricula en el frontend
    },
    "aiprovider": "openai" // Requerido | string | 'openai', 'anthropic', 'deepseek', 'gemini'
}
  • Successful Response (200 OK):
    {
    "message": "Aquí está la respuesta generada por la IA..." // string
}
  • Error Response:
    • 422 Unprocessable Entity: Si la validación falla (estructura incorrecta, valores inválidos).
    • 404 Not Found: Si el id_user en data_curso no existe.
    • 503 Service Unavailable / 4xx: Errores devueltos por la API del proveedor de IA (OpenAI, Gemini, etc.).
    • 400 Bad Request: Si el aiprovider no es soportado o hay errores de configuración.

POST /enroll

Registra la matrícula de un usuario a un curso después de un pago exitoso (ej. PayPal).

  • Descripción: Recibe los detalles del pago y el email del usuario, busca al usuario, crea un registro de Matricula y un registro de Pago.
  • Request Body:
    {
    "user_mail": "usuario@ejemplo.com", // Requerido | string
    "cursold": 10,                      // Requerido | integer
    "details": "{...}"                  // Requerido | string (JSON string de los detalles del pago, ej. de PayPal)
}
  • Successful Response (200 OK / 201 Created): Devuelve un mensaje de éxito o el objeto Matricula creado.
  • Error Response:
    • 404 Not Found: Si el user_mail no corresponde a ningún usuario registrado.
    • Errores de base de datos si falla la inserción.

POST /enrolled

Verifica si un usuario está matriculado en un curso específico.

  • Descripción: Comprueba si existe un registro de matrícula para la combinación de userId y cursold.
  • Request Body:
    {
    "userId": 1,    // Requerido | integer
    "cursold": 10   // Requerido | integer
}
  • Successful Response (200 OK):
    • Si está matriculado: Objeto Matricula.
    {
    "id": 123,
    "id_user": 1,
    "id_curso": 10,
    "id_sesion": 55,
    "estado": "Matriculado",
    // ...
}
    • Si no está matriculado: Devuelve 0 o null (según la implementación exacta, el frontend espera algo falsy).

POST /generateSpeech

Convierte texto a voz usando la API de OpenAI TTS.

  • Descripción: Recibe texto y devuelve los datos de audio correspondientes.
  • Request Body:
    {
    "text": "Este es el texto a convertir en audio.", // Requerido | string
    "user_id": 1 // Requerido | integer (Usado para nombrar el archivo temporalmente en backend)
}
  • Successful Response (200 OK):
    • Content-Type: audio/mpeg
    • Body: Los datos binarios del archivo de audio. (El frontend lo recibe como Blob).
  • Error Response: Si falla la comunicación con la API de OpenAI o la escritura del archivo temporal.

POST /getInteracciones

Obtiene el historial de interacciones (mensajes) para una sesión específica.

  • Descripción: Devuelve todos los mensajes de usuario y asistente para un usuario, curso y sesión dados.
  • Request Body:
    {
    "id_user": 1,       // Requerido | integer
    "id_curso": 10,     // Requerido | integer
    "id_sesion": 55     // Requerido | integer
}
  • Successful Response (200 OK):
    [
    { "id": 1, "role": "user", "content": "Hola", ... },
    { "id": 2, "role": "assistant", "content": "¿Cómo estás?", ... },
    // ... más interacciones
]
  • Error Response (422 Unprocessable Entity): Si faltan parámetros requeridos.

POST /getPreferences

Obtiene las preferencias guardadas para un usuario específico.

  • Descripción: Devuelve el objeto de preferencias del usuario (idioma, proveedor IA, etc.).
  • Request Body:
    {
    "user_id": 1 // Requerido | integer
}
  • Successful Response (200 OK):
    {
    "language": "es",
    "aiprovider": "openai"
    // ... otras preferencias
}
    • Devuelve null o un objeto vacío si no hay preferencias guardadas.
  • Error Response (404 Not Found): Si el user_id no existe.

POST /language

Obtiene el mapa de idiomas soportados.

  • Descripción: Devuelve un objeto JSON que mapea códigos de idioma (ej. 'en') a nombres completos (ej. 'English').
  • Request Body: (Aunque el backend no lo usa, el frontend envía requestData. Puede ser un objeto vacío {}).
  • Successful Response (200 OK):
    {
    "ar": "Arabic",
    "en": "English",
    "es": "Spanish",
    // ... etc
}

POST /next_session

Obtiene los datos de la siguiente sesión para una matrícula dada.

  • Descripción: Recibe el ID de la matrícula actual y calcula/devuelve el objeto de la siguiente sesión en el curso. Actualiza id_sesion en la matrícula.
  • Request Body:
    {
    "id_matricula": 123 // Requerido | integer
}
  • Successful Response (200 OK):
    • Si hay una siguiente sesión: Objeto Sesion de la siguiente sesión.
    { "id": 56, "id_curso": 10, "id_tema": 21, "nombre": "Props", ... }
    • Si es la última sesión: Devuelve false.
  • Error Response (404 Not Found): Si el id_matricula no existe.

POST /sesiones

Obtiene información sobre las sesiones de un curso o tema.

  • Descripción: Devuelve sesiones filtradas por ID de curso, ID de tema, o ID de sesión específico, o todas las sesiones si no se proporcionan filtros.
  • Request Body:
    {
    "cursold": 10,    // Opcional | integer
    "temald": 20,     // Opcional | integer
    "sesionId": 55    // Opcional | integer
}
  • Successful Response (200 OK): Array de objetos Sesion que coinciden con los filtros.
    [
    { "id": 55, "nombre": "Estado Local", "id_curso": 10, "id_tema": 20, ... },
    { "id": 56, "nombre": "Props", "id_curso": 10, "id_tema": 21, ... }
]

POST /storeInteraccion

Guarda una nueva interacción (mensaje de usuario o asistente) en la base de datos.

  • Descripción: Almacena un mensaje del chat. Usado internamente por interaction_engine después de una respuesta.
  • Request Body:
    {
    "id_user": 1,           // Requerido | integer
    "id_curso": 10,         // Requerido | integer
    "id_sesion": 55,        // Requerido | integer
    "role": "user",         // Requerido | string ('user' o 'assistant')
    "content": "Mensaje...", // Requerido | string
    "ia_provider": "openai" // Requerido | string (Proveedor que generó la respuesta si role='assistant')
}
  • Successful Response (201 Created):
    // Objeto de la Interaccion recién creada
{
    "id": 3,
    "id_user": 1,
    "id_curso": 10,
    "id_sesion": 55,
    "role": "user",
    "content": "Mensaje...",
    "ia_provider": "openai",
    // ... timestamps
}
  • Error Response (422 Unprocessable Entity): Si faltan datos o son inválidos.

POST /storePregunta

Guarda la respuesta y evaluación de una pregunta del cuestionario.

  • Descripción: Almacena los detalles de una pregunta del cuestionario, la respuesta del usuario, y la evaluación/calificación generada por la IA.
  • Request Body:
    {
    "data_curso": { // Requerido | object (Debe contener id_user, id_sesion)
        "id_user": 1,
        "id_sesion": 55,
         // ...otros datos que puedan ser útiles si la API los necesitara
    },
    "pregunta": "¿Qué son los props?", // Requerido | string
    "consecutivo": "1",               // Requerido | string o integer (Número de pregunta, ej. '1', '2')
    "respuesta": "Son propiedades...",// Requerido | string (Respuesta del usuario)
    "evaluacion": "Buena respuesta...", // Requerido | string (Feedback cualitativo de IA)
    "calificacion": "4",              // Requerido | string o number (Score numérico de IA)
    "Alprovider": "openai"           // Requerido | string (Proveedor IA que evaluó)
}
  • Successful Response (201 Created): Devuelve el objeto Pregunta creado o un mensaje de éxito.
  • Error Response (422 Unprocessable Entity): Si faltan datos o son inválidos.

POST /temas

Obtiene información sobre los temas de un curso.

  • Descripción: Devuelve temas filtrados por ID de curso o ID de tema específico, o todos los temas si no se proporcionan filtros.
  • Request Body:
    {
    "cursold": 10, // Opcional | integer
    "temald": 20   // Opcional | integer
}
  • Successful Response (200 OK): Array de objetos Tema que coinciden con los filtros.
    [
    { "id": 20, "nombre": "Conceptos Básicos", "id_curso": 10, ... },
    { "id": 21, "nombre": "Componentes Avanzados", "id_curso": 10, ... }
]

POST /updateMatricula

Actualiza el estado o la sesión actual de una matrícula.

  • Descripción: Puede usarse para avanzar a la siguiente sesión (next_session) o para marcar un curso como completado (estado).
  • Request Body (Opción 1: Avanzar Sesión):
    {
    "data_curso": {         // Requerido | object
        "id_user": 1,
        "id_curso": 10
        // El ID de la matrícula se infiere buscando con id_user y id_curso
    },
    "next_session": 56      // Requerido para avanzar | integer (ID de la nueva sesión)
}
  • Request Body (Opción 2: Actualizar Estado):
    {
    "data_curso": { ... },  // Requerido | object (Como arriba)
    "estado": "completed" // Requerido para cambiar estado | string (ej. "completed")
    // El frontend también envía el ID de matrícula directamente a veces:
    // "id": 123 // ID de la matrícula a actualizar (Ajustar API si es necesario)
}
  • Successful Response (200 OK):
    • Si se envió next_session: Devuelve el objeto Sesion correspondiente a next_session.
    • Si se envió estado: Devuelve el objeto Matricula actualizado.
  • Error Response (404 Not Found): Si no se encuentra la matrícula basada en data_curso.

POST /updatepreferences

Actualiza las preferencias de un usuario.

  • Descripción: Guarda las nuevas preferencias de idioma y proveedor de IA para el usuario.
  • Request Body:
    {
    "data": { // Requerido | object
        "user_id": 1,              // Requerido | integer
        "language": "en",          // Requerido | string (código de idioma, ej. 'en', 'es')
        "aiProvider": "gemini"     // Requerido | string (ej. 'openai', 'gemini')
    }
}
  • Successful Response (200 OK): Devuelve las preferencias actualizadas o un mensaje de éxito.
  • Error Response (404 Not Found): Si el user_id no existe.