Tokens da API de integração

A API de integração conecta os sistemas da sua organização (RH, ERP, BI) à Eduvem: cadastro e matrícula automáticos, extração de relatórios, download de certificados e mais. Todo acesso acontece por tokens criados pelo administrador.

Tela Configurações da API para Integrações, com a URL da API e a lista de tokens de integração

Criando e gerenciando tokens

Crie vários tokens nomeados e independentes - um por sistema integrado é a boa prática. Cada um pode ser revogado sem afetar os demais.
O valor do token é exibido uma única vez, na criação. Guarde-o no cofre de segredos da sua organização: se for perdido, o caminho é excluir o token e criar outro.
Alguns dados exigem permissão extra concedida no token: download de certificados, o histórico de auditoria de matrículas, os relatórios e, nas salas com gestão de matrículas, a decisão sobre as solicitações (Matrículas (escrita)). Conceda só o que a integração realmente usa. Para cadastrar, atualizar ou excluir participantes pela API, o token precisa de Usuários (escrita); para criar ou alterar salas, versões de conteúdo, grupos e papéis, veja Escrita de salas, versões, grupos e papéis pela API.
Para mudar os escopos de um token já criado, use o ícone de editar permissões na lista de tokens.
Os webhooks ficam vinculados ao token que os configurou: excluir o token, ou remover dele a permissão Relatórios (leitura), interrompe os webhooks dele. Ao trocar de token, a equipe de integração precisa reativar os webhooks com o token novo antes de você excluir o antigo.

Modal Editar permissões de um token, com os escopos Plataforma, Certificados, Auditoria, Relatórios e Webhooks

Editando as permissões de um token

As permissões de um token podem ser alteradas depois da criação, sem trocar o token: clique no ícone de lápis (Editar permissões) na linha do token. A janela abre com as permissões atuais já marcadas.

Adicionar uma permissão pede confirmação: como o token já está em uso, a integração passa a ter acesso aos novos dados imediatamente, na próxima chamada.
Remover uma permissão salva direto, sem confirmação.
A permissão Plataforma vem em todo token e não pode ser desmarcada.
Se outro administrador tiver alterado o mesmo token enquanto a janela estava aberta, a alteração é recusada e a lista é atualizada: revise e tente de novo.

O que a integração faz

Cadastro e atualização de participantes (individual e em lote), gestão de grupos e papéis, matrículas e mudanças de estado (aprovar, negar, cancelar, reativar), listagem e download de certificados em PDF, relatórios (resumo por sala e exportação por matrícula), catálogo de salas e conteúdos, e o ranking.

Na matrícula via API, o participante pode ser identificado por e-mail ou CPF - se ainda não existe, o cadastro é criado automaticamente.

Escrita de participantes pela API

A permissão Usuários (escrita) deixa o token cadastrar, atualizar, alterar a situação e excluir participantes pela API (POST /integrations/users, POST /integrations/users/multiple, PUT /integrations/users/{uuid}, PUT /integrations/users/{uuid}/status/{status} e DELETE /integrations/users/{uuid}). Ela está sempre disponível na lista de permissões, nunca vem marcada por padrão e não está incluída na permissão Plataforma.

Sem a permissão, essas chamadas recebem o erro 403 (insufficientScope). A consulta de participantes não muda e continua disponível a qualquer token.
Os tokens que já gravavam participantes receberam a permissão na atualização da plataforma. Qualquer outro token precisa que um administrador marque Usuários (escrita) em Editar permissões.
Matricular uma pessoa que ainda não existe, pelos endpoints de matrícula de sala ou de grupo, também exige Usuários (escrita), além da permissão da própria sala ou do grupo.
Alterar o e-mail ou definir a senha de uma pessoa com papel de administrador, publicador, observador ou tutor, por PUT /integrations/users/{uuid}, exige também Login de administradores e tutores. Veja Login de administradores e tutores.

Escrita de salas, versões de conteúdo, grupos e papéis pela API

Quatro permissões controlam as chamadas de escrita dessas áreas. Todas estão sempre disponíveis na lista de permissões, nunca vêm marcadas por padrão e não estão incluídas na permissão Plataforma. As consultas (GET) não mudam.

Permissão	O que libera
Salas (escrita)	Criar e atualizar salas (`POST /integrations/courseClasses/create`, `PUT /integrations/courseClasses/{uuid}`), matricular pessoas em uma sala (`POST /integrations/courseClasses`), remover matrículas (`DELETE /integrations/courseClasses`) e alterar o estado de uma matrícula (`PUT /integrations/enrollments/{uuid}/state/{state}`).
Versões de conteúdo (escrita)	Criar e atualizar versões de conteúdo (`POST /integrations/courseVersions/create`, `PUT /integrations/courseVersions/{uuid}`) e criar uma sala a partir de uma versão (`POST /integrations/courseVersions`).
Grupos (escrita)	Criar, atualizar e excluir grupos, adicionar ou remover pessoas e vincular ou desvincular salas (todas as chamadas de escrita de `/integrations/teams`).
Papéis (escrita)	Conceder e remover papéis (`POST /integrations/roles` e `DELETE /integrations/roles/{uuid}`), inclusive papéis de administrador. Conceda apenas a sistemas em que você confia plenamente. Conceder qualquer papel exige também Login de administradores e tutores.

Sem a permissão, a chamada recebe o erro 403 (insufficientScope).
Matricular ou adicionar a um grupo uma pessoa que ainda não existe exige também Usuários (escrita).
A autenticação de usuário (POST /integrations/auth/authenticationRequest) só exige Salas (escrita) quando a chamada usa autoEnroll com uma sala informada, pois é nesse caso que ela matricula alguém. Sem autoEnroll, não exige permissão de escrita.
Nas salas com gestão de matrículas, alterar o estado de uma matrícula exige Salas (escrita) e também Matrículas (escrita).
Os tokens que já faziam essas chamadas continuam funcionando depois da atualização da plataforma. Qualquer outro token precisa que um administrador marque a permissão em Editar permissões.

A permissão Login de administradores e tutores protege as contas de gestão. Sem ela, o token não age sobre quem tem papel de administrador, publicador, observador ou tutor (inclusive administrador de divisão). Ela é necessária para:

o login de parceiro (POST /integrations/auth/authenticationRequest) de uma pessoa com um desses papéis;
conceder qualquer papel pela API (POST /integrations/roles);
alterar o e-mail ou definir a senha de uma pessoa com um desses papéis (PUT /integrations/users/{uuid}).

Participantes não precisam dela. Administradores da plataforma Eduvem são sempre recusados, com ou sem a permissão. Sem ela, a chamada recebe o erro 403 (insufficientScope).

Os tokens que já existiam na atualização da plataforma receberam a permissão automaticamente. Os tokens novos começam sem ela: um administrador da instituição a marca em Editar permissões.
Ao marcá-la, a tela exibe o aviso: “Atenção: permite que este token faça o login de pessoas como seus administradores, publicadores, observadores e tutores pelo login de parceiro, sem a senha delas. Ligue apenas para uma integração de login único em que você confia plenamente.” A confirmação de adicionar repete o alerta: “Atenção: com o Login de administradores e tutores, esta integração pode abrir sessões como seus administradores, publicadores, observadores e tutores sem a senha deles.”

Matrículas gerenciadas pela API

A permissão Matrículas (escrita) deixa o token gerenciar as delegações de aprovadores e aprovar, negar e cancelar matrículas de salas com gestão de matrículas. Ela só aparece na lista de permissões enquanto a instituição tem a gestão de matrículas ativa (ou quando o token já a possui), nunca vem marcada por padrão e não está incluída na permissão Plataforma.

A permissão Sincronização de pessoas deixa o token enviar a lista completa de colaboradores, consultar as sincronizações e aprovar ou cancelar as sincronizações enviadas pela API - veja Sincronização de pessoas. Ela só aparece na lista de permissões enquanto a sincronização de pessoas está ativa na instituição (ou quando o token já a possui), nunca vem marcada por padrão e não está incluída na permissão Plataforma. Sincronizações que atingem um limite de segurança continuam exigindo a aprovação de uma pessoa na plataforma.

Aprovar, negar e cancelar uma matrícula

Use o endpoint de estado da matrícula, com o identificador de quem decide. O token precisa de Salas (escrita) e também de Matrículas (escrita):

PUT /integrations/enrollments/{enrollmentUUID}/state/{state}?approverIdentifier=<usuário, e-mail ou CPF>

Em uma sala com gestão de matrículas:

enrolled aprova uma matrícula solicitada; denied a nega. A sala cheia manda o aprovado para a lista de espera, em vez de dar a vaga.
cancelled cancela uma matrícula já matriculada. Qualquer outra mudança de estado é recusada com invalidEnrollmentStateTransition (400).
approverIdentifier é obrigatório e precisa ser uma pessoa que poderia decidir aquele pedido: o gestor do participante, um substituto dele, o gestor do gestor (por escalonamento) ou um administrador da sala. Ninguém aprova o próprio pedido.
A negação feita pela API registra o motivo Outro; não há campo de motivo.
Em caso de sucesso a resposta é 204, sem corpo.
Em salas sem gestão de matrículas, o endpoint continua como antes e ignora approverIdentifier.

Os erros mais comuns:

Código	Erro	Quando
403	`insufficientScope`	O token não tem Matrículas (escrita) ou Salas (escrita).
403	`approverNotAuthorized`	A pessoa informada não pode decidir esse pedido.
400	`approverIdentifierRequired`, `approverNotFound`	Faltou o `approverIdentifier` ou a pessoa não existe na instituição.
404	`enrollmentNotFound`	A matrícula não existe.
409	`requestsClosed`	O prazo da sala passou; a matrícula é encerrada.
409	`enrollmentStateChangedConcurrently`	Alguém alterou a matrícula antes.
409	`selfApprovalNotAllowed`	O aprovador é o próprio solicitante.

Posição na lista de espera

As leituras de matrícula (GET /integrations/enrollments/{enrollmentUUID} e a listagem) trazem o campo enrollmentQueuePosition: um número inteiro, em que 1 é o próximo a ser matriculado. Ele só é preenchido enquanto a matrícula está na lista de espera de uma sala gerida; nos demais casos vem vazio.

Substitutos de gestores

Sistemas de RH podem registrar quem substitui um gestor durante um período:

POST /integrations/managerDelegates, com principalIdentifier (o gestor), delegateIdentifier (o substituto), validFrom e validUntil em formato ISO-8601 com fuso (por exemplo, 2026-10-07T12:00:00Z). As pessoas são identificadas por usuário, e-mail ou CPF. Responde 201 com a delegação criada, com source igual a integration.
GET /integrations/managerDelegates?principalIdentifier=<gestor> lista apenas as delegações criadas pela integração.
DELETE /integrations/managerDelegates/{delegationUUID} revoga uma delegação (204, mesmo se ela já estava revogada).

O período precisa começar antes de terminar, terminar no futuro e ter no máximo 366 dias; o substituto precisa ser uma pessoa ativa e diferente do gestor. Essas chamadas respondem 403 (insufficientScope) sem a permissão ou (enrollmentManagementDisabled) se a linha de gestão ou a gestão de matrículas estiverem desligadas na instituição, e são limitadas a 60 por minuto.

Auditoria

Toda chamada feita pela API fica registrada pela plataforma (o quê, quando e com qual token). Esse registro não é exibido no painel administrativo: se você precisar saber o que um sistema externo fez, peça a consulta ao suporte da Eduvem informando o token e o período.

Limites de uso

O tráfego é limitado por instituição (orçamento padrão de 1.000 requisições por minuto, ajustável sob demanda).
Operações pesadas (exportações de auditoria/relatórios e download de certificados) têm um orçamento próprio, menor - um pico nelas não trava o restante da integração.
Listagens são paginadas (padrão 100 itens por página, máximo 1.000): oriente os integradores a sempre paginar.
A listagem de certificados tem um limite menor: no máximo 100 itens por página (uma página maior é recusada).
Cada servidor aceita no máximo 2 chamadas simultâneas por token e 4 por instituição. Uma chamada além disso recebe o erro 429 (integrationConcurrencyExceeded) com o cabeçalho Retry-After: 5: aguarde e repita. Integrações que fazem uma chamada por vez nunca são afetadas.
Para manter um sistema externo sincronizado, não baixe todas as matrículas a cada execução: depois da primeira carga, envie lastModified com o horário em que a sincronização anterior começou e atualize os registros pelo identificador da matrícula. Pare de paginar quando uma página vier com menos itens que o tamanho pedido.
Na listagem de matrículas por número de página, os totais (count e pageCount) são calculados uma vez por combinação de filtros em cada servidor e reaproveitados por até 10 minutos: podem não refletir matrículas criadas ou alteradas nesse intervalo. Por isso o critério de parada é a página que vem incompleta, não o pageCount.
Uma consulta pesada demais que estoura o tempo do banco recebe o erro 503 (queryTimeout) com o cabeçalho Retry-After: 60: aguarde um minuto e repita, de preferência com filtros mais estreitos ou com a paginação por cursor descrita na documentação da API.

Veja também

Documentação da API