Integração bancária API BTG Pactual
Atenção, Beta!
A integração com a API BTG Pactual e o envio de Template Cobrança Pix via WhatsApp com o Opa! Suite estão presentes na versão Beta do Sistema. Sua disponibilidade na versão Estável será a partir de Julho de 2025.
Este documento apresenta orientações detalhadas sobre a integração e uso da API do Banco BTG Pactual para emissão do boleto híbrido de cobrança, incluindo a configuração do Webhook para notificações em tempo real. A API proporciona automação dos processos bancários, enquanto o Webhook garante atualizações instantâneas sobre transações e eventos.
Objetivos da integração
- Ampliar as possibilidades de integração com o sistema.
- Atender clientes do Banco BTG Pactual que desejam utilizar a integração com o sistema.
- Permitir a emissão automática de boletos híbridos e o controle integrado da baixa de pagamentos.
- Oferecer mais uma alternativa de integração para os clientes, aumentando a flexibilidade na utilização de soluções financeiras.
Benefícios da integração
1. Automação de processos
- Baixa automática de pagamentos: os pagamentos realizados serão baixados automaticamente no sistema, proporcionando mais precisão e economia de tempo.
2. Economia e eficiência
- Redução de custos: com as tarifas competitivas do BTG Pactual, os clientes podem economizar nas transações ao usar uma solução integrada.
3. Melhor experiência para o cliente
- Atendimento à demanda: atende clientes que já possuem conta no BTG e querem utilizá-la no sistema.
- Facilidade para configurar: foi desenvolvida para ser fácil de implementar, possibilitando o uso imediato.
Processo de integração e homologação
Para realizar a integração e homologação da API BTG no sistema, siga os passos abaixo.
Homologação
Dados bancários necessários para a integração:
Banco BTG Pactual (API)
- 1 - Client_ID
- 2 - Client_Secret
Dica!
Caso tenha dúvida sobre algum desses dados bancários, entre em contato com seu gerente de contas ou com o suporte da instituição financeira.
Passo a passo para obter as credenciais da API
Aviso!
Para homologar a carteira de API do BTG é necessário gerar o Client ID e o Secret, que são as credenciais da aplicação da API criadas no Internet Banking do Banco BTG Pactual.
Para este processo, é obrigatório que seja utilizado o login de acesso do titular da conta bancária.
- Acesse o Internet Banking BTG Pactual.
- Faça login com sua conta.
- No menu lateral esquerdo, clique em Integrações.
- Role a página até a seção APIs e clique no botão Ir para Developers.
- Encontre e clique no botão Criar Aplicativos.
- Na tela de criação do aplicativo, o ambiente padrão estará definido como Sandbox. Marque a caixa de seleção para alterar para o ambiente Produção.
- Preencha os dados solicitados:
- Nome do aplicativo: insira um nome personalizado.
- Descrição do aplicativo: insira um breve resumo da finalidade do aplicativo.
- Tipo: selecione a opção Confidencial.
- Modelo de integração: selecione a opção First party - Consumir recursos de contas próprias.
- Clique no botão Continuar.
- Selecione os Escopos utilizados pela API:
- Perfil do usuário
- Banking: Pix Cobrança
- Banking: Saldo e Extrato
- Banking: Boleto Cobrança
- Banking: Cobranças
- Gestão de Webhooks
- Você será direcionado para a etapa de Resumo da aplicação. Verifique se os dados e os escopos estão corretos e clique em Continuar.
- O aplicativo será criado com sucesso, mas ficará pendente de aprovação.
- Na lateral esquerda, clique no menu Aprovações, localize a notificação de aprovação do novo aplicativo criado e conclua sua autorização para que fique ativo e pronto para uso em produção.
- Após autorizado, clique em Ir para Aplicativo.
- No menu do aplicativo, clique em Chaves.
- Copie as credenciais da aplicação:
- Client ID
- Secret
Credenciais criadas!
Agora, no Sistema, inicie a criação da carteira de cobrança.
- Não feche a página da aplicação de API, ela ainda será utilizada em passos de configuração futuros.
Criando a Carteira
- Acesse o menu Sistema.
- Entre na pasta Financeiro.
- Clique em Carteira de cobrança.
- Clique em Novo.
- Na primeira aba, chamada Carteira de cobrança, configure os seguintes campos:
- Descrição: Defina um nome para a carteira.
- Conta: Crie ou insira a conta responsável por armazenar os dados bancários (sua filial deve ser de mesmo CNPJ da conta BTG).
- Tipo de recebimento: Escolha a opção Gateway.
- Enviar e-mail para cliente ao gerar: Selecione Não, pois essa opção exige que o cliente tenha e-mail cadastrado e envia automaticamente a fatura ao banco, não sendo recomendada.
- Validar filial na venda: Selecione Sim.
- Planejamento analítico: Utilize o padrão 240 ou cadastre um novo.
Criando a Conta
- Conta: Defina um nome para a conta.
- Tipo da Conta: Marque Banco.
- Data de abertura: Informe a data em que está configurando a conta para esta carteira.
- Planejamento analítico: Para mais informações, acesse: Contas Contábeis Analíticas.
- Filial: Selecione o ID da filial para a qual a Conta e a Carteira serão criadas.
Atenção!
A integração com a API BTG Pactual exige que o CNPJ da conta associado à carteira de cobrança, seja o mesmo da conta bancária BTG Pactual.
Na aba Banco (Não obrigatório):
- Banco: busque e insira o código de cadastro
208 - Banco Pactual S.A.
- Agência: Digite o número da agência bancária.
- Dígito verificador da agência: Insira o dígito verificador localizado após o número da agência, caso possua.
- Número da conta: Informe o número da conta bancária.
- Dígito verificador da conta: Digite o dígito verificador da conta bancária, caso possua.
Configurações gateway
- Gateway: Selecione BTG Pactual.
- Ambiente gateway: Escolha Produção.
- Client_ID: Informe o Client ID gerado anteriormente em sua conta BTG.
- Client_Secret: Informe o Secret gerado anteriormente em sua conta BTG.
- Webhook ID: Este campo será preenchido em etapas posteriores.
- Data de crédito Pix: Informe a data em que o crédito das transações via Pix será considerado.
- Data de crédito boleto: Informe a data em que o crédito das transações por boleto (código de barras) será considerado.
Data de crédito!
- Valor 0: considera a data de crédito igual à data de pagamento.
- Valor 1: considera a data de crédito com um dia adicional à data de pagamento.
- Limite de pagamento após o vencimento (dias): Informe a quantidade de dias permitidos para pagamento após o vencimento do título.
- Envia e-mail gateways: Selecione Não.
- Gera Pix: Selecione Sim se desejar utilizar Pix no boleto.
Atenção, Beta!
O parâmetro Enviar cobrança Pix pelo WhatsApp está presente na versão Beta do Sistema. Sua disponibilidade na versão Estável será a partir de Julho de 2025.
- Enviar cobrança Pix pelo WhatsApp: Ativa a funcionalidade de envio do Template Cobrança Pix, exclusivo da integração com o Opa! Suite. Habilitando este parâmetro, um novo campo ficará visível e obrigatório:
- Tipo da chave Pix: Selecione na lista a opção que corresponde ao tipo da chave Pix que será utilizada (CPF/CNPJ, E-mail, Telefone ou Chave Aleatória).
- Chave Pix: Insira a chave Pix principal que está configurada e é utilizada pela sua conta na instituição financeira correspondente a esta carteira de cobrança.
- Tarifas Gateway: Defina como será feito o lançamento das tarifas, pois o banco não realiza esse processo automaticamente. Para mais informações, consulte o conteúdo Tarifas bancárias - Gateway, API e Pix.
Após o preenchimento das informações acima, clique no botão Salvar para que a carteira de cobrança seja registrada no sistema e seja possível gerar sua URL de webhook.
Em seguida, realize os passos abaixo:
- URL Webhook redirecionamento: clique em Gerar URL para que a URL da carteira seja criada no sistema. Finalize as alterações clicando em Salvar.
Com a URL Webhook redirecionamento gerada, acesse novamente a aplicação de API e configure a URL conforme instruções abaixo:
Configurando URL Webhook na API BTG
Após gerar o endereço da carteira no sistema:
- Acesse a aplicação de API em sua conta BTG Pactual, pelo menu Aplicativos.
- Na aplicação que foi criada, clique no botão de ações e selecione Detalhes.
- No painel de informações, clique em Editar aplicativo.
- No campo URI’s de redirecionamento, insira a URL Webhook redirecionamento criada anteriormente na carteira de cobrança.
- Clique em Continuar nas etapas seguintes e também na tela de Resumo para finalizar a edição.
Uma janela de confirmação será exibida. Preencha o motivo da alteração (ex: inserção do webhook) e clique em Confirmar.
Após configurar a URL na aplicação da API, volte à carteira de cobrança no sistema e acesse a aba Configurações gateway. Um novo botão estará disponível: Autenticar BTG Pactual.
Clique em Autenticar BTG Pactual, e você será direcionado à uma página do BTG para realizar login e concluir as etapas do processo de verificação:
- No primeiro passo será um informativo dos dados de sua conta que o aplicativo está solicitando, clique em Continuar.
- No segundo passo, você deve selecionar o CNPJ correspondente a sua conta bancária (certifique-se de ser o mesmo CNPJ da filial da conta no sistema), e então clicar no botão Continuar.
- No terceiro passo, serão listadas as contas bancárias disponíveis para seu CNPJ. Certifique-se de selecionar a conta correta e então clique no botão Confirmar.
Se o processo de autenticação for concluído com sucesso, você será redirecionado ao seu Sistema (pela URL de redirecionamento), e o campo Webhook ID será preenchido automaticamente.
Aviso!
Se houver falha no processo de autenticação, será exibida uma tela contendo mensagens de erro diretamente do BTG, indicando que há alguma falha na configuração.
Durante a autenticação, caso existam múltiplas empresas, será necessário selecionar a conta/empresa vinculada ao aplicativo. Após a seleção, o retorno ao Sistema ocorrerá automaticamente.Nesse momento, será necessário editar novamente a carteira de cobrança. Se o botão Autenticar BTG Pactual ainda estiver visível, a autenticação não foi concluída com sucesso. Neste caso, acesse os logs da carteira de cobrança para verificar o erro e realizar os ajustes necessários.
Informação!
A autenticação do Webhook ID é exigida pelo BTG a cada 24 horas. Para manter a integração ativa, o sistema executa uma rotina automática no seu servidor, três vezes ao dia, garantindo assim a continuidade da comunicação com a API.
Enviar Template Cobrança Pix via WhatsApp com o Opa! Suite
A integração do sistema com a plataforma de mensagens WhatsApp, em parceria com a Meta e OPA! Suite, abre novas possibilidades para a comunicação com seus clientes. Uma dessas funcionalidades é o envio detalhado de informações de cobrança Pix diretamente pelo aplicativo de mensagens WhatsApp. A funcionalidade está disponível em Sistema para carteiras de cobrança do tipo Gateway
e Pix
.
Quando configurado, seu Sistema estará habilitado para enviar um template otimizado de cobranças Pix ao seu cliente por meio da integração com o Opa! Suite.
Dica!
Para mais detalhes da funcionalidade e configuração, verifique em Enviar Template Cobrança Pix via WhatsApp com o Opa! Suite.
Juros/Multas/Desconto
- Juros %: Configure 0.033%, respeitando o limite legal.
- Multa %: Configure 2%, limite máximo permitido por lei.
- Desconto até o vencimento R$: Informe um valor fixo em Reais para desconto em pagamentos até a data do vencimento.
- Desconto até o vencimento %: Insira um percentual de desconto para pagamentos realizados até o vencimento.
Para mais informações, acesse: Juros, Multas e Desconto.
Instruções
Informação:
- Permitido o máximo de 200 caracteres por linha de instrução impressa no boleto.
- Não há limite de linhas.
- Instrução 1:
Após vencimento juros R$ #juro# ao dia.
- Instrução 2:
Após vencimento multa R$ #multa#.
Aviso!
Caso adicione mais linhas, também deve inserir a variável de leitura da linha de instrução, nos parâmetros Imprimir instruções quando…
Para mais informações, acesse: Instruções da Carteira de Cobrança.
Impressão
- Layout de impressão: Utilize o padrão 3 por página.
Para mais informações, acesse: Layouts de Impressão.
Duplicar Carteira de Cobrança API BTG Pactual
Aviso!
Por questões de segurança e de funcionamento da API, não é possível duplicar uma carteira de cobrança que utiliza a API BTG Pactual.
É necessário criar um aplicativo de API para cada carteira de cobrança que for configurada em seu Sistema.
Dados obrigatórios para criação de um boleto API BTG Pactual
Criação de Boleto:
Para criar e registrar boletos de cobrança para a API BTG Pactual a partir do Sistema, alguns campos de cadastro de cliente são obrigatórios, sendo eles:
Cadastro Cliente (Sistema)
- Aba Cliente:
- Razão social/Nome.
- CNPJ/CPF.
- Aba Endereço:
- CEP.
- Cidade.
- Estado.
- Endereço (rua).
- Número.
- Aba Contato:
- Telefone celular.
- E-mail principal.
Dica!
A API BTG não exige valor mínimo para o registro de uma cobrança, necessita que seja apenas maior que zero.
Conciliação Bancária!
No momento, não há suporte para o procedimento de conciliação bancária via Sistema.
Fluxo de Funcionamento
sequenceDiagram participant S as Sistema participant API as API BTG participant W as Webhook S->>API: Envia requisição (ex: gerar boleto) API->>S: Responde com dados do boleto Note over API,W: Evento ocorre (ex: pagamento) W->>S: Notifica sobre o evento S->>API: Confirma recebimento da notificação
Tarefa de Processamento de Retorno
Dica:
Caso queira uma garantia adicional de baixa de pagamentos, além do webhook, também é possível configurar uma tarefa que consulta os pagamentos.
Esta tarefa deve ser configurada para executar somente 1x no dia, pela manhã, e com isso sempre irá consultar os pagamentos dos títulos que vencem no dia anterior.
Para realizar a configuração, acesse:
- Menu Ferramentas
- Clique em Ferramentas
- Agenda de tarefas
- Botão Novo
- Tarefa: Selecione Processamento retorno BTG API
- Minuto (0-59): Coloque o valor dos minutos, entre 0 e 59 min
- Hora (0-23): Coloque o valor da hora, entre 0 e 23
Ativação
Finalizado!
Após seguir os passos acima, a carteira e as tarefas de consulta estarão configuradas. Agora, é possível gerar um boleto de teste e realizar um pagamento para verificar a baixa automática no sistema.
Quando a fatura for baixada automaticamente, significa que a homologação foi concluída com sucesso.
Alteração de Domínio ou URL do Sistema
Cuidado!
Se ocorrer a alteração do domínio de sua base/sistema, é necessário alterar a URL de Recebimento e a URL de Redirecionamento. Nesse caso, é necessário deletar o webhook na aplicação de API em sua conta BTG Pactual, deletar o Webhook ID na carteira de cobrança e realizar a autenticação novamente, no botão
Autenticar BTG Pactual
.
Considerações Finais
A integração entre o BTG Pactual e o Sistema representa um avanço importante para melhorar o funcionamento dos negócios de sua empresa. Com processos automatizados, redução de custos e suporte às necessidades dos clientes, essa parceria contribui para um gerenciamento financeiro mais eficiente e simples.
Etiquetas
IntegracaoBancaria APIBancaria BTG
Leia Também
- Carteira de Cobrança
- Integrações Bancárias - Carteira de Cobrança
- Integrações Bancárias - API
- Como Solicitar o Pix na Central do Assinante
- Tarefa - Processamento Retorno BTG Pactual
- Reenvio Webhook Pagamento API BTG Pactual
- Status API BTG Pactual: https://btgpactualempresas.statuspage.io/
- Manual API BTG Pactual: https://developers.empresas.btgpactual.com/docs/comecando