Autenticação

Aplicações web

É o método de autenticação que nós sugerimos!
Está menos disposto a ataques, porque as credênciais do cliente são diretamente colocadas no login do Moloni e não passam por interfaces de terceiros, acabando por se estabelecer uma relação de confiança entre o utilizador e a plataforma desenvolvida, porque sabe que está a inserir diretamente os dados no Moloni. Este processo é mais minuncioso na implementação e é o indicado para todas as plataformas web.

1º Passo

O primeiro contacto é feito redireccionando o seu utilizador para o endpoint da API com 3 parâmetros GET.

URL e parâmetros necessários

2º Passo

Após ter feito o pedido, irá ser mostrado o formulário de Login na API, que deverá preencher com os dados do utilizador Moloni, cuja conta pretende ter acesso através da API.

Se o login for bem sucedido, será apresentada uma mensagem perguntando ao utilizador que a aplicação está a tentar aceder à sua conta e com isso terá acesso a informação confidencial.

Se o utilizador aceitar, será redireccionado para o redirect_uri especificado na chamada com o parâmetro GET code preenchido com o authorization_code que necessita para solicitar o seu access_token.

3º Passo

O próximo passo será trocar o authorization_code que recebeu por um access_token e um refresh_token (Vêm sempre os dois juntos).

O pedido para estes dois códigos é feito por GET para o URL do end-point da API com 5 parâmetros.

URL e parâmetros necessários

A resposta chega em formato JSON

{
	access_token: 'bad936989865c810e14a81ea9fc2cd8ea8d5e9f6'
	expires_in: 3600
	token_type: 'bearer'
	scope: null
	refresh_token: '96f84474f2ed3ae07e4e1b5d08fe1893d08a204f'
}

Aplicações nativas

Este processo é consideravelmente mais simples que o anterior, usando directamente as credenciais do utilizador para obter os tokens. No entanto, terá que tomar medidas adicionais de segurança para as proteger. A nossa recomendação é que a password do utilizador não seja persistida, sendo-lhe pedida quando (e se) o refresh token expirar (mais sobre a validades dos tokens abaixo).

Basta enviar as suas credenciais de developer em conjunto com as credenciais de acesso do seu utilizador e ser-lhe-ão devolvidos os tokens.

URL e parâmetros necessários

Em caso de erro

Caso ocorra algum erro, é sempre devolvido um HTTP status com o código 400 (Bad request). Como este erro é demasiado genérico, no corpo da resposta é também devolvido um objecto JSON com os campos error e error_description, que identificam claramente o problema ocorrido.

Depois de ter os tokens

A partir deste momento, deve fazer os pedidos normalmente para a API, sendo que por GET deve enviar sempre o access_token.

Quanto aos restantes dados, terá que ter em atenção que estes deverão ser enviados no BODY do POST, e podem ser enviados em dois formatos diferentes, sendo que por defeito a API aceita valores em formato Query String., ou se preferir, pode enviar os seus dados em formato JSON.

Para enviar os seus dados em formato de JSON, terá que enviar o header correcto (application/x-www-form-urlencoded), bem como enviar por GET o parâmetro json=true.

A título de exemplo, em PHP pode usar a classe cURL que lhe facilita bastante todas as operações de envio da comunicação e existem paralelos ao cURL em várias linguagens.

Validade dos tokens

Os tokens de acesso têm uma validade limitada, por isso convém que o sistema criado tenha em conta estes timings para que possa desenvolver rotinas de requisação de novos tokens.

Fazer refresh ao Access Token

Antes que o access_token expire, o mecanismo que criar tem que fazer um pedido de refresh por GET para o URL do end-point da API com 5 parâmetros. Ser-lhe-ão devolvidos novos tokens, tanto de access como de refresh.

URL e parâmetros necessários

Se o refresh_token ultrapassar os 14 dias de validade, o utilizador terá que voltar a autenticar-se segundo um dos dois métodos acima.