Antes de utilizar este serviço é necessário que o desenvolvedor valide com o time de Recursos Humanos o que significa, para eles, o termo treinamento pois, pela nossa experiência, alguns clientes entendem como treinamento:

• O módulo;
• A trilha de aprendizagem;
• Ou o ambiente.

Como esta é uma API genérica, que atende a todos estes cenários, é necessária esta definição antes de iniciar os trabalhos de desenvolvimento.

Além disso, 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.

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

3.     Ambiente de Produção

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

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.

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

1. Nos casos em que o login é efetuado no próprio site
2. 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.

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: 

{

    "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"

}

{

    "error": "error_code",

    "error_description": "This is an error."

}

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.    Históricos

5.1. POST {customerId}/attempts/historyData

Este serviço deve ser utilizado para consultar o andamento dos treinamentos realizadas pelos usuários. Através deste serviço é possível obter dados de um ou mais usuários em diversos treinamentos bem como filtrar pelo status de realização do treinamento.

Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão CertificateManagement, 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 obrigatórios e opcionais que podem ser enviados na requisição.

Onde:  

Importante: É extramamente recomendado o uso o filtro de datas para reduzir o volume de dados e acelerar a pesquisa

Exemplo de chamada para consulta dos treinamentos realizados pelos usuários.

Retornos: 

{

   "count": 0,

   "results": [

     {

               "user_id": 175933,

            "user_name": "João da Silva",

            "user_login": "joao.silva",

 "course_id": "44041",

            "entity_type_id": "RD",

            "course_name": "modulo 01",

            "course_external_code": "mission_01",

            "progress": 100.0,

            "score": 100.0,

            "first_start_date": "2021-10-01T07:28:14.063-03:00",

            "finalization_date": "2021-10-02T14:22:22.267-03:00"           

    }

  ]

}

Onde:

{

     "count": 1,

     "errors": [

         {

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

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

            "data_occurred": "2021-11-11T13:45:14.2586346-03:00"

         }

     ]

}