Como Criar Um Boleto

O que você precisa saber antes de começar

Boleto bancário é um documento de cobrança emitido por instituições financeiras brasileiras, mas isso não quer dizer que você possa simplesmente gerar um PDF bonito e esperar que pague. O processo envolve regras do Febrabran, código de barras com dígito verificador calculado corretamente e integração com o sistema de compensação dos bancos. Se algo estiver errado, o boleto volta para a sua conta e ninguém fica feliz.

Eu já vi gente tentar usar geradores online gratuitos que criavam boletos com campos preenchidos, mas na hora do cliente pagar, o banco rejeitava porque o campo "nosso número" estava formatado de forma inconsistente com o sistema do banco específico. Isso acontece com frequência. Cada instituição tem suas próprias regras de formatação, mesmo que todas sigam o padrão Febrabran no papel.

Como criar um boleto passo a passo

Você tem três caminhos principais. O primeiro e mais direto é usar o internet banking do seu banco. Quase todas as grandes instituições oferecem um módulo de emissão de boletos embutido. Você preenche os dados do pagador, valor, vencimento, mensagem de cobrança e o próprio banco gera o documento com todo o código de barras pronto. É rápido, leva entre 3 e 5 minutos por boleto, mas tem limitações sérias se você precisa emitir em volume. O segundo caminho é uma API de emissão. Empresas como Gerencianet, Iugu, Mercado Pago e outras oferecem APIs REST onde você envia os dados da cobrança e recebe o boleto formatado em JSON com o link para visualização ou o PDF completo. Uma única chamada de API com os dados mínimos pode gerar um boleto válido em segundos. Isso é o que eu recomendo para quem está construindo um sistema ou loja virtual. O custo gira em torno de R$0,50 a R$2,00 por boleto emitido, dependendo do provedor e do volume.

O terceiro caminho, o mais complexo, é implementar o protocolo manualmente. Você precisa gerar o registro linha digitável do padrão Febrabran, calcular os dígitos verificadores usando o algoritmo módulo 10 e módulo 11, montar o código de barras em imagem com a fonte específica, posicionar corretamente os campos do cartão de apresentação, do sacado, do beneficiário e do local de pagamento. Isso dá trabalho. Muito trabalho. Aqui vai algo que poucos explicam: o campo "nosso número" não é um número aleatório. Ele serve para o banco identificar unicamente a cobrança dentro da conta do beneficiário. Se você reutilizar o mesmo nosso número para dois boletos diferentes, ou se enviar um nosso número que o banco já registrou como pago, o sistema vai conflituar. Eu perdi horas tentando rastrear um boleto que dizia "já quitado" quando na verdade eu tinha simplesmente reutilizado o código de controle do nosso número num lote seguinte. A solução foi implementar um contador sequencial que nunca se repete e controlar o ciclo de cada banco separadamente. O Banco do Brasil usa nosso número com 17 dígitos, o Itaú com 8, o Bradesco com 11. Cada um tem uma lógica de geração própria.

Bibliotecas e ferramentas úteis

Se você quer implementar do zero, existem bibliotecas open-source em diversas linguagens. Para Python, a biblioteca boletoapi ou Pyboleto funcionam razoavelmente bem. Para Node.js, o node-boleto ou brboleto são opções. Para PHP, o zf1-boleto ainda aparece em projetos legados, mas há pacotes mais modernos no Composer. Essas bibliotecas tratam da geração do código de barras, do cálculo dos dígitos e do layout do cartão. Uma limitação importante que essas bibliotecas nem sempre deixam claro: elas geram o boleto visualmente correto, mas isso não garante que o banco aceite. A validação real só acontece quando o pagador vai ao banco ou app e tenta quitar. Se o nossonúmero estiver fora do padrão do banco beneficiário, o boleto é gerado lindamente mas retorna como "não compensável". Sempre teste com valores pequenos e verifique a compensação antes de colocar em produção.

Outro detalhe prático que custa caro se você não sabe: o preço da tarifa. Quando você cria um boleto, precisa decidir quem paga a tarifa — o emitente ou o pagador. Se for para o pagador, o valor total do boleto é o valor da dívida mais a tarifa. Isso precisa estar explicitamente separado no campo "Demonstrativo de elaboração" do documento. O bacana é que muitos geradores automáticos não tratam essa separação corretamente, e o cliente acaba achando que está sendo cobrado um valor a mais sem explicação. Semelhante acontece com o Juros de atraso e o Desconto — ambos precisam estar detalhados linha por linha. Eu costumava adicionar um campo extra de observações no meu sistema que obrigatoriamente descrevia cada componente do valor antes de gerar o boleto, só para evitar essa confusão.

Erros comuns que você deve evitar

A data de vencimento não pode ser inferior a 5 dias corridos da data de emissão, exceto em casos específicos como duplicatas com data pré-fixada. Um boleto com vencimento para amanhã quase sempre será rejeitado pelo banco do pagador. O endereço do beneficiário precisa estar completo no formato que o banco espera. Campos incompletos ou com abreviações excessivas podem fazer o boleto cair para a carteira de inadimplência automática em alguns bancos.

O limite de caracteres nos campos de mensagem é restrito. "Instruções" aceita até 2 linhas com 43 caracteres cada. "Demonstrativo" aceita até 3 linhas com 40 caracteres cada. Passar disso e o banco corta ou rejeita. Eu já vi gente colocar instruções de pagamento inteiras nesses campos e se perguntar por que o boleto voltava. Sobre segurança: boleto é um documento público. Qualquer pessoa que tiver o código de barras consegue consultar a situação cadastral em sites de consulta. Isso significa que você não deve incluir informações sensíveis como CPF completo do pagador ou detalhes financeiros além do necessário no corpo do boleto. Código de barras por si só já carrega todas as informações necessárias para pagamento.

Alternativas quando boleto não faz sentido

Se o seu negócio emite menos de 20 boletos por mês, o internet banking do banco resolve. Não vale a pena integrar API ou desenvolver nada. Se você emite mais de 100 por mês e não tem equipe técnica, use uma API de terceiros. O custo por boleto compensa o tempo que você economiza.

Se você já tem volume alto e precisa de customização completa — como boleto com logo próprio, cores da marca, campos personalizados — aí sim vale a pena desenvolver com uma biblioteca open-source e manter o controle do processo internamente. Mas prepare-se para atualizar periodicamente quando o Febrabran lançar novas regras, o que acontece a cada 6 a 12 meses. Existe também o Pix, que substituiu a maior parte dos usos de boleto no Brasil. Transferência instantânea, sem tarifa para o pagador, confirmação em segundos. A única vantagem real do boleto hoje em dia é para pagamentos parcelados de alto valor onde o pagador não tem conta digital, ou para cobradores que precisam de comprovante formal de emissão com data certa. Para a maioria dos cases, Pix é mais eficiente e custa menos.