Documentação da API

Toda instituição tem sua própria documentação interativa da API, disponível em /docs/ a partir do endereço da sua Eduvem - por exemplo, https://love.eduvem.com/docs/. É o material que o time técnico responsável pela integração (RH, ERP, BI ou qualquer sistema externo) vai usar para conhecer e testar a API antes de escrever qualquer código.

O que você encontra lá

A documentação reúne todos os endpoints da API de integração: parâmetros aceitos, esquemas de requisição e de resposta, e os escopos exigidos por cada chamada. A página é interativa - dá para expandir qualquer endpoint, preencher os parâmetros e enviar a requisição direto pelo navegador, usando um token real, sem precisar de Postman nem de nenhuma outra ferramenta externa.

Onde encontrar o link

Na aba Integrações das configurações da instituição (Instituição > Integrações), a seção Configurações da API para Integrações traz:

• O link Documentação da API, que abre o /docs/ da sua instituição.
• A URL da API, já pronta para copiar - o endereço base usado em toda chamada de integração.

Dica

Cada instituição tem sua própria documentação, no seu próprio domínio. Se você administra ou integra mais de uma Eduvem, confirme sempre qual /docs/ está usando - o de cada instituição é diferente.

Autenticação

Para testar uma chamada direto na documentação interativa - ou para configurar uma integração de verdade - você precisa de um token da API válido. A criação, a revogação e os escopos dos tokens são gerenciados na mesma aba Integrações: veja Tokens da API de integração. Sem um token, a documentação continua navegável e cada endpoint fica visível, mas o botão de enviar a requisição retorna erro de autenticação.

Aulas de um conteúdo

Uma integração que trata cada aula como uma tarefa própria - um plano de desenvolvimento individual em um sistema de RH, por exemplo - pode consultar a lista de aulas de um conteúdo e, por matrícula, o status de cada uma:

• GET /integrations/courseVersions/{courseVersionUUID}/lessons retorna a lista ordenada e somente leitura das aulas do conteúdo publicado - aulas do wizard agrupadas por módulo, os SCOs de um pacote SCORM, ou a unidade única de um coursebox.
• GET /integrations/enrollments/{enrollmentUUID}/lessons retorna a mesma lista para uma matrícula específica, com o status “visualizada”/“concluída” de cada aula e o progresso geral da matrícula.

As duas chamadas têm limite de uso próprio: 120 requisições por minuto, por instituição, para cada uma.

Todos os campos, escopos e exemplos completos de cada endpoint estão na documentação interativa da API da sua instituição (acima).

Dica

O identificador de cada aula (lessonKey) é a identidade da aula; a posição dela na lista (position) é só a ordem de exibição - se um autor reordenar as aulas, a posição muda, mas o lessonKey continua o mesmo. A estabilidade do lessonKey também varia por tipo de conteúdo: as aulas do wizard mantêm o mesmo identificador mesmo depois de republicadas ou traduzidas. Já as aulas de um conteúdo SCORM usam os próprios caminhos de arquivo do pacote - os identificadores podem mudar ou desaparecer se o pacote for substituído por uma nova versão ou, na consulta por matrícula, quando o primeiro acesso do participante fixa um idioma cujo pacote traz arquivos diferentes. Uma integração que guarda esse identificador (para acompanhar tarefas, por exemplo) precisa ressincronizar depois de qualquer uma dessas mudanças. A maioria dos conteúdos SCORM tem uma única aula.

Etapas e progresso de uma trilha

Uma integração que acompanha uma trilha - um conjunto de salas que compõem um mesmo percurso - pode consultar a lista de etapas da trilha e o progresso de cada participante nela:

• GET /integrations/categories/{categoryUUID}/steps retorna a lista ordenada e somente leitura das etapas (salas) que compõem a trilha, com o nome de cada uma e o prazo em dias configurado (0 quando não há prazo). Funciona só para uma categoria marcada como trilha - em qualquer outra categoria, a chamada retorna erro de “não encontrado”.
• GET /integrations/categories/{categoryUUID}/progress retorna, por participante, o total de etapas concluídas e o estado de cada etapa (não matriculado, matriculado, bloqueado por uma etapa anterior, aguardando avaliação ou concluído). Exige a permissão Relatórios (leitura) no token e tem limite de uso próprio: 120 requisições por minuto.

Como nas aulas de um conteúdo, todos os campos de cada resposta estão na documentação interativa da API da sua instituição (acima).

Treinamentos NR para sistemas de SST

Integrações com o sistema de SST da empresa (SOC, Senior, TOTVS) podem buscar os treinamentos NR concluídos, os mesmos do relatório Exportação de treinamentos NR:

• GET /integrations/reports/nrTrainingRecords retorna, paginada, a lista de treinamentos NR com certificado emitido no período. Exige a permissão Relatórios (leitura) no token. O parâmetro certifiedSince é obrigatório (aaaa-mm-dd ou um instante ISO-8601 com Z ou deslocamento) e certifiedUntil é opcional (o padrão é agora); ps limita a página a 500 registros. A resposta traz também o total, a quantidade de pessoas anonimizadas excluídas e a versão do layout da Tabela 28 do eSocial.

O endpoint tem limite de uso próprio (60 requisições por minuto) e só responde para instituições com o recurso de NR habilitado; nas demais, a chamada retorna erro. Todos os campos estão na documentação interativa da API da sua instituição (acima).

Identificador do seu sistema de RH (externalId)

Quando a instituição carrega as pessoas por sincronização de pessoas, cada pessoa tem um externalId: o código que o sistema de RH usa para ela. A API de integração passa a devolvê-lo, para que o sistema externo não precise cruzar por e-mail ou CPF:

• Usuários (GET /integrations/users e a consulta de um usuário): campo externalId.
• Matrículas (GET /integrations/enrollments): campo personExternalId, no bloco da pessoa.
• Webhooks de matrícula e de trilha: campo person.externalId no bloco da pessoa do aviso.
• Filtro: GET /integrations/users?externalId=<código> devolve só a pessoa cujo externalId é exatamente igual ao valor informado.

A chave é omitida quando a pessoa não tem externalId. Por isso, as respostas e os avisos assinados de instituições que não usam a sincronização de pessoas continuam idênticos aos de antes. A descrição de cada campo está na documentação interativa, nos quatro idiomas.

Copiar a lista de matrículas

Para copiar todas as matrículas da instituição para outro sistema (um BI ou um data lake, por exemplo), use o cursor de GET /integrations/enrollments em vez de pedir página por página pelo número:

1. Faça a primeira chamada sem pn (ou com pn=1). Toda página cheia traz o campo nextCursor.
2. Chame de novo enviando cursor=<o nextCursor recebido>, exatamente como veio, até uma resposta trazer nextCursor nulo.

Cada página por cursor custa o mesmo, seja a primeira ou a milésima, enquanto pedir a página 500 pelo número obriga a releitura das 499 anteriores. Nas respostas por cursor, count, pageCount e pageNumber vêm nulos.

• Não combine cursor com pn maior que 1, lastModified ou startedSince, e repita os mesmos filtros courseClassUUID, userUUID e teamUUID da chamada que gerou o cursor. Caso contrário, a resposta é um erro cursorConflict.
• Alterações recentes: o cursor só entrega matrículas alteradas há mais de 5 minutos. Uma alteração aparece em uma cópia por cursor depois disso.
• Entrega pelo menos uma vez: uma matrícula alterada durante a cópia pode vir de novo mais adiante. Atualize pelo enrollmentUUID em vez de inserir de novo.
• Sincronização incremental: guarde o maior lastModificationDate recebido e, na próxima execução, comece com lastModified=<esse valor menos 5 minutos>.

Cuidado

Pedir a lista inteira página por página pelo número, sem nenhum filtro, está descontinuado: essas respostas trazem os cabeçalhos Deprecation e Sunset (3 de janeiro de 2027). Depois dessa data, uma versão futura poderá recusar páginas profundas sem filtro e pedir o cursor.

Veja também

• Tokens da API de integração