Saltar al contenido principal

Integración con LMS - Automatización por API

  • Actualización

Este artículo explica cómo automatizar por API las dos operaciones que requiere la Integración con LMS: vincular a los usuarios de SMARTFENSE con su usuario del LMS, y obtener el paquete SCORM de una campaña.

Qué se puede automatizar

La puesta en marcha de la integración tiene dos operaciones, y cada una puede hacerse desde la plataforma o por API. Ambos caminos conviven: la API es un canal adicional, no un reemplazo.

  • Vinculación de usuarios: desde la plataforma se carga un archivo CSV; por API se envían los usuarios con su ID del LMS.
  • Paquete SCORM: desde la plataforma se descarga con el botón del Calendario; por API se solicita y la plataforma devuelve un enlace de descarga.

Automatizar estas operaciones es útil cuando la organización da de alta usuarios con frecuencia, o cuando gestiona varios contenidos y no quiere descargar y subir cada paquete a mano.

Si busca los pasos manuales, consulte Integración con LMS - Vinculación de usuarios e Integración con LMS - Configuración de campañas.

Antes de empezar

Las dos operaciones requieren que su organización tenga contratado el componente de Integración con LMS y que la instancia esté activa y vigente.

Además, necesita una aplicación registrada en Configuración > Integraciones > API. El procedimiento completo de registro está en Integración de APIs en SMARTFENSE.

Al registrar la aplicación, seleccione únicamente los alcances que va a usar:

  • Vincular usuarios con un LMS externo, para la vinculación.
  • Descargar paquetes SCORM de integración LMS, para el paquete.

Son alcances separados a propósito: una integración que solo carga usuarios no necesita poder descargar contenido, y una que solo descarga paquetes no necesita poder modificar el padrón.

Vincular usuarios con el LMS

Establece o actualiza el ID que cada usuario tiene en el LMS externo, identificándolo por su dirección de correo electrónico en SMARTFENSE.

 
POST /api/v1/users/lms-id

El cuerpo de la solicitud lleva la lista de usuarios a vincular:

 
json
{
  "users": [
    { "email": "ana.perez@ejemplo.com", "lms_id": "aperez" },
    { "email": "juan.gomez@ejemplo.com", "lms_id": "jgomez" }
  ]
}

Reglas de la solicitud

  • Se admiten hasta 200 usuarios por solicitud.
  • El ID del LMS admite hasta 250 caracteres. Enviarlo vacío desvincula al usuario.
  • El ID del LMS no puede comenzar con los caracteres =, +, @, coma, punto y coma o guion, ni contener < o >. La plataforma rechaza esos valores en lugar de alterarlos, porque modificarlos rompería la correspondencia con el LMS.
  • Si una misma solicitud repite un correo o un ID del LMS, se rechazan todas las apariciones repetidas, no solo la segunda.

Respuesta

Los usuarios se procesan de forma independiente: uno que falla no revierte los que ya se aplicaron, igual que en la importación por CSV. La respuesta separa los dos grupos:

 
json
{
  "processed": [
    { "email": "ana.perez@ejemplo.com", "lms_id": "aperez" }
  ],
  "errors": [
    { "email": "no.existe@ejemplo.com", "error_code": "...", "error": "..." }
  ],
  "details": { "total_processed": 1, "total_errors": 1 }
}

Cada elemento de errors indica el motivo: que el correo no corresponde a ningún usuario de la organización, o que el correo o el ID venían repetidos en la solicitud.

La operación queda registrada en la auditoría de administración, con el total de usuarios actualizados y el detalle por usuario.

Obtener el paquete SCORM de una campaña

Devuelve el mismo paquete que produce el botón de descarga del Calendario, para cargarlo en el LMS sin pasos manuales.

 
GET /api/v1/campaigns/{tipo_de_campaña}/{id_de_campaña}/scorm-package

Los tipos de campaña válidos son training (Módulos Interactivos), video, videogame y exam.

La campaña tiene que estar configurada con la opción Integrar esta campaña con un LMS. Si no lo está, la respuesta es la misma que si la campaña no existiera.

Respuesta

 
json
{
  "file_url": "https://...",
  "file_name": "lms-integration-....zip",
  "expires_in": 14400
}

El enlace de descarga es temporal: expires_in informa en segundos cuánto tiempo sigue siendo válido. Descargue el archivo dentro de esa ventana; pasada, hay que volver a pedir el paquete.

💡 Mejores prácticas

  • Verificar que los usuarios existan en ambas plataformas antes de vincularlos: la API resuelve al usuario por su correo y devuelve un error si no lo encuentra.
  • Enviar los usuarios en lotes de hasta 200 y revisar el bloque errors de cada respuesta antes de dar por terminada la carga.
  • Usar el identificador que pide su LMS. En Moodle, por ejemplo, corresponde al campo username del usuario.
  • Solicitar el paquete SCORM en el momento de cargarlo en el LMS, y no con anticipación, ya que el enlace vence.
  • Registrar una aplicación por integración, con los alcances mínimos que esa integración necesita.

Artículos relacionados