001 - Banco do Brasil

Sumário:

1. Visão Geral
2. Fluxograma completo de utilização
3. Vídeo explicativo do processo!
4. Como obter credenciais junto ao banco
   1. Passo 1 - Acesso ao portal developer BB
   2. Passo 2 - Criação da aplicação
   3. Passo 3- Preenchimento dos dados necessários
   4. Passo 4 - Obtenção das credenciais em HOMOLOGAÇÃO
   5. Passo 5 - Solicitando as credenciais em PRODUÇÃO
   6. Passo 6 - Cadastro do WebHook em produção (Opcional)
   7. Passo 7 - Revisão da aplicação e finalização do processo 
5. Como configurar as credenciais no PlugBoleto
6. Recursos disponíveis API BB
   1. Boleto Hibrido BB
      1. O que é necessário para utilizar o Boleto Hibrido com o banco BB?
      2. Emitindo o boleto híbrido VIA API
      3. Consultando o boleto híbrido
      4. Impressão do boleto híbrido
   2. Consulta de Boletos
      1. Consulta individual
      2. Consulta geral em boletos REGISTRADOS
      3. Informações sobre Pagamento de Boletos disponível na API BB
   3. Alteração de Boletos
      1. Requisitos para a Alteração de Boletos 
      2. Como disparar a requisição para realizar a alteração individual via API BANCÁRIA.
      3. Campos disponíveis para alteração 
   4. Baixa de Boletos
      1. Requisitos para a Baixa de Boletos
      2. Como solicitar a Baixa

Visão Geral

O recurso de transmissão instantânea foi desenvolvido para facilitar a integração de sistemas de cobrança com as APIs bancárias, oferecendo uma solução prática e eficiente para desenvolvedores.

Esse método permite a consulta direta dos dados dos boletos nos servidores bancários, retornando imediatamente após sua criação o status REGISTRADO como nos boletos de cobranças de grandes marketplaces.

Ao utilizar a transmissão instantânea, desenvolvedores conseguem implementar um fluxo de emissão de boletos mais ágil e seguro, permitindo que clientes finais possam realizar o pagamento dos títulos logo após a criação. Isso elimina o tempo de espera que existe no tradicional método de transmissão de remessas e obtenção de retorno que é D+1, já que cada boleto emitido pelo sistema é validado instantaneamente, integrando-se com o servidor bancário em tempo real.

Essa solução simplifica a comunicação com instituições financeiras, reduzindo o esforço de implementação e manutenção de sistemas de cobrança, enquanto melhora a experiência do usuário final. Com a transmissão instantânea, é possível construir aplicações financeiras robustas que garantem precisão nos dados de pagamento, ao mesmo tempo em que agilizam o processo de verificação e registro de boletos.

Atenção: Apesar de a captura do status de REGISTRO ou REJEIÇÃO via API ser imediato as LIQUIDAÇÕES(pagamentos) não seguem a mesma dinâmica, dependendo dos procedimentos internos do banco. Isso significa que o status de liquidação não está disponível instantaneamente e depende dos prazos internos de atualização de suas bases. Esse tempo pode variar de acordo com o banco e o serviço de API.

Fluxograma completo de utilização.

Vídeo explicativo do processo!  

Como obter as credenciais junto ao Banco do Brasil

Para conseguir realizar a habilitação da transmissão instantânea você precisará os seguintes passos, primeiramente será necessário realizar o acesso ao portal developer, com os dados do administrador da conta, e após este passo será feita a aquisição das credenciais, onde serão explicadas logo abaixo.

Passo 1 - Acesso ao portal developer do BB.

Crie um cadastro no portal com os dados do titular da conta corrente.

Passo 2 - Criação da aplicação

Após feito o login no portal developer será necessario criar sua aplicação para isso clique em "CRIAR NOVA APLICAÇÃO".

Passo 3 - Preenchimento dos dados necessários 

Escolha um nome e descrição para a nova aplicação que será criada, esses dados nao influenciam na cobrança portanto pode ser preenchidos com qualquer dados.

No icone da aplicação deixe em branco o campo de URL.

Nesta mesma tela selecione também o serviço que estará no escopo desta credencial, no nosso caso selecione o produto "COBRANÇAS" e no final da pagina clique em "CRIAR".

Passo 4 - Obtenção das credenciais em HOMOLOGAÇÃO

Após realizar o passo 3 você ja terá uma api criada em HOMOLOGAÇÃO conforme print abaixo:

Clique sobre a área da api criada e então você será redirecionado a pagina de detalhes da aplicação, para obter as credenciais de homologação basta clicar em "Credenciais".

Passo 5 - Solicitando as credenciais em produção

Para finalizar o processo em produção clique em "ENVIAR PARA PRODUÇÃO" no canto inferior direito da pagina e então você será redirecionado para a pagina "Solicitar Produção".

Preencha o campo "CNPJ" com os dados da empresa e clique em "PESQUISAR CNPJ" caso a empresa seja correntista BB aparecerá sua razão social e cnpj abaixo e então clique em "PROXIMO".

Passo 6 - Cadastro do WebHook em produção (Opcional) 

Para realizar o cadastro dos WebHooks em produção clique em "WebHook" no menu a aplicação de cobrança: 

Passo 1:

Passo 2 - Selecicone "Cadastrar novo evento": 

Passo 3 - Preencha a URL de Callback com a URL devolvida no campo "plugboletoCallback" da rota dessa documentação - Consultando URL de CallBack para cadastro no Banco do Brasil V2 - Clique em Salvar e estará tudo certo para o cadastro. 

1 - Selecionar o convênio; 
2 - Adicione a URL de callback;
3 - Adicione o e-mail do responsável técnico da SH;
4 - Selecione o evento "BAIXA OPERACIONAL".

Passo 7 - Revisão da Aplicação

Revise os dados apresentados e se tudo tiver correto clique em "SOLICITAR PRODUÇÃO"

Caso o cadastro tenha sido corretamente feito no cpf do admnistrador da empresa as credenciais de produção já estarão disponíveis basta voltar a tela do passo 4 clicar em Credenciais e depois clicar em Produção conforme print abaixo ilustra

Como configurar as credenciais no PlugBoleto

Para melhor visualização e entendimento do processo vamos utilizar nossa GUI WEB para explicar o preenchimento de campos mas esse processo também poderá ser realizado via API conforme a documentação de integração com a API PlugBoletos.

Após realizar o cadastro da conta, acesse a na página de convênios e caso não tenha sido ainda criado o convenio referente a conta deve ser criado conforme a documentação de cadastro de convênios.

Com o convenio criado ative a opção "Registro instantâneo", esse campo é onde você habilita o uso desse recurso no seu convênio.

Quando o campo Registro instantâneo for ativado deve aparecer logo abaixo novos campos o primeiro é Versão web service, preencha o com V2 em seguida temos o campo API-ID que deve ser preenchido com o client_id disponibilizado pelo banco o próximo é o campo Chave Key que deve ser preenchido com o developer_application_key disponibilizado pelo banco e por fim o campo Secret deve ser preenchido com o client_secret informado pelo banco.

Instruções para emissão no ambiente de homologação do Banco do Brasil v2

Para emissão no ambiente de homologação v2 do Banco do Brasil, o banco exige que seja enviado CNPJ's e CPF's específicos para testes, essas informações devem ser enviadas nos campos  SacadoCpfCnpj e SacadoNome do Plugboleto. Abaixo está a lista exigida pelo banco:

Por padrão o Plugboleto vai enviar alguns dados que precisam se fixos no ambiente de homologação, esses dados são:

Recursos disponíveis na API Banco do Brasil

Boleto Hibrido

O boleto híbrido do BB combina as opções de pagamento via boleto e Pix para uma mesma cobrança. Isso permite oferecer aos clientes a flexibilidade de quitar o pagamento utilizando o código de barras do boleto ou o QR Code do Pix.

O que é necessário para utilizar o Boleto Hibrido com o banco Banco do Brasil?

Para utilizar o boleto híbrido com o Banco BB, basta realizar a liberação das credenciais conforme descrito neste passo. Após isso, você estará apto a usar a API bancária. No caso do BB, não é necessária nenhuma liberação adicional de escopos ou serviços junto ao banco, com a credencial padrão já é possível realizar o registro.

Emitindo o boleto híbrido VIA API

Para comandar que um boleto seja  registrado no modelo HIBRIDO basta adicionar ao JSON de envio anteriormente implementado o campo chamado "hibrido": true, caso tenha duvidas sobre a implementação da rota de inclusão de boletos basta acessar nossa documentação.

Abaixo um exemplo do campo a ser adicionado:

{
  ...
  ...
  "TituloNossoNumero":"123",
  "TituloValor":"100,00",
  "hibrido": true
}

Consultando o boleto híbrido

A consulta do boleto hibrido segue a mesma implementação da consulta de boletos tradicionais conforme a documentação de consulta de boletos, sendo necessário apenas a leitura dos dois novos campos referentes ao boleto hibrido.

{
  "hibrido": true,
  "UrlPix": "http://plugboleto.com.br/api/v1/boletos/impressao/HRKCVJXVV/pix",
}

Impressão do boleto híbrido

Para saber mais sobre os tipos de impressão, acesse a documentação referente aos exemplos de impressão.

Exemplo de boleto híbrido:

Consulta de Boletos

Consulta individual

As  requisições que forem disparadas para o endpoint de consulta do Plugboleto serão imediatamente processadas e apresentará os dados atuais do titulo em nosso banco de dados, em seguida replicaremos a consulta diretamente no servidor bancário a fim de buscar uma possível atualização de dados, caso seja identificado uma atualização de status automaticamente será disparado um webhook de notificação para a Software House, caso não tenha webhook configurado é possível obter as atualizações realizando uma nova consulta em seguida.

Um boleto pode ter 7 situações diferentes, que podem ser verificadas neste link.

Para verificar quais campos são retornados nesta consulta, clique aqui.

Consulta Automática

 O PlugBoletos conta com rotinas de consultas automáticas que tem como intuito dar mais confiabilidade e celeridade as conciliações de boletos, no momento para o banco BB V2 temos disponível apena a consulta geral, sem webhook ou francesa.

Consulta geral em boletos REGISTRADOS

Considerando que a consulta francesa e o webhook não estão disponíveis para o BB é realizada uma consulta em todos os títulos com status de REGISTRADO em nossa base, ela se inicia as  7 horas da manha e seu tempo de execução pode variar de acordo com o tamanho da base a ser consultada.

Informações do boleto atualizadas após a conciliação na API BB.

Com a atualização via API o banco BB reduz a quantidade de informações disponibilizadas sobre o pagamento limitando se as principais informações de LIQUIDAÇÃO:

• Situação

• PagamentoData

• PagamentoDataCredito

• PagamentoValorPago

• PagamentoValorAcrescimos

Vale apenas ressaltar que todas as outras informações da cobrança já foram capturadas e estamos focando apenas em campos atualizados após o pagamento do titulo.

Alteração Individual de Boletos via API

A alteração de boletos é útil em situações onde informações previamente registradas, como data de vencimento, valor ou valor de abatimento precisam ser modificadas após o titulo ja estar registrado. Abaixo está uma visão geral de como funciona o processo de alteração de boletos via API bancária no PlugBoletos.

Requisitos para a Alteração de Boletos

Antes de comandar uma alteração, é importante garantir que o boleto se enquadra em alguns requisitos. O boleto precisa estar REGISTRADO no BB.

• Apenas determinados campos podem ser modificados, como data de vencimento, valor de cobrança, multa, juros e descontos aplicáveis.

• É necessário possuir as credenciais de autenticação bancárias descritas em Como obter credenciais junto ao Banco para acessar a API BB V2.

Como disparar a requisição para realizar a alteração individual via API BANCÁRIA.

POST

Homologação:

Produção:

Headers

Headers (Opcional)

Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:

Para solicitar a alteração individual BB, o objeto JSON pode ter os seguintes campos:
 

Campos disponiveis para alteração BB v2

Baixa de Boletos

Para boletos que alcançaram o status de REGISTRADO, o cancelamento só pode ser realizado através de uma solicitação formal de BAIXA. Esse processo, para o BB, pode ser automatizado diretamente por meio da API bancária, facilitando o cancelamento e integração com sistemas de cobrança.

Requisitos para a Baixa de Boletos

1. Status de REGISTRADO: Assim que um boleto é registrado no banco, ele fica disponível para pagamento e segue sob controle do sistema bancário.

2. Solicitação de Baixa: Caso o boleto precise ser cancelado (por exemplo, devido a duplicidades, erros ou desistência de cobrança), uma requisição de baixa deve ser enviada ao banco.

3. É necessário possuir as credenciais de autenticação bancárias descritas em Como obter credenciais junto ao Banco para acessar a API BB.

Como solicitar a Baixa

Para realizar a solicitação de baixa basta realizar a integração com o endpoint de baixa do Plugboletos.