API Passo 2 - Obtendo o Bearer Token

Modificado em Ter, 12 Nov na (o) 4:02 PM

Abaixo está um guia passo a passo para auxiliar na integração com a API da Engage, incluindo pré-requisitos, detalhes dos ambientes de desenvolvimento e produção, autenticação e especificações do método POST /auth.

Pré-requisitos (IMPORTANTE)

Antes de iniciar a integração com a API da Engage, você precisará dos seguintes parâmetros:

username: login do usuário;
password: senha do usuário;
customer_id: ID que representa o ambiente do cliente;
customer_token: token único da instância do cliente;
client_id: ID da aplicação que está se integrando ao Engage;
client_secret: chave secreta da aplicação.

Para obter esses parâmetros, siga as instruções fornecidas neste tutorial de configuração. Caso tenha dúvidas ou dificuldades para obtê-los, entre em contato com o Suporte Técnico da Engage pelo e-mail: meajuda@engage.bz.

Recomendação: Realize todos os testes e desenvolvimentos da integração no ambiente de homologação da Engage. A integração só deve ser direcionada ao ambiente de produção após a conclusão dos testes.

1. Ambiente de Homologação

Para o desenvolvimento e testes de integração, utilize o ambiente de homologação:

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

2. Ambiente de Produção

Após a homologação da integração, utilize o ambiente de produção para a operação real:

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

3. Autenticação

Para acessar os dados da API, é necessário autenticar-se utilizando um access_token. Este token deve ser incluído no cabeçalho HTTP com o tipo de autenticação HTTP Bearer:

Authorization: Bearer {access_token}

Observação: A palavra "Bearer" deve ser incluída antes do token, seguida por um espaço.

4. Método POST /auth

O método POST /auth é utilizado para autenticação e renovação do token de acesso. Esse método é necessário nos seguintes cenários:

Ao efetuar o login no site.
Para realizar operações que exigem autenticação.

Para acessar métodos que necessitam de autenticação, envie o parâmetro access_token na requisição ou armazene o cookie gerado pelo método de autenticação para uso em requisições subsequentes.

Observação: O access_token possui validade de 25 minutos. Após esse período, ele expira, retornando um status HTTP 401 - Unauthorized. Uma nova chamada ao endpoint será necessária para obter um novo token.

Parâmetros da Requisição

Parâmetro	Tipo	Obrigatório	Valor Padrão	Descrição
grant_type	String	Sim	password	Defina como password ao utilizar autenticação via usuário e senha.
username	String	Sim	-	Login do usuário que está realizando a integração.
password	String	Sim	-	Senha correspondente ao usuário.
client_id	String	Sim	-	ID da aplicação que está se integrando ao Engage, fornecido pela equipe da Engage.
client_secret	String	Sim	-	Chave secreta da aplicação, fornecida pela equipe da Engage.
customer_id	String	Sim	-	ID do cliente representando o ambiente, fornecido pela equipe da Engage.

Nota: Defina o Content-Type dos parâmetros como application/x-www-form-urlencoded, conforme ilustrado no exemplo abaixo (usando Postman):

POST /auth Content-Type: application/x-www-form-urlencoded grant_type=password&username={username}&password={password}&client_id={client_id}&client_secret={client_secret}&customer_id={customer_id}

Retornos

Em caso de sucesso, a resposta da requisição será um JSON semelhante ao exemplo 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"
}