boleto-utils

Valida e interpreta boletos a partir da linha digitável ou do código de barras: banco, valor e vencimento. Funciona com boletos bancários (47 dígitos) e de arrecadação, como contas de luz, água, telefone e tributos (48 dígitos). Não tem dependências.

O problema do fator de vencimento

O vencimento do boleto é um contador de dias desde 07/10/1997, com 4 dígitos. Ele chegou a 9999 em 21/02/2025 e voltou para 1000 em 22/02/2025. Desde então, o mesmo fator corresponde a duas datas com 9000 dias de diferença. Código antigo que só soma dias à data-base mostra vencimentos em 1997–2000.

Aqui, factorToDate escolhe a data mais próxima da data de referência (hoje, por padrão), que é a forma recomendada pela Febraban na transição.

factorToDate('1000'); // '2025-02-22' (e não '2000-07-03')

Uso

import { parseBoleto } from 'boleto-utils';

parseBoleto('34191.09008 00012.345674 89012.345677 6 16000000123456');
// {
//   valid: true, type: 'bank', bankCode: '341', currency: 'BRL',
//   amount: 1234.56, dueDate: '2026-10-15',
//   barcode: '34196160000001234561090000012345678901234567',
//   line: '34191090080001234567489012345677616000000123456',
//   formattedLine: '34191.09008 00012.345674 89012.345677 6 16000000123456'
// }

parseBoleto('83600000001-5 57900048000-7 00000000000-0 00202610150-7');
// { valid: true, type: 'collection', segment: 'energia e gás', amount: 157.9, ... }

parseBoleto('34191.09008 00012.345674 89012.345677 6 16000000123457'); // último dígito trocado
// { valid: false, error: 'Dígito verificador inválido' }

Aceita entrada com ou sem pontos e espaços. Também aceita o código de barras de 44 dígitos que um leitor ou a câmera do celular devolve.

O que é validado

tipo	verificação
bancário (47)	DV módulo 10 de cada um dos 3 campos + DV geral módulo 11 do código de barras
arrecadação (48)	DV de cada bloco + DV geral, em módulo 10 ou 11 conforme o identificador de valor (3º dígito)
código de barras (44)	DV geral; a conversão para a linha recalcula os DVs dos campos

Os testes trocam cada um dos 47 dígitos de uma linha válida e conferem que todos os erros são detectados.

API

Função	Descrição
parseBoleto(input, { reference? })	identifica, valida e extrai dados (nunca lança exceção)
bankLineToBarcode / bankBarcodeToLine	conversão bancária 47 ↔ 44
collectionLineToBarcode / collectionBarcodeToLine	conversão de arrecadação 48 ↔ 44
factorToDate(fator, ref?) / dateToFactor(data)	fator de vencimento ↔ YYYY-MM-DD
buildBankBarcode({ bankCode, amount, dueDate, freeField })	monta um código de barras a partir do campo livre do banco
formatBankLine(line)	00000.00000 00000.000000 00000.000000 0 00000000000000

Desenvolvimento

npm test

Licença

MIT