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 

    Atenção: É 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.

IMPORTANTE: Por fim, para que seja possível fazer o De-Para dos usuários na Engage com o sistema de terceiro, a partir das instruções disponíveis neste tutorial, é neccessário que o usuário esteja previamente cadastrado no portal Engage ou que o cliente desenvolva em seu processo de integração uma rotina para, primeiramente, criar o usuário na Engage e depois sim fazer o De-Para com os usuários de seu sistema. A documentação para criar novos usuários na Engage encontram-se dissponíveis neste link.

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

• URL da API REST   
  • https://my.engage.bz/api/v1/
• URL do front-end
  • https://one.engage.bz/ (URL padrão da plataforma) OU
  • https://{customer_id}.engage.bz/ 

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 2018 20:06:53 GMT",

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

}

{

    "error": "error_code",

    "error_description": "This is an error."

}

Para viabilizar o SSO na plataforma Engage com o ID interno de um sistema de terceiros, é necessário criar uma espécie de “De-Para” dentro do Engage. Este serviço permite que esta tarefa seja realizada.

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

Onde:  

Este grant_type é uma forma nativa do Engage de permitir o SSO do usuário utilizando o identificador de sistemas de terceiros podendo ser um UserId, um Guid, etc...

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": "fluig",

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

    "key": "633cd237-42f4-4859-ba84-27789a39e8a1"

}

{

    "error": "error_code",

    "error_description": "This is an error."

}

Em posse do parâmetro key - obtido no Passo 6 - basta fazer o redicionamento de sua aplicação para uma das URL's abaixo, a depender do ambiente que você está utilizando, passando o key obtido, conforme exemplo abaixo:

No ambiente de Homologação:

• https://sandbox.one.engage.bz/#/login?key={key}

No ambiente de Produção: 

• https://one.engage.bz/#/login?key={key} - com a URL padrão da plataforma https://one.engage.bz OU
• https://{customer_id}.engage.bz/#/login?key={key} - com o subdomínio do cliente na plataforma.

O SSO será realizado e o acesso à plataforma Engage será liberado.