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

O formulário de criação pede três grupos de informações:

• Informações básicas: o nome da aplicação e uma descrição de seu propósito;
• Configurações adicionais: URLs de callback, de redirecionamento e de destino, utilizadas pelos fluxos de autenticação da sua integração quando aplicáveis;
• APIs disponíveis: a lista das APIs liberadas para a sua conta. Utilize a busca pelo nome, selecione a API e o plano que a aplicação vai consumir.

Caso ainda tenha dúvidas sobre o que se trata uma aplicação, é fortemente recomendável que leia as perguntas frequentes do portal, e em seguida retorne a introdução deste tutorial.

Conhecendo uma aplicação

A página apresenta:

• Credenciais: o Client ID e o Client Secret da aplicação, utilizados na autenticação OAuth 2 das chamadas à API. Utilize os botões ao lado de cada chave para exibi-la e copiá-la;
• APIs associadas: as APIs selecionadas na criação (ou nas edições posteriores) da aplicação;
• Tokens de acesso: os tokens emitidos para a aplicação.

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

Gerenciando minhas aplicações

Autenticando acesso para uma API Privada

Como mencionado antes uma API privada necessita de autenticação antes de consumida. No portal do Banestes, a autenticação segue o padrão OAuth 2, o que exige credenciais no padrão Client ID e Client Secret — ambas disponíveis na página da aplicação, descrita na seção anterior.

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, como o Postman (https://www.postman.com/). Em resumo, o fluxo é o seguinte:

1. Configure a autenticação do tipo OAuth 2 com o grant Client Credentials;
2. Informe a URL do serviço de token, os valores de Client ID e Client Secret da sua aplicação e o escopo desejado — as URLs e os escopos de acesso são definidos pela documentação de cada API;
3. Solicite o access token e utilize-o nas chamadas à API.

Para conhecer mais sobre os escopos de acesso e as URLs de autenticação das APIs do Banestes, consulte a documentação de cada API e as perguntas frequentes.