Onboarding BTG

Clique em Novo consentimento;
Na etapa de Parametrizações, preencha o campo CNPJ, e em seguida, habilite os escopos desejados;
Clique em Iniciar o consentimento;
Você é encaminhado para a tela de cadastro do BTG, onde é necessário possuir uma conta cadastrada para acessar;
Ao acessar, são mostrados os escopos que foram habilitados na etapa de Parametrização, no ERP senior X. Clique em Continuar;
Você é encaminhado para a tela de confirmação CNPJ. Após confirmar, você é redirecionado para o ERP senior X;
Já no ERP senior X, o consentimento é finalizado;
Clique em Finalizar;

Após isso, o escopo habilitado passa a ser exibido na Lista de Consentimentos, e através do botão Ações, é possível Refazer o consentimento ou então Consultar o histórico.

Fluxo do processo

Redirecionamento Inicial

Quando um usuário tenta acessar os serviços do BTG a partir do ERP Banking, ele é redirecionado para a página de login do BTG. Durante esse redirecionamento, são enviados vários dados essenciais, incluindo a URL de redirecionamento, o client_id do ERP Banking, um código de sessão para controle interno e outros parâmetros necessários para o processo de autenticação.

Concessão de Permissões

Na página de login do BTG, o usuário deve conceder permissões para os escopos solicitados pelo ERP Banking. Após a concessão das permissões, o usuário é redirecionado de volta para a URL especificada inicialmente.

Recebimento de Dados

No redirecionamento de volta para o ERP Banking, são recebidos dois elementos chave: o código de sessão, que é utilizado para controle interno do ERP Banking, e um authorization code, que indica que o usuário concedeu as permissões necessárias.

Obtenção de Tokens

O authorization code recebido é então utilizado, junto com o client_id e o client_secret, para obter os tokens de acesso (accessToken) e atualização (refreshToken). Esses tokens são cruciais para futuras interações com as APIs do BTG.

Os tokens devem estar vinculados ao usuário e serem utilizados nas chamadas às APIs do BTG para operações em contas bancárias, como emissão de boletos, transferências via PIX, entre outras.

O accessToken é válido por 24 horas, enquanto o refreshToken tem validade de 10 dias. Em geral, cada requisição às APIs retorna um refreshToken atualizado.

Se o refreshToken expirar, é necessário passar novamente pelo processo de consentimento.

Armazenamento e Uso dos Tokens

Os tokens (accessToken e refreshToken) obtidos são armazenados e vinculados ao usuário no ERP Banking. Esses tokens são necessários para a execução de operações financeiras através das APIs do BTG, como emissão de boletos, realização de transferências via PIX, entre outras.

autenticacaoBtg

Armazena tokens de autenticação e informações de consentimento do banco BTG.

Atributos:

Id do registro;
CNPJ consentido;
Access Token para acesso às APIs do BTG;
Refresh Token para solicitação de um novo Access Token;
Status do consentimento com BTG:
- PROCESSANDO;
- ATIVO;
- ATIVO_COM_ALERTA;
- INATIVO.
Mensagem em caso de erro;
Data e hora do último consentimento bem-sucedido;
Escopo utilizado na integração com BTG.

autenticacaoBtgHistorico

Armazena o histórico de autenticações realizadas com o banco BTG.

Atributos:

Id do registro;
Access Token para acesso às APIs do BTG;
Status da autenticação com BTG;
Mensagem em caso de erro;
Data e hora do último consentimento bem-sucedido.

Caminho para configuração

Acesse Tecnologia > Configuração > Por Tenant;
Filtre pelo seu tenant;
Pesquise pelo domínio erpx_bnk;
No serviço onboarding, clique em Editar;
Acesse a guia Sistema. Esta guia possui os parâmetros para a configuração do serviço onboarding.

Estrutura

"Action para iniciar autenticação com o banco BTG"
        action gerarAutenticacaoBtg {
        	in {
        		"Código de autorização do consentimento no BTG"
        		authorizationCode: string
        		"CNPJ que foi feito o consentimento"
                cnpj: string
        	}
        	out{}
        }
        
        "Signal para gerar autenticação com o banco BTG"
        signal gerarAutenticacaoBtgAsync {
        	in {
        		"Código de autorização do consentimento no BTG"
        		authorizationCode: string?
        		"Id do registro de autenticação com o BTG no banking"
        		autenticacaoBtgId: string?
        	}
        }
        
        "Sinal para atualizar o token de acesso as APIs do BTG"
        signal refreshBtgToken {
        	in {
	        	"CNPJ que foi feito o consentimento"
	            cnpj: string
        	}
        }
        
        "Event para avisar como finalizou a autenticação com BTG"
        event autenticacaoBtgFinalizada {
        	payload {
        		"Status da autenticação com BTG"
        		situacao: enumSituacaoAutenticacaoBtg?
        		"Mensagem em caso de erro na autenticação"
        		mensagemErro: string?
        	}
        }
    }

Processos

Ao chamar a API, é verificado se há alguma autenticação em andamento. Se uma autenticação estiver em processo, a seguinte exceção é lançada: "Existe um consentimento sendo processado. Aguarde-o finalizar antes de avançar."

Composição da URL

Ao realizar a verificação da autenticação, caso não haja erros, a URL é montada com os seguintes critérios e valores:

URL base: a URL base é montada de acordo com o valor da propriedade BTG - Produção habilitado que pode ser encontrada neste caminho.

Caso esteja Verdadeiro, a URL será: https://id.sandbox.btgpactual.com
Caso esteja Falso, a URL base será: https://id.btgpactual.com

API de autenticação: compõe a URL com o trecho: /oauth2/authorize
Client ID: a URL recebe o seguinte trecho: ?client_id= O valor da propriedade BTG - Client id
Response type: compõe a URL com o trecho: &response_type=code
URL de redirecionamento do banking: a URL de consentimento recebe o parâmetro redirect_uri, que compõe com o seguinte trecho: &redirect_uri=endereço do serviço
Ao informar o campo CNPJ, devem constar os seguintes parâmetros na URL gerada:
- state=CNPJ INFORMADO
- resource=CNPJ INFORMADO
Escopo: é necessário constar na URL o escopo que será disponibilizado no BTG, com seguinte trecho: &scope=openid empresas.btgpactual.com/bank-slips empresas.btgpactual.com/bank-slips.readonly empresas.btgpactual.com/accounts empresas.btgpactual.com/accounts.readonly
Prompt: compõe a URL com o trecho: &prompt=consent

A partir desses parâmetros a URL de consentimento é montada, e sua estrutura fica de acordo com o exemplo:

https://id.sandbox.btgpactual.com/oauth2/authorize?client_id=1c2c82a2-f9e8-40f8-a802-6ab9842860d1&response_type=code&redirect_uri=https://cloud-leaf.senior.com.br/gestao-empresarial/erpx_bnk_cob/pix&scope=openid empresas.btgpactual.com/bank-slips empresas.btgpactual.com/bank-slips.readonly empresas.btgpactual.com/accounts empresas.btgpactual.com/accounts.readonly&prompt=consent

Estrutura

"Action para iniciar autenticação com o banco BTG" action gerarAutenticacaoBtg { in { "Código de autorização do consentimento no BTG" authorizationCode: string "CNPJ que foi feito o consentimento" cnpj: string } out{} } "Signal para gerar autenticação com o banco BTG" signal gerarAutenticacaoBtgAsync { in { "Código de autorização do consentimento no BTG" authorizationCode: string? "Id do registro de autenticação com o BTG no banking" autenticacaoBtgId: string? } } "Sinal para atualizar o token de acesso as APIs do BTG" signal refreshBtgToken { in { "CNPJ que foi feito o consentimento" cnpj: string } } "Event para avisar como finalizou a autenticação com BTG" event autenticacaoBtgFinalizada { payload { "Status da autenticação com BTG" situacao: enumSituacaoAutenticacaoBtg? "Mensagem em caso de erro na autenticação" mensagemErro: string? } } }

Processos gerarAutenticacaoBtg

A API gerarAutenticacaoBtg recebe um código de autorização (authorizationCode) do BTG:

Se existir alguma autenticação sendo processada, lança a exceção: "Existe um consentimento sendo processado. Aguarde-o finalizar antes de avançar";
Se não existir, cria um registro na tabela autenticacaoBtg com os seguintes valores:
- autenticacaoBtg.situacao = PROCESSANDO;
- autenticacaoBtg.cnpj = CNPJ INFORMADO.

Veja abaixo os detalhes em caso de Sucesso e em caso de Falha da autenticação:

Processos refreshBtgToken

A API refreshBtgToken recebe o CNPJ e atualiza os tokens da tabela autenticacaoBtg para o CNPJ informado. Além disso, ela é responsável por atualizar os tokens de autorização do BTG a cada 12 horas.

Na chamada da API refreshBtgToken, é buscado o último registro de consentimento na tabela autenticacao_btg com situacao = SUCESSO.

Caso encontre algum registro, busca o campo autenticacao_btg.refresh_token, e descriptografá-o.

Após descriptografar o refresh token, chama a API de autenticação do BTG para buscar os novos tokens de autorização:
- Ao buscar os novos tokens, criptografá-os e atualiza a tabela autenticacao_btg nos seguintes campos:
  - autenticacao_btg.acess_token;
  - autenticacao_btg.refresh_token;
  - autenticacao_btg.situacao = SUCESSO.

Qualquer erro que ocorra neste processo, atualiza a tabela autenticacao_btg para ERRO:
- autenticacao_btg.situacao = ERRO;
- autenticacao_btg.mensagem_erro = mensagem de erro ocorrida durante o processo.

Onboarding BTG

Como realizar o consentimento?

Fluxo do processo de consentimento com o banco BTG

Microsserviço e entidades

Criação do consentimento

PORTAL DE DOCUMENTAÇÃO
Gestão Empresarial \| ERP senior X