Usando as APIs

Como utilizar uma API privada

Introdução

APIs privadas são aquelas APIs que trabalham com dados sensíveis, fazendo alterações ou retornando informações que não podem ser acessadas sem devido monitoramento ou identificação do solicitante.

No portal do desenvolvedor do Banestes existem dois tipos de APIs privadas: API privada com documentação pública para qualquer um que se deseja cadastrar e API privada com documentação também privada, especificamente feita para um determinado tipo de cliente.

No caso do Pix, por exemplo, a documentação da API é de domínio público e está acessível sem nenhuma restrição no portal. No outro caso, podemos, por exemplo, ter uma API para envio de remessa da arrecadação estadual, a qual somente a secretaria da fazenda pode ter acesso à documentação desta API, visando várias questões, entre elas a de segurança.

Independentemente do tipo de API privada, o primeiro passo para utilizá-la exige que o usuário crie uma aplicação dentro do portal.

O que é uma Aplicação

De forma simples, uma aplicação é um microambiente criado dentro do portal pelo usuário para englobar uma ou mais APIs privadas, juntamente com as informações inerentes para acessá-las ou tratá-las como credenciais e URLs de callback.

É possível que se encontre outros nomes como “projeto” ou “workspace” no portal do desenvolvedor de outras instituições, mas, de forma geral, é mais comumente conhecida como aplicação.

O usuário pode criar tantas aplicações quantas forem necessárias para atender suas necessidades, desde que o contrato permita isso.

Criando uma Aplicação

Para criar uma aplicação dentro do portal do Banestes, é necessário, primeiramente, que o usuário esteja devidamente logado no portal. Uma vez que isso tenha sido feito, basta acessar o Menu do usuário e clicar na opção “Nova Aplicação”. Veja Figura 1:

Após clicar na opção indicada, surge a página para seleção da API (Figura 2). Nesta página você pode escolher qual API deseja utilizar.

Selecione uma das APIs listadas e clique em [Continuar] para que uma surja uma nova página. Nesta página (Figura 3) é necessário preencher o nome que você deseja dar à sua aplicação e uma descrição.

Ao criar o nome da aplicação, exige-se uma atenção especial pois o campo não aceita caracteres especiais e espaços, exceto o símbolo do travessão “_” também conhecido como “underline”. Exemplos:

Certo	Errado
appFaturamento	app faturamento
Web_Portal_teste	Web%portal%teste

NOTA: De qualquer forma, o campo para inserir o nome da aplicação possui restrições para evitar que, por acidente, sejam criados nomes que não se enquadrem nas devidas restrições. Por outro lado, o campo de descrição permite inserir textos longos sem nenhum bloqueio de caracteres.

Após inserir o nome e a descrição da aplicação, o usuário poderá clicar no botão [Criar aplicação]. Com isso, uma nova aplicação é criada e de imediato é fornecido acesso a todas as informações oferecidas por este ambiente criado dentro da aplicação.

Caso ainda tenha dúvidas sobre aplicações, é fortemente recomendável que leia as FAQs relativas ao portal do desenvolvedor e em seguida retorne à introdução deste tutorial.

Conhecendo uma aplicação

Uma vez que o usuário tenha criado ou acessado a aplicação, surge uma nova página no portal apresentando informações necessárias para a utilização da aplicação e configuração da mesma.

Observe a página da aplicação conforme mostrada na Figura 4. A página está dividida em seções para facilitar o entendimento deste tutorial:

A seção 1 conforme identificada acima, permite ao usuário verificar o nome da aplicação e a descrição da mesma. Caso o usuário deseje, é possível alterar o nome e descrição da aplicação apertando o botão [Editar]. Uma vez que o botão seja clicado, o usuário será redirecionado a uma página similar à mostrada na Figura 3 e poderá editar o nome e descrição da aplicação.

A seção 2 apresenta duas opções que, ao serem clicadas, modificam o conteúdo interno da página. A primeira opção nessa seção, denominada Credenciais, permite ao usuário acessar as informações de autenticação da API. É possível verificar as chaves geradas para developer_application_key, cliente_id e cliente_secret, conforme o padrão OAuth 2.

Para saber mais sobre o padrão de autenticação OAuth 2 acesse a FAQ: Quais tecnologias preciso conhecer para utilizar as APIs do portal do desenvolvedor?

É possível observar ainda na Figura 4 que em frente às chaves existem botões para copiá-las de forma correta e um botão especial denominado [Gerar Novo Client Secret] que serve para criar nova chave caso a anterior esteja comprometida.

Em relação à segunda opção “API vinculada”, ao ser selecionada, surge um formulário (Figura 5) que indica qual API foi selecionada para esta aplicação e um campo para o usuário inserir o URL de Redirecionamento.

Caso deseje saber mais sobre o endereço de retorno, acesse a FAQ: O que é URL de Redirecionamento?

Por fim, a seção 3 apresenta em seu rodapé uma opção para excluir a aplicação, caso esta não seja mais necessária. Após clicar na opção “Apagar Projeto”, uma tela de confirmação será solicitada, e, caso seja confirmado, a aplicação deixará de existir e todas as informações de credenciais e URL de retorno serão perdidas.

Gerenciando minhas aplicações

É comum, depois de algum tempo, haver necessidade de mais de uma aplicação, assim o portal oferece uma página para gerenciar todas as aplicações.

Para acesso à página de gerenciamento de aplicações, é necessário fazê-lo através do menu do usuário escolhendo a opção “Minhas Aplicações” conforme mostrado na Figura 6.

Após acessar a opção indicada, o usuário será redirecionado para a página na qual poderá visualizar todas as suas aplicações já criadas.

Conforme pode ser visto na Figura 7 as aplicações estão dispostas em cards onde é possível observar o nome da aplicação, ID e qual API a aplicação está utilizando.

Caso o usuário clique na opção “Ver mais”, na parte de baixo do card, será redirecionado para a página da aplicação conforme visto anteriormente na Figura 4.

Ainda nesta página, é possível observar o card indicando a opção “Nova aplicação”. Essa opção tem o mesmo efeito da opção de mesmo nome no menu do usuário e, ao ser acessada, o usuário será redirecionado para a página de seleção de API conforme a Figura 2 apresenta.

Autenticando acesso para uma API Privada

Como mencionado antes, uma API privada necessita de autenticação antes de consumida. No portal do Banestes, as autenticações se dão através do padrão OAuth 2, o que exige credenciais no padrão cliente_id e cliente_secret.

Para saber mais sobre o padrão de autenticação OAuth 2 acesse a FAQ: Quais tecnologias preciso conhecer para utilizar as APIs do portal do desenvolvedor?

Normalmente o processo de autenticação é realizado dentro da aplicação que irá consumir a API, porém é possível, como teste, autenticar uma API privada utilizando ferramentas do mercado que permitem realizar testes em APIs.

Para este tutorial foi selecionada a ferramenta Postman versão desktop. Este tutorial não pretende ser um curso de como utilizar esta ferramenta, porém se o usuário desejar conhecer mais sobre o Postman é aconselhável que verifique o site da fabricante (www.postman.com) ou outro material na internet que aborde os conceitos e utilização da mesma.

Para testar a autenticação, o primeiro passo a seguir é abrir o Postman e criar uma nova “Colection”. Nesta collection, o usuário pode colocar o nome que desejar e configurar as informações necessárias para realizar a autenticação. Observe a Figura 8:

Existem cinco informações principais que devem ser feitas num primeiro momento. A primeira é inerente apenas ao postam, que é o padrão de autenticação. Informando em “Type” a opção OAuth 2.0, o usuário estará habilitando a tela do Postman para inserir as próximas informações necessárias à autenticação.

Em seguida é necessário configurar o campo “Grant Type” informando a opção “Client Credentials”. Esta opção refere-se ao tipo de serviço e credencial fornecido pelo portal do desenvolvedor para autenticação.

Uma vez selecionado “Client Credentials”, o usuário poderá preencher o campo “Access Token URL” com a URL do serviço de autenticação encontrada na página da documentação da API (Figura 9) e os campos Client ID e Client Secret com suas credenciais de acesso correspondentes encontradas na página da aplicação (Figura 10).

Ainda no Postman, será necessário preencher uma última informação que é referente ao escopo de acesso dentro do campo Scope. Essa informação é encontrada na página da documentação da API (Figura 9) juntamente com a URL do serviço de autenticação. Abaixo a Figura 11 apresenta o campo de escopo de acesso:

Por fim, após todos os campos devidamente preenchidos, é necessário clicar no botão [Get New Access Token].