Desarrolladores · Documentación de la API

Integración con Moodle

Cómo se integran EduPay y Moodle: plugin, inicio de sesión único, bloque del alumno, grupos, bloqueo por atraso y rutas del plugin.

EduPay y Moodle se comunican en los dos sentidos:

  • De Moodle a EduPay, por el plugin instalado en Moodle: el alumno entra a Moodle con el inicio de sesión de EduPay, ve su situación financiera en un bloque y abre el portal del alumno sin escribir la contraseña.
  • De EduPay a Moodle, por el servicio web de Moodle: cuando se hace la matrícula, EduPay crea el usuario en Moodle y lo pone en la cohorte del grupo. Si el alumno se atrasa, EduPay lo saca de la cohorte; cuando paga, lo devuelve.

Esta página describe la integración tal como funciona hoy, para quien instala el plugin y para quien da soporte a la escuela.

Las piezas

Pieza Dónde está Para qué
Plugin auth_edupay (Edupay SSO) Moodle, en auth/edupay Botón "Iniciar sesión con edupay" en la pantalla de inicio de sesión de Moodle
Plugin block_edupay (Portal Financiero edupay) Moodle, en blocks/edupay Bloque con el resumen financiero y el botón del portal del alumno
Integración con Moodle de EduPay Panel de EduPay, en Integraciones → Plataformas LMS Dirección de Moodle y el token del servicio web, para que EduPay matricule, bloquee y libere

Los dos plugins funcionan en Moodle 4.1 o más reciente y están en portugués, inglés y español.

Qué ve el alumno

  • En el inicio de sesión de Moodle, el botón Iniciar sesión con edupay. Entra con el mismo e-mail o CPF (documento fiscal de persona física en Brasil) y la misma contraseña del portal del alumno de EduPay.
  • En Moodle, el bloque Portal Financiero edupay con "Bienvenido, nombre", cuántas cuotas están pendientes, el estado del contrato y el botón Acceder al portal financiero, que abre el portal del alumno en una pestaña nueva, con la sesión ya iniciada.
  • En el portal del alumno de EduPay, el botón Acceder al Sistema Académico, que abre Moodle con la sesión ya iniciada (después de que el alumno se sincronizó con Moodle al menos una vez).
  • En los cursos, entra solo cuando se hace la matrícula, sale si atrasa el pago más allá del plazo de la escuela y vuelve cuando paga.

Instalar en Moodle

Quien instala es un administrador de Moodle.

  1. Pida al equipo de EduPay los archivos auth_edupay.zip y block_edupay.zip.
  2. En Administración del sitio → Extensiones → Instalar extensiones, suba los dos (o copie las carpetas edupay en auth/ y blocks/) y complete la actualización de Moodle.
  3. En Administración del sitio → Extensiones → Autenticación → Gestionar autenticación, habilite Edupay SSO.
  4. En Administración del sitio → Características avanzadas, active Habilitar servicios web, y en Extensiones → Servicios web → Gestionar protocolos, active REST. El plugin no activa esto solo.

Instale los dos plugins, aunque la escuela solo quiera el bloque: los usuarios que EduPay crea en Moodle usan el método de autenticación de auth_edupay.

En la instalación, el bloque crea en Moodle el servicio externo Edupay Integration (edupay_integration), con las seis funciones que usa EduPay (vea "De EduPay a Moodle", más abajo).

Configurar

1. En EduPay: las claves de los plugins

En Integraciones → Tokens de API, cree la clave con uno de los paquetes de Moodle:

Paquete Permisos Dónde usarla
Moodle (completo) moodle:auth, moodle:student, moodle:portal En los dos plugins
Moodle (solo SSO) moodle:auth En auth_edupay
Moodle (solo bloque) moodle:student, moodle:portal En block_edupay

La clave de Moodle funciona con la API pública activada o desactivada. Al rotar, la clave anterior vale solo 24 horas más: cámbiela en los dos plugins dentro de ese plazo.

2. En Moodle: los plugins

auth_edupay (Administración del sitio → Extensiones → Autenticación → Edupay SSO):

Configuración Qué es Predeterminado
URL del tenant edupay La dirección de EduPay (https://edupay.estudiosite.com) vacío
Token de API La clave edp_... con moodle:auth vacío
Texto del botón de inicio de sesión El texto del botón en la pantalla de inicio de sesión Iniciar sesión con edupay
Crear usuarios automáticamente Crea el usuario en Moodle en el primer inicio de sesión, si todavía no existe activado
Actualizar usuario al iniciar sesión En cada inicio de sesión, actualiza el nombre y el apellido con los de EduPay activado

block_edupay (Administración del sitio → Extensiones → Bloques → Portal Financiero edupay):

Configuración Qué es
URL del tenant edupay La dirección de EduPay
Token de API La clave edp_... con moodle:student y moodle:portal
Token REST de Moodle Botón Generar token de Moodle: crea el token que EduPay usa para llamar a Moodle (vea el paso 3)

Después, agregue el bloque en el Área personal (Dashboard) o en las páginas de los cursos. En cada bloque se puede ocultar el resumen y cambiar el texto del botón.

3. En EduPay: la integración con Moodle

  1. En Moodle, en la configuración del bloque, haga clic en Generar token de Moodle en Token REST de Moodle y copie el token. Pertenece al administrador que hizo clic, no vence y sirve solo para el servicio Edupay Integration. Regenerar token borra los tokens anteriores del servicio.
  2. En EduPay, en Integraciones → Plataformas LMS → Moodle, complete la URL base de la plataforma (con https://, exactamente la dirección del sitio Moodle), pegue el Token REST de Moodle, active la integración (Integración activa) y guarde.
  3. Haga clic en Probar conexión.

4. Grupos y cursos

EduPay pone al alumno en una cohorte de Moodle. Quien lleva la cohorte a los cursos es el propio Moodle:

  1. Cada grupo de EduPay se vincula a una cohorte. Al crear el grupo, marque Crear también en Moodle; en un grupo que ya existe, use el botón Crear grupo en Moodle en la página del grupo. La cohorte se crea en todo el sitio, y los alumnos ya matriculados en el grupo se envían a Moodle. También se puede informar a mano el ID del grupo en Moodle: es el número interno de la cohorte (el id que aparece en la dirección de la cohorte), no el campo "ID number".
  2. En cada curso de Moodle, agregue el método de matriculación Sincronización de cohortes con esa cohorte.

Inicio de sesión único: cómo funciona

  1. El alumno hace clic en Iniciar sesión con edupay en Moodle.
  2. Moodle lo lleva a https://edupay.estudiosite.com/moodle/sso, con la dirección del propio Moodle. EduPay encuentra la escuela por esa dirección: tiene que ser igual a la URL base registrada en la integración.
  3. Si el alumno ya tiene la sesión iniciada en el portal de EduPay, sigue directo. Si no, entra con el usuario y la contraseña del portal.
  4. EduPay devuelve al alumno a Moodle con un código de uso único, que vale 5 minutos.
  5. El plugin cambia el código por los datos del alumno (nombre y e-mail), encuentra el usuario de Moodle por el e-mail — o lo crea, si "Crear usuarios automáticamente" está activado — e inicia la sesión del alumno.

El inicio de sesión normal de Moodle sigue disponible para quien no usa el botón. Los usuarios con el método edupay solo entran por el botón: la contraseña de Moodle no vale para ellos, ni el cambio de contraseña de Moodle.

De EduPay a Moodle

EduPay llama al servicio web de Moodle (/webservice/rest/server.php) con el token REST:

Función de Moodle Cuándo
core_webservice_get_site_info Probar conexión
core_user_get_users Encontrar el usuario del alumno por el e-mail
core_user_create_users Crear el usuario, si no existe (nombre de usuario = e-mail, método edupay)
core_cohort_create_cohorts Crear la cohorte del grupo
core_cohort_add_cohort_members Poner al alumno en la cohorte (matrícula y liberación)
core_cohort_delete_cohort_members Sacar al alumno de la cohorte (bloqueo y cancelación)

Cuándo el alumno entra, sale y vuelve:

Momento Qué ocurre en Moodle
Matrícula hecha por la escuela (panel o API) Entra en la cohorte en el momento
Compra por la página de ventas Entra cuando se confirma el primer pago (en el momento, si no hay nada que pagar)
Cuota vencida hace más días que el plazo de la escuela Sale de la cohorte (rutina diaria, de madrugada)
Pago que elimina el atraso Vuelve a la cohorte
Matrícula cancelada Sale de la cohorte

El plazo de bloqueo es el campo Días para marcar como vencido en Configuración (predeterminado: 30). A pesar del nombre, la cuota pasa a vencida el día siguiente al vencimiento; ese número solo decide cuántos días de atraso sacan al alumno de Moodle.

Cuando una llamada a Moodle falla, la sincronización de la matrícula queda como "Fallo" y el error aparece en la integración. En la pantalla de la matrícula, el botón Re-sincronizar Moodle intenta de nuevo.

Puntos de atención

  • Todo se vincula por el e-mail. El alumno de EduPay y el usuario de Moodle son el mismo cuando el e-mail es el mismo. Un alumno sin e-mail no va a Moodle.
  • "Actualizar usuario al iniciar sesión" cambia el método de autenticación de un usuario de Moodle que ya existía con el mismo e-mail a edupay. Después de eso, su contraseña anterior en Moodle deja de funcionar. Para profesores y administradores con el mismo e-mail que un alumno, desactive esa opción.
  • Un cambio de nombre o e-mail en EduPay no llega a Moodle solo. El nombre se actualiza en el próximo inicio de sesión por el botón, si la opción está activada.
  • Concluir la matrícula no saca al alumno de Moodle. Solo la cancelación y el bloqueo por atraso lo sacan.
  • Salir de la cohorte tiene en el curso el efecto configurado en la matriculación por cohorte de Moodle. Con la configuración predeterminada de Moodle, el alumno queda desmatriculado del curso.
  • Los profesores y administradores que no son alumnos en EduPay ven en el bloque "No se pudieron cargar los datos". Es lo esperado.
  • El bloque guarda el resumen durante 5 minutos en la sesión de Moodle. Un pago nuevo aparece en el bloque después de ese tiempo, o en el próximo inicio de sesión.

Rutas usadas por los plugins

Las rutas de abajo son solo de los plugins. Están congeladas: no cambian con las versiones de la API pública, para que el plugin instalado en las escuelas siga funcionando sin actualización. Para integrar otros sistemas, use la API pública.

Ruta Permiso Respuesta de éxito
GET /api/moodle/auth/verify?token= moodle:auth {"name", "email", "student_id"}
GET /api/moodle/student/summary?email= moodle:student {"student_name", "open_installments", "contract_status", "contract_status_label"}
POST /api/moodle/auth/portal-token (cuerpo {"email"}) moodle:portal {"url", "expires_in": 300}
  • Clave en el encabezado Authorization: Bearer edp_..., la misma de las claves de la API pública. La escuela es la de la clave.
  • Errores en el formato antiguo, {"error": "..."}: 401 "Unauthorized", 403 "Forbidden — insufficient scope", 404 "Not found" (o "Invalid or expired token" y "Student not found" en verify) y 422 "Portal not configured".
  • Límite de 60 llamadas por minuto por clave, separado de los límites de la API pública.
  • No dependen del interruptor de la API pública.

Moodle en la API pública

Para seguir la sincronización desde otro sistema:

  • GET /students/{id} trae moodle_user_id, el número del usuario en Moodle.
  • GET /enrollments trae moodle_sync_status: null (todavía no fue a Moodle), synced, suspended (fuera de la cohorte por atraso), removed (fuera por cancelación) o failed.
  • GET /cohorts trae moodle_cohort_id, y GET /offerings, moodle_course_id.
  • Los avisos enrollment.suspended y enrollment.reactivated llegan cuando el alumno sale de la cohorte por atraso y cuando vuelve. Vea Avisos automáticos.
  • POST /students/{id}/portal-link genera el mismo enlace de acceso al portal que usa el bloque, para cualquier sistema.