Aceder à API

Neste tutorial, que está dividido em três partes, vamos descrever passo a passo como aceder à Best Bank API. O nosso objetivo é conseguir um Access Token para aceder à conta de um utilizador do Banco Best, em ambiente de sandbox.

Requisitos para começar

Para aceder à API é necessário:

Registar-se na plataforma do Best Banking API
Registar a sua aplicação
Obter um certificado válido (.cer)

Registo na API

Após o seu registo e com o login feito, deve aceder à página das aplicações. Essa página deve conter os dados de todas as suas aplicações registadas. Para registar uma nova aplicação, deve clicar em "Nova Aplicação".

Criar nova aplicação

Para criar a sua primeira aplicação, serão necessários alguns dados de preenchimento obrigatório. Siga o modelo de formulário apresentado e tenha em atenção que na criação de uma nova aplicação, o campo “Ambiente” deve ser preenchido com a opção de “Sandbox”.

Após o registo da sua nova aplicação, ser-lhe-ão fornecidos o Consumer Key e Secret Key respetivos à sua aplicação. Deverá guardar estes dados num local seguro, uma vez que o Secret Key não estará visível novamente. Com o registo feito, já pode aceder à API sandbox.

Funções do Certificado

De forma a ter acesso à API, será necessário um certificado válido. Os certificados terão diferentes Funções PSP (Payment Service Provider) que irão indicar como os nossos parceiros podem utilizar a nossa API. Cada pontos de acceso terá uma lista de Funções a indicar as Funções necessárias para sua utilização.

As Funções existentes são as seguintes:

Código	Nome da Função	Tradução
PSP_AI	Account Information	Informação de Conta
PSP_AS	Account Servicing	Serviço de Conta
PSP_IC	Card-Based Payment Instruments	Instrumentos de Pagamento baseado em Cartão
PSP_PI	Payment Initiation	Iniciação de Pagamento

Aceder à API

Para aceder à API, usamos o protocolo OAuth 2.0. Caso não esteja familiarizado com este termo, sugerimos uma leitura mais profunda sobre o assunto antes de prosseguir.

Resumidamente, o objetivo do fluxo de autenticação é que a sua aplicação obtenha um Access Token. Com este Access Token, a aplicação fica autorizada a realizar as operações de um utilizador. No entanto, o utilizador da sua aplicação terá de autorizar previamente o acesso aos dados pessoais.

O acesso à API tem três passos:

Obter o URL de autentição do utilizador para o Banco Best.
Após login do utilizador, obter o código temporário.
Com esse código temporário, obter o Access Token.

Neste primeiro passo, o objectivo é obter um URL de login no ambiente do Banco Best, onde o utilizador da sua aplicação irá fazer o login, escolher a conta bancária e as funcionalidades que autoriza a sua aplicação a ter acesso. Não é possivel inserir simplesmente o URL de login do utilizador na plataforma do Banco Best, é sempre necessário juntamente com o URL enviar alguns parâmetros Query String usados pelo Banco Best. Daí, a necessidade primeiro do que chamamos "aperto de mãos" (handshaking) entre a aplicação e a API.

Como este é um tutorial, vamos começar a ligação ao ambiente Sandbox do Best Banking API utilizando uma ferramenta de testes de webservices, como por exemplo o Postman, mas pode utilizar outra ferramenta da sua preferência.

Segue infra o endpoint no qual estamos a ligar-nos para obter o URL de login. Na ferramenta de testes, insira este endereço:

https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Initiate

Agora, é preciso adicionar um header de autorização. No Postman clique em Headers e adicione um parâmetro com uma Key chamada "Authorization". No valor deste parâmetro devem estar as variáveis de acesso. Que parâmetros são estes? Vejamos quais são e a função de cada um deles na tabela abaixo:

Variável	Valor de Exemplo	Descrição	Obrigatório?
oauth_consumer_key	0f4c0d842b0e70d42348280681...	Consumer Key da aplicação	Sim
oauth_timestamp	1529597435	Unix Timestamp em UTC	Sim
oauth_version	1.1	Versão da API	Sim
oauth_signature	6YWEI87xEHTqOSXsL...	Assinatura que valida o cabeçalho. O padrão usado no Banco Best é SHA256.	Sim
oauth_guid	5cc22f7f-0f39-422c-b69f-a232954c7929	GUID aleatória gerada para o pedido.	Sim

É necessário um header do Certificado eDAIS (qSEAL). Adicione um parâmetro com uma Key chamada "certificate". No valor deste parâmetro deve estar o certificado que contém a chave pública. O valor desta varíavel é em base64.

Depois da mensagem formatada, o Header de um pedido será muito semelhante ao exemplo abaixo:

Header

Authorization:OAuth 
oauth_consumer_key=0f4c0d842b0e70d423482806812bd42657a155eb759530f4b9d4c95c81cd485c,
oauth_timestamp=1672531200,
oauth_version=1.1,
oauth_signature=5YWEI87xEHTqOSXsL%2B8mzUDKYypH6LYBt400fWek2rU%3D,
oauth_guid=5cc22f7f-0f39-422c-b69f-a232954c7929,
Certificate:9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==

Os parâmetros do Header Authorization não devem ter espaços após a vírgula.

Relembrar de nunca partilhar a chave privada da sua aplicação (oauth_consumer_secret) neste Header. Este campo deve ser passado exclusivamente na assinatura!

Neste momento já deve estar apto a preencher o pedido acima com os dados da sua aplicação, o timestamp atual que deverá estar em tempo UTC, o URL para retornar à sua aplicação.

O timestamp será validado de forma a garantir que o tempo está em UTC, e a GUID deverá ser gerada aleatóriamente e única. Uma combinação repetida de timestamp + GUID irá resultar em erro. Não permitimos uso repetido de assinatura.

Mas e o oauth_signature? Vamos ver agora:

Gerar assinatura

Gerar uma assinatura é um processo comum na autenticação OAuth, neste tutorial iremos descrever resumidamente este processo.

Para gerar uma assinatura precisamos primeiro de formar uma Base String. O padrão da Base String do Best Banking API segue as seguintes regras:

Variável	Descrição
oauth_consumer_key	Consumer Key da aplicação
oauth_guid	GUID aleatória gerada para o pedido.
oauth_timestamp	Unix Timestamp em UTC
oauth_version	Versão da API
oauth_consumer_secret	Consumer Secret Key da aplicação (DEVE ESTAR NO FIM!)

Todas variáveis estão em ordem alfabética, exceto a Consumer Secret Key que será sempre adicionada ao fim da base string.

Segue um exemplo de uma base string:

Base String

oauth_consumer_key%3D735a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1%26oauth_guid%3D5cc22f7f-0f39-422c-b69f-a232954c7929%26oauth_timestamp%3D1531842924%26oauth_version%3D1.1%26oauth_consumer_secret%3D635a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1

Como se pode perceber que a mensagem acima está codificada. Para gerar uma base string, é necessário antes converter para codificação de URL.

Para gerar uma assinatura, usamos HMAC SHA256 juntamente com a App Secret. No caso da base string acima, foi gerada usando HMAC SHA256 com a App Secret (a App Secret deste exemplo é: 635a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1) a seguinte assinatura:

a453de63e7e926d29aacaec8b9a3a8976f2ed98ad12897b96874388bef949fd2

Mas espere, esta ainda não é a assinatura final. Agora necessita converter em Base 64:

pFPeY+fpJtKarK7IuaOol28u2YrRKJe5aHQ4i++Un9I=

Espere, também há a necessidade de converter em codificação de URL:

pFPeY%2BfpJtKarK7IuaOol28u2YrRKJe5aHQ4i%2B%2BUn9I%3D

Pronto, nós temos a assinatura correta.

Para continuar este tutorial, construa a base string com os dados de sua aplicação ou use a base string acima. Você pode usar esta ferramenta online para gerar a assinatura. Se você testar a base string acima com esta ferramenta, use a seguinte App Secret Key como chave:

635a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1

Depois de gerado a assinatura em Base 64, pode-se usar esta outra ferramenta online para codificação de URL.

O campo abaixo é editável e pode ajudar-te a construir uma base string correta.

Retorno

Depois da base string ter sido gerada e já tendo a assinatura, podemos seguir agora para o Header.

O campo abaixo é editável e pode ajudá-lo a montar um Header corretamente.

Mude o método de pedido para POST e envie. Em caso de sucesso, será retornada uma mensagem similar à apresentada abaixo:


{
    "LoginUrl": "http://www.bestbank.pt/LoginPSD2/Auth/LoginSandbox?login_token=eyJub25jZSI6ImYxODgyNTk5YjIxIiwic2NvcGUiOiJ1c2VyIiwicmVkaXJlY3RVcmwiOiJodHRwOi8vaHR0cGJpbi5vcmcvZ2V0Iiwic3RhdGUiOiJub25lMiIsIm5hbWUiOiJBcHAgUG9ydHVnYWwgU2FuZCJ9&state=none"
}

Por fim, a aplicação deve redirecionar o utilizador para a página de login do Banco Best.

Finalizámos a primeira parte da autenticação ao Banco Best, iremos agora ver a segunda parte: Como Obter um Código Temporário

Obter código temporário

No passo anterior vimos como registar a sua aplicação e como fazer o "aperto de mãos" (handshaking) entre a aplicação e a API. Nesta parte, vamos obter o código temporário.

Redirecionamento do utilizador

No passo anterior, o serviço devolveu o JSON abaixo:

{
    "LoginUrl": "http://www.bestbank.pt/LoginPSD2/Auth/LoginSandbox?login_token=eyJub25jZSI6ImYxODgyNTk5YjIxIiwic2NvcGUiOiJ1c21VyIiwicmVkaXJlY3RVcmwiOiJodHRwOi8vaHR0cGJpbi5vcmcvZ2V0Iiwic3RhdGUiOiJub25lMiIsIm5hbWUiOiJBcHAgUG9ydHVnYWwgU2FuZCJ9&state=none2"
}

Variável	Descrição
LoginUrl	Contém o endereço url do login do Banco Best, para a qual a aplicação irá redirecionar o utilizador.

A sua aplicação deve tratar o JSON devolvido, e redirecionar o utilizador para a página de login do Banco Best.

Caso esteja a testar a sua aplicação em ambiente Sandbox, o URL devolvido irá para uma página do ambiente bancário da própria Sandbox. Poderá usar o seu login da conta da Sandbox para entrar neste ambiente bancário de testes. Este login tem o objetivo de simular o ambiente bancário do Banco Best num ambiente seguro.

A partir deste momento, a sua aplicação poderá apenas esperar o utilizador terminar a autenticação e voltar à aplicação a partir do endereço de URL enviado no passo anterior. Neste momento o utilizador está a navegar no ambiente de autenticação bancária fornecido pelo Banco Best.

Como neste tutorial estamos em ambiente sandbox, deverá fazer login no ambiente Sandbox:

Antes de inciar este processo, adicione uma conta bancária virtual ao seu ambiente de administração da Sandbox. Para adicionar uma nova conta bancária virtual deve após o login, selecionar no seu menu “Sandbox” e abaixo de Virtual Sandbox Bank Account clicar em “adicionar”. Neste campo, deve definir o montante da sua conta bancária virtual e ao clicar em “criar” irá obter o seu IBAN virtual.
Neste momento deve aceder ao URL devolvido no passo anterior. Caso esteja a testar numa ferramenta de testes como foi sugerido no passo anterior, é necessário aceder ao URL num browser externo. Se o seu token estiver expirado, faça novo pedido igual ao que foi feito no passo anterior e será gerado outro URL de login.
Se o seu token estiver expirado, faça novo pedido igual ao que foi feito no passo anterior e será gerado outro URL de login.
Faça login no ambiente da Sandbox. Para fazer o seu login, irá precisar do seu login e password do próprio ambiente.
Se já estiver logado ou depois de se logar, aparecerá uma página mostrando que o seu login terá sido efectuado com sucesso. Caso não apareça uma mensagem de sucesso, possivelmente você não adicionou uma conta bancária virtual do Sandbox. Siga as instruções da página para criar uma conta bancária virtual e depois volte a primeiro passo desta lista.
Clique no botão “Voltar à aplicação” e será redirecionado para o endereço de URL fornecido no passo anterior.

Após o login, o ambiente da sua Sandbox estará o mais próximo possível do ambiente real do banco.

Retorno

O último passo do utilizador é retornar ao endereço fornecido pela aplicação. Ao retornar, duas variáveis serão retornadas via Query String.

Variável	Descrição
oper_id	Identificador da operação
code	Código temporário para obter o Access Token
status	Variável de controle da própria aplicação, enviada na primeira requisição

Segue abaixo o exemplo de URL devolvido:

http://www.myapplication.pt/Login?code=abb96157cbcc4867b60479616d4af4e2&status=none

A variável code é um código temporário que iremos usar no próximo passo para o nosso objetivo final que é obter o Access Token. Juntamente à variável code está a vir a variável status que pode ser usada pela sua aplicação e foi devolvido exatamente o mesmo valor que foi enviado no passo anterior.

Finalizámos a segunda parte da autenticação ao Banco Best, iremos agora ver a última parte: Como Obter o Access Token. Para isto, copie o código da variável code que irá ser usado no próximo passo.

Obter Access Token

No passo anterior vimos como obter o código temporário, após o utilizador se autenticar no ambiente do Banco Best. No nosso caso, o ambiente Sandbox deste. Vamos agora finalizar o acesso à API e obter o Access Token.

Como feito no primeiro passo, vamos começar a ligação ao ambiente Sandbox do Best Bank API usando uma ferramenta de testes de webservices, como por exemplo o Postman , mas pode usar outra ferramenta da sua preferência.

https://dev.openbank.bancobest.pt/sandbox/api/v2/OAuth/Token

Precisamos agora de adicionar um Header de autorização. Assim a exemplo do que foi feito no primeiro passo, no Postman clique em Headers. Adicione um parâmetro com uma Key chamada "Authorization". No valor desse parâmetro devem estar os parâmetros de acesso. Precisamos enviar as seguintes variáveis:

Variável	Valor de Exemplo	Descrição	Obrigatório?
code	c0d842b0e70d42348280...	Código temporário retornado após autenticação do utilizador do aplicativo	Sim
oauth_consumer_key	0f4c0d842b0e70d42348280681...	Consumer Key da aplicação	Sim
oauth_timestamp	1529597435	Unix Timestamp	Sim
oauth_version	1.1	Versão da API	Sim
oauth_guid	5cc22f7f-0f39-422c-b69f-a232954c7929	GUID aleatória gerada para o pedido.	Sim
oauth_signature	6YWEI87xEHTqOSXsL...	Assinatura que valida o cabeçalho. O padrão usado no Best Bank é SHA256.
certificate	9dFpJUCnQcwe80aAOHx7...	Chave pública do certificado eDAIS em base64.	Sim

Com a mensagem formatada, o Header de um pedido estará muito próximo do exemplo abaixo:

Header

Authorization:OAuth 
code=a9dadedc4ea94f2da6a87be6a66e45a4,
oauth_consumer_key=835a1oicfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1,
oauth_timestamp=1672531200,
oauth_version=1.1,
oauth_guid=5cc22f7f-0f39-422c-b69f-a232954c7929,
oauth_signature=frBL78jfC5TlWOYCm62Nw8wjjtYknW2xkYqcRfyIG0U%3d
certificate:9dFpJUCnQcwe80aAOHx7YWYlqisICXNnVSKiaiA9vGO8YnzlZoJcUVPJ/rZ68X8FD==

O campo abaixo é editável e pode ajuda-lo a montar um Header corretamente conforme a sua aplicação.

Para conseguir a assinatura, a formatação da base string é parecida com o processo que vimos no primeiro passo. Segue abaixo um exemplo de base string para esse pedido:

Base String

code%3Dcefda5ea083a459ba1370ca8149d1dea%26%0Aoauth_consumer_key%3D835a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1%26%0Aoauth_guid%3D5cc22f7f-0f39-422c-b69f-a232954c7929%26%0Aoauth_timestamp%3D1672531200%26%0Aoauth_version%3D1.1%26%0Aoauth_consumer_secret%3DSECRET835a1cfe04e53298929bd4fa59ab12a1b004bab5eea1edbdcc980741df181af1

O campo abaixo é editável e pode ajuda-lo a montar um Base String corretamente conforme a sua aplicação.

Retorno

No final do pedido será retornado o Access Token como está no pedido abaixo:

{
    "access_token": "0c08dbacf98549e9a552a58371a41618",
    "expires_in": 1532262026
}

Variável	Descrição
access_token	Código de Access Token
expires_in	Unit Timestamp com a validade do Access Token

Com a obtenção do Access Token, finalizamos o acesso à API e já é possível realizar operações no Best Bank API.

Este Access Token deverá ser utilizado no Header de Authorization de todos os pedidos de operações não "Initiate". (contido no nome do endpoint)

Tomar em consideração que apenas um Access Token pode estar ativo por utilizador. Ao fazer um pedido com sucesso a este endpoints, o Access Token previamente ativo deixará de estar válido para utilização.

Os endpoints qu utilizam um Access Token inválido retornam o erro interno de Sistema descrito como EGEN003.

Sugerimos que consulte a restante documentação para ver como utilizar todas as outras operações disponíveis.

Aceder à API

Requisitos para começar

Aceder à API

Obter URL de Login

Obter código temporário

Obter Access Token