Documentação para Obtenção de Conquistas Desbloqueadas por Usuário

Modificado em Qui, 25 Jul, 2024 na (o) 6:52 PM

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.

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.

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

}

3.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:

4. Conquistas obtidas pelos usuários

4.1. GET {customerId}/achievements/userAchievements

Este serviço deve ser utilizado para consultar as conquistas desbloqueadas, ou obtidas, pelos usuários à medida que vão realizando os módulos na plataforma, sendo possível a filtragem por ambiente, período e/ou status dos usuários.

Para consumir este serviço, é necessário estar autenticado com um usuário que possua a permissão AchievementManagement, 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.

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.
userLogin	Query	String	Não	Login do usuário que deseja filtrar. Se este parâmetro não for informado, todos os usuários serão retornados.
competitionId	Query	Inteiro	Não	ID do ambiente vinculada às conquistas que se pretende filtrar. Se não for informado nenhum ambiente, todas as conquistas serão retornadas.
startDate	Query	DateTime	Não	Data de início na qual se quer filtrar as conquistas obtidas a partir da data informada. Se não for informado nenhuma data, todas as conquistas serão retornadas.
endDate	Query	DateTime	Não	Data final na qual se quer filtrar as conquistas obtidas até a data informada Se não for informado nenhuma data, todas as conquistas serão retornadas.
userStatus	Query	String	Não	O status do usuário que se quer filtrar. Os valores aceitos são: active - Apenas usuários ativos serão retornados. Se não for informado, este será o valor padrão. inactive - Apenas usuários inativos serão retornados all – Retorna todos os usuários – ativos e inativos que concluiram

Retornos:

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

{

"count": 649,

"results": [

{

"user_id": 323136,

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

"user_login": "joao.silva",

"achievement_id": 3757,

"achievement_name": "Medalha de Ouro",

"achievement_description": " Medalha de Ouro ",

"acquired_date": "01/02/2021 16:18",

"expire_date": "31/12/2100 23:59",

"competition_id": 5347,

"competition_name": "Game Engage",

“achievement_icon”: “https://s3.engage.bz/client/conquistas/achievement.png”

}

]

}

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 contém os dados sobre o andamento do aluno no módulo.
user_id	Inteiro	ID do usuário no Engage.
user_name	String	Nome completo do usuário que obteve a conquista
user_login	Decimal	Login – campo utilizado para autenticação no Engage – do usuário
achievement_id	Inteiro	Id da conquista que usuário conquistou
achievement_name	Date	Nome da conquista obtida pelo usuário
achievement_description	Date	Descrição da conquista obtida pelo usuário
acquired_date	String	Data de aquisição da conquista, sempre no formato dd/MM/yyyy HH:mm
expire_date	String	Data de Expiração da conquista. Como, atualmente, no Engage as conquistas não têm prazo de expiração, é enviado sempre o valor fixo 31/12/2100 23:59 - formato dd/MM/yyyy HH:mm
competition_id	Inteiro	Id do ambiente na qual a conquista está vinculada
competition_name	String	Nome do ambiente
achievement_icon	String	Endereço completo da imagem referente a conquista desbloqueada pelo usuário

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": "2019-02-04T13:45:14.2586346-03:00"

}

]

}

Este artigo foi útil?