Andrés Martínez Soto

Si usas Moodle o te interesa automatizar tus procesos dentro de la plataforma, probablemente hayas oído hablar de la Moodle REST API. Moodle es una herramienta increíble, potente y flexible… pero a veces requiere demasiado trabajo manual: crear usuarios uno a uno, matricularlos en cursos, generar informes de notas o mover datos entre sistemas. Parece que pasamos más tiempo gestionando Moodle que ayudando a la gente a aprender.

La Moodle REST API es esa función “oculta” que muchos asocian con programadores o tareas técnicas, pero que en realidad puede ser tu mejor aliada. Permite que tu Moodle trabaje para ti, automatizando procesos y conectándose con tus otras herramientas sin esfuerzo.

Si todavía no tienes tu plataforma lista, empieza por esta guía: Instala Moodle en tu VPS Ubuntu: Guía Paso a Paso para No Expertos.

Pero ¿y si te digo que esa API es, en realidad, tu mejor aliada? ¿Y si fuera la llave para que Moodle trabaje para ti y no al revés?

En este artículo vamos a desmitificar la Moodle REST API. Te explicaré qué es, cómo empezar a usarla (aunque no seas técnico), y te mostraré ejemplos reales de cómo puede ahorrarte horas de trabajo y hacer que tu Moodle sea más inteligente y eficiente. Créeme, marcará un antes y un después.

1️⃣ Vale, pero ¿qué es exactamente la Moodle REST API ?

Olvida los tecnicismos por un segundo.
Imagina que Moodle es una cocina súper equipada. Normalmente, para hacer algo (como un pastel o “crear un usuario”), tienes que entrar en la cocina, buscar los ingredientes, usar la batidora, meterlo al horno… todo manualmente desde la interfaz.

La API REST es como un camarero al que le das órdenes desde tu mesa.

Tú, desde tu sistema de ventas, tu aplicación o un simple script, le dices al camarero: “Oye, créame un usuario llamado Juan Pérez con esta contraseña y mételo en el curso de ‘Introducción’”.

El camarero (la API) entra en la cocina (Moodle), hace todo el trabajo por ti y vuelve con la respuesta: “Hecho. El ID de Juan es el 45”.

Eso es todo. Es un puente que permite que tus otras aplicaciones hablen con Moodle en un idioma que ambos entienden (normalmente, un formato sencillo llamado JSON).

Si buscas integraciones estandarizadas además de la API REST, te puede interesar LTI 1.3 en Moodle: Integración Paso a Paso.

Con este “camarero” puedes:

• Crear usuarios cuando se registran en tu web.
• Matricularlos en un curso justo cuando pagan en tu tienda online.
• Obtener las notas de todos tus alumnos y enviarlas a un sistema de análisis como Power BI, sin exportar ni un solo Excel.
• Y mucho más.

Y si quieres llevar esa automatización más lejos, mira Automatización Avanzada en Moodle: Cron Jobs, Scripts PHP y el Poder de las Tareas Programadas.

2️⃣ ¿Por qué deberías tomarte un café con la Moodle REST API?

“Suena bien”, pensarás, “pero ¿realmente la necesito?”. Déjame que te lo resuma así:

🔹 Para dejar de hacer trabajo de robot
¿Cuántas horas has pasado subiendo usuarios con un archivo CSV o matriculando manualmente a decenas de personas? La API hace eso en segundos. Es automatización pura. Recuperas tu tiempo para dedicarlo a lo que de verdad importa: crear buenos cursos y acompañar a tus alumnos.

🔹 Porque tu Moodle no vive solo
Tu plataforma de e-learning forma parte de un ecosistema. Seguramente tienes una web (quizás en WooCommerce o Shopify), un CRM (como HubSpot o Salesforce) o un sistema de RRHH. La API hace que todos hablen entre sí. Por ejemplo: cuando RRHH contrata a alguien, Moodle puede crear automáticamente su cuenta y asignarle el curso de bienvenida. Sin que nadie intervenga.

🔹 Para crecer sin morir en el intento
Gestionar 100 usuarios a mano es tedioso; gestionar 10.000 es imposible. La API te da la escalabilidad que necesitas para crecer sin que tu equipo de administración se desborde.

🔹 Porque es segura (si se hace bien)
No estás entregando la llave maestra de tu Moodle. Estás creando una llave de invitado (un token) que solo puede realizar las acciones que tú le permitas. Es controlado, seguro y cada acción queda registrada.

3️⃣ Preparando el terreno: activando la Moodle REST API

Vamos paso a paso. Esto se hace una sola vez, y solo lo puede hacer un administrador.

Paso 1. Activar los servicios web

1. Ve a Administración del sitio → Servidor → Servicios web → Vista general.
2. Activa estas dos casillas ( si no estuvieran ya habilitadas ):
   • ✅ Habilitar servicios web
   • ✅ Habilitar protocolo REST

Paso 2. Crear un usuario dedicado a la API

Esto no es opcional: es una regla de seguridad fundamental.
Nunca uses tu cuenta de administrador (ni ninguna cuenta personal) para realizar llamadas a la Moodle REST API.

En su lugar, crea un usuario exclusivo para este propósito —por ejemplo, api_manager—.
Este usuario actuará como el puente entre Moodle y tus integraciones externas.

De esta manera, si en el futuro detectas una actividad sospechosa o dejas de usar esa integración, bastará con desactivar o eliminar ese usuario para revocar el acceso de inmediato.

Veamos cómo hacerlo paso a paso:

1️⃣ Accede a la administración de usuarios.
Entra en tu Moodle como administrador y ve a:
Administración del sitio → Usuarios → Cuentas → Añadir un nuevo usuario.

2️⃣ Crea un usuario técnico.
En el campo “Nombre de usuario”, escribe algo claro como api_manager.
Para el nombre y los apellidos, puedes usar “API” y “Manager”, o algo similar.
En el correo, usa una dirección interna o genérica (por ejemplo, moodle-api@tu-dominio.com), que te permita rastrear notificaciones.

3️⃣ Selecciona el método de autenticación correcto.
Si tienes habilitada la opción “Web services authentication”, selecciónala.
Así el usuario no podrá iniciar sesión desde la web, solo mediante tokens.
Si no aparece, puedes dejar “Cuentas manuales” y definir una contraseña fuerte.

4️⃣ Establece una contraseña segura.
Genera una contraseña larga y aleatoria (usa un gestor de contraseñas).
Desactiva la opción de enviar notificación al usuario (no la necesita)
y no marques “Forzar cambio de contraseña”, ya que este usuario nunca entrará desde el navegador.

5️⃣ Guarda los cambios.
Haz clic en “Crear usuario”. Moodle te llevará a su perfil, donde podrás ajustar más detalles si lo deseas.

💡 Consejo:
Anota el ID del usuario (id=XX en la URL). Lo necesitarás si más adelante revisas logs o tokens.

En este punto ya tienes creado tu usuario técnico de servicio, totalmente independiente del resto.
Más adelante, a este usuario le asignarás un rol personalizado (por ejemplo, “Integración API”) con permisos mínimos y le generarás un token seguro para acceder a la Moodle REST API.

---

🔐 Da un paso más allá: crea un rol personalizado

Lo ideal es complementar ese usuario con un rol específico para integraciones, por ejemplo, Integración API.
Así podrás controlar con precisión qué acciones puede ejecutar el usuario que usará el token.

Para crear este rol, sigue esta ruta:
👉 Administración del sitio → Usuarios → Permisos → Definir roles → Agregar un nuevo rol

En “Por defecto / Usar rol o arquetipo” Aquí Moodle te pregunta si quieres basar tu nuevo rol en uno existente.

🔹 Selecciona: Usar rol predeterminado → Rol de usuario identificado

Por qué: este rol tiene lo básico para iniciar sesión, sin permisos administrativos. Es el punto de partida más seguro para un usuario técnico o de servicio.

❗ No uses “Administrador” ni “Gestor” como base. Darían acceso total a toda la plataforma.

🧩 Configuración del rol “Integración API” paso a paso

Datos generales del rol

• Nombre corto: integracion_API
• Nombre completo: Integración API
• Descripción:“Rol seguro para integraciones externas mediante la Moodle REST API. Permite crear usuarios, matricularlos y consultar calificaciones sin acceso a configuración ni contenidos.”

Arquetipo

• Selecciona: Usuario identificado Esto garantiza que el rol tenga solo los permisos básicos para iniciar sesión, sin privilegios adicionales.

Tipos de contexto donde puede asignarse

✅ Marca solo:

• Sistema (para integraciones globales)
• Usuario (para crear o consultar usuarios)
• Curso (para matrículas o calificaciones)

🔸 No marques “Categoría”, “Módulo de actividad” ni “Bloque”, ya que no son necesarios para las llamadas REST.

Capacidades que debes permitir

Busca cada una en el filtro superior (“Capacidad”) y márcalas como Permitir:

🔹 Usuarios

• moodle/user:create → Crear usuarios
• moodle/user:viewalldetails → Ver detalles de usuarios
• moodle/user:update → Actualizar usuarios (si tu integración necesita editar datos básicos)
  

🔹 Matrículas

• enrol/manual:enrol → Matricular usuarios
• enrol/manual:unenrol → Desmatricular usuarios
• enrol/manual:manage → (opcional) gestionar matrículas manuales si tu API lo requiere

🔹 Calificaciones

• moodle/grade:viewall → Consultar calificaciones de todos los usuarios
  

🔹 Servicios web

• webservice/rest:use → Usar protocolo REST
• moodle/webservice:createtoken → Crear tokens de servicio web
• moodle/webservice:managealltokens → (opcional, si gestionas tokens desde ese usuario)

Capacidades que debes dejar sin marcar (prohibidas)

⚠️ No marques nunca las siguientes categorías o permisos:

🔸 Administración

• moodle/site:config
• moodle/site:manageblocks
• moodle/role:manage
• moodle/user:delete
• moodle/course:delete
• moodle/backup:downloadfile
• moodle/site:uploadusers

🔸 Seguridad o mantenimiento

• moodle/site:maintenanceaccess
• moodle/site:trustcontent
• moodle/user:loginas
• moodle/site:viewreports
  

🔸 Contenido o edición de cursos

• Todo lo que empiece por mod/ (foros, tareas, cuestionarios, etc.)
• Todo lo que empiece por block/
• Todo lo que empiece por repository/

Esto evita que el usuario API pueda manipular contenido o cursos directamente.

Asigna el rol a tu usuario API

Ve a:
Administración del sitio → Usuarios → Cuentas → Examinar lista de usuarios → api_manager → Entra a su perfil → Asignar roles del sistema → Integración API

🔒 Resultado final

Tu usuario api_manager con el rol Integración API podrá:

• Crear y actualizar usuarios
• Matricular/desmatricular
• Consultar calificaciones
• Ejecutar peticiones REST

Pero no podrá alterar la configuración del sitio, borrar datos, ni acceder a cursos o archivos confidenciales.

💡 ¿Quieres reforzar la seguridad de tu plataforma?
Consulta mi guía: ¡Blindaje Extra para tu Moodle! Guía de Configuración MFA y Consejos de Seguridad Esenciales, donde explicamos cómo proteger el inicio de sesión con autenticación multifactor y buenas prácticas de seguridad.

Paso 3. Generar la llave mágica (el token)

1. Ve a Administración del sitio → Seguridad → Claves de servicio web.
2. Crea una nueva clave.
3. Elige el usuario api_manager.
4. Moodle generará una cadena larga de letras y números, algo así como:
   a9f3b71c93bfca42a2d98f9a31234567

Este es tu tesoro. Guárdalo en un lugar seguro (por ejemplo, un gestor de contraseñas).
Nunca lo pegues en un archivo público ni en el código visible de una web.
Y recuerda: usa siempre HTTPS para evitar que alguien pueda interceptarlo.

4️⃣ Anatomía de una petición: cómo hablar con Moodle a través de su REST API

Todas las peticiones se envían a la misma dirección (endpoint):
https://tu-moodle.dominio.com/webservice/rest/server.php

Cada llamada debe incluir tres datos básicos:

1. wstoken: tu llave mágica (el token).
2. wsfunction: la función que quieres ejecutar (por ejemplo, core_user_create_users).
3. moodlewsrestformat: el formato de respuesta, normalmente json.

Importante: las peticiones REST de Moodle no usan JSON en el cuerpo.
Debes enviar los parámetros como datos de formulario (tipo application/x-www-form-urlencoded).

A partir de ahí, solo necesitas pasar los “ingredientes” de la acción: si creas un usuario, su nombre, contraseña, correo, etc.

Cuando empieces a orquestar varios procesos, combina tus llamadas REST con tareas programadas siguiendo Automatización Avanzada en Moodle: Cron Jobs, Scripts PHP y el Poder de las Tareas Programadas .

5️⃣ ¡Hagamos magia! Ejemplo 1: Crear un usuario

Vamos a crear a “Juan Pérez” sin tocar la interfaz de Moodle. Puedes hacerlo desde la terminal o con un pequeño script.

Usando curl

curl -X POST \
-d "wstoken=a9f3b71c93bfca42a2d98f9a31234567" \
-d "wsfunction=core_user_create_users" \
-d "moodlewsrestformat=json" \
-d "users[0][username]=juan.perez" \
-d "users[0][password]=Jp@12345" \
-d "users[0][firstname]=Juan" \
-d "users[0][lastname]=Pérez" \
-d "users[0][email]=juan.perez@ejemplo.com" \
https://tu-moodle.dominio.com/webservice/rest/server.php

curl -X POST \
-d "wstoken=a9f3b71c93bfca42a2d98f9a31234567" \
-d "wsfunction=core_user_create_users" \
-d "moodlewsrestformat=json" \
-d "users[0][username]=juan.perez" \
-d "users[0][password]=Jp@12345" \
-d "users[0][firstname]=Juan" \
-d "users[0][lastname]=Pérez" \
-d "users[0][email]=juan.perez@ejemplo.com" \
https://tu-moodle.dominio.com/webservice/rest/server.php

Moodle responderá algo como: [{"id":45}].
Eso significa que el usuario se ha creado correctamente con el ID 45.

💡 Nota de seguridad: No uses contraseñas simples en tus scripts.
Define políticas de contraseñas seguras en Moodle y, si creas usuarios automáticamente, genera contraseñas temporales o exige cambio en el primer acceso.

Usando Python

import requests

url = "https://tu-moodle.dominio.com/webservice/rest/server.php"
params = {
    "wstoken": "a9f3b71c93bfca42a2d98f9a31234567",
    "wsfunction": "core_user_create_users",
    "moodlewsrestformat": "json"
}
data = {
    "users[0][username]": "juan.perez",
    "users[0][password]": "Jp@12345",
    "users[0][firstname]": "Juan",
    "users[0][lastname]": "Pérez",
    "users[0][email]": "juan.perez@ejemplo.com"
}

response = requests.post(url, params=params, data=data)
print(response.json())

import requests

url = "https://tu-moodle.dominio.com/webservice/rest/server.php"
params = {
    "wstoken": "a9f3b71c93bfca42a2d98f9a31234567",
    "wsfunction": "core_user_create_users",
    "moodlewsrestformat": "json"
}
data = {
    "users[0][username]": "juan.perez",
    "users[0][password]": "Jp@12345",
    "users[0][firstname]": "Juan",
    "users[0][lastname]": "Pérez",
    "users[0][email]": "juan.perez@ejemplo.com"
}

response = requests.post(url, params=params, data=data)
print(response.json())

Y listo: ya has creado un usuario automáticamente. Imagina hacerlo para cientos o miles de alumnos sin subir archivos ni perder tiempo.

6️⃣ Ejemplo 2: Matricular a Juan en un curso

Supongamos que Juan (ID 45) debe ser inscrito en el curso con ID 3.

curl -X POST \
-d "wstoken=a9f3b71c93bfca42a2d98f9a31234567" \
-d "wsfunction=enrol_manual_enrol_users" \
-d "moodlewsrestformat=json" \
-d "enrolments[0][roleid]=5" \
-d "enrolments[0][userid]=45" \
-d "enrolments[0][courseid]=3" \
https://tu-moodle.dominio.com/webservice/rest/server.php

curl -X POST \
-d "wstoken=a9f3b71c93bfca42a2d98f9a31234567" \
-d "wsfunction=enrol_manual_enrol_users" \
-d "moodlewsrestformat=json" \
-d "enrolments[0][roleid]=5" \
-d "enrolments[0][userid]=45" \
-d "enrolments[0][courseid]=3" \
https://tu-moodle.dominio.com/webservice/rest/server.php

ℹ️ Importante: El roleid=5 corresponde normalmente al rol de estudiante, pero puede variar según tu instalación.
Para comprobarlo, entra a cualquier curso en Moodle, edita una matrícula manual y observa el número del rol en la URL o usa el servicio core_role_get_roles.

Para flujos más complejos (altas, matrículas y avisos), aquí te explico cómo programarlo: Automatización Avanzada en Moodle: Cron Jobs, Scripts PHP y el Poder de las Tareas Programadas.

7️⃣ Ejemplo 3: Obtener las notas para tu informe

¿Cansado de exportar el libro de calificaciones?
Con la función gradereport_user_get_grade_items, puedes obtener las calificaciones de un alumno (o de todos) de forma automatizada.

Solo tienes que hacer una llamada similar, indicando el userid. Moodle devolverá los datos en formato JSON, listos para integrarse con Power BI o Google Data Studio.
Así podrás generar informes en tiempo real sin depender de exportaciones manuales.

8️⃣ El caso estrella: tu tienda online (WooCommerce o Shopify)

Este es uno de los escenarios más potentes.

El escenario antiguo:
Alguien te compra un curso a las 3 de la madrugada. Tú te despiertas, lees el correo, entras en Moodle, creas el usuario, lo matriculas y le envías sus credenciales. El alumno ha tenido que esperar.

El escenario moderno con la API:

1. El alumno compra un curso.
2. Tu tienda (WooCommerce, por ejemplo) notifica al servidor.
3. Un script usa la API REST para crear el usuario y matricularlo.
4. El alumno recibe acceso inmediato.

El resultado: un cliente feliz que empieza su curso de inmediato, y tú… sigues durmiendo.

¿Quieres validar automáticamente el acceso de usuarios tras la compra? Mira este enfoque con Automatización Robótica de Procesos (RPA): Verificación del Login en Moodle con Python y Selenium.

9️⃣ Seguridad y buenas prácticas con la Moodle REST API

Usar la API implica responsabilidad. Manejas datos personales y accesos, así que es vital hacerlo bien:

• 🔒 Usa siempre HTTPS. Sin cifrado, cualquiera podría interceptar tus tokens.
• 👤 Usa un usuario dedicado con rol limitado. No des permisos de administrador.
• 🧩 Crea un rol personalizado con los permisos mínimos que necesite tu integración.
• 🔑 Protege tu token. Guárdalo en un entorno seguro, nunca en un archivo público o repositorio.
• 🧱 Habilita solo las funciones necesarias. No abras todas las funciones “por si acaso”.
• 🕒 Revoca tokens que ya no uses. Si un proyecto termina o cambias de sistema, elimina su acceso.

💡 Consejo adicional: Moodle también ofrece OAuth 2 como método de autenticación moderno y más seguro.
Puedes usarlo si tu sistema externo soporta este estándar.

Y no olvides fortalecer el inicio de sesión con MFA: ¡Blindaje Extra para tu Moodle! Guía de Configuración MFA y Consejos de Seguridad Esenciales.

Errores frecuentes (y cómo salir del lío)

Aunque la API de Moodle es bastante amigable, tarde o temprano te vas a topar con mensajes que no dicen demasiado o que parecen sacados de otra dimensión. No pasa nada: aquí te dejo varios tropiezos habituales y cómo solucionarlos sin perder la cabeza.

❌ 1) “capability denied”

Este es el clásico. Quieres crear un usuario, matricular o hacer algo “simple”, y Moodle te mira mal.

Qué está pasando:
El usuario al que le has dado el token no tiene permiso para hacer esa acción.

Qué hacer:

1. Comprueba qué rol tiene ese usuario.
2. Edita ese rol en Administración → Usuarios → Permisos → Definir roles.
3. Activa las capacidades necesarias (por ejemplo: moodle/user:create, enrol/manual:enrol).
4. Guarda y prueba otra vez.

✅ Ojo aquí:
No basta con crear un rol; asegúrate de asignarlo al usuario en el contexto correcto (sistema, categorías, cursos…).

❌ 2) “Invalid token”

Este también es recurrente.

Qué está pasando:
El token no es válido: se copió mal, pertenece a un usuario inactivo o directamente se ha eliminado.

Qué hacer:

• Comprueba que el token sea el correcto.
• Verifica que el usuario sigue activo.
• Si todo está bien, genera un token nuevo y vuelve a probar.

❌ 3) “Access control exception”

Otro mensaje críptico.

Qué está pasando:
La función que estás intentando usar no está habilitada dentro del servicio web.

Qué hacer:

• Ve a Administración → Servicios Web → Servicios externos.
• Abre el servicio que estés usando.
• Añade esa función a la lista de permitidas.

❌ 4) Parámetros raros o respuestas vacías

A veces la API ni siquiera protesta, simplemente responde en blanco o hace como que no te ha escuchado.

Qué está pasando:
Los parámetros llegaron mal: nombre incorrecto, estructura equivocada, JSON roto…

Qué hacer:

• Revisa la documentación de la función.
• Asegúrate de que los nombres de los parámetros sean EXACTOS.
• Valida el JSON antes de enviarlo.

Cómo depurar sin sufrir

• Activa el modo DEBUG
  En Administración → Desarrollo → Depuración
  Selecciona Desarrollador para ver más detalles.
• Revisa los logs
  Te ayudarán a ver qué está pasando “por dentro”.
• Prueba primero con cURL o Postman
  Así descartas si el problema está en tu script o si viene directamente de Moodle.

⚙️ Trucos y consejos pro para exprimir la API

🧠 Usa scripts programados.
Configura tareas automáticas con cron (Linux) o el programador de tu sistema para ejecutar acciones de forma regular.

📡 Centraliza las integraciones.
Si usas varios sistemas, crea un pequeño servicio intermedio (middleware) que gestione todas las llamadas a Moodle, registrando errores y controlando accesos.

🧩 Documenta tus integraciones.
Anota qué tokens usas, qué funciones REST están activas y quién las mantiene.

🧰 Consulta la documentación viva de tu Moodle.
Visita /admin/webservice/documentation.php en tu sitio para ver todas las funciones disponibles y ejemplos de uso.

🚀 Más allá del código: una mentalidad de automatización

Dominar la API REST no es solo aprender a hacer llamadas o escribir scripts: es adoptar una mentalidad de automatización.

Cada vez que te encuentres repitiendo una tarea en Moodle, pregúntate:

“¿Podría esto hacerlo Moodle solo?”

La mayoría de las veces, la respuesta será sí.
Empiezas automatizando usuarios, luego cursos, después reportes… y cuando menos te das cuenta, Moodle se autogestiona.

Automatizar no es deshumanizar. Es liberar tiempo para centrarte en lo que de verdad importa: enseñar, innovar y acompañar a tus alumnos.

✨ Recursos útiles

• Documentación oficial de Moodle sobre servicios web (en español)
• Referencia técnica de la API REST en tu Moodle (/admin/webservice/documentation.php)
• Tester de API en línea (ReqBin)
• Foro de desarrolladores de Moodle
• Guía de autenticación OAuth 2 en Moodle
  
  ¿Aún sin entorno? Empieza aquí: Instala Moodle en tu VPS Ubuntu: Guía Paso a Paso para No Expertos.

✅ Conclusión: Tu Moodle, pero con superpoderes

La API REST de Moodle no es una caja negra para programadores: es una puerta abierta a la eficiencia.
Transforma Moodle de una plataforma aislada en un sistema conectado, capaz de trabajar de forma automática con tus herramientas y liberar tu tiempo para lo que realmente importa: enseñar, innovar y acompañar a tus alumnos.

Empieza con algo pequeño: una llamada curl, un usuario de prueba, una inscripción automática.
Cuando veas que todo funciona “por arte de magia”, entenderás su verdadero potencial.

El futuro del e-learning no está en trabajar más horas, sino en automatizar mejor.
Y la API REST de Moodle es tu mejor aliada para conseguirlo. Y la API REST de Moodle es tu mejor aliada para conseguirlo.