Sumário:
- Visão Geral
- Fluxograma completo de utilização
-
Como obter credenciais junto ao banco
- Pré-requisitos para realizar o procedimento completo de liberação de credenciais bancárias.
- Passo 1 - Acesso ao portal developer BB
- Passo 2 - Criação da aplicação
- Passo 3- Preenchimento dos dados necessários
- Passo 4 - Obtenção das credenciais em HOMOLOGAÇÃO
- Passo 5 - Solicitando as credenciais em PRODUÇÃO
- Passo 6- Revisão da aplicação e finalização do processo
- Como configurar as credenciais no PlugBoleto
-
Recursos disponíveis API BB
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.
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 - 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:
| Nome da Empresa | CNPJ |
| TECIDOS FARIA DUARTE | 74910037000193 |
| LIVRARIA CUNHA DA CUNHA | 98959112000179 |
| DOCERIA BARBOSA DE ALMEIDA | 92862701000158 |
| DEPOSITO ALVES BRAGA | 94491202000127 |
| PAPELARIA FILARDES GARRIDO | 97257206000133 |
| Nome | CPF |
| VALERIO DE AGUIAR ZORZATO | 96050176876 |
| JOAO DA COSTA ANTUNES | 88398158808 |
| VALERIO ALVES BARROS | 71943984190 |
| JOÃO DA COSTA ANTUNES | 97965940132 |
| JOÃO DA COSTA ANTUNES | 75069056123 |
Por padrão o Plugboleto vai enviar alguns dados que precisam se fixos no ambiente de homologação, esses dados são:
| NumeroConvenio | 3128557 |
| NumeroCarteira | 17 |
|
NumeroVariacaoCarteira |
35 |
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
| Nome | Descrição | Exemplo |
|---|---|---|
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| cnpj-sh | CNPJ da Software House | 01001001000113 |
| token-sh | Token da Software House | f22b97c0c9a3d41ac0a3875aba69e5aa |
Headers (Opcional)
Utilizar esses headers em caso de autenticação direto com as credenciais do cedente:
| Nome | Descrição | Exemplo |
|---|---|---|
| Content-Type | Indica o tipo de arquivo | application/json |
| cnpj-cedente | CNPJ do Cedente | 01001001000113 |
| token-cedente | Token do Cedente | f22b97c0c9a3d41ac0a3875aba69e5aa1 |
Para solicitar a alteração individual BB, o objeto JSON pode ter os seguintes campos:
Campos disponiveis para alteração BB v2
| Campo | Descrição | Exemplo |
| TituloDataVencimento | Alterar a data de vencimento | 15/03/2023 |
| TituloCodDesconto | Alterar o tipo de desconto | 2 |
| TituloDataDesconto | Alterar a data do desconto | 15/02/2023 |
| TituloValorDescontoTaxa | Alterar o valor do desconto | 100 |
| TituloCodDesconto2 | Alterar o tipo do segundo desconto | 2 |
| TituloDataDesconto2 | Alterar a data do segundo desconto | 15/02/2023 |
| TituloValorDescontoTaxa2 | Alterar o valor do segundo desconto | 100 |
| TituloCodDesconto3 | Alterar o tipo do terceiro desconto | 2 |
| TituloDataDesconto3 | Alterar a data do terceiro desconto | 15/02/2023 |
| TituloValorDescontoTaxa3 | Alterar o valor do terceiro desconto | 100 |
| TituloValorAbatimento | Adicionar, alterar ou reduzir valor de abatimento do boleto | 5 |
| TituloValorJuros | Alterar o valor/taxa de juros | 1,0 |
| TituloCodigoJuros | Alterar o código de juros | 2 |
| TituloCodigoMulta | Alterar o código de multa | 1 |
| TituloValorMultaTaxa | Alterar o valor da multa | 1,0 |
| TituloDataMulta | Alterar a data da multa | 15/02/2023 |
| TituloCodProtesto | Alterar o código de protesto | 8 |
| TituloPrazoProtesto | Alterar a data do protesto | 20/02/2023 |
| SacadoEnderecoNumero | Alterar o número de endereço do sacado | 15 |
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
- Status de REGISTRADO: Assim que um boleto é registrado no banco, ele fica disponível para pagamento e segue sob controle do sistema bancário.
- 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.
- É 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.
Comentários
0 comentário
Por favor, entre para comentar.