Funcionalidade disponível a partir da versão 03.40.00.

Objetivo

Este documento tem como principal objetivo orientar sobre a configuração e utilização da integração do BRC com o Webhook de Cobrança do Banco do Brasil.

Descrição

Visando o recebimento dos pagamentos de boletos em tempo real e a liquidação dos débitos sem a necessidade de importar arquivos de retorno bancário, foi realizada a nova implementação descrita neste documento. Esta atualização permitirá maior agilidade e eficiência no processamento dos pagamentos.

O Banco do Brasil (BB) enviará os pagamentos em tempo real e fará até três tentativas de comunicação para garantir o recebimento. Recomendamos que os clientes continuem fazendo a importação manual de retorno, pois, o Webhook não envia as confirmações de alteração e baixa de boletos, essas informações continuarão sendo enviadas apenas no retorno bancário. Além disso, o retorno servirá como uma garantia de que todos os pagamentos foram processados.

Alteração Importante

A partir da versão 03.44.01, foi incluído o campo Data Crédito no processamento do Webhook do Banco do Brasil.

Esse campo passou a ser utilizado diretamente pelo sistema para registrar a data de crédito informada pelo BB, eliminando a necessidade de cálculo manual a partir da data de pagamento.

Caso o campo não esteja presente ou venha vazio no payload, o sistema mantém a regra anterior de cálculo com base na data de pagamento.

Pré-condição

Antes de utilizar a nova funcionalidade, é imprescindível configurar a Integração Boleto Registrado para a API Cobrança do Banco do Brasil, conforme detalhado no documento disponível em:

BRConselhos – Módulo Financeiro – Integração API de Cobrança BB (PIX)

Parâmetros e Cadastros

Na parametrização da integração, será necessário informar um usuário de sistema. Este ficará registrado nos logs dos pagamentos realizados pela integração com o BB.

• Recomendamos que seja criado um novo usuário somente para isso, este usuário não precisa ter nível de ‘admin’, porém, ele deve conseguir acessar o sistema.

Para isso, acesse o módulo Interno > Usuários > Novo.

Cadastre o novo usuário, informando a visão organizacional e um grupo de acesso, então salve.

Com o usuário cadastrado, no sistema da BRC acesse o módulo Interno >Parâmetros>Financeiro> Integração boleto registrado.

Acesse Interno > Parâmetros > Financeiro > Parâmetros do módulo Financeiro > Integração Boleto Registrado > Selecionar a integração que já possui.

Após selecionar o registro configurado para o ‘Banco do Brasil API Cobrança’, será possível identificar alguns campos criados para a implementação do webhook, sendo eles:

Utilizar recebimento automático (Webhook): Esse campo precisa ser marcado para que a coleção e os campos pertinentes ao webhook se tornem visíveis para o usuário.

Usuário Webhook: vincule o usuário cadastrado anteriormente.

Validar Certificado: Define se será realizada a verificação do certificado recebido na requisição para realizar o processamento dos pagamentos. Por questão de segurança, este campo sempre deve permanecer marcado, salvo exceções alinhadas com a BRC.

URL de envio de pagamentos: esse link será utilizado posteriormente para cadastro no site do BB.

Processamento

É necessário cadastrar os movimentos bancários que serão enviados pelo BB, conforme abaixo:

Tipo = Retorno On-line;

Ação = Liquidação de título;

Descrição = Este campo é utilizado para nomear o movimento bancário;

Código = Código que corresponderá ao campo codigoEstadoBaixaOperacional da requisição recebida.

• Atualmente o BB envia apenas os 2 códigos destacados abaixo, portanto, estes devem ser cadastrados, em: Financeiro > Informações bancárias > Carteiras de cobrança > Selecione a carteira > Movimentos > Novo > cadastrar o movimento e salvar.

• Importante: Vale ressaltar que a existência desse movimento, de acordo com os campos informados acima, definirá como o sistema irá processar o registro recebido.*

A partir da versão 03.44.01, os pagamentos recebidos pelo Webhook do Banco do Brasil passam a considerar o campo Data Crédito.

O sistema irá priorizar o uso do campo enviado pelo BB. Caso este campo não esteja presente ou venha vazio, será aplicada a regra de cálculo baseada na data de pagamento.

O BB também envia uma informação de ‘Canal de Agendamento’ que serve para indicar onde foi realizado o pagamento. Esta informação será armazenada no BRC no campo Ocorrência do Movimento. Porém, para que isso seja armazenado corretamente, é necessário cadastrar os códigos de ocorrência utilizados pelo BB, conforme abaixo.

Cadastre a ocorrência da Baixa Operacional, acesse Ocorrências, clique em Novo e cadastre as ocorrências conforme o código do canal (após salvar o movimento, habilita a opção Ocorrências).

PS: No caso da Ocorrência do PIX (4), é possível informar uma ‘forma de liquidação’ diferente, para que esse pagamento fique separado dos demais, conforme página 10.

Permissão de acesso a Integração Bancária

Foi criada uma nova tela para apresentar os pagamentos recebidos pelo Webhook do BB, com isso, será necessário liberar a permissão de acesso aos usuários.

Acesse o módulo Segurança > Módulos > localize e acesse Financeiro > vá para Páginas > localize e acesse Integração Bancária > Itens > na coluna Legenda localize e acesse ‘Retorno On-line’ > vá para Grupos e Adicione o grupo que deve ter acesso.

Portal do BB

Para realizar a integração, é preciso configurar uma comunicação segura entre as duas partes (BB e BRC). Isto será feito através de uma validação de certificado de segurança, onde a BRC importa os certificados fornecidos pelo BB e banco faz a liberação do Certificado usado pelo BRC.

Para os clientes que utilizam servidores BRC (na nuvem), a importação de certificados já está feita, com isso, você precisa apenas solicitar a liberação do certificado BRC na sua conta do BB, conforme demonstramos abaixo.

Já para os clientes que utilizam servidor próprio, recomendamos que entrem em contato com a consultoria para contratar um serviço de liberação dos certificados.

No sistema do Banco do Brasil, após acessar a aplicação, acesse o ícone da sua API de cobrança e acesse a opção Certificados

https://app.developers.bb.com.br/#/menu/certificado/home

Clique no botão Liberação Automática

Informar a URL utilizada para acessar o sistema da BRC e Solicitar.

Aguarde até que a situação saia de e fique como .

Este processo pode levar alguns minutos, aguarde para continuar a configuração.

Após isso, será necessário ativar o envio de pagamentos do BB, então, retorne para a tela ‘Detalhes da Aplicação’ do Portal do BB e clique na opção Webhook.

Informe a URL, e-mail, selecione o Convênio de cobrança e Tipo de evento ‘Baixa Operacional’, clique em Salvar.

Dados salvos.

Após essa configuração, o BB começará a enviar os pagamentos para o BRC.

Processamento dos pagamentos

Condições para registros e baixas

Os registros dos pagamentos recebidos serão salvos no sistema de acordo com o convênio informado em cada registro enviado pelo Banco do Brasil em suas requisições, de forma que o resultado final será a criação de uma integração bancária para cada convênio encontrado por dia.

Quando recebido um registro de pagamento e havendo uma integração bancária para aquele convênio na data atual, será criado um novo item – registro de integração bancária item – para processamento dentro da integração bancária encontrada.

Caso não haja uma integração bancária para a data atual com aquele determinado convênio, uma nova integração será criada e o item adicionado à mesma para o processamento da baixa.

Para ambos os casos, é necessário que haja um registro para o convênio informado no sistema. Caso contrário, o registro do pagamento em questão não será salvo na integração bancária ou processado pelo sistema do BRC.

Verificação de registros

Os pagamentos recebidos nas requisições serão registrados no sistema, podendo ser verificados e/ou acompanhados na tela de Integração Bancária > Retorno On-line.

À partir da versão 03.41.01, todos os pagamentos serão agendados (e processados logo em seguida), por questão de performance do sistema. Com isso, os itens do retorno bancário poderão estar com a situação ‘Não processado’. Nestes casos. é necessário aguardar o término da execução do agendamento.

O registro do agendamento e o status do mesmo podem ser acompanhados em Interno > Agendamentos, sob o nome “Geração de baixa automática de títulos”.

Log e Auditoria

Para que haja um controle das requisições recebidas, todas elas serão armazenadas na tabela de Auditoria, independentemente de haver sucesso no pagamento ou no registro recebido pelo banco.

A tabela de auditoria pode ser consultada através do módulo ‘Interno’, acesse: Interno > Integração auditoria.