Pular para o conteúdo principal
Pular para o conteúdo principal

Documentação @box4dev/gerador-boleto

Gerador de boleto padrão FEBRABAN com linha digitável e código de barras.

O @box4dev/gerador-boleto é uma biblioteca open-source lightweight para o ecossistema Node.js, projetada especificamente para a geração dinâmica de dados de boletos bancários no padrão FEBRABAN.

NPM versionNPM downloads

Primeiros Passos

Sobre o Gerador de Boleto

Gerador de Boleto no padrão FEBRABAN: Linha Digitável e Código de Barras.

Sem HTML, PDF ou renderização gráfica — apenas dados prontos para JSON.

Ideal para geração de massa para testes automatizados.

Instalação

Instale a biblioteca utilizando o seu gerenciador de pacotes preferido:

NPM

Shell
Instalar via NPM

Yarn

Shell
Instalar via Yarn

PNPM

Shell
Instalar via PNPM

Importação

Importe as funções da biblioteca no seu projeto TypeScript ou JavaScript:

JS
import { gerarBoleto } from '@box4dev/gerador-boleto';
JS
const { gerarBoleto } = require('@box4dev/gerador-boleto');

Utilização

Gere dados completos de boletos com facilidade utilizando valores padrão ou customizados.

Uso Básico com Dados Aleatórios

JS
const dados = gerarBoleto();
console.log(dados.codigoBarras);
// '03396145000000996689025708991834007174230101'
console.log(dados.linhaDigitavel);
// '03399.02579 08991.834006 71742.301014 6 14500000099668'
console.log(dados);
/*
{
codigoBarras: '03396145000000996689025708991834007174230101',
linhaDigitavel: '03399.02579 08991.834006 71742.301014 6 14500000099668',
banco: 'santander',
codigoBanco: '033-7',
dataEmissao: '2026-05-13T00:00:00.000Z',
dataVencimento: '2026-05-18T00:00:00.000Z',
valorDocumento: 99668,
nossoNumero: 918340071742,
nossoNumeroDv: 3,
agencia: 1674,
codigoCedente: 257089,
carteira: '101',
localPagamento: 'Até o vencimento, preferencialmente no Banco Santander',
instrucoesPagamento: 'Sr. Caixa, cobrar multa de 2% após o vencimento. Receber até 10 dias após o vencimento.'
}
*/

Exemplos por Banco

JS
console.log(gerarBoleto({ banco: 'bradesco' }));
console.log(gerarBoleto({ banco: 'caixa' }));
console.log(gerarBoleto({ banco: 'itau' }));
console.log(gerarBoleto({ banco: 'santander' }));

Parâmetros de Uso

JS
console.log(
gerarBoleto({
banco: 'bradesco',
valorDocumento: 15990,
nossoNumero: '12345678901',
agencia: '1229',
codigoCedente: '0000469',
carteira: '9',
})
);

Parâmetros de Uso

JS
console.log(
gerarBoleto({
banco: 'caixa',
dataEmissao: new Date(),
dataVencimento: vencimento,
valorDocumento: 88800,
nossoNumero: '12345678987654321',
agencia: '1234',
codigoCedente: '654321',
carteira: '14',
localPagamento: 'Local Teste',
numeroDocumento: '999888',
cedente: 'Empresa Teste LTDA',
cedenteCnpj: '54811186000198',
instrucoesPagamento: 'Instrução Teste',
identificadorEmissao: '4',
})
);

Bancos suportados

Atualmente a biblioteca oferece suporte oficial aos seguintes bancos:

BancoDescrição
santanderBanco Santander (Código 033)
bradescoBanco Bradesco (Código 237)
caixaCaixa Econômica Federal (Código 104)
itauBanco Itaú Unibanco (Código 341)

Contribuição

Contribuições são bem-vindas! Consulte o guia de contribuição no GitHub:

Repositório GitHub do @box4dev/gerador-boleto

Licença

Distribuído sob a licença MIT. Livre para uso pessoal e comercial.

Segurança

Os boletos gerados são puramente computacionais e destinados a testes. Nenhuma informação bancária sensível é coletada ou enviada a servidores externos.

Perguntas Frequentes

O que exatamente é um boleto bancário?
Um boleto é um título de crédito padronizado no Brasil usado para cobranças. Contém código de barras, linha digitável, valor, data de vencimento e dados do cedente (quem emite). Pode ser pago até 90 dias após o vencimento em bancos, lotéricas e online.
Para que serve o Gerador de Boleto?
Serve para criar boletos fictícios para fins de teste. Use para validar mascaras de entrada, testar o processamento de linhas digitáveis, simular pagamentos em ambientes de desenvolvimento, ou treinar equipes sem usar dados reais.
Os boletos gerados são válidos e podem ser pagos?
Não. Os boletos gerados são estruturalmente válidos (seguem o padrão técnico), mas não possuem validade legal ou financeira. Nenhum banco brasileiro aceitará o pagamento de um boleto gerado por esta ferramenta. Eles existem apenas como dados para teste.
Posso usar os boletos gerados para emitir cobranças reais?
Absolutamente não. Isso é fraude e é crime. Usar boletos falsificados para tentar receber pagamentos, enganar pessoas ou terceiros é ilegal segundo a Lei de Crimes de Informática (Lei 12.737/12) e Lei de Estelionato (Código Penal, art. 171). Pode resultar em processo criminal, multas altas e prisão.
Quais são as implicações legais do uso indevido?
Usar boletos falsificados para fraude é crime federal no Brasil. As penalidades incluem: multa de até R$ 150 mil, prisão de 1 a 3 anos, e antecedentes criminais. Além disso, vítimas podem processar civilmente por danos morais e patrimoniais. Bancos e órgãos de segurança monitoram e investigam atividades fraudulentas.
Como validar se um boleto gerado está correto?
O boleto gerado está correto se: (1) a linha digitável e código de barras são números contínuos sem caracteres especiais (exceto na forma formatada), (2) o dígito verificador é calculado corretamente, (3) as datas estão no formato correto (sempre futuras para vencimento), e (4) o valor é numérico válido. Use o Validador de Boleto da Box4Dev para confirmar.
Qual é a diferença entre um boleto real e um gerado?
Um boleto real é registrado no banco com identificação única, possui cedente (empresa) validada, e pode ser pago legalmente. Um boleto gerado é apenas dados estruturais, sem registro bancário, sem cedente verificado, e não pode ser pago. Um é um documento legal, o outro é apenas uma estrutura de dados.
Posso compartilhar ou distribuir os boletos gerados?
Para fins educacionais ou documentação de desenvolvimento, sim. Mas nunca envie boletos gerados para pessoas com intenção de enganá-las ou fazer com que paguem. Compartilhar boletos falsificados com intenção fraudulenta é crime de estelionato e falsificação.
Este gerador é seguro? Posso confiar nos dados?
Sim, é seguro para uso legítimo de teste. Os dados são gerados localmente seguindo o padrão técnico oficial. Não há envio de dados para servidores externos. Porém, segurança técnica não significa que você pode usar para fraude - continue sendo responsável legalmente pelo uso.
Que informações os boletos gerados contêm?
Banco (selecionado ou aleatório), agência, conta, nosso número, carteira, data de emissão/vencimento, valor do documento, cedente (empresa), número do documento, instruções de pagamento, local de pagamento, código de barras e linha digitável - tudo gerado aleatoriamente e sem vincular a dados reais.
Qual banco usar para testar?
Todos os bancos da lista funcionam para teste. Escolha um que sua aplicação precise processar. Os algoritmos de validação de código de barras são iguais para todos. O que muda é o código do banco e regras específicas de agência/conta para alguns bancos - dados que você controla no gerador.
Posso importar esses boletos em um sistema de cobrança real?
Não funciona. Sistemas de cobrança reais validam o boleto com o banco - um boleto gerado não existe no banco e será rejeitado. Além disso, injetar boletos falsificados é crime. Sempre use dados reais em produção e boletos gerados apenas em ambiente de teste isolado.