API pública do Brusnika.LMS — integração com RH, CRM e BI

A API pública do Brusnika.LMS é uma interface de programação para conectar a LMS a sistemas externos, como sistemas de RH, CRMs, sites e plataformas de BI. Ela permite trabalhar com usuários e conteúdos de aprendizagem, criar atribuições, obter resultados de treinamento e enviar notificações de eventos para sistemas externos.

A API pública está atualmente em beta. Suas configurações ficam em Gerenciamento do sistema → API pública e estão disponíveis para o administrador do portal.

A API é destinada principalmente a desenvolvedores que criam integrações para clientes e parceiros. O administrador do portal cria as chaves de acesso e define quais áreas da API cada chave pode acessar.

O que a API pública do Brusnika.LMS permite fazer

A API pode ser usada para:

• consultar e pesquisar usuários;
• criar usuários externos e contas com login;
• alterar usuários externos;
• trabalhar com departamentos e campos personalizados do perfil;
• criar, consultar, alterar e excluir aulas, cursos, programas e testes;
• criar e gerenciar atribuições de conteúdos e programas;
• trabalhar com subcontas;
• enviar, obter e excluir arquivos;
• trabalhar com pastas e materiais da base de conhecimento;
• gerenciar inscrições em materiais da base de conhecimento;
• obter relatórios de aprendizagem;
• obter resultados de testes, avaliações 360, certificados emitidos e respostas de pesquisas;
• criar assinaturas para webhooks de saída;
• receber notificações sobre alterações na LMS;
• verificar o status do serviço.

Assim, a API permite tanto consultar dados da LMS quanto executar operações de escrita que sejam suportadas por cada área da API.

Como funciona o acesso à API

O acesso à API pública é controlado por chaves.

Ao criar uma chave, o administrador pode definir:

• nome da chave;
• permissões por área da API;
• permissões de leitura e escrita separadamente;
• prazo de validade.

As opções de validade são:

• sem prazo de expiração;
• 30 dias;
• 90 dias;
• 365 dias.

O valor da chave é mostrado uma única vez durante a criação.

A lista de chaves mostra seus status:

• ativa;
• expirada;
• revogada.

Uma chave também pode ser revogada.

Cada chave funciona somente no portal em que foi criada. Uma chave de um portal não pode ser usada como chave de API para outro portal.

A documentação da API está disponível no endereço do próprio portal.

Permissões da API

As permissões são configuradas separadamente para cada área da API. Leitura e escrita podem ser controladas de forma independente.

Por exemplo, uma integração pode receber uma chave com permissão apenas para consultar relatórios, sem autorização para alterar dados da LMS.

As operações disponíveis dependem da área da API e das permissões atribuídas à chave.

Recursos disponíveis na API

Aulas

A API permite:

• listar;
• consultar;
• criar;
• alterar;
• excluir aulas.

Cursos

Para cursos, estão disponíveis:

• listagem;
• consulta;
• criação;
• alteração;
• exclusão.

Programas

Os programas podem ser:

• listados;
• consultados;
• criados;
• alterados;
• excluídos.

Testes

A API permite:

• listar testes;
• consultar testes;
• criar;
• alterar;
• excluir.

Atribuições

É possível gerenciar atribuições de conteúdos e programas:

• listar;
• consultar;
• criar;
• alterar;
• excluir.

Usuários

A API de usuários permite:

• listar e pesquisar;
• consultar;
• criar o perfil do usuário;
• criar uma conta com login;
• gerar um link de convite;
• alterar dados;
• alterar o departamento.

Esses usuários são usuários externos do Brusnika.LMS.

A API pública não cria usuários reais do Bitrix24 nem assentos no CRM. Ela cria usuários externos e contas dentro do portal correspondente da LMS.

A alteração via API é permitida somente para usuários cadastrados como usuários externos.

Não é possível excluir um usuário pela API. É possível desativá-lo, mantendo seu histórico de aprendizagem.

Ao criar usuários, pode ser aplicado o limite de assentos previsto pelo plano contratado.

Subcontas

A API permite:

• listar subcontas;
• consultar;
• criar;
• alterar;
• excluir.

Departamentos

É possível obter a lista de departamentos pela API.

Campos personalizados do perfil

A API permite:

• listar;
• consultar;
• criar;
• alterar;
• excluir campos personalizados.

Cadastros de referência

A API disponibiliza dados de referência, incluindo:

• modelos de certificados;
• categorias.

Arquivos

As operações disponíveis incluem:

• listar;
• enviar;
• obter;
• excluir arquivos.

API da base de conhecimento

A API pública também permite trabalhar com a base de conhecimento do Brusnika.LMS.

Pastas da base de conhecimento

É possível:

• listar pastas;
• obter a árvore de pastas;
• consultar uma pasta;
• obter os materiais de uma pasta;
• verificar onde uma pasta é utilizada;
• criar;
• alterar;
• excluir pastas.

Materiais da base de conhecimento

A API permite:

• listar;
• consultar;
• obter estatísticas de visualização;
• verificar onde o material é utilizado;
• criar;
• alterar;
• mover;
• excluir materiais.

Inscrições na base de conhecimento

É possível:

• listar inscrições;
• consultar inscrições;
• inscrever usuários;
• cancelar inscrições.

Assim, uma integração externa pode trabalhar com as partes suportadas da estrutura da base de conhecimento, seus materiais e inscrições.

Relatórios pela API

A API pública oferece cinco grupos principais de relatórios:

1. progresso de aprendizagem;
2. resultados de testes;
3. resultados da avaliação 360;
4. certificados emitidos;
5. respostas de pesquisas.

Os relatórios podem ser filtrados por:

• funcionário;
• objeto;
• status;
• datas;
• “alterado desde”.

Grandes conjuntos de resultados são retornados de forma paginada.

A paginação é importante para integrações que precisam buscar regularmente grandes volumes de dados, por exemplo para processamento em uma plataforma de BI.

Em pesquisas anônimas, os relatórios não contêm dados que identifiquem os respondentes.

Webhooks de saída

Os webhooks de saída permitem que o Brusnika.LMS envie uma notificação para um sistema externo quando ocorre um evento suportado.

Os eventos disponíveis incluem:

• alteração do status de conclusão;
• emissão de certificado;
• registro de resultado de teste;
• recebimento de resposta de pesquisa;
• alteração do status de uma avaliação 360.

Para os webhooks, é possível:

• criar assinaturas de eventos;
• testar a entrega;
• alterar o segredo.

As notificações só podem ser enviadas para endereços públicos protegidos.

Se a entrega falhar, o sistema tenta enviá-la novamente.

Os eventos não são necessariamente enviados imediatamente após a alteração. Os webhooks são ativados no servidor da instalação, e os eventos são identificados de acordo com o intervalo de consulta de alterações configurado. Se ocorrerem várias alterações de status durante o mesmo intervalo, elas podem ser entregues como uma única notificação.

Verificação de disponibilidade

A API possui uma função de verificação do estado do serviço.

Um sistema externo pode utilizar essa informação para monitorar a disponibilidade da interface de integração.

Onboarding automático a partir de um sistema de RH

Um cenário de uso da API é automatizar o onboarding de novos funcionários.

Por exemplo:

1. O sistema de RH registra uma nova contratação.
2. O sistema externo cria o usuário no Brusnika.LMS pela API.
3. O programa de integração é atribuído ao funcionário pela API.
4. O Brusnika.LMS envia um webhook quando um certificado é emitido.
5. O sistema de RH pode utilizar esse evento para registrar a conclusão da etapa correspondente.

O cenário utiliza recursos específicos da API: criação de usuário externo, atribuição de programa e notificações por webhook.

Exportação de resultados para BI

Outro cenário é enviar regularmente os dados de aprendizagem para uma plataforma de BI.

Por exemplo:

1. O administrador cria uma chave com permissão de leitura de relatórios.
2. A chave recebe validade de 365 dias.
3. A plataforma de BI consulta a API periodicamente.
4. O progresso de aprendizagem e os resultados dos testes são obtidos de forma paginada.
5. O sistema externo processa os dados recebidos.

A API não cria os dashboards ou análises de BI. Ela fornece os dados da LMS que estão disponíveis nos relatórios suportados.

Relação com outros recursos do Brusnika.LMS

A API pública está relacionada a vários recursos da LMS, incluindo:

• usuários;
• subcontas;
• departamentos;
• aulas;
• cursos;
• programas;
• testes;
• atribuições;
• base de conhecimento;
• certificados;
• pesquisas;
• avaliação 360;
• relatórios.

Dessa forma, a API pode funcionar como uma camada de integração entre o Brusnika.LMS e sistemas externos quando a operação necessária estiver disponível na área correspondente da API.

Brusnika.LMS junto com sistemas de negócio

O Brusnika.LMS pode ser utilizado junto com os sistemas de negócio em que os funcionários já trabalham. A API pública permite conectar a LMS a sistemas externos de RH, CRMs, sites e plataformas de BI.

No entanto, a existência de uma integração com determinado sistema não significa automaticamente que todos os recursos da API estejam disponíveis dentro dele. A possibilidade de cada cenário depende da integração correspondente e de sua implementação.

Também é importante diferenciar a API pública de outros mecanismos de integração.

Mecanismos de integração relacionados

“Chaves”

O Brusnika.LMS possui também o caminho Gerenciamento do sistema → Chaves, que contém identificadores do portal utilizados para integrações ou suporte.

Essas chaves não devem ser automaticamente consideradas iguais às chaves de acesso da API pública, que são criadas em Gerenciamento do sistema → API pública.

Webhooks de entrada do Bitrix24

Os webhooks de entrada do Bitrix24 permitem conectar uma LMS separada ao Bitrix24 sem instalar um aplicativo pelo Marketplace.

Esse é um mecanismo separado de integração, e não outra área da API pública do Brusnika.LMS.

Albato e Apify

Nas edições correspondentes, o Brusnika.LMS possui conectores para Albato e Apify. Eles são mecanismos relacionados de integração e não fazem parte da API pública da versão instalada.

Limitações e condições

Ao desenvolver uma integração, é importante considerar estas regras.

A API pública está atualmente em beta.

As chaves são vinculadas ao portal. Uma chave criada em um portal não pode ser usada em outro.

A API trabalha com usuários externos da LMS. Ela não cria usuários reais do Bitrix24 nem assentos no CRM.

Não é possível excluir usuários pela API. Eles podem ser desativados, mantendo seu histórico de aprendizagem.

A alteração pela API é permitida somente para usuários criados como externos.

A criação de usuários pode estar sujeita ao limite de assentos do plano.

Pesquisas anônimas não apresentam dados de identificação dos respondentes nos relatórios.

A entrega dos webhooks depende do mecanismo de consulta de alterações no servidor. Por isso, os eventos podem chegar com atraso e várias alterações de status ocorridas durante o mesmo intervalo podem ser entregues como uma única notificação.

O link de convite não está disponível na LMS separada. Nessa instalação, o acesso é feito com login e senha.

Configurações da API

As principais configurações estão em:

• Gerenciamento do sistema → API pública — criação e gerenciamento das chaves de acesso da API;
• Gerenciamento do sistema → Chaves — identificadores do portal utilizados em integrações ou para suporte.

A documentação da API está disponível no endereço do portal correspondente.

Perguntas frequentes

O que é a API pública do Brusnika.LMS?

É uma interface de programação que conecta o Brusnika.LMS a sistemas externos de RH, CRMs, sites e plataformas de BI e permite executar operações suportadas com dados e objetos da LMS.

Quem pode criar chaves de API?

O administrador do portal cria as chaves em Gerenciamento do sistema → API pública.

É possível limitar as permissões de uma chave?

Sim. As permissões de leitura e escrita podem ser configuradas separadamente para diferentes áreas da API.

É possível criar usuários pela API?

Sim. A API permite criar usuários externos e contas com login. Ela não cria usuários reais do Bitrix24 nem assentos no CRM.

É possível excluir um usuário pela API?

Não. O usuário pode ser desativado, mantendo seu histórico de aprendizagem.

É possível obter resultados de aprendizagem pela API?

Sim. A API disponibiliza relatórios de progresso, resultados de testes, avaliações 360, certificados emitidos e respostas de pesquisas.

É possível enviar dados de aprendizagem para BI?

Sim. Os relatórios suportados podem ser obtidos pela API, inclusive de forma paginada para grandes volumes de dados.

É possível receber notificações sobre alterações na LMS?

Sim. Os webhooks de saída podem informar alterações de status, emissão de certificados, resultados de testes, respostas de pesquisas e alterações de status da avaliação 360.

A API pública pode ser usada com o Bitrix24?

O Brusnika.LMS possui integração com sistemas de negócio, incluindo o Bitrix24, mas a disponibilidade de cada recurso da API depende da integração correspondente. A API pública não cria usuários do Bitrix24 nem assentos no CRM.

É possível usar a API com a base de conhecimento?

Sim. As operações suportadas incluem pastas, materiais e inscrições da base de conhecimento.

Qual é a validade de uma chave de API?

A chave pode não ter prazo de expiração ou pode expirar em 30, 90 ou 365 dias.

A chave de API pode ser visualizada novamente depois da criação?

O valor da chave é exibido uma única vez durante a criação. Depois, o administrador pode ver o status da chave na lista, mas o valor secreto não é exibido novamente.

Resumo

A API pública do Brusnika.LMS é uma interface de integração em beta para conectar a LMS a sistemas de RH, CRMs, sites e plataformas de BI. Ela permite executar operações suportadas com usuários, conteúdos, atribuições e base de conhecimento, além de consultar relatórios de aprendizagem. Webhooks de saída permitem notificar sistemas externos sobre alterações de aprendizagem, certificados, resultados de testes, pesquisas e avaliações 360.