Documentação para Recebimento de Treinamentos Realizados em Outras Plataformas para a Engage

Modificado em Qui, 25 Jul na (o) 7:29 PM

1. 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.

2. 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/

3. Ambiente de Produção

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

4. 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.1 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 2017 20:06:53 GMT",

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

}

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

{

"error": "error_code",

"error_description": "This is an error."

}

4.2. Permissões de Acesso

Os acessos aos métodos da API são autorizados com base nas permissões que um determinado possui. Por exemplo, para acessar determinados endpoints, não basta apenas estar autenticado, mas, também, possuir permissão de acesso ao recurso. Por exemplo, para efetuar cadastros de usuários é necessária permissão “UserManagement” no sistema. Abaixo, segue a lista das principais permissões do sistema.

UserManagement:
ScoreManagement:
GameManagement:
GroupManagement:
AchievementManagement:

5. Pontuações

5.1 POST {customerId}/answers

Este serviço deve ser utilizado para importar para a plataforma Engage os históricos de treinamentos realizados pelos usuários em sistemas de terceiros. Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão ScoreManagement, 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}

Atenção: Para que a integração de pontuações funcione corretamente, é necessário que os vínculos entre Usuário x Grupo, Ambiente x Grupo e Usuário x Trilha estejam devidamente e corretamente configurados dentro do Engage. Para maiores informações, contate a equipe de Suporte da Engage.

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.
scores	Body	Array	Sim	Deve ser enviado um array de objetos no corpo da requisição, conforme exemplo abaixo: [ { "competition_code": "string", "round_code": "string", "activity_code": "string", "user_login": "string", "dissertative_answer" : "string", "score": “double”, "answer_date": "dateTime" } ] OBS: Content-Type deste parâmetro deve ser application/json

Onde:

Parâmetro	Tipo de Dado	Obrigatório	Descrição
competition_code	String	Sim	ID do ambiente, previamente vinculado usuário.
round_code	String	Não	ID do módulo, previamente vinculado ao usuário.
activity_code	String	Sim	ID da atividade. Neste caso, a atividade aqui se refere ao treinamento realizado na plataforma terceira. Aqui é necessário enviar o ID da atividade no Engage.
user_login	String	Sim	Campo chave do usuário (login)
dissertative_answer	String	Não	Para respostas do tipo dissertativa é necessário enviar o texto da resposta. Caso não seja uma resposta dissertativa, enviar vazio (“”).
score	Double	Não	Pontuação do usuário obtida no treinamento – entre 0 e 100. Se for enviar decimais, utilizar “.” ao invés de “,” EX: 94.5
answer_date	DateTime	Não	Data de conclusão da atividade. Deve ser enviada no formato “dd/MM/yyyy hh:mm:ss” (sem aspas)

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 ambiente informada não existe no sistema ou encontra-se inativa",

“A atividade não encontra-se associada às respectivos modulos e ambiente”

]

{

"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 scores).
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."

}

]

}