Comment on page

Autenticação simplificada

NOTA:

A presente página apresenta uma versão simplificada do processo de autenticação. Caso este não seja suficiente para a sua aplicação, ou encontre algum erro, ou dificuldade, consulte a página seguinte, de autenticação detalhada.

Passo 1: Obtenção das credenciais de acesso à nossa API comercial

Neste passo, deverão ser obtidos os seguintes dados, necessários para que possam aceder à nossa API comercial:
  • Identificador (a que chamamos "OAUTH_CLIENT_ID", ou simplesmente "client_id", nos exemplos posteriores)
  • Segredo (a que chamamos "OAUTH_CLIENT_SECRET", ou simplesmente "secret", nos exemplos posteriores)
  • Endereço de autenticação por OAuth (a que chamamos "OAUTH_URL" nos exemplos posteriores)
  • Endereço de acesso à API (a que chamamos "API_URL" nos exemplos posteriores)
Os quatro dados de acesso acima indicados são todos obtidos directamente da empresa à qual se pretende aceder via API. Para os obter, deverá fazer o seguinte:
  1. 1.
    Entrar na empresa com uma conta de Empresário
  2. 2.
    Aceder através do menu à opção Empresa > Configurações > Dados API
  3. 3.
    Usar os dados apresentados para autenticação e acesso à API

Passo 2: Obtenção do authorization_code

NOTA: Caso esteja a utilizar Postman, deverá desativar a opção "Automatically follow redirects", nas definições do pedido

Neste passo, deverá ser feito um pedido GET ao endereço OAUTH_URL/auth com:
Na query do Url, os parâmetros:
  • client_id=OAUTH_CLIENT_ID
  • redirect_uri=OAUTH_REDIRECT_URL
  • response_type=code
  • scope=commercial
Nos headers, os seguinte:
  • Content-Type: application/json
O exemplo seguinte ilustra o pedido feito no terminal, usando o curl:
curl -v -H 'Content-Type: application/json' \
'<OAUTH_URL>/auth?client_id=<client_id>\
&redirect_uri=http://127.0.0.1:4080/oauth/callback\
&response_type=code&scope=commercial'
A resposta esperada é como a seguinte:
GET /oauth/auth?client_id
<client_id>&redirect_uri=http://127.0.0.1:4080/oauth/callback
&response_type=code&scope=commercial
HTTP/1.1 > Accept: */* > Content-Type: application/json >
< HTTP/1.1 302 Moved Temporarily
< Content-Type: text/html
< Location: http://127.0.0.1:4080/oauth/callback?
code=<authorization_code>
Utilizando o authorization_code recebido na resposta, deverá seguir o próximo passo

Passo 3: Obtenção do access_code

Neste passo, deverá ser feito um pedido POST ao endereço OAUTH_URL/token com:
  1. 1.
    No body do pedido, os parâmetros:
  • grant_type=authorization_code
  • code= o "authorization_code" obtido do passo anterior.
  • scope=commercial
  1. 1.
    Nos headers, os seguinte:
  • Content-Type: application/x-www-form-urlencoded
  • Accept: application/json
  • Authorization: o texto "Basic", seguido dum espaço, seguido dum texto formado pela concatenação do "client_id", seguido de ':', seguido do "secret", tudo codificado em base 64. Por exemplo, se o "client_id" fosse "test" e o "secret" fosse "abcdef", o valor deste header seria "Basic dGVzdDphYmNkZWY=", sendo "dGVzdDphYmNkZWY=" o texto "test:abcdef" em base 64.
O exemplo seguinte ilustra o pedido feito no terminal, usando o curl:
curl -v -X POST -H 'Content-Type: application/x-www-form-urlencoded'\
-H 'Accept: application/json'\
-H 'Authorization: Basic <client_id + ':' + secret, codificados em base 64>' \
-d 'grant_type=authorization_code&\
code=<authorization_code>&scope=commercial' \
'<OAUTH_URL>/token'
A resposta esperada é como a seguinte:
> POST /oauth/token HTTP/1.1 >
Content-Type: application/x-www-form-urlencoded >
Accept: application/json >
Authorization: Basic dGVzdHM6ZWJhOTI3NjM3MzRlN2MwMg== >
< HTTP/1.1 200 OK < Content-Type: application/json;charset=utf-8
< {"access_token":"10dc1d36e24b790540d087ea238ec345abd1a02daa73ae45a09",
"expires_in":7890000,
"refresh_token":"f71824c9e4675a8aa9661f18ae5341e977d37",
"token_type":"Bearer"}
Daqui, tem então o access_token necessário para a utilização da API, referenciado nas restantes páginas de pedidos de exemplo