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:
2. Ambiente de Produção
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."
}
4.1. 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.1 GET/{customerId}/attributes
O endpoint acima retorna a lista de campos personalizados, que chamamos de atributos, cadastrados no ambiente do cliente, como por exemplo, empresa e cargo. A propriedade atribute_id precisará ser enviada no endpoint para cadastrar o campo personalizado no cadastro do usuário.
ONDE:
- customerId: É o ID do ambiente do cliente;
RETORNO:
{
"count": 2,
"results": [
{
"attribute_id": 67,
"guid": "62364127-93ac-40e7-8a1d-e767927d40a2",
"attribute_type": {
"attribute_type_id": 1,
"guid": "241d4ace-1d28-4569-b6f6-704ee8a8eeca",
"name": "TEXT",
"status": true,
"languages": [
{
"language_id": "pt-BR",
"text": "Texto"
}
]
},
"name": "cargo",
"status": true,
"values": [],
"languages": [
{
"language_id": "es-ES",
"text": "Puesto"
}
]
}
]
}
5.2 POST: {customerId}/users/importAttributes/import
- 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. |
importAttributes | Body | Array | Sim | Deve ser enviado um array de objetos no corpo da requisição, conforme exemplo abaixo: [ { "Login": "string", "campo_adicional": "string", } ] OBS: Content-Type deste parâmetro deve ser application/json. O parâmetro campo_adicional é referente ao nome do campo adicional cadastrado na plataforma, e o seu tipo, pode variar de acordo com o tipo do campo adicional cadastrado (por exemplo: "cargo_na_empresa":"Recepcionista", ou, "idade_colaborador":25) ou "data_nascimento" : "25-09-1996" |
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 campo personalizado não existe na plataforma; Campo = nomeCampo",
"O login do usuário não existe na base de dados"
]
}
}
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo