Introdução

Nesta seção descrevemos alguns guias que em complemento as descrições no swagger ajudarão a entender os fluxos e negócio e sequência de chamadas das APIs nos processos mais complexos.

Autenticação

OAuth 2.0

Basicamente, o OAuth 2.0 é um protocolo dos diversos tipos de fluxos de autorização de padrão aberto, que permite a terceiros (aplicações) acessarem dados de um usuário sem saber sua senha. O OAuth serve como um facilitador que os APPs usam para obter acesso a conta e aos dados de um determinado usuário, através um Client ID ou Secret (chaves de autenticação do OAuth). Caso queira saber mais, acesse este link.

Obtendo o Access Token

OAuth 2.0 Authorization Code

Passo 1 - Grant code

Após efetuar seu cadastro no portal, você deverá cadastrar a sua APP. Essa APP é o seu meio de acesso e consumo as APIs disponibilizadas. Após a criação dessa APP, você receberá o client_id, que será o primeiro item a ser passado no endpoint a seguir, via POST:

http://api-cea.sensedia.com/oauth/grant-code

O cabeçalho deve conter a seguinte informação:
Content-Type : application/json
 
O corpo deve conter a estrutura abaixo:
{  
  "client_id": "f9212173-e705-373b-a698-61923e378359",
  "redirect_uri": "http://localhost/"
}
OBS.: O client_Id a ser passado deve ser o mesmo da APP criada.
 
Como resultado, espera-se uma resposta com um “authorization code” conforme exibido abaixo:
{
  "redirect_uri": "http://localhost/?code=ee476c58-c719-37dc-9145-cd66a599123b"
}
 
 

Passo 2 - Access token

Em seguida, deve-ser realizar um novo POST no seguinte endpoint:
https://api-cea.sensedia.com/oauth/access-token
 
O cabeçalho deve conter as seguintes informações:
Content-Type: application/x-www-form-urlencoded
Authorization : Basic client_id:client_secret
 
OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada. O exemplo do cabeçalho com o client_id e secret convertidos para base64, seria:
Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==
 
O corpo deve conter a estrutura abaixo (no campo code, deve ser informado o authorization code, recuperado na chamada anterior):
"grant_type": "authorization_code"
"code" : "8748d39f-1d4f-311f-92c6-4b279db1b317"
 
Como resultado, espera-se uma resposta com um "access token" que permitirá o consumo das APIs, conforme exibido abaixo:
{
  "access_token": "57f10f0e-3d2e-311f-a797-4011f66e1cbf",
  "refresh_token": "ca81cb16-43e4-3e96-aaea-4861e7791dc7",
  "token_type": "access_token",
  "expires_in": 3600
}
 
 

Passo 3 - Consumo das APIs

Com o par de tokens em mãos, basta utilizá-los no header de suas chamadas, conforme exibido abaixo:
client_id : f9212173-e705-373b-a698-61923e378359
access_token : 57f10f0e-3d2e-311f-a797-4011f66e1cbf
 

OAuth 2.0 Refresh Token

Sempre que seu access_token expirar, para que não tenha que refazer o ciclo de autenticação, desde a chamada do grant code, você pode utilizar o refresh token, onde a partir de apenas 1 requisição, você tem um novo access token para consumo. Para isso, você deve realizar uma chamada muito parecida com a do access token, após a recuperação do grant code, onde ao invés de solicitar um authorization_code, você solicitará um refresh_token, conforme exemplos abaixo:
 
Deve-ser realizar um novo POST no seguinte endpoint:
http://api-cea.sensedia.com//oauth/access-token
 
O cabeçalho deve conter as seguintes informações:
Content-Type: application/x-www-form-urlencoded
Authorization : Basic client_id:client_secret
 
OBS.: Este client_id:client_secret deve ser uma string convertida em Base64, usando os dados da APP criada. O exemplo do cabeçalho com o client_id e secret convertidos para base64, seria:
Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==
 
O corpo deve conter a estrutura abaixo (no campo refresh_token, deve ser informado o refresh token, recuperado na chamada anterior, onde foi recuperado o access_token):
"grant_type": "refresh_token"
"refresh_token" : "ca81cb16-43e4-3e96-aaea-4861e7791dc7"
 
Como resultado, espera-se uma resposta com um novo "access token", oriundo agora do seu antigo refresh token, que permitirá o consumo das APIs, conforme exibido abaixo:
{
  "access_token": "ca81cb16-43e4-3e96-aaea-4861e7791dc7",
  "refresh_token": "677b881a-d0b6-3b29-b9a8-f0cdb50ce035",
  "token_type": "access_token",
  "expires_in": 3600
}
 
Endereços para chamadas OAuth
grant-code   http://api-cea.sensedia.com//oauth/grant-code
access-token   http://api-cea.sensedia.com//oauth/access-token

 

Login e Autenticação do Usuario

Login

Para acesso das aplicações e áreas logadas é preciso que o cliente tenha feito o login de usuário. Neste caso, o aplicativo deverá fazer uma chamada POST no recurso /user-token conforme documentado neste aqui acesse este link.

Após efetuar o login a aplicação consumidora irá receber um token jwt com a chave da sessão do usuário, que será passada nas demais requisições no header pelo parametro authorization

Com o jwt e tendo o aplicativo consumidor relizado o fluxo OAuth 2.0, a chama nas APIs conterão os hearders de exemplo abaixo
client_id : f9212173-e705-373b-a698-61923e378359
access_token : 57f10f0e-3d2e-311f-a797-4011f66e1cbf
Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
 

 

Status Codes

Código Erro Descrição
200 OK

Sucesso.
400 Bad Request

A requisição possui parametro(s) inválido(s).
401 Unauthorized

O token de acesso não foi informado ou não possui acesso as APIs.
404 Not Found

O recurso informado no request não foi encontrado.
413 Request is to Large

A requisição está ultrapassando o limite permitido para o perfil do seu token de acesso.
422 Unprocessable Entity

A requisição possui erros de negócio.
429 Too Many Requests

O consumidor estourou o limite de requisições por tempo.
500 Internal Server Error

Erro não esperado, algo está quebrado na API.
Português, Brasil