Funcionalidades disponíveis

1. Buscar o último boleto gerado.
2. Criar novo boleto a partir do último gerado.
3. Gerar PDF do modelo do boleto de acordo com o padrão do Banco do Brasil.

Funcionalidades pendentes

1. Adicionar pagamento por PIX.

Configuração

1. Baixe o pacote com npm i boleto-banco-brasil.
2. No seu projeto faça o import do pacote usando import { BBClient } from 'boleto-banco-brasil';.

Como usar

Instancie a classe Client:

import { BBClient } from 'boleto-banco-brasil';

const bbClient = new BBClient({
  BB_API_KEY: '0000000000111111111133333333335555555555',
  BB_BASIC_CREDENTIALS: 'Basic key',
  BB_CONVENIO: '1234567',
  BB_WALLET: '00',
  BB_WALLET_VARIATION: '11',
  BB_AGENCIA: '222',
  BB_CONTA: '987654',
  ENVIRONMENT: 'dev'
});

Tenha atenção em colocar corretamente suas credênciais da sua conta do Banco do Brasil.

Observe o parâmetro ENVIRONMENT. Ele serve para você informar se quer usar o sandbox da API do Banco do Brasil ou o ambiente de produção. Use dev para sandbox e prod para produção.

Para fazer uma busca do último boleto gerado use:

bbClient.SearchLastPurchase().then(response => console.log(response)); 

Para criar um boleto a partir do último gerado, use:

bbClient.CreatePurchase({
  customerAddress: 'Mocambinho',
  customerCity: 'Teresina',
  customerCPF: '96050176876',
  customerName: 'Filipe A. Sampaio',
  customerNeighborhood: 'Avenida Santa joana Darq',
  customerStateCode: 'PI',
  customerZipCode: '77458000',
  purchaseValue: '1200'
}).then(response => console.log(response));

E para criar o PDF do boleto use:

bbClient.CreatePurchase({
  customerAddress: 'Mocambinho',
  customerCity: 'Teresina',
  customerCPF: '96050176876',
  customerName: 'Filipe A. Sampaio',
  customerNeighborhood: 'Avenida Santa joana Darq',
  customerStateCode: 'PI',
  customerZipCode: '77458000',
  purchaseValue: '1200'
}).then(response => console.log(bbClient.CreatePurchaseTicket({
  numericBarcode: response.purchaseBarCode,
  ticketValue: 1200,
  purchaseId: response.purschaseId,
  dueDate: '19/11/2022',
  customerName: 'Filipe A. Sampaio',
  customerZipcode: '77458000',
  customerAddress: 'Mocambinho',
  customerCity: 'Teresina',
  customerStateCode: 'PI',
})));

Observe que foi usado o método de criar o boleto mesclado com o método de gerar o PDF do boleto. Separamos as duas funções pois em alguns momentos poderemos gerar uma segunda via de um boleto já gerado. Veja abaixo a chamada ao método que só gera o PDF do modelo:

bbClient.CreatePurchaseTicket({
  numericBarcode: response.purchaseBarCode,
  ticketValue: 1200,
  purchaseId: response.purschaseId,
  dueDate: '19/11/2022',
  customerName: 'Filipe A. Sampaio',
  customerZipcode: '77458000',
  customerAddress: 'Mocambinho',
  customerCity: 'Teresina',
  customerStateCode: 'PI',
});

Esse método por sua vez retorna o caminho onde o arquivo PDF foi salvo. Ele por padrão é salvo sempre em tmp/uploads/boletos/, dentro do seu projeto.

Observações gerais

1. Os boletos em PDF são salvos na pasta tmp/uploads/boletos/ na raíz do seu projeto.
2. Tenha em mente em usar configurações de teste da sua conta do Banco do Brasil, para evitar usar os números reais da API.
3. Durante seus testes em algum momento talvez a criação do boleto falhe devido ao número do boleto gerado já está em uso. Mas não se preocupe, isso é normal pois a API do Banco do Brasil é compartilhada com todos os Devs da API. logo, por exemplo, se você gerou um número de boleto 1 não necessáriamente o seu próximo número será 2. Assim, adicionamos uma flag de controle de ambiente de desenvolvimento chamada environment, onde se você estiver executando em ambiente de desenvolvimento, você deve colocar a flag dev e em ambiente de produção você deve colocar a flag prod. A flag dev criará números de boleto aleatório, já a prod procurará o último boleto da sua conta.
4. Criamos um controle de último boleto gerado quando você tentar criar um boleto novo. Funciona da seguinte forma: quando você tentar criar um boleto novo, antes o SDK irá procurar o último boleto gerado, pesquisando os últimos 3 dias da API do Banco do Brasil. Se ele não achar boletos nesse intervalo, o SDK fará uma nova pesquisa para os 3 dias anteriores ao intervalo anterior, e fará isso até achar uma lista de boletos.

Fluxograma do SDK

stateDiagram-v2
    [*] --> Start

    Start --> banco_do_brasil

    banco_do_brasil --> SDK
    SDK --> banco_do_brasil

    SDK --> gera_boleto

    gera_boleto --> End

Diagramas do funcionamento

Modelo do PDF do boleto gerado

Abaixo mostramos o modelo que o SDK gera do boleto:

O que esse SDK propõe?

• Gerar boletos válidos do Banco do Brasil. Mas como?
  • O SDK irá requisitar sempre a API do Banco do Brasil usando suas credênciais para achar o último boleto gerado válido. Ele irá procurar por um range que você pode configurar, porém o padrão será de até 3 dias. Após essa listagem, será pego o último boleto e seu número será incrementado para o novo boleto válido.
• Gerar PDF do modelo do boleto usado pelo Banco do Brasil.

Testes Unitários

Ainda não há testes unitários na versão refatorada. Pretendemos adicionar.

Melhorias pendentes

• [ ] [BUG] caso a conta seja nova e nunca foi gerado um boleto, a criação do boleto falhará, pois ele tentará achar o último boleto gerado infinitamente
• [ ] Adicionar método de pagamento por PIX.