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 acessíveis 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, cuja somente a secretaria da fazenda pode ter acesso a 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 utiliza-la exige que o usuário crie uma aplicação dentro do portal.

O que é uma Aplicação

De forma simples, uma aplicação e um microambiente, criado dentro do portal pelo usuário, para englobar uma ou mais APIs privadas, juntamente com as informações inerentes para acessa-las ou trata-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 isto.

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 a 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 seja criado nomes que não se enquadre nas devidas restrições. Por outro lado, o campo de “descrição” permite inserção de textos longos sem nenhuma restrição 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 poderá ter acesso a todas as informações fornecidas dentro do ambiente oferecida por este ambiente criado dentro da aplicação.

Caso ainda tenha dúvidas sobre o que se trata uma aplicação, é fortemente recomendável que leia os FAQs relativos ao portal do desenvolvedor, e em seguida retorne a 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 do 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 a 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 nesta seção, denominada “Credenciais” permite o 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 acessos o FAQ: Quais tecnologias preciso conhecer para utilizar as APIs do portal do desenvolvedor.

É possível observar ainda na Figura 4, que em frente as chaves existem botões para copia-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 a segunda opção “API vinculada”, ao ser selecionada, surge um formulário (Figura 5) que indica qual a 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 o 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. Caso seja do interesse do usuário excluir a aplicação. 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 perdidos.

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 acessar a página de gerenciamento de aplicações, é necessário acessar 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 onde 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”. Esta 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 acessos o 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 do fabricante https://www.postman.com/ ou outro material na internet que aborde os conceitos e utilização desta.

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.

Existe 5 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 a 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 “Acces 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 correspondentes credenciais de acesso encontrados na página da aplicação (Figura 10).

Ainda no Postman, será necessário preencher uma ultima informação que é referente ao escopo de acesso dentro do campo Scope. Esta 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 Scopo de acesso:

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