API: Como criar e atualizar usuários

A API do Learning.Rocks dispõe de endpoints para a criação e atualização de usuários. Clicando aqui você pode acessar a collection completa de users.

Como criar usuários

Para criar um usuário, é necessário enviar um comando POST para a seguinte URL: https://knowledge.skore.io/workspace/v1/users

No momento da criação, algumas informações são obrigatórias, enquanto outras são opcionais.

As informações obrigatórias que devem constar no body da requisição são:

• name: Nome do usuário na plataforma;
• email: campo identificador preenchido com o e-mail do usuário;
• username: Campo identificador alternativo, que pode ser preenchido com qualquer informação, desde que exclusiva e não repetida entre os usuários (ex.: CPF ou matrícula da empresa).

Além das informações obrigatórias, existem outros campos do perfil que podem ser preenchidos conforme a necessidade do projeto:

• password: Senha de acesso à plataforma, que pode ser alterada após o primeiro login.
  • Se não for preenchido, o usuário deverá acessar via SSO ou clicar em “Esqueci minha senha” para redefinir a senha por e-mail.
• role: Define a permissão do usuário — pode ser student, expert ou admin.
  • Se não for preenchido, o usuário será criado com a permissão padrão student.
• language: Define o idioma da plataforma para o usuário — pode ser en-US, pt-BR ou es-ES.
  • Se não for preenchido, será considerado o idioma padrão do ambiente.
• leaders: Define quem são os líderes do usuário, que terão acesso aos relatórios de uso do liderado.
  • Um usuário pode ter múltiplos líderes.
  • São aceitos como identificadores: id, email ou username.
  • É possível enviar os três tipos de identificadores na mesma requisição.
• metadata: define os metadados do usuário. Para preencher esses dados, é importante que o metadado já esteja previamente criado no Gestor de Dados da plataforma.
  O envio deve ser feito em formato JSON ou string, listando o nome do metadado e, na sequência, seu valor.

É importante enviar o nome do metadado sempre em caixa baixa, sem acentuação e com “_” no lugar de espaços.

Exemplo: "metadata": {"cpf": "00000000000", "cargo": "analyst", "departamento": "product", "filial": "são paulo", "data_de_admissao": "01/01/2024"}

• team_ids: Definição de quais times o usuário fará parte. É necessário identificar o time pelo seu id, que pode ser obtido com um “Get All Teams”, presente na collection de Teams, ou então nos relatórios da plataforma. Exemplo: “team_ids”: [12546, 58795]

Exemplo de body para a criação de um usuário:

Se a criação ocorrer corretamente, você receberá o retorno “200 OK”, e uma response com detalhes da criação e informações do usuário, conforme exemplo abaixo:

Como atualizar usuários

Abaixo estão descritos os comandos que podem ser utilizados para atualizar usuários. Entretanto, nem todos os campos precisam (ou devem) ser enviados em todas as requisições. Envie apenas os campos que você deseja atualizar, pois os comandos seguem uma lógica de sobrescrita de informações.

Se você não deseja alterar o valor de um campo, não o inclua no body da requisição. Caso envie o campo com valor vazio, como no exemplo abaixo:

• “username”: “”,

A API interpretará que o campo deve ser apagado, deixando o valor em branco — e não que você deseja mantê-lo inalterado.

Para atualizar um usuário, é necessário enviar um comando PATCH para a seguinte URL: https://knowledge.skore.io/workspace/v1/users/30386

O último número da URL corresponde ao ID do usuário na plataforma LXM. Esse ID pode ser obtido de três maneiras:

• Nos relatórios da plataforma;
• Na response da API, logo após a criação do usuário;
• Ou enviando um GET no endpoint “List Users v2”, disponível em: https://knowledge.skore.io/workspace/v2/users.

As informações que podem ser atualizadas no perfil de um usuário são:

• name: nome do usuário na plataforma;
• email: campo identificador preenchido com o e-mail do usuário;
• username: campo identificador alternativo, que pode ser preenchido com qualquer informação, desde que exclusiva e não repetida entre os usuários (ex.: CPF ou matrícula da empresa);
• password: senha de acesso à plataforma, que pode ser alterada após o login;
• active: status do usuário na plataforma — utilizado para inativar ou reativar usuários.
  • false → usuário inativo;
  • true → usuário ativo;
• role: permissão do usuário. Pode ser student, expert ou admin;
• language: define o idioma da plataforma para o usuário. Pode ser en-US, pt-BR ou es-ES;
• leaders: define quem são os líderes do usuário, que terão acesso aos relatórios de uso do liderado.
  • Um usuário pode ter múltiplos líderes;
  • São aceitos como identificadores: id, email ou username.

• metadata: define os metadados do usuário.
  • É importante que os metadados já estejam criados no Gestor de Dados da plataforma;
  • O envio deve ser feito em formato JSON ou string, listando o metadado e seu respectivo valor;
  • O nome do metadado deve ser enviado em caixa baixa, sem acentuação e com “_” no lugar de espaços.

Exemplo: "metadata": {"cpf": "00000000000", "cargo": "analyst", "departamento": "product", "filial": "são paulo", "data_de_admissao": "01/01/2024"}

• Team_ids: Define os times dos quais o usuário fará parte. É necessário identificar cada time pelo seu ID, que pode ser obtido por meio de um “Get All Teams” (disponível na collection “Teams”) ou nos relatórios da plataforma. Exemplo: “team_ids”: [12546, 58795]

Exemplo de body para a atualização de um usuário:

Se a atualização ocorrer corretamente, você receberá o retorno “200 OK”, e uma response com detalhes da atualização e informações do usuário, conforme exemplo abaixo: