Integração Bancária API Banco do Brasil Webhook
Este documento fornece instruções detalhadas sobre a integração e utilização da API do Banco do Brasil, incluindo a configuração do Webhook para notificações em tempo real. A API permite a automação de processos bancários, enquanto o Webhook garante atualizações instantâneas sobre transações e eventos.
Requisitos Importantes
- Sistema operacional Debian 10.
- Para a homologação de uma carteira API o indicado é abrir um novo convênio de conta bancária. Caso deseje utilizar um que já esteja em uso no Sistema e/ou que já tenha boletos emitidos por ele, deve estar ciente de que podem ocorrer divergências nos relatórios provenientes de arquivos de retorno.
Entre as divergências estão: Informação de Título não encontrado nos processamentos de retorno (quem se referem a títulos da carteira de API), liquidações atreladas a boletos divergentes, etc.- Além disso, após a homologação de sua carteira de API, é crucial evitar a geração de novos boletos pela antiga carteira de remessa/retorno, que utiliza o mesmo convênio.
Funcionalidades principais
- Geração automática de boletos.
- Consulta de status de transações.
- Recebimento de notificações em tempo real por meio do Webhook.
- Gerenciamento da carteira de cobrança.
Funcionamento no sistema
A integração da API do Banco do Brasil no sistema ocorre da seguinte forma:
- Autenticação:
- O sistema utiliza as credenciais fornecidas pelo Banco do Brasil para se autenticar e acessar a API.
- Sincronização de dados:
- O sistema envia as informações de cobrança para o Banco do Brasil.
- Recebe atualizações sobre o status dos boletos e dos pagamentos.
- Processamento automático:
- Os pagamentos são baixados automaticamente no sistema.
- Interface de usuário:
- Os usuários conseguem gerenciar boletos e visualizar as informações diretamente no sistema.
Processo de integração e homologação
Para realizar a integração e homologação da API do Banco do Brasil no sistema, siga os passos abaixo:
Homologação
Dados bancários necessários para a integração:
001 - Banco do Brasil (API)
- 1 - Número da agência com dígito?
- 2 - Número da conta com dígito?
- 3 - Número do Convênio / Beneficiário ou Cedente?
- 4 - Número da carteira?
- 5 - Variação da carteira?
- 6 - Client_ID?
- 7 - Client_Secret?
- 8 - Developer Aplication Key?
- 9 - Este convênio bancário é totalmente novo ou já foi usado para emissão?
Dica!
Caso tenha dúvida sobre algum dos dados bancários, consulte o(a) Gerente de sua Conta Bancária.
Passo a passo para obter as Credenciais da API
Informação!
Para a homologação da carteira de API do Banco do Brasil, você também precisa gerar o Client-ID, Client_Secret e a Developer application key, que são as credenciais da aplicação da API no site Developers do Banco do Brasil:
- Acesse o Developers Banco do Brasil.
- Faça login com sua conta.
- Clique em Nova Aplicação.
- Insira um nome e uma descrição para a sua aplicação e prossiga.
- No tópico chamado Selecione pelo menos uma API para sua aplicação, marque os escopos que deseja utilizar.
- Neste caso, selecione os escopos:
- Cobranças
- PIX - Clique no botão Criar. Você será redirecionado novamente ao menu de Aplicações.
- Clique sobre a aplicação que acabou de criar.
- No menu lateral esquerdo, clique no botão Produção.
- Siga os passos pedidos e insira suas informações para seguir com a contratação das chaves em produção.
- Após concluir a contratação, clique em Credenciais no menu lateral esquerdo e localize as seguintes chaves: Client-ID, Client_Secret e Developer application key. Copie essas chaves, pois serão usadas para configurar a carteira.
Credenciais API Finalizadas!
Com essas informações e os demais dados bancários, o atendente da IXC Soft poderá seguir com a homologação da sua carteira de cobrança via API.
Criando a carteira
- Acesse o menu Sistema.
- Vá até a pasta Financeiro.
- Clique em Carteira de cobrança.
- Clique em Novo.
- Na aba chamada Carteira de cobrança, realize as seguintes configurações:
- Descrição: Defina o nome da carteira.
- Conta: Crie a conta responsável por guardar as informações bancárias.
- Tipo de recebimento: Escolha a opção Gateway.
- Enviar e-mail para cliente ao gerar: Selecione Não, pois exige e-mail cadastrado no cliente e envia a fatura automaticamente para registro no banco (por isso, não é recomendado utilizar).
- Validar filial na venda: Marque como Sim.
- Planejamento analítico: Utilize 240, ou cadastre um novo código.
Criando a conta
- Conta: Dê um nome à conta.
- Tipo da Conta: Escolha a opção Banco.
- Data de abertura: Indique a data do dia da configuração da conta.
- Planejamento analítico: Para mais informações, acesse: Formulário Planejamento Analítico.
- Filial: Escolha o ID da filial para à qual a Conta e a Carteira serão vinculadas.
Na aba seguinte, Banco:
- Banco: Selecione o ID da instituição bancária, conforme o cadastro nacional. Para o Banco do Brasil, utilize:
- 001 - Banco do Brasil S.A.
- Agência: Preencha o número da sua agência.
- Dígito verificador da agência: Informe o dígito após o número da agência.
- Número da conta: Informe o número da conta bancária.
- Dígito verificador da conta: Informe o dígito verificador da conta.
- Caso alguma informação for “x”, preencha com letra maiúscula X.
Configurações gateway
- Gateway: Selecione o Banco do Brasil.
- Importado gateway: Marque como Não.
- Ambiente gateway: Escolha a opção Produção.
- Client_Id e Client_secret: Cole os códigos gerados no site Developers Banco do Brasil, conforme os passos anteriores.
- Data de crédito Pix e Data de crédito boleto: Indique, em dias, os prazos para o valor cair na conta após o pagamento. Exemplo: Pix = 0 (crédito no mesmo dia), Boleto = 1 (crédito no dia seguinte).
- Envia e-mail Gateways: Marque como Não.
- Usar webhook: Marque como Sim.
- Webhook URL callback: Clique no botão para gerar a URL.
- Gera pix: Marque como Sim.
- Tarifas Gateway: Defina o lançamento das tarifas manualmente, pois o banco não faz isso automaticamente.
- Data de crédito Pix / Data de crédito boleto: Informe as datas em que a movimentação financeira será registrada no sistema.
Configurações bancárias
- Número do convênio: Informe o número do convênio, beneficiário ou cedente vinculado à sua conta bancária.
- Carteira: Preencha com o número da carteira fornecido pelo banco.
- Variação da carteira: Informe a variação da carteira.
- Prazo após vencimento (dias): Insira o número de dias que o título ficará disponível para pagamento após o vencimento. O valor padrão é 90 dias, mas confirme com o gerente da sua conta.
Dica!
Para a API do Banco do Brasil, não é necessário o uso de Contador.
Juros/Multas/Desconto
- Juros %: Valor padrão permitido por lei: 0.033% (acima deste, pode ser considerado abusivo).
- Multa %: Valor padrão permitido por lei: 2%.
- Desconto até o vencimento R$: Informe o valor do desconto em Reais caso o pagamento ocorra até o vencimento.
- Desconto até o vencimento %: Informe o desconto em Porcentagem para pagamento até o vencimento.
Para mais informações, acesse: Juros, Multas e Desconto.
Instruções
Informação:
- A API do Banco do Brasil permite até 165 caracteres ao todo.
- Não há limite de linhas, mas cada linha deve ter até 55 caracteres.
- Atenção: não são permitidos caracteres de escape (\r ou \n).
Remova as aspas das hashtags nas instruções abaixo:
- Instrução 1:
Após vencimento juros R$ #juro# ao dia.
- Instrução 2:
Após vencimento multa R$ #multa#.
Aviso!
Se adicionar mais linhas de instrução, insira também as variáveis de leitura correspondentes em 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.
Configurando o Webhook
- Acesse o Developers Banco do Brasil.
- Selecione a aplicação desejada.
- No menu lateral esquerdo, clique no botão Webhook.
- Clique na aba Eventos e depois em Cadastrar Evento.
- Selecione o convênio de cobrança e preencha com os seguintes dados:
Eventos:
- URL: Cole a URL Webhook gerada na carteira de cobrança do sistema.
- E-mail: Informe um e-mail para receber informações da API do banco.
- Tipo de evento: Marque a opção BAIXA OPERACIONAL.
- Após preencher os dados, clique em Salvar.
- No menu lateral esquerdo, clique em URLs.
- Em URL de Callback, insira a mesma URL que foi informada anteriormente.
- Finalize clicando no botão Editar.
Fluxo de funcionamento
sequenceDiagram participant S as Sistema participant API as API Banco do Brasil 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
Ativação
Finalizado!
Com todos os passos anteriores concluídos, a carteira e suas tarefas estão prontas. Você já pode gerar um boleto de teste, realizar o pagamento e validar se a baixa foi feita automaticamente pelo sistema.
Quando a baixa automática for confirmada, o processo de homologação estará concluído.
Considerações finais
A integração com a API do Banco do Brasil, junto com a configuração do Webhook, permite uma gestão financeira mais automatizada e eficiente. Mantenha sempre suas credenciais seguras e atualizadas para garantir o bom funcionamento do sistema.
Etiquetas
IntegracaoBancaria ApiBancaria BancoDoBrasil