Skip to main content
Skip to main content

@box4dev/gerador-boleto Documentation

Generate FEBRABAN-compliant boletos with typeable line and barcode online.

The @box4dev/gerador-boleto is a lightweight open-source library for the Node.js ecosystem, specifically designed for the dynamic generation of bank boleto data in FEBRABAN standard.

NPM versionNPM downloads

Getting Started

About the Boleto Generator

Boleto generator in the FEBRABAN standard: typeable line and barcode.

No HTML, PDF or graphic rendering — just JSON-ready data.

Ideal for mass generation for automated testing.

Installation

Install the library using your preferred package manager:

NPM

Shell
Install via NPM

Yarn

Shell
Install via Yarn

PNPM

Shell
Install via PNPM

Import

Import library functions in your TypeScript or JavaScript project:

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

Usage

Generate complete bank slip data easily using default or custom values.

Basic Usage with Random Data

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.'
}
*/

Examples by Bank

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

Usage Parameters

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

Usage Parameters

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',
})
);

Supported Banks

Currently the library officially supports the following banks:

BankDescription
santanderBanco Santander (Code 033)
bradescoBanco Bradesco (Code 237)
caixaCaixa Econômica Federal (Code 104)
itauBanco Itaú Unibanco (Code 341)

Contribution

Contributions are welcome! Check the contribution guide on GitHub:

@box4dev/gerador-boleto GitHub Repository

License

Distributed under the MIT License. Free for personal and commercial use.

Security

Generated bank slips are purely computational and intended for testing. No sensitive banking information is collected or sent to external servers.

Frequently Asked Questions

What exactly is a bank slip (boleto)?
A boleto is a standardized credit document used in Brazil for bill collection. It contains a barcode, typeable line, amount, due date, and cedent (issuer) information. It can be paid up to 90 days after the due date at banks, lottery outlets, and online platforms.
What is the Boleto Generator for?
It creates fictitious boletos for testing purposes. Use it to validate input masks, test typeable line processing, simulate payments in development environments, or train teams without using real data.
Are generated boletos valid and can they be paid?
No. Generated boletos are structurally valid (follow technical standards) but have no legal or financial validity. No Brazilian bank will accept payment of a boleto generated by this tool. They exist only as test data.
Can I use generated boletos to issue real charges?
Absolutely not. This is fraud and is a crime. Using falsified boletos to attempt to receive payments, deceive people, or commit fraud violates Brazilian law (Cybercrime Law - Law 12.737/12 and Fraud Law - Penal Code, Article 171). This can result in criminal prosecution, substantial fines, and imprisonment.
Which bank should I use for testing?
Any bank from the list works for testing. Choose one your application needs to process. Barcode validation algorithms are the same for all. What differs is the bank code and specific agency/account rules for some banks.