APP de autenticação

Dev. Portal

Se você está acessando esta página, quer dizer que já deu o primeiro passo para iniciar a comunicação com as nossas APIs.

Agora você poderá prosseguir com os próximos passos para consumo das nossas APIs.

Obter uma APP

O que é APP?

Para acessar as nossas APIs é necessário ter um código de identificação, chamado de “APP”.

Por meio desta “APP”, a plataforma consegue autenticar e autorizar as ações feitas pelas suas aplicações. Por exemplo:

• Operações vinculadas a um cliente Banestes*, como consultar extrato bancário, fazer pagamentos, alterar dados cadastrais, geração de qr-code PIX, etc.
• Em alguns casos, as operações não estão associadas a um cliente Banestes, como consulta de registro de boletos, lista de bancos no SPB (Sistema de Pagamentos Brasileiro), etc. * As execuções de operações vinculadas a um cliente Banestes só podem ser acessadas após autorizações explícitas dadas pelo próprio cliente Banestes via bankline. Este item será melhor detalhado nos tópicos abaixo.

Uma APP é representada na plataforma pelo seu código “Client ID”, no padrão GUID. Recomendamos que você tenha:

• Uma APP diferente por aplicação (CRM, ERP, e-commerce) ou por grandes processos da sua aplicação (abertura de conta, pagamentos de conta, PIX, etc.);
• Obrigatoriamente uma APP diferente por ambiente (produção e sandbox);
• E também obrigatoriamente, uma APP por Conta Corrente (CC).

Cadastre uma APP

O cadastro de uma APP é feito por um processo simples, disponível no link:

• Minhas aplicações

Para este cadastro, você deverá preencher o formulário com as informações solicitadas:

• Nome: nome da APP (livre digitação, mas recomendamos que use nomes associados a sistema ou processos);

• Link para sua app: Informação de preenchimento opcional que consiste na URL de identificação da sua APP que pode ser um website ou documentação/help;

• Descrição: campo de livre digitação, mas recomendamos que coloque informações como finalidade da APP na sua aplicação. Será muito interessante sabermos as suas ideias e projetos;

• Ambiente de Acesso: selecionar se a APP será utilizada me ambiente 'Sandbox' ou 'Production'; As informações daqui para baixo são referentes a Conta Corrente que será associado a APP e posteriormente ao Certificado. Se as informações forem fornecidas de forma errada, a criação da APP não será permitida.

• Nome Titular: nome do titular da Conta Corrente (CC) que esta APP irá representar.

• E-mail: informação importante caso seja necessário entrarmos em contato;

• CPF/CNPJ: identificação do proprietário da CC que esta APP irá representar;

• Agência: informação que esta APP irá representar. Caso não exista, coloque apenas o número um (1);

• Conta Corrente: informação que esta APP irá representar;

• Cidade: nome da cidade de nascimento/registro do CPF/CNPJ (sem acentuação);

• Estado: sigla do estado (UF), da cidade informada;

• País: Sigla do país, do estado informado.

• Após preenchimento do formulário, os dados informados serão validados pelo time do Banestes. Enviaremos um e-mail informando se a APP foi Aprovada ou Reprovada a sua criação;
• Após o cadastro e geração da sua APP, mantenha de forma segura a informação do seu “CLIENT ID” e, principalmente, o “CLIENT SECRET”;
• Caso a criação da APP for aprovada e o ambiente de criação for 'Sandbox', o Banestes irá disponibilizar uma massa de dados para os seus testes.

Certificado de Autorização

Descrição do processo para criação e ativação do certificado de autenticação para acesso às APIs do Banestes.

Sobre a Solução

Objetivo

Esclarecer e orientar as áreas responsáveis pela integração entre parceiros/clientes e Banestes, informando os requisitos de segurança para a utilização das APIs e os direcionamentos técnicos para que um parceiro possa interagir com recursos disponibilizados para este processo. Nessa documentação, você encontrará o fluxo de autenticação e configuração de certificado nas chamadas das APIs.

Modelo de autenticação

O nosso modelo de comunicação atual requer a execução de dois fluxos de segurança pelo parceiro:

• OAuth 2.0 Client Credentials e
• Certificado (fluxo mTLS) Para acessar os dados corretamente, é importante que o processo de autenticação seja devidamente concluído antes do início dos testes. As etapas do processo de autenticação estão detalhadas a seguir.

Credenciais OAuth 2.0

Para iniciar a sua jornada de desenvolvimento, é importante que o ambiente esteja preparado e configurado para realizar os testes e suportar o desenvolvimento da aplicação de maneira segura. O nosso modelo de comunicação atual requer a autenticação do parceiro através do fluxo OAuth 2.0.

Esse fluxo é composto pelo client_id, que identifica a aplicação do parceiro, também conhecida como APP, e pelo client_secret, que é uma espécie de “senha” da APP, gerado automaticamente pelos nossos sistemas.

O parceiro terá dois conjuntos diferentes de credenciais: um para o ambiente Sandbox, para desenvolvimento e testes, e o outro para o ambiente de Produção.

Para ter acesso às credenciais do ambiente de produção, você seguirá o mesmo procedimento de sandbox, porém o time Banestes irá fazer uma validação mais criteriosa antes de disponibilizar as informações de acesso.

As credenciais client_id e client_secret serão criadas pelo nosso Dev. Portal de forma automática ou não para o ambiente Sandbox e, para as credenciais de Produção, necessitará de uma aprovação do nosso time de atendimento, sendo o prazo para a resposta de aproximadamente 5 dias úteis. Fique atento à resposta do e-mail.

Mais informações sobre este processo, veja o item “Cadastre uma APP”.

Criação e Ativação do Certificado

Os certificados terão validade de 365 dias, podendo ser renovados a partir dos 60 dias que antecedem o seu vencimento, e são de uso exclusivo do parceiro, sendo este o único responsável pela correta utilização e renovação. As chaves são monitoradas, e podem ser revogadas a critério do time responsável do Banestes em casos de: compartilhamento, interações estabelecidas muito acima do considerado normal e fim da parceria, por exemplo.

Pré-requisitos

Processo

• Manual
• Automático

Para gerar o certificado dinâmico, devem ser instalados:

• Git com módulo OpenSSL.
• OU apenas o OpenSSL

→ OpenSSL

É importante validar se o seu ambiente está com o OpenSSL instalado de forma correta, para isso execute o seguinte comando em um terminal de seu sistema operacional para verificar se possui o OpenSSL instalado. Caso não obtenha retorno, instale o aplicativo OpenSSL e tente novamente.

Comando:

Exemplo de retorno (deverá apresentada a versão instalada):

Caso decida seguir os passos de criação e registro de Certificado de forma "automática" e via formulário. Será necessário ter acesso aod Portal dos Desenvolvedores do Banestes para execução dos procedimentos. ... conforme iremos explicar nos próximos passos desta documentação.

CNF

Processo

• Manual
• Automático

Com o OpenSSL instalado de forma correta, podemos prosseguir com o processo de geração do par de chaves RSA. Para gerar, execute os comandos abaixo, preenchendo com as informações solicitadas:

Comando:

• UID = Client ID da APP criada no Dev. Portal;
• DC = Ambiente que a APP foi criada e o certificado será utilizado (“Sandbox” ou “Producao”);
• CN = Nome do proprietário da CC e CPF/CNPJ que será utilizado o certificado;
• O = Número do CPF ou CNPJ do titular da CC que será acessada pelo certificado;
• OU = Número da Agência “-” Número da Conta Corrente que será acessada pelo certificado;
• L = Nome da cidade de nascimento/registro do CPF/CNPJ (sem acentuação);
• ST = Sigla do estado (UF), da cidade informada;
• C = Sigla do país, do estado informado.

Exemplo do comando:

Para execução do comando CNF, é necessário ter uma APP já criada e aprovada pelo Banestes, desta forma certifique-se que já tenha esta APP.

Para criar um comando CNF de forma "automática", basta seguir os procedimentos abaixo:

• Logar no Portal dos Desenvolvedores do Banestes;
• Acessar o formulário "Certificados para operações de PIX" por este link;
• Será apresentado uma listagem de todas as APPs que foram criadas por você no portal;
• Na listagem de APP clique no botão "CNF";
• De forma automática, será gerado o comando CNF da APP selecionada, conforme imagem de exemplo abaixo:

Request Certificate e Key

Processo

• Manual
• Automático

Com o OpenSSL instalado de forma correta, e o comando openssl do CNF preenchido da forma correta, podemos prosseguir com o processo de geração do par de chaves RSA.

Exemplo do comando:

Exemplo de retorno:

Este comando deverá gerar a chave privada “PRIVATE_KEY.key”, que não deve ser compartilhada, e a chave de solicitação de registro “REQUEST_CERTIFICADO.csr”, que deverá ser enviada para o Banestes para validação, assinatura e geração do certificado final.

Exemplo e validação do request certificate e key

Veja abaixo um exemplo do conteúdo da chave de solicitação de registro:

Exemplo do conteúdo do arquivo “REQUEST_CERTIFICADO.csr”

Veja abaixo um exemplo do conteúdo da chave privada:

Exemplo do conteúdo do arquivo “PRIVATE_KEY.key”

Para validar se a chave de solicitação de registro foi criada corretamente:

Comando:

Exemplo de retorno:

Para execução do comando CNF e consequente criação do Request Certificate e sua KEY, é necessário ter uma APP já criada e aprovada pelo Banestes.

Mesmo com o comando CNF em mãos, gerado no processo anterior, você pode optar por não executá-lo e deixar que o Portal dos Desenvolvedores do Banestes faça este processo para você. Para criar o Request Certificate e a sua respectiva KEY de forma "automática", basta seguir os procedimentos abaixo:

• Logar no Portal dos Desenvolvedores do Banestes;
• Acessar o formulário "Certificados para operações de PIX" por este link;
• Será apresentado uma listagem de todas as APPs que foram criadas por você no portal;
• Na listagem de APP clique no botão "CSR e KEY";
• De forma automática, será gerado os arquivos CSR (Request Certificate) e KEY (chave privada), conforme imagem de exemplo abaixo:

Registrar o Certificado

Processo

Para execução destes processos, é necessário ter uma APP criada e aprovada pelo Banestes.

• Registrar Certificado
• Gerar e Registrar Certificado

Para execução destes processos, é necessário ter gerado o Request Certificate (CSR) e KEY de forma manual ou pelo Portal dos Desenvolvedores do Banestes.

Para enviar o Request Certificate (CSR) ao Banestes e registrá-lo como Certificado de acesso, basta seguir os procedimentos abaixo:

• Logar no Portal dos Desenvolvedores do Banestes;
• Acessar o formulário "Certificados para operações de PIX" por este link;
• Será apresentado uma listagem de todas as APPs que foram criadas por você no portal;
• Na listagem de APP clique no botão "Registrar Certificado" e, no formulário apresentado, clique no botão "Registrar Certificado";
• No campo apropriado, preencha com o Request Certificate (CSR) e clique no botão "Confirmar";
• O arquivo será enviado para o Banestes valida-lo. Caso passe pela validação automática, o certificado será gerado de forma imediata. Se o Banestes entender que precisa de validações mais detalhada, retornaremos por e-mail a geração do certificado;

Consideramos a execução deste processo como um processo "automático", ou seja, não é necessário gerar e executar o CNF e muito menos ter em mãos o Request Certificate (CSR) e KEY.

Para Gerar e Registrar um Certificado, basta seguir os procedimentos abaixo:

• Logar no Portal dos Desenvolvedores do Banestes;
• Acessar o formulário "Certificados para operações de PIX" por este link;
• Será apresentado uma listagem de todas as APPs que foram criadas por você no portal;
• Na listagem de APP clique no botão "Registrar Certificado" e, no formulário apresentado, clique no botão "Gerar e Registrar Certificado";
• Este processo enviará uma solicitação de Certificado ao Banestes e o mesmo irá validar a sua solicitação. Caso passe pela validação automática, o certificado será gerado de forma imediata. Se o Banestes entender que precisa de validações mais detalhada, retornaremos por e-mail a geração do certificado;

Exemplo do Certificado

example

Exemplo do conteúdo de um Certificado (chave pública) após validado, assinado e registrado pelo Banestes.

• Ter uma APP (client_id e client_secret), criada e autorizada;
• Ter um certificado (CRT e KEY), criado e registrado.

.... você poderá iniciar o processo de consumo das APIs. Para isto siga as instruções do tópico “Consumo das APIs”.

Renovação do Certificado

processo

O certificado poderá ser renovado a partir dos 60º dia que antecedem o término da sua validade. Caso contrário, o certificado ficará inválido para o consumo das APIs e será necessário refazer todo o fluxo de criação, validação e registro de um novo certificado para a APP.

O Banestes não avisará quando o certificado expirará, porém é possível consultar esta informação no Portal dos Desenvolvedores conforme descrito abaixo:

• Logar no Portal dos Desenvolvedores do Banestes;
• Acessar o formulário "Certificados para operações de PIX" por este link;
• Será apresentado uma listagem de todas as APPs que foram criadas por você no portal;
• Na listagem de APP clique no botão "+ detalhes";
• Será apresentado um formulário com as informações da APP e todos os seus certificados. Entre as informações será possível ver a data de validade do Certificado;

Processo de renovação

O processo de renovação é o mesmo da criação de um novo certificado, a única diferença é que a renovação só é possível ser feito se o atual certificado estiver com a sua validade igual ou inferior a 60 dias.

Revogação do Certificado

processo

Os certificados do Banestes são revogáveis e o processo pode ser feito pelo dono da APP ou pelo time de Segurança do Banestes sem aviso prévio.

Caso o dono da APP necessite revogar um certificado, siga os passos abaixo:

• Logar no Portal dos Desenvolvedores do Banestes;
• Acessar o formulário "Certificados para operações de PIX" por este link;
• Será apresentado uma listagem de todas as APPs que foram criadas por você no portal;
• Na listagem de APP clique no botão "+ detalhes";
• Será apresentado um formulário com as informações da APP e todos os seus certificados. No certificado ativo, clique no botão "Revogar acesso";
• Justifique o motivo da revogação e clique no botão "Confirmar";

Consumo das APIs

Com a criação da APP para autenticação (doc) e com a geração e registro do Certificado para autorização (doc), agora você está apto a consumir as APIs do Banestes.

Para isso siga os passos descritos abaixo

Base URLs

Antes de entrarmos nos detalhes do processo, é importante ressaltar como identificar as APIs do Banestes e em qual ambiente ela se encontra, que pode ser SANDBOX ou PRODUÇÃO.

APIs e Modelo de autenticação

Nossas APIs são RESTful, seguem as regras definidas na arquitetura REST - Representational State Transfer (referência: W3C), e utilizam JSON como formato de troca de dados (referência: json.org). Elas também são compatíveis com o protocolo OAuth 2.0, contemplando especialmente o fluxo client_credentials e mTLS para autorizar acesso a dados e transações baseado em tokens de acesso, no qual utilizamos fluxos específicos para a situação server-to-server.

Desta forma, o acesso a todas as nossas APIs, independente do ambiente, segue o padrão OAuth 2.0 Client Credentials, para geração do “access_token”. Porém, cada ambiente (Sandbox e Produção) tem a sua própria APP para geração dos Access Tokens, e cada ambiente tem o seu certificado para o fluxo de mTLS (handshake).

Lembrando que a etapa de testes em sandbox é fortemente recomendada antes das chamadas para as APIs produtivas, já que nele você pode testar vários cenários para entender o processo de implantação do access token + certificado e facilitar o momento da entrada em produção da sua aplicação.

• Certificado, do fluxo de mTLS, é válido por 365 dias;
• Access token é válido por 5 minutos (300 segundos);
• É necessário utilizar o certificado válido tanto para o processo de geração do access token quanto para chamar as operações das APIs.
• As credências obtidas (APP e Certificados) são específicos por ambiente, ou seja, as credenciais de Sandbox não funcionarão no ambiente de Produção e vice-versa.

Segue abaixo procedimentos para gerar as chaves e token específicos por ambiente:

Geração do Access Token

Com as informações da APP, também conhecido como Authorization (“client_id:client_secret” em base64) e o certificado da APP (CRT e KEY) específico do ambiente (sandbox ou produção), a operação de geração do access token é a seguinte:

Comando:

Onde: base64(client_id:client_secret) = Trata-se do “client_id”, seguido de “:” e do “client_secret” da sua APP, convertido em Base64;

Exemplo do comando:

Exemplo do retorno:

Acesso às APIs Banestes

Com a informação do access token gerada para a APP, também conhecido como "Authorization Bearer" ou "Bearer access token" e o certificado da APP (CRT e KEY) do ambiente (sandbox ou produção), você poderá acessar as APIs do Banestes.

Comando:

Onde: {{access_token}} = Trata-se do access token gerado no processo de obtenção do token de acesso;

Exemplo do comando:

Exemplo do retorno:

• Navegue pelo nosso catálogo de APIs e explore nossas documentações;
• Clique em ver especificação técnica, localizado no card da API, ou abra a API que deseja testar e clique no botão ver especificação técnica.

Notificação Webhook

Introdução

O que é Webhook?

O objetivo de um Webhook é notificar uma entidade externa, por exemplo o parceiro, do acontecimento de um evento de negócio ou técnico.

A aplicação responsável pela emissão do evento possui o controle de quem deve ser notificado na ocorrência do mesmo, podendo controlar os destinatários corretos para cada tipo de evento emitido. Esses filtros são chamados de target-id.

Através desses targets, o Hub de Notificação do Banestes filtra as mensagens que são enviadas para um endpoint centralizado e, em seguida, envia para os destinatários parceiros via webhook.

As respostas provenientes das notificações são posteriormente enviadas para os tópicos de resposta, onde a aplicação emissora do evento pode consumi-las e ter o resultado da notificação.

Quando deve ser utilizado?

A utilização do Hub de Notificação é indicada para arquiteturas que tenham a necessidade de notificar o(s) parceiro(s) interno(s) ou externo(s) do Banestes.

Em local apropriado, que iremos explicar neste tutorial, o Banestes deverá ser informado qual é a URL de notificação de webhook que irá utilizar para enviar os requests de notificação por produto (API).

Configure a sua Infraestrutura

Cadastre a sua URL

As notificações são por produto (API) e, desta forma, a configuração da sua URL deverá ser feita por produto conforme documentação Swagger da API do produto.

Por exemplo, a API “PIX ARRECADAÇÃO Banestes” tem as operações de cadastro e gestão de Webhook (/webhook). Com a operação “[PUT] /webhook/{chave}” vocês poderão cadastrar a URL da sua operação de notificação, e com as demais operações (GET e DELETE), poderão gerenciar o cadastro feito.

Após o cadastro, quando o Banestes precisar notificá-los, iremos enviar um request POST informando o conteúdo da notificação.

Para mais detalhes técnicos do cadastro, gestão e conteúdo das notificações, veja a documentação Swagger da API do produto, path “/webhook”

Segurança de acesso

Por questão de segurança, as suas operações de recepção das notificações de webhook que o Banestes irá enviar não podem ficar expostas para a internet de forma 100% pública. Desta forma, precisamos que vocês configurem um fluxo de validação de acesso por mTLS

Porém, antes, vamos entender o que é mTLS (Mutual Transport Layer Security): O mTLS é um protocolo de criptografia de autenticação mútua que tem como principal finalidade garantir que as duas pontas de uma conexão de rede são quem afirmam ser, verificando também suas respectivas chaves privadas. Ele se baseia no Transport Layer Security (TLS), que tem como papel autenticar o servidor em uma conexão client-server e criptografar as comunicações. O TLS trabalha utilizando a técnica de criptografia assimétrica, que depende de um par de chaves: uma chave pública e uma chave privada. Desta forma o mTLS é um método que faz com que o servidor faça a validação do cliente, utilizando TLS. O mTLS é comumente utilizado no mercado financeiro, principalmente para identificação de instituições e suas transações entre si, já que as mesmas terão suas chaves de identificação. Portanto, ao analisar uma requisição em uma API financeira, é possível verificar que a entidade A fez uma transação com a entidade B através dos certificados usados, que normalmente são gerados por uma certificadora que faz as devidas validações de instituição por TrustCA.

Configure a sua Infraestrutura

Desta forma, o Banestes precisará que vocês configurem o ambiente de notificações de webhook para validar o certificado de acesso do Banestes através da TrustCA:

APOIO

Seguem abaixo alguns materiais de apoio para auxiliá-los na jornada de integração com o Banestes.

• Collection Postman: API Pix ARRECADAÇÃO (banestes).postman_collection.json;
• Collection Postman: API Pix COBRANÇA (banestes).postman_collection.json;
• Environment Postman: Banestes-ClientSandbox.postman_environment.json;