Tokens de la API de integración

La API de integración conecta los sistemas de su organización (RH, ERP, BI) con Eduvem: registro y matrícula automáticos, extracción de informes, descarga de certificados y más. Todo acceso se realiza mediante tokens creados por el administrador.

Creando y gestionando tokens

• Cree varios tokens nombrados e independientes - uno por sistema integrado es la buena práctica. Cada uno puede revocarse sin afectar a los demás.
• El valor del token se muestra una única vez, al crearlo. Guárdelo en la bóveda de secretos de su organización: si se pierde, el camino es eliminar el token y crear otro.
• Algunos datos exigen permiso adicional otorgado en el token: descarga de certificados, el historial de auditoría de matrículas, los informes y, en las salas con gestión de matrículas, la decisión sobre las solicitudes (Matrículas (escritura)). Otorgue solo lo que la integración realmente usa. Para registrar, actualizar o eliminar participantes mediante la API, el token necesita Usuarios (escritura); para crear o modificar salas, versiones de contenido, grupos y roles, consulte Escritura de salas, versiones de contenido, grupos y roles mediante la API.
• Para cambiar los alcances de un token ya creado, use el ícono de editar permisos en la lista de tokens.
• Los webhooks quedan vinculados al token que los configuró: eliminar el token, o quitarle el permiso Informes (lectura), detiene sus webhooks. Al cambiar de token, el equipo de integración debe reactivar los webhooks con el token nuevo antes de que usted elimine el anterior.

Editar los permisos de un token

Los permisos de un token se pueden cambiar después de crearlo, sin reemplazar el token: haga clic en el ícono de lápiz (Editar permisos) en la fila del token. La ventana se abre con los permisos actuales ya marcados.

• Agregar un permiso pide confirmación: como el token ya está en uso, la integración obtiene acceso a los nuevos datos de inmediato, en su próxima llamada.
• Quitar un permiso se guarda directamente, sin confirmación.
• El permiso Plataforma viene en todos los tokens y no se puede desmarcar.
• Si otro administrador cambió el mismo token mientras la ventana estaba abierta, el cambio se rechaza y la lista se actualiza: revísela e inténtelo de nuevo.

Qué hace la integración

Registro y actualización de participantes (individual y por lote), gestión de grupos y roles, matrículas y cambios de estado (aprobar, rechazar, cancelar, reactivar), listado y descarga de certificados en PDF, informes (resumen por sala y exportación por matrícula), catálogo de salas y contenidos, y el ranking.

En la matrícula vía API, el participante puede identificarse por correo electrónico o CPF - si aún no existe, el registro se crea automáticamente.

Escritura de participantes por la API

El permiso Usuarios (escritura) permite que el token registre, actualice, cambie el estado y elimine participantes mediante la API (POST /integrations/users, POST /integrations/users/multiple, PUT /integrations/users/{uuid}, PUT /integrations/users/{uuid}/status/{status} y DELETE /integrations/users/{uuid}). Siempre está disponible en la lista de permisos, nunca viene marcado por defecto y no está incluido en el permiso Plataforma.

• Sin el permiso, estas llamadas reciben el error 403 (insufficientScope). La consulta de participantes no cambia y sigue disponible para cualquier token.
• Los tokens que ya escribían participantes recibieron el permiso en la actualización de la plataforma. Cualquier otro token necesita que un administrador marque Usuarios (escritura) en Editar permisos.
• Matricular a una persona que todavía no existe, mediante los endpoints de matrícula de sala o de grupo, también requiere Usuarios (escritura), además del permiso de la sala o del grupo.
• Cambiar el correo electrónico o definir la contraseña de una persona con rol de administrador, publicador, observador o tutor, mediante PUT /integrations/users/{uuid}, exige además Inicio de sesión de administradores y tutores. Vea Inicio de sesión de administradores y tutores.

Escritura de salas, versiones de contenido, grupos y roles mediante la API

Cuatro permisos controlan las llamadas de escritura de estas áreas. Todos están siempre disponibles en la lista de permisos, nunca vienen marcados por defecto y no están incluidos en el permiso Plataforma. Las consultas (GET) no cambian.

Permiso	Qué permite
Salas (escritura)	Crear y actualizar salas (POST /integrations/courseClasses/create, PUT /integrations/courseClasses/{uuid}), matricular personas en una sala (POST /integrations/courseClasses), eliminar matrículas (DELETE /integrations/courseClasses) y cambiar el estado de una matrícula (PUT /integrations/enrollments/{uuid}/state/{state}).
Versiones de contenido (escritura)	Crear y actualizar versiones de contenido (POST /integrations/courseVersions/create, PUT /integrations/courseVersions/{uuid}) y crear una sala a partir de una versión (POST /integrations/courseVersions).
Grupos (escritura)	Crear, actualizar y eliminar grupos, añadir o quitar personas y vincular o desvincular salas (todas las llamadas de escritura de /integrations/teams).
Roles (escritura)	Otorgar y quitar roles (POST /integrations/roles y DELETE /integrations/roles/{uuid}), incluidos los roles de administrador. Otorgue solo a sistemas en los que confíe plenamente. Otorgar cualquier rol exige además Inicio de sesión de administradores y tutores.

• Sin el permiso, la llamada recibe el error 403 (insufficientScope).
• Matricular a alguien que todavía no existe, o añadirlo a un grupo, requiere además Usuarios (escritura).
• La autenticación de usuario (POST /integrations/auth/authenticationRequest) solo requiere Salas (escritura) cuando la llamada usa autoEnroll con una sala indicada, porque es entonces cuando matricula a alguien. Sin autoEnroll, no requiere permiso de escritura.
• En las salas con gestión de matrículas, cambiar el estado de una matrícula requiere Salas (escritura) y también Matrículas (escritura).
• Los tokens que ya hacían estas llamadas siguen funcionando después de la actualización de la plataforma. Cualquier otro token necesita que un administrador marque el permiso en Editar permisos.

Inicio de sesión de administradores y tutores

El permiso Inicio de sesión de administradores y tutores protege las cuentas de gestión. Sin él, el token no puede actuar sobre quien tenga un rol de administrador, publicador, observador o tutor (incluido el administrador de división). Es necesario para:

• el inicio de sesión de socio (POST /integrations/auth/authenticationRequest) de una persona con uno de esos roles;
• otorgar cualquier rol mediante la API (POST /integrations/roles);
• cambiar el correo electrónico o definir la contraseña de una persona con uno de esos roles (PUT /integrations/users/{uuid}).

Los participantes no lo necesitan. Los administradores de la plataforma Eduvem siempre son rechazados, con o sin el permiso. Sin él, la llamada recibe el error 403 (insufficientScope).

• Los tokens que ya existían en la actualización de la plataforma recibieron el permiso automáticamente. Los tokens nuevos comienzan sin él: un administrador de la institución lo marca en Editar permisos.
• Al marcarlo, la pantalla muestra la advertencia: “Atención: permite que este token inicie la sesión de personas como sus administradores, publicadores, observadores y tutores mediante el inicio de sesión de socio, sin su contraseña. Actívelo solo para una integración de inicio de sesión único en la que confíe plenamente.” La confirmación de agregar repite la alerta: “Atención: con el Inicio de sesión de administradores y tutores, esta integración puede abrir sesiones como sus administradores, publicadores, observadores y tutores sin su contraseña.”

Enlace de acceso del inicio de sesión de socio

El inicio de sesión de socio (POST /integrations/auth/authenticationRequest) devuelve una URL que su sistema abre para llevar a la persona a la plataforma, ya autenticada y, cuando se indica, directo a la sala.

• La URL lleva un código de un solo uso, válido por 2 minutos. No es la sesión de la persona: la sesión solo se crea cuando la página abre y canjea el código. Después de eso, la dirección que muestra el navegador no guarda nada sensible.
• Genere la URL en el momento del clic y ábrala enseguida. No guarde la URL para reutilizarla ni la envíe por correo: un enlace abierto por segunda vez, o después de 2 minutos, no inicia sesión.
• En ese caso la pantalla de inicio de sesión muestra: “Este enlace de acceso expiró o ya fue utilizado. Vuelve al sistema de donde viniste y abre el contenido nuevamente.” Basta con volver al sistema de origen y hacer clic de nuevo.
• Si otra persona ya tiene la sesión iniciada en el mismo navegador, el enlace cambia la sesión a la persona del enlace, como antes.

Matrículas gestionadas por la API

El permiso Matrículas (escritura) permite que el token gestione las delegaciones de aprobadores y apruebe, deniegue y cancele matrículas de salas con gestión de matrículas. Solo aparece en la lista de permisos mientras la institución tiene la gestión de matrículas activa (o cuando el token ya lo tiene), nunca viene marcado de forma predeterminada y no está incluido en el permiso Plataforma.

El permiso Sincronización de personas permite que el token envíe la lista completa de colaboradores, consulte las sincronizaciones y apruebe o cancele las sincronizaciones enviadas por la API; vea Sincronización de personas. Solo aparece en la lista de permisos mientras la sincronización de personas está activa en la institución (o cuando el token ya lo tiene), nunca viene marcado de forma predeterminada y no está incluido en el permiso Plataforma. Las sincronizaciones que activan un límite de seguridad siguen exigiendo la aprobación de una persona en la plataforma.

Aprobar, denegar y cancelar una matrícula

Use el endpoint de estado de la matrícula, con el identificador de quien decide. El token necesita Salas (escritura) y también Matrículas (escritura):

PUT /integrations/enrollments/{enrollmentUUID}/state/{state}?approverIdentifier=<usuario, correo o CPF>

En una sala con gestión de matrículas:

• enrolled aprueba una matrícula solicitada; denied la deniega. Una sala llena envía a la persona aprobada a la lista de espera, en lugar de darle la plaza.
• cancelled cancela una matrícula que ya está matriculada. Cualquier otro cambio de estado se rechaza con invalidEnrollmentStateTransition (400).
• approverIdentifier es obligatorio y debe ser una persona que podría decidir esa solicitud: el gestor del participante, un sustituto suyo, el gestor del gestor (por escalamiento) o un administrador de la sala. Nadie aprueba su propia solicitud.
• La denegación hecha por la API registra el motivo Otro; no hay campo de motivo.
• En caso de éxito la respuesta es 204, sin cuerpo.
• En salas sin gestión de matrículas, el endpoint sigue como antes e ignora approverIdentifier.

Los errores más comunes:

Código	Error	Cuándo
403	insufficientScope	El token no tiene Matrículas (escritura) o Salas (escritura).
403	approverNotAuthorized	La persona indicada no puede decidir esta solicitud.
400	approverIdentifierRequired, approverNotFound	Falta el approverIdentifier o la persona no existe en la institución.
404	enrollmentNotFound	La matrícula no existe.
409	requestsClosed	El plazo de la sala pasó; la matrícula se cierra.
409	enrollmentStateChangedConcurrently	Alguien cambió la matrícula antes.
409	selfApprovalNotAllowed	El aprobador es el propio solicitante.

Posición en la lista de espera

Las lecturas de matrícula (GET /integrations/enrollments/{enrollmentUUID} y el listado) traen el campo enrollmentQueuePosition: un número entero, donde 1 es el próximo en ser matriculado. Solo se rellena mientras la matrícula está en la lista de espera de una sala gestionada; en los demás casos viene vacío.

Sustitutos de gestores

Los sistemas de RR. HH. pueden registrar quién sustituye a un gestor durante un período:

• POST /integrations/managerDelegates, con principalIdentifier (el gestor), delegateIdentifier (el sustituto), validFrom y validUntil en formato ISO-8601 con zona horaria (por ejemplo, 2026-10-07T12:00:00Z). Las personas se identifican por usuario, correo o CPF. Responde 201 con la delegación creada, con source igual a integration.
• GET /integrations/managerDelegates?principalIdentifier=<gestor> lista solo las delegaciones creadas por la integración.
• DELETE /integrations/managerDelegates/{delegationUUID} revoca una delegación (204, incluso si ya estaba revocada).

El período debe empezar antes de terminar, terminar en el futuro y durar como máximo 366 días; el sustituto debe ser una persona activa y distinta del gestor. Estas llamadas responden 403 (insufficientScope) sin el permiso, o (enrollmentManagementDisabled) si la línea de gestión o la gestión de matrículas están desactivadas en la institución, y están limitadas a 60 llamadas por minuto.

Auditoría

Toda llamada realizada por la API queda registrada por la plataforma (qué, cuándo y con qué token). Ese registro no se muestra en el panel administrativo: si necesita saber qué hizo un sistema externo, solicite la consulta al soporte de Eduvem indicando el token y el período.

Límites de uso

• El tráfico está limitado por institución (presupuesto estándar de 1.000 solicitudes por minuto, ajustable a pedido).
• Las operaciones pesadas (exportaciones de auditoría/informes y descarga de certificados) tienen un presupuesto propio, menor - un pico en ellas no bloquea el resto de la integración.
• Los listados están paginados (100 elementos por página de forma predeterminada, máximo 1.000): oriente a los integradores a paginar siempre.
• El listado de certificados tiene un límite menor: máximo 100 elementos por página (una página mayor es rechazada).
• Cada servidor acepta como máximo 2 llamadas simultáneas por token y 4 por institución. Una llamada adicional recibe el error 429 (integrationConcurrencyExceeded) con el encabezado Retry-After: 5: espere y vuelva a intentarlo. Las integraciones que hacen una llamada a la vez nunca se ven afectadas.
• Para mantener un sistema externo sincronizado, no descargue todas las inscripciones en cada ejecución: después de la primera carga, envíe lastModified con la hora en que comenzó la sincronización anterior y actualice los registros por el identificador de la inscripción. Deje de paginar cuando una página traiga menos elementos que el tamaño solicitado.
• En el listado de inscripciones por número de página, los totales (count y pageCount) se calculan una vez por combinación de filtros en cada servidor y se reutilizan hasta 10 minutos: pueden no reflejar inscripciones creadas o modificadas en ese intervalo. Por eso el criterio de parada es la página incompleta, no pageCount.
• Una consulta demasiado pesada que supera el tiempo del banco de datos recibe el error 503 (queryTimeout) con el encabezado Retry-After: 60: espere un minuto y vuelva a intentarlo, preferiblemente con filtros más acotados o con la paginación por cursor descrita en la documentación de la API.

Consejo

Trate los tokens como contraseñas: nunca en planillas ni correos electrónicos, siempre uno por sistema, y revoque de inmediato los tokens de integraciones desactivadas.

Vea también

• Documentación de la API