Documentação para Integração de Usuários

Modificado em Sex, 30 Ago, 2024 na (o) 10:17 AM

Pré-requisito (IMPORTANTE)

Para utilização dos serviços da API da Engage é necessário ter em mãos os parâmetros abaixo:

username;
password;
customer_id;
customer_token;
client_id;
client_secret.

Para gerar estes parâmetros, siga os procedimentos descritos neste tutorial. Caso tenha alguma dúvida ou enfrente qualquer problema para obtê-los, entre em contato com o Suporte Técnico da Engage através do endereço meajuda@engage.bz

Por fim, é extremamente recomendado que os testes e desenvolvimento da integração sejam feitos utilizando nosso ambiente de HOMOLOGAÇÃO. Aponte a integração para o ambiente produtivo da Engage somente quando ela estiver concluída, testada e homologada.

1. Ambiente de Homologação

Para desenvolvimento e testes de integração com a plataforma Engage, é disponibilizada abaixo a URL do ambiente de homologação:

https://sandbox.engage.bz/api/v1/

2. Ambiente de Produção

https://my.engage.bz/api/v1/

3. Autenticação

Para obter acesso aos dados disponibilizados pelos serviços da API é necessário fazer a autenticação utilizando o access_token enviado. Como o serviço utiliza o tipo de autenticação HTTP Bearer, o token de acesso deverá ser inserido na propriedade Authorization do cabeçalho HTTP, conforme exemplo abaixo:

Authorization Bearer {access_token}

OBS.: A palavra Bearer deve ser adicionada antes do token e separada por um espaço.

4. POST /auth

Este método deve ser utilizado nos seguintes cenários:

Nos casos em que o login é efetuado no próprio site
Para executar métodos que necessitam de autenticação.

Para acessar os métodos que necessitam de autenticação é preciso enviar o parâmetro access_token como argumento para as requisições, ou guardar o cookie gerado a partir deste método e utilizá-lo nas requisições seguintes.

OBS.: O access_token tem um tempo de vida de 25 minutos. Transcorrido este tempo, ele expira e o acesso aos endpoints é negado – devolvendo o status HTTP 401- Unauthorized – sendo necessário renová-lo a partir de uma nova chamada a este endpoint.

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetro	Tipo	Obrigatório	Valor Padrão	Descrição
grant_type	String	Sim	password	Como a autenticação se dará por usuário e senha, o grant_type a chamada deverá enviar o valor password para este parâmetro.
username	String	Sim	-	Login do usuário.
password	String	Sim	-	Senha do respectivo usuário.
client_id	String	Sim	-	ID da aplicação que está se integrando ao Engage. Esta informação será fornecida pela equipe da Engage.
client_secret	String	Sim	-	Senha da aplicação que está se integrando ao Engage. Esta informação será fornecida pela equipe da Engage.
customer_id	String	Sim	-	ID da instância que representa o ambiente do cliente. Esta informação será fornecida pela equipe da Engage.

OBS: O Content-Type dos parâmetros acima deve ser: application/x-www-form-urlencoded, conforme exemplo abaixo feito através do software Postman:

Retornos:

Em caso de sucesso, o retorno será semelhante ao JSON abaixo:

{

"access_token": "dskdmkdnfi3948339w",

"token_type": "bearer",

"expires_in": 1499,

"client_id": "my_client_id",

"customer_id": "customer_id",

"user_id": "1",

".issued": "Fri, 11 Aug 2018 20:06:53 GMT",

".expires": "Fri, 11 Aug 2018 20:31:53 GMT"

}

Em caso de falha, o retorno será semelhante ao JSON abaixo:

{

"error": "error_code",

"error_description": "This is an error."

}

5. Usuários

5.1. POST {customerId}/users

Este serviço deve ser utilizado para criar novos usuários e/ou editar usuários no LMS Engage. É importante ressaltar que o sistema faz a checagem de existência do usuário através da propriedade login enviado no array users de cada objeto user no JSON.

Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão UserManagement, ou seja, durante a chamada a este método, é obrigatório o envio do access_token no Header da requisição de algum usuário que possua esta permissão de acesso. Para maiores detalhes, consulte o capítulo Autenticação.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization: Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro	Tipo do Parâmetro	Tipo do Dado	Obrigatório	Descrição
customerId	Path	String	Sim	Id da instância que compõe a rota do endpoint. Esta informação será fornecida pela equipe da Engage.
customerToken	Query	String	Sim	O Token que representa a instância. Este parâmetro deve ser enviado por questões de segurança, visando manter a integridade dos dados. Esta informação é fornecida pela equipe da Engage e deve ser armazenada pela aplicação terceira em local seguro.
users	Body	Array	Sim	Deve ser enviado um array de objetos no corpo da requisição, conforme exemplo abaixo: [ { "name": "string", "document": "string" "email": "string", "login": "string", "status": true, "blocked": false, "groups": [ 0 ], "tracks": [ { "track_id": 0, "game_profile_id": 0 } ], "attributes": [ { "campo_adicional": "string", } ] } ] OBS: Content-Type deste parâmetro deve ser application/json,

Onde:

Parâmetro	Tipo de Dado	Obrigatório	Único	Descrição
name	String	Sim	Não	Nome completo do usuário que será criado/editado
email	String	Não	Sim	E-mail do usuário
document	String	Não	Sim	CPF do usuário (caso Brasil) ou qualquer outro documento caso não seja Brasi
login	String	Sim	Sim	Login do usuário, é através desta informação que o usuário se autentica no sistema – seja através de senha ou por meio de SSO.
status	Booleano	Sim	Não	Indica se o usuário está ativo ou não no sistema. true representa que o usuário está ativo false representa que o usuário está inativo.
blocked	Booleano	Não	Não	Indica se o usuário está bloqueado. Quando ativada, esta opção faz com que o usuário não consiga logar na plataforma. true representa que o usuário está bloqueado false representa que o usuário está desbloqueado. Importante: Se esta propriedade não for informada no JSON o valor padrão será false, indicando que o usuário não está bloqueado.
groups	Array	Sim	Não	Array de inteiros, que contém os Ids dos grupos nos quais o usuário precisará ser vinculado. Para maiores detalhes sobre a consulta de grupos, consultar o capítulo 7.2
tracks	Array	Não	Não	Array que representa em qual trilha o usuário será alocado e seu respectivo perfil: [ { "track_id": 0, "game_profile_id": 0 } ] Onde: track_id: O id da trilha na qual o usuário estará vinculado. game_profile_id: Indica o perfil do usuário na trlha, onde: Se o usuário tiver que pontuar nos módulos e o treinamento for obrigatório, enviar 1 (indica que ele terá o perfil obrigatório) Se o usuário tiver que pontuar nos módulos, enviar 2 (indica que ele terá o perfil participa) Se o usuário não precisar pontuar no game da trilha, enviar 3 (indica que ele será gestor na trilha e não pontuará)
attributes	Array	Não	Não	Array que representa os campos adicionais que serão atribuídos ao usuário. [ { "campo_adicional": "valor do campo adicional" } ] Onde: campo_adicional : Código do campo adicional cadastrado na plataforma. O valor do campo adicional é o dado que será atribuído ao usuário. No exemplo a seguir é apresentado como esse array deve ser enviado para cada usuário: [ { "cargo":"Recepcionista" }, { "matricula":11111 }, { "data_nascimento": "25-09-1996" } ]

Segue abaixo um exemplo de como a chamada para este endpoint deve ser realizada:

Retornos:

Em caso de sucesso – HTTP 200 (OK) – o retorno será semelhante ao JSON abaixo:

{

"count": 2,

"results": [

{

"record_number": 2,

"success": true,

"messages": [

“Operação realizada com sucesso”

]

{

"record_number": 1,

"success": false,

"messages": [

"O login do usuário é obrigatório",

“O nome do usuário é obrigatório”

]

}

Onde:

Parâmetro	Tipo de Dado	Descrição
count	Inteiro	Total de logs retornados após a conclusão do processo.
results	Array	Coleção que informa, por item do array, o resultado do processamento de cada registro enviado à API.
record_number	Número Inteiro	É o mesmo índice do registro que foi enviado no array de entrada (parâmetro users).
success	Booleano	true quando o registro foi processado com sucesso. Caso contrário, retorna false.
messages	Array	Contém informações sobre o resultado do processamento de cada registro. (Sejam eles mensagens de erros ou informação de sucesso).

Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "unauthorized",

"message": "Você não está autorizado a acessar este recurso."

}

]

}

6. Ambientes

6.1. GET {customerId}/competitions

Este serviço retorna a lista de cambientes disponíveis na plataforma da Engage.

Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão GameManagement, ou seja, durante a chamada a este método, é obrigatório o envio do access_token no Header da requisição de algum usuário que possua esta permissão de acesso. Para maiores detalhes, consulte o capítulo Autenticação.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro	Tipo do Parâmetro	Tipo do Dado	Obrigatório	Descrição
customerId	Path	String	Sim	Id da instância que compõe a rota do endpoint.
skip	Query	Inteiro	Não	Número da página.
take	Body	Inteiro	Não	Tamanho da página. Se não for informada os 10 primeiros items serão retornados.

Retornos:

Em caso de sucesso – HTTP 200 (OK) – o retorno será semelhante ao JSON abaixo:

{

"count": 2,

"results": [

{

" competition_id": 1,

“name”: “Nome do ambiente”,

“description”: “Descrição do ambiente”,

“available”: true

}

]

}

]

}

Onde:

Parâmetro	Tipo de Dado	Descrição
count	Inteiro	Total de itens retornados de acordo com o resultado da pesquisa.
results	Array	Coleção que informa, por item do array, todas os ambientes retornadas pela pesquisa.
competition_id	Inteiro	Id do ambiente.
name	String	Nome do ambiente.
description	String	Descrição do ambiente
available	Boleano	Indica se o ambiente está ativa (true) ou inativa (false)

Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "Não encontrado.",

"message": "Sua pesquisa não retornou resultados.",

"data_occurred": "2017-08-21T13:45:14.2586346-03:00"

}

]

}

6.2. GET {customerId}/competitions/{competitionId}/tracks

Este serviço retorna a lista de trilhas vinculadas aos ambientes informada.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro	Tipo do Parâmetro	Tipo do Dado	Obrigatório	Descrição
customerId	Path	String	Sim	Id da instância que compõe a rota do endpoint.
competitionId	Path	Inteiro	Sim	Id do ambiente que deseja-se obter a lista de trilhas.

Retornos:

Em caso de sucesso – HTTP 200 (OK) – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"results": [

{

"track_id": 1732,

"description": "Minha Trilha",

"status": true,

"is_visible": true,

"type_id": "customhtml",

]

}

Onde:

Parâmetro	Tipo de Dado	Descrição
count	Inteiro	Total de itens retornados de acordo com o resultado da pesquisa.
results	Array	Coleção que informa, por item do array, todas as trilhas vinculadas ao ambiente
track_id	Inteiro	ID da trilha.
description	String	Nome da trilha
status	Boleano	Indica se a trilha está ativa (true) ou inativa (false)
is_visible	Boleano	Indica se a trilha está visível (true) ou invisível (false)
type_id	String	Tipo da trilha. Se é customhtml, lista ou library

Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "Não encontrado.",

"message": "Sua pesquisa não retornou resultados.",

"data_occurred": "2017-08-21T13:45:14.2586346-03:00"

}

]

}

6.3. POST {customerId}/competitions

Este serviço deve ser utilizado para criar novos ambientes no Engage. Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão GameManagement, ou seja, durante a chamada a este método, é obrigatório o envio do access_token no Header da requisição de algum usuário que possua esta permissão de acesso. Para maiores detalhes, consulte o capítulo Autenticação.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization: Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro	Tipo do Parâmetro	Tipo do Dado	Obrigatório	Descrição
customerId	Path	String	Sim	Id da instância que compõe a rota do endpoint. Esta informação será fornecida pela equipe da Engage.
competition	Body	Objeto	Sim	Deve ser enviado um objeto JSON no corpo da requisição, conforme exemplo abaixo: { "name": "string", "description": "string" } OBS: Content-Type deste parâmetro deve ser application/json

Onde:

Parâmetro	Tipo de Dado	Obrigatório	Único	Descrição
name	String	Sim	Não	Nome do ambiente
description	String	Não	Sim	Descrição do ambiente

Retornos:

Em caso de sucesso – HTTP 200 (OK) – o retorno será idêntico ao JSON abaixo *:

{

"competition_id": 100,

"name": "Ambiente 1",

"description": “Meu ambiente - Descrição”,

"available": true,

“is_visible”: true

}

Onde:

Parâmetro	Tipo de Dado	Descrição
competition_id	Inteiro	ID gerado, após a criação do ambiente
name	String	Nome do ambiente
description	String	Descrição do ambiente
available	Booleano	Status do ambiente. true, ativo. false, inativo.
is_visible	Booleano	true, se o ambiente estiver visível para o usuário. false, invisível para o usuário.

* A API devolve mais campos, porém os principais são estes. Os demais são controles usados no sistema, que são gerados automaticamente.

Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "unauthorized",

"message": "Você não está autorizado a acessar este recurso."

}

]

}

6.4. PUT {customerId}/competitions/{competitionId}

Este serviço deve ser utilizado para editar ambientes existentes ambientes no Engage. Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão GameManagement, ou seja, durante a chamada a este método, é obrigatório o envio do access_token no Header da requisição de algum usuário que possua esta permissão de acesso. Para maiores detalhes, consulte o capítulo Autenticação.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization: Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro	Tipo do Parâmetro	Tipo do Dado	Obrigatório	Descrição
customerId	Path	String	Sim	Id da instância que compõe a rota do endpoint. Esta informação será fornecida pela equipe da Engage.
competitionId	Path	Inteiro	Sim	ID do ambiente que se pretende editar, compondo a rota do endpoint.
competition	Body	Objeto	Sim	Deve ser enviado um objeto JSON no corpo da requisição, conforme exemplo abaixo: { "name": "string", "description": "string" } OBS: Content-Type deste parâmetro deve ser application/json

Onde:

Parâmetro	Tipo de Dado	Obrigatório	Único	Descrição
name	String	Sim	Não	Nome do ambiente
description	String	Não	Sim	Descrição do ambiente

Retornos:

Em caso de sucesso – HTTP 204 (No Content)
Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "unauthorized",

"message": "Você não está autorizado a acessar este recurso."

}

]

}

7. Grupos

7.1. POST {customerId}/groups

Este serviço deve ser utilizado para criar novos grupos na plataforma Engage. Grupos que são utilizados para agrupar usuários seguindo os critérios de negócio definidos pelo cliente – que podem no formato de departamentos, equipes, etc.

Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão GroupManagement, ou seja, durante a chamada a este método, é obrigatório o envio do access_token no Header da requisição de algum usuário que possua esta permissão de acesso. Para maiores detalhes, consulte o capítulo Autenticação.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro	Tipo do Parâmetro	Tipo do Dado	Obrigatório	Descrição
customerId	Path	String	Sim	Id da instância que compõe a rota do endpoint. Esta informação será fornecida pela equipe da Engage.
customerToken	Query	String	Sim	O Token que representa a instância. Este parâmetro deve ser enviado por questões de segurança, visando manter a integridade dos dados. Esta informação é fornecida pela equipe da Engage e deve ser armazenada pela aplicação terceira em local seguro.
groups	Body	Array	Sim	Deve ser enviado um array de objetos no corpo da requisição, conforme exemplo abaixo: [ { "name": "string", "description": "string", "external_code": "string", "parent_code": "string", "status": “boolean”, "competitions": [ 0 ] } ] OBS: Content-Type deste parâmetro deve ser application/json

Onde:

Parâmetro	Tipo de Dado	Obrigatório	Único	Descrição
name	String	Sim	Não	Nome do grupo.
description	String	Não	Sim	Descrição do grupo
external_code	String	Sim	Sim	Identificador do grupo. Este dado que é utilizada para criar grupos, editar grupos existentes e pode ser utilizado para fazer buscas por grupos já cadastrados previamente.
parent_code	String	Não	Não	Código externo do grupo imediatamente superior ao grupo que se pretende criar e/ou editar. Caso o grupo seja raiz na hierarquia basta passar vazio para esta propriedade.
status	Booleano	Sim	Não	Indica se o grupo está ativo ou não no sistema. true representa que o grupo está ativo false representa que o grupo está inativo.
competitions	Array	Não	Não	Array de inteiros, que contém os Ids das ambientes que deverão estar vinculadas ao grupo. Para maiores detalhes de como obter a lista de ambientes, consulte o capítulo 5.

Retornos:

Em caso de sucesso – HTTP 200 (OK) – o retorno será semelhante ao JSON abaixo:

{

"count": 2,

"results": [

{

"record_number": 1,

"success": false,

"messages": [

"O código externo do grupo é obrigatório",

]

{

"record_number": 2,

"success": true,

"messages": [

“Operação realizada com sucesso”

]

}

Onde:

Parâmetro	Tipo de Dado	Descrição
count	Inteiro	Total de logs retornados após a conclusão do processo.
results	Array	Coleção que informa, por item do array, o resultado do processamento de cada registro enviado à API.
record_number	Inteiro	É o mesmo índice do registro que foi enviado no array de entrada (parâmetro groups).
success	Booleano	true quando o registro foi processado com sucesso. Caso contrário, retorna false.
messages	Array	Contém informações sobre o resultado do processamento de cada registro. (Sejam eles mensagens de erros ou informação de sucesso).

Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "unauthorized",

"message": "Você não está autorizado a acessar este recurso."

}

]

}

7.2. GET {customerId}/groups/externalCodes/{externalCodes}

Este serviço deve ser utilizado para consultar os grupos a partir do código externo que é definido no cadastro do mesmo na área administrativa ou via API REST.

Para consumir este serviço, é necessário estar autenticado, ou seja, durante a chamada a este método, é obrigatório o envio do access_token no Header da requisição. Para maiores detalhes, consulte o capítulo Autenticação.

Abaixo, segue um exemplo de como o token de acesso deve ser enviado no Header da requisição.

Authorization: Bearer {access_token}

Abaixo, seguem descritos os parâmetros que devem ser enviados na requisição.

Parâmetros de Entrada:

Parâmetro

Tipo do Parâmetro

Tipo do Dado

Obrigatório

Descrição

customerId

Path

String

Sim

Id da instância que compõe a rota do endpoint. Esta informação será fornecida pela equipe da Engage.

externalCodes

Query

Array

Sim

Códigos externos dos grupos que devem ser pesquisadas. Para se filtrar mais de um grupo, deve-se passar os códigos separados por vírgula, como no exemplo abaixo:

EX:

externalCodes=trilha1,trilha2

Retornos:

Em caso de sucesso – HTTP 200 (OK) – o retorno será semelhante ao JSON abaixo:

{

"count": 2,

"results": [

{

"group_id": 9518,

"parent_group_id": null,

"name": "Superior",

"description": "Superior",

"status": true,

"external_code": "superior"

{

"group_id": 9517,

"parent_group_id": null,

"name": "Técnico",

"description": "Técnico",

" status ": true,

"external_code": "tecnico"

}

]

}

Onde:

Parâmetro	Tipo de Dado	Descrição
count	Inteiro	Total de itens retornados de acordo com o resultado da pesquisa.
results	Array	Coleção que informa, por item do array, todos os relacionamentos para as atividades informadas no parâmetro externalCodes.
group_id	Inteiro	Código externo do módulo que foi filtrada na requisição.
parent_group_id	Inteiro	ID do grupo superior, se houver.
name	String	Nome do grupo
description	String	Descrição do grupo.
status	Booleano	Status do grupo. true: Grupo Ativo false: Grupo inativo.
external_code	String	Código externo do grupo.

Em caso de falha – HTTP 400 (BadRequest), 404 (NotFound), etc – o retorno será semelhante ao JSON abaixo:

{

"count": 1,

"errors": [

{

"error_code": "Não encontrado.",

"message": "Sua pesquisa não retornou resultados.",

"data_occurred": "2018-08-21T13:45:14.2586346-03:00"

}

]

}