Endpoints disponibles

Endpoints de cursos

Gestiona los cursos de tu academia programaticamente:

• GET /api/v1/courses — Lista todos los cursos de la academia. Soporta filtros por estado (published, draft), categoria y busqueda por titulo. Paginacion con page y limit.
• GET /api/v1/courses/:id — Obtiene el detalle de un curso incluyendo modulos, lecciones y configuracion.
• POST /api/v1/courses — Crea un nuevo curso. Requiere rol admin o owner. Body: { "title", "description", "price", "category_id" }.
• PATCH /api/v1/courses/:id — Actualiza propiedades de un curso existente. Solo envia los campos que deseas cambiar.
• DELETE /api/v1/courses/:id — Elimina un curso (soft delete: se marca como eliminado pero no se borra de la base de datos). Requiere rol admin.

Endpoints de inscripciones

• GET /api/v1/enrollments — Lista todas las inscripciones. Filtrable por course_id, student_id, status y rango de fechas.
• GET /api/v1/enrollments/:id — Detalle de una inscripcion con progreso del estudiante, lecciones completadas y fecha de inscripcion.
• POST /api/v1/enrollments — Crea una inscripcion manual (no requiere pago). Requiere rol admin. Body: { "student_id", "course_id" }.
• DELETE /api/v1/enrollments/:id — Cancela una inscripcion. Requiere rol admin.

Endpoints de estudiantes

• GET /api/v1/students — Lista estudiantes registrados con paginacion. Soporta busqueda por nombre y email.
• GET /api/v1/students/:id — Perfil del estudiante con datos de contacto, inscripciones activas y progreso general.
• GET /api/v1/students/:id/progress — Progreso detallado por curso: porcentaje completado, lecciones finalizadas, ultima actividad y calificaciones.

Endpoints de pagos

• GET /api/v1/payments — Historial de pagos con filtros por fecha, proveedor (stripe, mercadopago, lemonsqueezy, hotmart) y estado.
• GET /api/v1/payments/:id — Detalle de un pago individual con referencia del proveedor, monto, moneda y estudiante asociado.

Endpoints de suscripciones

• GET /api/v1/subscriptions — Lista suscripciones activas, canceladas y expiradas.
• GET /api/v1/subscriptions/:id — Detalle de una suscripcion: plan, fecha de inicio, proxima renovacion, estado y historial de pagos.

Codigos de estado HTTP

La API utiliza los siguientes codigos de estado estandar:

• 200 OK — peticion exitosa, datos en el body.
• 201 Created — recurso creado correctamente.
• 400 Bad Request — datos invalidos en la peticion (campos faltantes, formatos incorrectos).
• 401 Unauthorized — no autenticado (token faltante, expirado o invalido).
• 403 Forbidden — no autorizado (permisos insuficientes para la operacion).
• 404 Not Found — recurso no encontrado.
• 429 Too Many Requests — limite de peticiones excedido (ver articulo de rate limits).
• 500 Internal Server Error — error interno del servidor.

Preguntas frecuentes

• ¿Los endpoints respetan Row Level Security?

  Si. Cuando usas un JWT de usuario, los endpoints solo devuelven datos que el usuario tiene permiso de ver segun su rol y las politicas RLS. Con la Service Role Key, se omite RLS y se accede a todos los datos.

• ¿Puedo filtrar cursos por estado y categoria simultaneamente?

  Si. Combina multiples parametros de query: GET /api/v1/courses?status=published&category_id=abc123&limit=10.

• ¿Los endpoints de pagos permiten procesar reembolsos?

  No. Los endpoints de pagos son de solo lectura (GET). Los reembolsos se procesan directamente desde el dashboard del proveedor de pago (Stripe, MercadoPago, etc.).

• ¿Puedo crear inscripciones masivas via API?

  Si. Usa el endpoint POST /api/v1/enrollments en un loop para inscribir multiples estudiantes. Respeta los rate limits de tu plan para evitar errores 429.

• ¿Los endpoints devuelven datos en español?

  Los datos se devuelven tal como fueron ingresados. Si los titulos de tus cursos estan en español, la API los devuelve en español. Los mensajes de error del sistema estan en ingles.