Documentación de la API

Cada institución tiene su propia documentación interactiva de la API, disponible en /docs/ a partir de la dirección de su Eduvem - por ejemplo, https://love.eduvem.com/docs/. Es el material que el equipo técnico responsable de la integración (RH, ERP, BI o cualquier sistema externo) usará para conocer y probar la API antes de escribir cualquier código.

Qué encuentra allí

La documentación reúne todos los endpoints de la API de integración: parámetros aceptados, esquemas de solicitud y de respuesta, y los alcances (scopes) exigidos por cada llamada. La página es interactiva - puede expandir cualquier endpoint, completar los parámetros y enviar la solicitud directamente desde el navegador, usando un token real, sin necesitar Postman ni ninguna otra herramienta externa.

Dónde encontrar el enlace

En la pestaña Integraciones de la configuración de la institución (Institución > Integraciones), la sección Configuración de la API para Integraciones incluye:

• El enlace Documentación de la API, que abre el /docs/ de su institución.
• La URL de la API, ya lista para copiar - la dirección base usada en toda llamada de integración.

Consejo

Cada institución tiene su propia documentación, en su propio dominio. Si usted administra o integra más de una Eduvem, confirme siempre cuál /docs/ está usando - el de cada institución es diferente.

Autenticación

Para probar una llamada directamente en la documentación interactiva - o para configurar una integración real - usted necesita un token de la API válido. La creación, la revocación y los alcances de los tokens se gestionan en la misma pestaña Integraciones: consulte Tokens de la API de integración. Sin un token, la documentación sigue siendo navegable y cada endpoint permanece visible, pero el botón para enviar la solicitud devuelve un error de autenticación.

Clases de un contenido

Una integración que trata cada clase como una tarea propia - un plan de desarrollo individual en un sistema de RRHH, por ejemplo - puede consultar la lista de clases de un contenido y, por matrícula, el estado de cada una:

• GET /integrations/courseVersions/{courseVersionUUID}/lessons devuelve la lista ordenada y de solo lectura de las clases del contenido publicado - clases del wizard agrupadas por módulo, los SCOs de un paquete SCORM, o la unidad única de un coursebox.
• GET /integrations/enrollments/{enrollmentUUID}/lessons devuelve la misma lista para una matrícula específica, con el estado “visualizada”/“completada” de cada clase y el progreso general de la matrícula.

Ambas llamadas tienen su propio límite de uso: 120 solicitudes por minuto, por institución, para cada una.

Todos los campos, alcances y ejemplos completos de cada endpoint están en la documentación interactiva de la API de su institución (arriba).

Consejo

El identificador de cada clase (lessonKey) es la identidad de la clase; su posición en la lista (position) es solo el orden de visualización - si un autor reordena las clases, la posición cambia, pero el lessonKey sigue siendo el mismo. La estabilidad del lessonKey también varía según el tipo de contenido: los identificadores de las clases del wizard se mantienen incluso después de una nueva publicación o de una traducción. Los identificadores de las clases SCORM, en cambio, son las propias rutas de archivo del paquete: los identificadores pueden cambiar o desaparecer si el paquete se reemplaza por una nueva versión o, en la consulta por matrícula, cuando el primer acceso del participante fija un idioma cuyo paquete trae archivos diferentes. Una integración que guarda este identificador (para hacer seguimiento de tareas, por ejemplo) necesita resincronizar después de cualquiera de estos cambios. La mayoría de los contenidos SCORM tiene una única clase.

Etapas y progreso de una ruta

Una integración que hace seguimiento de una ruta - un conjunto de salas que forman un mismo recorrido - puede consultar la lista de etapas de la ruta y el progreso de cada participante en ella:

• GET /integrations/categories/{categoryUUID}/steps devuelve la lista ordenada y de solo lectura de las etapas (salas) que forman la ruta, con el nombre de cada una y el plazo en días configurado (0 cuando no hay plazo). Solo funciona para una categoría marcada como ruta - en cualquier otra categoría, la llamada devuelve un error de “no encontrado”.
• GET /integrations/categories/{categoryUUID}/progress devuelve, por participante, el total de etapas completadas y el estado de cada etapa (no matriculado, matriculado, bloqueado por una etapa anterior, esperando evaluación o completado). Exige el permiso Informes (lectura) en el token y tiene su propio límite de uso: 120 solicitudes por minuto.

Como en las clases de un contenido, todos los campos de cada respuesta están en la documentación interactiva de la API de su institución (arriba).

Capacitaciones NR para sistemas de SST

Las integraciones con el sistema de SST de la empresa (SOC, Senior, TOTVS) pueden obtener las capacitaciones NR concluidas, las mismas del informe Exportación de capacitaciones NR:

• GET /integrations/reports/nrTrainingRecords devuelve, paginada, la lista de capacitaciones NR con certificado emitido en el período. Exige el permiso Informes (lectura) en el token. El parámetro certifiedSince es obligatorio (aaaa-mm-dd o un instante ISO-8601 con Z o desplazamiento) y certifiedUntil es opcional (por defecto, ahora); ps limita la página a 500 registros. La respuesta también trae el total, la cantidad de personas anonimizadas excluidas y la versión del diseño de la Tabla 28 de eSocial.

El endpoint tiene su propio límite de uso (60 solicitudes por minuto) y solo responde para instituciones con la función de NR habilitada; para las demás, la llamada devuelve un error. Todos los campos están en la documentación interactiva de la API de su institución (arriba).

Resumen de una sala

Una integración que muestra el avance de una sala en otro sistema (un panel de BI, por ejemplo) puede consultar su resumen agregado:

• GET /integrations/reports/courseClasses/{courseClassUUID}/summary devuelve la cantidad de matriculados y de certificados de la sala, la tasa de finalización y el promedio de las notas. Exige el permiso Informes (lectura) en el token y tiene su propio límite de uso: 120 solicitudes por minuto.

Una sala que existe pero todavía no tiene ninguna matrícula responde con normalidad (HTTP 200) con un resumen vacío: enrolledCount y certifiedCount iguales a 0, y completionRate y averageAssessmentScore nulos. Una sala que no existe, fue eliminada, es una sala de prueba o pertenece a otra institución sigue devolviendo “no encontrada” (HTTP 404, courseClassNotFound).

Nota

Antes, la llamada para una sala sin matrículas devolvía 404. Si su integración trataba ese error como “sala vacía”, pase a tratar el resumen vacío.

Identificador de su sistema de RR. HH. (externalId)

Cuando la institución carga a las personas mediante la sincronización de personas, cada persona tiene un externalId: el código que el sistema de RR. HH. usa para ella. La API de integración ahora lo devuelve, para que el sistema externo no tenga que cruzar por e-mail o CPF:

• Usuarios (GET /integrations/users y la consulta de un usuario): campo externalId.
• Matrículas (GET /integrations/enrollments): campo personExternalId, en el bloque de la persona.
• Webhooks de matrícula y de ruta: campo person.externalId en el bloque de la persona del aviso.
• Filtro: GET /integrations/users?externalId=<código> devuelve solo a la persona cuyo externalId es exactamente igual al valor indicado.

La clave se omite cuando la persona no tiene externalId. Por eso, las respuestas y los avisos firmados de las instituciones que no usan la sincronización de personas siguen idénticos a los de antes. La descripción de cada campo está en la documentación interactiva, en los cuatro idiomas.

Copiar la lista de matrículas

Para copiar todas las matrículas de la institución a otro sistema (un BI o un data lake, por ejemplo), use el cursor de GET /integrations/enrollments en lugar de pedir página por página por número:

1. Haga la primera llamada sin pn (o con pn=1). Cada página completa trae el campo nextCursor.
2. Llame de nuevo enviando cursor=<el nextCursor recibido>, exactamente como vino, hasta que una respuesta traiga nextCursor nulo.

Cada página por cursor cuesta lo mismo, sea la primera o la milésima, mientras que pedir la página 500 por número obliga a releer las 499 anteriores. En las respuestas por cursor, count, pageCount y pageNumber vienen nulos.

• No combine cursor con pn mayor que 1, lastModified ni startedSince, y repita los mismos filtros courseClassUUID, userUUID y teamUUID de la llamada que generó el cursor. De lo contrario, la respuesta es un error cursorConflict.
• Cambios recientes: el cursor solo entrega matrículas modificadas hace más de 5 minutos. Un cambio aparece en una copia por cursor después de ese plazo.
• Entrega al menos una vez: una matrícula modificada durante la copia puede llegar de nuevo más adelante. Actualice por enrollmentUUID en lugar de insertar de nuevo.
• Sincronización incremental: guarde el mayor lastModificationDate recibido y, en la próxima ejecución, empiece con lastModified=<ese valor menos 5 minutos>.

Precaución

Pedir la lista entera página por página por número, sin ningún filtro, está obsoleto: esas respuestas traen las cabeceras Deprecation y Sunset (3 de enero de 2027). Después de esa fecha, una versión futura podrá rechazar páginas profundas sin filtro y pedir el cursor.

Vea también

• Tokens de la API de integración