Documentación de la app

Integración con Zoom en EduShield

Guía oficial para que docentes, estudiantes y equipos de revisión agreguen, usen y eliminen la app de Zoom dentro de EduShield. Todo el flujo está construido sobre OAuth 2.0 — nunca pedimos tu contraseña.

Última actualización: 30 de abril, 2026 OAuth 2.0 · Tokens cifrados (AES-GCM) Apto para revisión del Zoom Marketplace

01

Resumen general

EduShield es una plataforma educativa que ayuda a docentes a planificar y dictar clases. La integración con Zoompermite que un docente conecte su propia cuenta de Zoom y, desde EduShield, programe, comparta y administre clases en vivo de Zoom sin salir de la pestaña de su curso.

Para los estudiantes, esto significa que el enlace de la clase aparece automáticamente dentro del curso, junto con su título, hora y duración. Mientras la sesión está en curso, EduShield puede además reflejar el audio, la transcripción en vivo y el chat de la reunión dentro del curso. Y al finalizar, si la cuenta del docente tiene Cloud Recording, los enlaces a la grabación, transcripción y chat aparecen en la misma tarjeta.

Programar reuniones

Crear, reagendar o cancelar la reunión Zoom asociada a la clase del curso.

Audio, transcript y chat en vivo

Reflejar audio, transcripción y chat en tiempo real de la clase Zoom dentro del curso.

Sin contraseñas

Solo OAuth 2.0. Los tokens se cifran en reposo con AES-GCM y nunca llegan al navegador.

Permisos (scopes) que solicita la app

EduShield usa el modelo de scopes granulares de Zoom. Cada permiso habilita una acción puntual y nada más. Los once scopes listados abajo son los únicos que la app pide durante el consentimiento OAuth, divididos en tres categorías: Meeting, Cloud Recording y User.

CategoríaScopeDescripción ZoomPara qué lo usa EduShield
Useruser:read:userView a userIdentificar al usuario Zoom conectado y mostrar la cuenta vinculada en el perfil.
Meetingmeeting:write:meetingCreate a meeting for a userCrear la reunión Zoom asociada a cada clase en vivo del curso.
Meetingmeeting:read:meetingView a meetingMostrar el meeting ID, join URL, título, fecha y hora dentro del curso.
Meetingmeeting:update:meetingUpdate a meetingReagendar la clase (fecha, hora, duración) sin cambiar el join link.
Meetingmeeting:delete:meetingDelete a meetingEliminar la reunión Zoom cuando el docente cancela la clase en EduShield.
Meetingmeeting:read:meeting_audioGet all real-time audio streams of a user's meetingsAcceder al audio en tiempo real de la clase en vivo para asistencia y soporte de la sesión.
Meetingmeeting:read:meeting_transcriptGet all real-time audio transcripts of a user's meetingsMostrar la transcripción en tiempo real de la clase en vivo a docente y estudiantes inscritos.
Meetingmeeting:read:meeting_chatGet all real-time meeting chats in a user's meetingsMostrar el chat en tiempo real de la clase para que quede registrado dentro del curso.
Cloud Recordingcloud_recording:read:list_user_recordingsLists all cloud recordings for a userListar las grabaciones cloud del docente para mostrarlas en su perfil.
Cloud Recordingcloud_recording:read:list_recording_filesReturns all of a meeting's recordingsListar los archivos individuales (mp4, m4a, transcripción .vtt, chat .txt) de una grabación.
Cloud Recordingcloud_recording:read:recordingView a recordingObtener el play URL y el download URL de una grabación específica para mostrarlos en la tarjeta de la clase finalizada.

EduShield nunca solicita permisos sobre reuniones de otros usuarios que no haya creado el docente conectado, ni accede a webinarios, suscripciones, facturación, contactos, o llamadas Zoom Phone.

Webhooks que EduShield recibe de Zoom

EventoPara qué lo usa EduShield
endpoint.url_validationHandshake inicial cuando registramos la URL del webhook en el Marketplace. Devolvemos el HMAC-SHA256 del plainToken firmado con el Secret Token.
recording.completedNotificación de que una grabación cloud terminó de procesarse. EduShield marca la clase como “grabación lista” en su base de datos para que aparezca automáticamente dentro del curso. No persistimos URLs ni archivos.
app_deauthorizedEl usuario revocó la app desde el Zoom Marketplace. EduShield purga inmediatamente los tokens cifrados, el Zoom user ID, el correo Zoom y el scope concedido.

Todas las requests entrantes de Zoom se validan contra el header x-zm-signature usando el Secret Token de la app con HMAC-SHA256, y rechazamos eventos con timestamp fuera de una ventana de 5 minutos para impedir replays.

02

Cómo agregar la app

La integración se conecta una sola vez por docente. EduShield expone dos puntos de entrada equivalentes para iniciar el flujo OAuth (cualquiera de los dos lleva a la misma pantalla oficial de Zoom). Si algo no funciona en cualquier paso, consultá la guía de solución de problemas más abajo.

Opción A — Desde tu perfil

  1. 1
    Iniciá sesión en EduShield con tu cuenta de docente. Si todavía no tenés cuenta, creala desde Iniciar sesión o pedí una invitación a tu coordinador.
  2. 2
    Andá a tu Perfil (avatar arriba a la derecha → Mi perfil) o abrí /profile/me. Bajá hasta la tarjeta Integraciones de clases en vivo.
  3. 3
    En la fila de Zoom, hacé clic en Conectar Zoom. EduShield te llevará a la pantalla oficial de autorización OAuth de Zoom.
  4. 4
    Iniciá sesión en Zoom con la cuenta que querés vincular y revisá la lista de permisos solicitados. Hacé clic en Allow.
  5. 5
    Zoom redirige de vuelta a EduShield. Verás un mensaje verde de confirmación y, en la tarjeta de Zoom, aparecerá tu correo Zoom con la etiqueta Conectado.

Opción B — Desde el panel de Clases en vivo

Si ya estás programando una clase, no hace falta salir del flujo: el propio panel de Clases en vivo te ofrece conectar Zoom en línea.

  1. 1
    Ingresá como docente y abrí /teacher/live-sessions (menú lateral → Clases en vivo).
  2. 2
    Si todavía no conectaste Zoom, vas a ver el aviso “¿Aún no conectaste Google Meet o Zoom? Conectá tu cuenta →” en la parte superior, y un botón Conectar → dentro de la tarjeta de Zoom al programar la sesión.
  3. 3
    Hacé clic en Conectar →. EduShield te lleva al mismo flujo OAuth oficial de Zoom y, al volver, queda listo para usarse desde el modal de programación.
¿Algo falló durante la autorización?Revisá la sección Solución de problemas más abajo o escribinos desde la página de contacto.

03

Uso de la app

Una vez conectada Zoom, cada acción en EduShield se traduce a una llamada concreta a la API de Zoom usando el token cifrado del docente. A continuación describimos cada función con su caso de uso, prerequisitos y scope que la habilita.

3.1 Confirmar la cuenta conectada

Caso de uso: mostrar al docente con qué cuenta de Zoom quedó vinculado EduShield, para evitar enredos cuando alguien tiene varias cuentas Zoom (personal vs. institucional).

Prerequisitos: haber completado los pasos del apartado 02.

Dónde: Perfil → Integraciones de clases en vivo → tarjeta Zoom.

API que llamamos: GET /v2/users/me. Scope: user:read:user.

3.2 Crear o programar una clase en vivo

Caso de uso: el docente programa una clase del curso (por ejemplo, “Repaso final — capítulo 3”) y EduShield genera automáticamente la reunión Zoom con su enlace de unión, configurando además sala de espera, silenciar al entrar y grabación a la nube.

Prerequisitos:

  • Tener Zoom conectado.
  • Ser docente, co-docente o creador del curso.
  • El curso tiene que existir y estar ACTIVE.

Pasos:

  1. 1
    Abrí el curso en /courses/[id].
  2. 2
    Seleccioná la pestaña Clases en vivo.
  3. 3
    Hacé clic en Programar clase.
  4. 4
    Llená título, fecha, hora, duración y asegurate de que el proveedor esté en Zoom.
  5. 5
    Hacé clic en Guardar.

API que llamamos: POST /v2/users/me/meetings. Scope: meeting:write:meeting.

3.3 Ver la información de la clase

Caso de uso: docentes y estudiantes inscritos ven el join URL, meeting ID, título, fecha y hora directamente en la tarjeta de la clase, sin tener que pasar por su correo o por zoom.us.

Prerequisitos: existir la clase en EduShield, estar inscrito en el curso (o ser su docente).

Dónde: Curso → Clases en vivo → tarjeta de la sesión.

API que llamamos: GET /v2/meetings/{id}. Scope: meeting:read:meeting.

3.4 Reagendar una clase ya creada

Caso de uso: el docente cambia la fecha o duración de una clase existente. EduShield mantiene la misma reunión Zoom (mismo link), solo actualiza la hora.

Prerequisitos: ser el docente de esa clase y que aún esté programada (no eliminada).

API que llamamos: PATCH /v2/meetings/{id}. Scope: meeting:update:meeting.

3.5 Cancelar o eliminar una clase

Caso de uso: el docente cancela una clase que no se va a dictar. EduShield la elimina de la pestaña y, en paralelo, borra la reunión Zoom asociada para que el join link deje de funcionar.

Prerequisitos: ser el docente de la clase.

Dónde: Curso → Clases en vivo → ícono de papelera o botón Eliminar.

API que llamamos: DELETE /v2/meetings/{id}. Scope: meeting:delete:meeting.

3.6 Audio en tiempo real de la clase

Caso de uso: mientras la clase está en curso, EduShield se suscribe al stream de audio en vivo del docente para alimentar herramientas internas de asistencia (detección de inicio/cierre real de la sesión, indicadores de actividad y soporte a estudiantes con baja conectividad).

Prerequisitos: la clase tiene que estar en curso y el docente conectado a Zoom desde la sala que generó EduShield.

Scope: meeting:read:meeting_audio (Get all real-time audio streams of a user's meetings).

3.7 Transcripción en tiempo real de la clase

Caso de uso: mostrar a docente y estudiantes inscritos la transcripción en vivo que genera Zoom durante la sesión, para mejorar accesibilidad (estudiantes con dificultades auditivas o con audio cortado) y dejar un registro textual dentro del curso.

Prerequisitos:

  • La clase tiene que estar en curso.
  • La cuenta Zoom del docente tiene que tener habilitada la transcripción automática (Audio Transcript / Live Transcription).

Scope: meeting:read:meeting_transcript (Get all real-time audio transcripts of a user's meetings).

3.8 Chat en tiempo real de la clase

Caso de uso: reflejar el chat de la sesión Zoom dentro del curso para que los mensajes (preguntas, links, materiales) queden registrados y disponibles para los estudiantes que se conecten desde EduShield sin abrir el chat de Zoom.

Prerequisitos: la clase tiene que estar en curso y el chat de la reunión debe estar habilitado por el docente.

Scope: meeting:read:meeting_chat (Get all real-time meeting chats in a user's meetings).

3.9 Acceder a la grabación cloud después de la clase

Caso de uso: al finalizar la clase, EduShield consulta la API de grabaciones de Zoom y muestra dentro de la tarjeta del curso los enlaces oficiales Play y Download de la grabación cloud (video, audio, transcripción y chat). El docente y los estudiantes inscritos pueden abrir la grabación sin tener que entrar a zoom.us.

Prerequisitos:

  • La clase debe haber terminado y Zoom haber procesado los archivos (suele tardar entre 5 y 30 minutos según el largo).
  • La cuenta Zoom del docente debe tener Cloud Recording habilitado. Esto requiere un plan Pro, Business o Enterprise — los planes Free no permiten subir grabaciones a la nube. Si tu plan no lo permite, te recomendamos consultar con la institución a la que pertenecés para ver si pueden migrarte a un plan superior.
  • La opción de grabación automática a la nube tiene que estar activa al inicio de la sesión (EduShield la activa por defecto al crear cada reunión).

Pasos para el docente:

  1. 1
    Abrí el curso en /courses/[id] → pestaña Clases en vivo.
  2. 2
    Buscá la tarjeta de la clase finalizada y hacé clic en Ver grabación.
  3. 3
    EduShield consulta los archivos disponibles y los muestra con los botones Play y Download.

API que llamamos: GET /v2/meetings/{id}/recordings. Scopes: cloud_recording:read:recording, cloud_recording:read:list_recording_files, cloud_recording:read:list_user_recordings.

Webhook que escuchamos: recording.completed. Apenas Zoom termina de procesar la grabación cloud, EduShield recibe el evento y marca la clase con recordingReadyAt, de modo que la grabación aparece automáticamente dentro del curso sin que el docente tenga que recargar nada.

¿Tus estudiantes ven la pantalla "[tu nombre] shared a recording with you" al darle Reproducir?

Esa página intermedia la muestra Zoom, no EduShield. Si querés que el video se reproduzca directo, abrí zoom.us/profile/setting · Recording y desactivá las opciones “Require users to authenticate before viewing cloud recordings”, “Viewers must enter their name and email address before watching” y “On-demand viewers must register”. El ajuste vale para todas tus grabaciones futuras y para las ya existentes que aún no compartiste.

Los flujos de audio, transcripción y chat en vivo (3.6 a 3.8) no se almacenan ni se retienen después del fin de la clase. Las URLs de la grabación cloud (3.9) tampoco se guardan en EduShield: se solicitan en tiempo real al abrir la tarjeta de la clase, contra la API oficial de Zoom. Cuando el docente desconecta Zoom, todos esos accesos dejan inmediatamente de funcionar desde EduShield.

04

Cómo eliminar la app

EduShield ofrece dos rutas equivalentes para desinstalar la app: una desde el propio EduShield y otra desde el Zoom App Marketplace. Cualquiera de las dos invalida los tokens.

A. Desde EduShield (recomendado)

  1. 1
    Andá a Mi perfil → Integraciones de clases en vivo.
  2. 2
    En la tarjeta de Zoom, hacé clic en Desconectar.
  3. 3
    Confirmá la acción en el cuadro de diálogo.

EduShield llama a POST https://zoom.us/oauth/revoke con el refresh token y luego elimina el registro UserIntegration correspondiente.

B. Desde el Zoom App Marketplace

  1. 1
    Iniciá sesión en marketplace.zoom.us.
  2. 2
    Abrí Manage → Added Apps.
  3. 3
    Buscá EduShield y hacé clic en Remove.

Zoom enviará una notificación de des-autorización a EduShield, que marcará automáticamente la integración como revocada y borrará los tokens de la base de datos.

Implicaciones de la des-autorización

  • EduShield deja inmediatamente de poder crear, modificar o eliminar reuniones de Zoom en tu cuenta.
  • Las clases en vivo ya creadas siguen funcionando dentro de Zoom (los join URLs ya entregados a los estudiantes son válidos), pero no podrás reagendar ni eliminarlas desde EduShield.
  • Los streams de audio, transcripción y chat en vivo, y las URLs a las grabaciones cloud, dejan de poder consultarse desde EduShield. La información sigue viviendo en tu cuenta Zoom y se administra desde zoom.us (las grabaciones específicamente desde zoom.us/recording).
  • Para volver a usar la integración hay que repetir los pasos del apartado 02.

Cómo eliminamos tus datos al desconectar

Apenas se desconecta la app — ya sea desde EduShield o desde el Zoom Marketplace — ejecutamos en el mismo momento las siguientes acciones, sin requerir intervención manual:

  • Revocación del token: llamamos a POST https://zoom.us/oauth/revoke con el refresh token para invalidarlo del lado de Zoom.
  • Borrado de credenciales: eliminamos el registro UserIntegration del docente, lo que purga el access token cifrado, el refresh token cifrado, el scope concedido y los timestamps asociados.
  • Borrado del identificador Zoom: el Zoom user ID y el correo Zoom vinculado se eliminan junto con el registro de integración.
  • IDs de reuniones creadas: los IDs de reuniones que EduShield había guardado para reagendarlas o eliminarlas desde la plataforma se eliminan al borrar la cuenta de EduShield desde Eliminar mis datos. La desconexión sola no borra esos IDs porque se siguen necesitando para mostrar las clases pasadas dentro del curso.
  • Webhook app_deauthorized: si la baja se origina en Zoom, recibimos el evento oficial y aplicamos el mismo borrado de tokens/identificadores de manera automática, conforme a los requisitos del Marketplace.

Para el detalle completo de qué guardamos y qué nunca guardamos, ver la sección 05 — Datos almacenados y eliminación.

Requisitos específicos para desinstalar

  • Si desconectás desde EduShield, tenés que estar autenticado con la misma cuenta de docente que conectó la integración.
  • Si desconectás desde el Zoom Marketplace, tenés que estar autenticado con la cuenta Zoom que aprobó originalmente la app.
  • No hace falta contactar al equipo de soporte de EduShield para desinstalar: ambas rutas son self-service y se completan en menos de un minuto.
  • La des-autorización no exige cancelar tu cuenta de EduShield. Podés volver a conectar Zoom (o conectar otra cuenta Zoom) cuando quieras.

05

Datos almacenados y eliminación

Qué guardamos

  • Tokens OAuth (access + refresh) — cifrados con AES-GCM antes de tocar disco. Solo el servidor los descifra al momento de hacer una llamada a la API de Zoom.
  • Identificador y email Zoom del docente, para poder mostrar “Conectado como X”.
  • Scope concedido, fecha de conexión, fecha de último uso y fecha de expiración del access token.
  • ID de cada reunión Zoom creada por EduShield (para poder reagendarla, eliminarla y mostrarla dentro del curso).

Qué NO guardamos

  • El contenido del audio en vivo, las transcripciones en vivo o los mensajes de chat de la reunión. Esos streams se reflejan dentro del curso en tiempo real mientras la clase está en curso, pero EduShield no los persiste en su base de datos al finalizar la sesión (salvo que el docente los guarde manualmente como material del curso).
  • El video, audio o transcripción de las grabaciones cloud. Esos archivos siguen viviendo en tu cuenta Zoom; EduShield solo solicita los enlaces oficiales de Play y Download en el momento en que el usuario abre la tarjeta de la clase.
  • La contraseña de tu cuenta Zoom (no la pedimos nunca).
  • Datos de tus contactos, calendario, webinarios o llamadas Phone — no pedimos esos scopes.

Cómo se eliminan tus datos

  • Al desconectar (sección 04), borramos inmediatamente todos los tokens y el registro de integración.
  • Si eliminás tu cuenta de EduShield desde Eliminar mis datos, además se borran los IDs de las reuniones que habíamos guardado.
  • Cuando Zoom envía un evento app deauthorized, EduShield acepta el webhook y purga la integración automáticamente.

06

Solución de problemas

Hago clic en “Conectar Zoom” pero no pasa nada.

Probablemente tu navegador está bloqueando ventanas o cookies de terceros. Permití cookies para zoom.us y volvé a intentarlo. Si usás un perfil empresarial, pedile a tu admin que apruebe la app desde el Marketplace.

Veo el error “Token expirado” en la tarjeta de Zoom.

El refresh token de Zoom caduca por inactividad (~90 días). Hacé clic en Reautorizar en la tarjeta y completá el OAuth de nuevo. No perdés ninguna clase ya creada.

Creo una clase y EduShield dice “Zoom no devolvió join_url”.

Eso suele ocurrir cuando la cuenta Zoom no tiene permiso para crear reuniones (cuentas con licencia bloqueada por el admin). Pedile a tu admin de Zoom que habilite el rol “Schedule meetings” para tu usuario, o conectá una cuenta personal Pro.

No veo el audio, transcript o chat en vivo dentro del curso.

Esos flujos requieren que la clase esté en curso y que el docente esté conectado a la reunión Zoom desde la sala que generó EduShield. Para la transcripción en vivo, además, la cuenta del docente tiene que tener habilitada la opción Audio Transcript / Live Transcription en su perfil de Zoom.

La clase ya terminó pero no veo la grabación cloud.

Verificá tres cosas: (1) que tu cuenta Zoom tenga Cloud Recording activo (planes Pro o superiores; los planes Free no permiten subir grabaciones a la nube — si tu plan no lo permite, consultá con tu institución si pueden migrarte a un plan superior); (2) que la grabación automática a la nube haya estado activa al inicio de la sesión; (3) que hayan pasado 5–30 minutos desde el final, ya que Zoom procesa el video, audio y transcripción de forma asíncrona. Si pasaron 30+ minutos y siguen sin aparecer, abrí zoom.us/recording para ver el estado.

La tarjeta de Zoom dice "Reautorizá para ver grabaciones".

Eso aparece cuando tu integración fue creada antes de que EduShield añadiera los scopes de Cloud Recording. Hacé clic en Reautorizar en la tarjeta y completá el OAuth de nuevo: vas a ver una lista de permisos un poco más larga (incluye los tres cloud_recording:read:*). No perdés ninguna clase ya creada y, una vez reautorizado, las grabaciones aparecen automáticamente en las tarjetas de las clases finalizadas.

Borro la clase en EduShield y la reunión sigue apareciendo en zoom.us.

EduShield manda DELETE /meetings/{id} en cuanto confirmás. Si el token estaba expirado al momento del borrado, el evento queda solo en EduShield. Reautorizá Zoom y volvé a borrar la sesión, o eliminala manualmente desde zoom.us/meeting.

¿Cómo confirmo que mis tokens están seguros?

Los tokens se cifran con AES-256-GCM (clave en variable de entorno del servidor) antes de persistir en la base de datos. Nunca se exponen al cliente, ni siquiera a través de la API de EduShield. El campo UserIntegration.accessTokenEnc en la base de datos contiene texto cifrado, no el token en claro.

07

Contacto y soporte

Si necesitás ayuda con la integración o querés reportar un problema de seguridad, escribinos desde nuestro formulario oficial de soporte:

Ir a la página de contacto

  • Soporte general: elegí el motivo “Integraciones / Zoom” en el formulario.
  • Equipo de revisores Zoom: indicá “Zoom Marketplace Review” en el campo de asunto del formulario para escalado prioritario.
  • Reportes de seguridad: elegí el motivo “Seguridad / Vulnerabilidad”; tu mensaje llega cifrado a nuestro equipo.

Documentos relacionados: Términos del servicio, Política de privacidad, Eliminar mis datos, Integración con Google.