Boleto

Boleto de cobrança e de arrecadação: validação, formatação, leitura e decodificação da linha digitável e do código de barras.

Validar

Valida um boleto: a linha digitável de cobrança bancária com 47 dígitos ou o seu código de barras com 44 dígitos, ou um boleto de arrecadação na forma de linha digitável com 48 dígitos ou de código de barras com 44 dígitos.

A função verifica todos os dígitos verificadores do leiaute escolhido (conforme a Carta-Circular BCB 2.926/2000 e o leiaute de arrecadação da FEBRABAN).
O código de moeda (posição 4 do código de barras e da linha digitável) precisa ser 9 (real), o único código que a Carta-Circular BCB 2.926/2000 define. A 2.4.0 aceitava qualquer dígito nessa posição.
A única exceção é o boleto da "Situação 2" da Convenção da Cobrança da FEBRABAN, emitido por uma instituição identificada só pelo ISPB: código do banco 988, código de moeda 0, fator de vencimento 0000 e o ISPB completado com zeros até 10 dígitos nas posições 10 a 19 do código de barras, no lugar do valor. O banco 988 com código de moeda 9 é um boleto comum.
O código de barras de cobrança bancária tem 44 dígitos: código do banco, código de moeda 9, o dígito verificador módulo 11 na posição 5, fator de vencimento, valor e campo livre. Ele é conferido pelas mesmas regras da linha digitável. Até a 2.4.0 esse código de barras era rejeitado.
Um valor de 44 dígitos que começa com 8 é sempre um código de barras de arrecadação (o 8 é o seu identificador de produto). Um código de barras de cobrança bancária de um banco 8xx não é aceito, porque os dois leiautes não poderiam ser distinguidos.
Os caracteres de máscara (espaço em branco, ., - e /) são aceitos entre os dígitos, inclusive uma sequência deles, e espaços nas pontas. Qualquer outro caractere torna o valor inválido: letras, pontuação ou um caractere de máscara no início ou no fim dos dígitos. Então uma linha digitável cercada de letras é rejeitada. Até a 2.4.0 todo caractere que não era dígito era descartado.
Um valor que não é string é inválido.

Parâmetro	Tipo	Obrigatório
`value`	`string`	sim
retorna	`boolean`

Valida um boleto (meio de pagamento brasileiro).

Aceita a linha digitável de 47 dígitos da "cobrança bancária", o seu código de barras de 44 dígitos (código do banco, código de moeda 9, o dígito verificador módulo 11 na posição 5, fator de vencimento, valor e campo livre) e, do "boleto de arrecadação", seja a linha digitável de 48 dígitos, seja o código de barras de 44 dígitos. Um valor de 44 dígitos começando por 8 é sempre um código de barras de arrecadação (o 8 é o identificador de produto da arrecadação na FEBRABAN), então o código de barras de cobrança bancária de um código de banco de 800 a 899 (só existe o 804) não é aceito na forma de código de barras, pois os dois não se distinguiriam; a linha digitável de 47 dígitos dele é aceita. Até a 2.4.0 o código de barras da cobrança bancária era rejeitado.
Os caracteres de máscara usuais (espaço, ., - e /) são aceitos entre os dígitos; qualquer outro caractere invalida o valor, então abc + uma linha digitável + zzz é rejeitado, não lido como os seus dígitos (até a 2.4.0 todo não dígito era descartado).
O código de moeda (posição 4 do código de barras e da linha digitável da cobrança bancária) precisa ser 9 (real), o único código que a Carta-Circular BCB nº 2.926/2000 atribui. A única exceção é o boleto da "Situação 2" da Convenção da Cobrança da FEBRABAN, emitido por instituição identificada apenas pelo ISPB: código de banco 988, código de moeda 0, fator de vencimento 0000 e o ISPB, completado com zeros, no lugar do valor. Qualquer outro dígito é rejeitado.

import { isValidBoleto } from '@brazilian-utils/brazilian-utils';

isValidBoleto('00190000090114971860168524522114675860000102656'); // true
isValidBoleto('00196758600001026560000001149718606852452211'); // true (código de barras da cobrança bancária)
isValidBoleto('846100000005246100291102005460339004695895061080'); // true (boleto de arrecadação)
isValidBoleto('00170000010114971860168524522114275860000102656'); // false (código de moeda 7)
isValidBoleto('abc00190000090114971860168524522114675860000102656zzz'); // false (letras em volta dos dígitos)
isValidBoleto('98800000060114971860168524522114100000018236120'); // true (Situação 2: banco 988, moeda 0, ISPB)

Fonte: Carta-Circular BCB nº 2.926/2000, FEBRABAN, Layout Padrão de Arrecadação, Versão 08 (vigente desde 01/06/2026), FEBRABAN, Convenção da Cobrança.

Código: brazilian-utils/javascript

Teste com JavaScript isValidBoleto

Casos de teste compartilhados (65) e o resultado em cada biblioteca boleto.isValid

Os casos, em JSON

Formatar

Formata a linha digitável de um boleto com a máscara impressa.

A função agrupa a linha digitável de cobrança bancária de 47 dígitos como 00000.00000 00000.000000 00000.000000 0 00000000000000.
Uma linha digitável de 48 dígitos que começa com 8 (boleto de arrecadação) recebe quatro blocos de 11 dígitos, cada um seguido do seu dígito verificador. O código de barras de arrecadação de 44 dígitos mantém a máscara de cobrança bancária, e um valor de 44 dígitos que começa com 8 é sempre lido como código de barras de arrecadação.
Todo caractere que não é dígito é removido antes, então um valor com máscara é aceito. Os dígitos além do tamanho do padrão são descartados.
Sem options.pad, um valor curto recebe a máscara só até onde vão os seus dígitos (104914 dá 10491.4).
Um valor sem dígitos (string vazia, abc, null) retorna uma string vazia, mesmo com options.pad. Até a 2.4.0 pad: true retornava a máscara inteira de zeros para uma string vazia ou sem dígitos.
options.pad completa o valor com zeros à esquerda até o tamanho do padrão, antes de aplicar a máscara.
Um número só é lido se for um inteiro seguro não negativo. Número negativo, fracionário, não finito ou inseguro retorna uma string vazia (a 2.4.0 lia os dígitos de qualquer número).

Parâmetro	Tipo	Obrigatório
`value`	`string \| number`	sim
`options`	`FormatBoletoOptions`	não
`options.pad`	`boolean`	não
retorna	`string`

Formata um número de boleto.

Opções (FormatBoletoOptions): pad preenche o valor com zeros à esquerda até o tamanho do padrão antes de aplicar a máscara (padrão false). Um valor vazio, ou sem dígitos, devolve '' mesmo com pad.
Uma linha digitável de 48 dígitos que começa com 8 recebe a máscara de arrecadação: quatro blocos de 11 dígitos, cada um seguido do seu dígito verificador. O código de barras de arrecadação de 44 dígitos mantém a máscara de "cobrança bancária".

import { formatBoleto } from '@brazilian-utils/brazilian-utils';

formatBoleto('00190000090114971860168524522114675860000102656'); // 00190.00009 01149.718601 68524.522114 6 75860000102656
formatBoleto('1900000901149', { pad: true }); // 00000.00000 00000.000000 00000.000000 0 01900000901149
formatBoleto('846100000005246100291102005460339004695895061080'); // 84610000000-5 24610029110-2 00546033900-4 69589506108-0 (linha digitável de arrecadação, 48 dígitos)
formatBoleto('84610000000246100291100054603390069589506108'); // 84610.00000 02461.002911 00054.603390 0 69589506108 (código de barras de arrecadação de 44 dígitos mantém a máscara bancária)

Fonte: FEBRABAN, Layout Padrão de Arrecadação, Versão 08 (vigente desde 01/06/2026).

Código: brazilian-utils/javascript

Teste com JavaScript formatBoleto

Casos de teste compartilhados (71) e o resultado em cada biblioteca boleto.format

Os casos, em JSON

Interpretar

Remove de um boleto todo caractere que não é dígito (máscara, espaços, letras) e retorna os dígitos, sem conferir se o boleto é válido.

O resultado é cortado em 47 dígitos, ou em 48 quando os dígitos começam com 8 (boleto de arrecadação). Os dígitos além disso são descartados.
Um número só é lido se for um inteiro seguro não negativo. Número negativo, fracionário, não finito ou inseguro retorna uma string vazia (a 2.4.0 lia os dígitos de qualquer número).

Parâmetro	Tipo	Obrigatório
`value`	`string \| number`	sim
retorna	`string`

Remove a formatação do boleto, mantém apenas os dígitos e limita o resultado a 47 dígitos (48 para boleto de arrecadação).

import { parseBoleto } from '@brazilian-utils/brazilian-utils';

parseBoleto('00190.00009 01149.718601 68524.522114 6 75860000102656'); // 00190000090114971860168524522114675860000102656

Fonte: Carta-Circular BCB nº 2.926/2000, FEBRABAN, Layout Padrão de Arrecadação, Versão 08 (vigente desde 01/06/2026).

Código: brazilian-utils/javascript

Teste com JavaScript parseBoleto

Casos de teste compartilhados (10) e o resultado em cada biblioteca boleto.parse

Os casos, em JSON

Gerar

Gera um número de boleto aleatório e válido.

Por padrão, a função gera uma linha digitável de cobrança bancária com 47 dígitos. Com params.type definido como arrecadação, ela gera um boleto de arrecadação com 48 dígitos.
Um boleto de cobrança bancária recebe um código de banco aleatório de 3 dígitos, o código de moeda 9 (real) e um fator de vencimento 0000 (sem vencimento) ou de 1000 a 9999. Os fatores 0001 a 0999 não indicam data e nunca são sorteados.
Um boleto de arrecadação sorteia o segmento de 1 a 7 (o segmento 9 é de uso dos próprios bancos) e o identificador de valor entre os quatro valores (6 e 8 para valor efetivo, 7 e 9 para quantidade de referência), então hasEffectiveValue pode ser verdadeiro ou falso.
boleto.isValid aceita o resultado.
O sorteio usa Math.random(), então não é criptograficamente seguro. Não use para fins de segurança.

Parâmetro	Tipo	Obrigatório
`params`	`GenerateBoletoParams`	não
`params.type`	`"bancario" \| "arrecadacao"`	não
retorna	`string`

Gera um boleto válido aleatório.

Informe { type: 'arrecadacao' } (GenerateBoletoParams) para um boleto de arrecadação de 48 dígitos em vez do tipo padrão 'bancario' (cobrança bancária, 47 dígitos).
Um boleto de cobrança bancária traz o código de moeda 9 e um fator de vencimento 0000 (sem vencimento) ou de 1000 a 9999; de 0001 a 0999 o fator não indica data.

import { generateBoleto } from '@brazilian-utils/brazilian-utils';

generateBoleto(); // "00190000090114971860168524522114675860000102656"
generateBoleto({ type: 'arrecadacao' }); // "846100000005246100291102005460339004695895061080"

Fonte: Carta-Circular BCB nº 2.926/2000, FEBRABAN, Layout Padrão de Arrecadação, Versão 08 (vigente desde 01/06/2026).

Código: brazilian-utils/javascript

Teste com JavaScript generateBoleto

Casos de teste compartilhados (3) e o resultado em cada biblioteca boleto.generate

Os casos, em JSON

Decodificar

Interpreta um boleto e retorna o valor, a data de vencimento e o código do banco: da linha digitável de 47 dígitos ou do código de barras de 44 dígitos de um boleto de cobrança bancária, ou de um boleto de arrecadação. Retorna null quando a entrada não é um boleto válido.

O resultado traz amount (em centavos), expirationDate e bankCode (o código COMPE de 3 dígitos).
A data de vencimento é null quando o boleto não traz fator de vencimento (um fator abaixo de 1000).
O ciclo do fator de vencimento reiniciou em 2025-02-22, então um fator corresponde a duas datas com 9000 dias de diferença. Nenhuma publicação da FEBRABAN ou do Banco Central diferencia os ciclos; a regra vem de manuais de bancos. options.referenceDate resolve o ciclo com base nessa data, em vez de hoje. Passe-a sempre que a resposta precisar ser estável, pois o mesmo boleto pode passar a resolver para a outra data com o tempo.
A janela em torno de referenceDate é de 3000 dias para trás e 5500 dias para frente, e o candidato mais próximo vence quando nenhum cai dentro dela. Um boleto que vence até 3499 dias (cerca de 9,5 anos) antes de referenceDate mantém a sua data. Um que vence 3500 dias (cerca de 9,6 anos) ou mais antes dela é lido como o próximo ciclo (uma data no futuro). Para ler um boleto antigo, passe uma referenceDate perto da data de emissão. A busca nunca desce abaixo do primeiro ciclo, então uma referenceDate mais antiga ainda resolve o fator para a data mais antiga que ele pode indicar, nunca uma anterior à data-base 1997-10-07.
Uma referenceDate que não é um Date válido (um Date inválido, uma string, um número, null) é ignorada e usa-se hoje. A chamada nunca lança erro. Até a 2.4.0 um Date inválido dava a data-base de 1997 e uma string ou um número lançavam erro.
O código de barras de 44 dígitos é lido para os mesmos campos da linha digitável: o valor nas posições 10 a 19 e o fator de vencimento nas posições 6 a 9. Até a 2.4.0 o código de barras de cobrança bancária dava null. Um valor que não é string retorna null.
Um valor de 44 dígitos que começa com 8 é sempre lido como código de barras de arrecadação, nunca de cobrança bancária: retorna o resultado de arrecadação quando é um código de barras de arrecadação válido e null caso contrário, mesmo que fosse um código de barras válido de um banco 8xx.
Um boleto de arrecadação não tem código do banco nem data de vencimento: bankCode é "" e expirationDate é null. Ele também traz type ("arrecadacao"), segment (de 1 a 7, ou 9 para uso dos próprios bancos), value (o valor em reais, amount dividido por 100) e hasEffectiveValue (se o valor é efetivo ou uma quantidade de referência).
Um boleto da "Situação 2" da FEBRABAN (banco 988, código de moeda 0, ver boleto.isValid) traz o ISPB de 8 dígitos do emissor no lugar do valor. O resultado tem ispb com esse ISPB, amount igual a 0 e expirationDate null. O campo ispb é novo na 2.5.0 e não aparece em nenhum outro boleto.
Retorna null exatamente quando boleto.isValid retorna false, então um boleto com código de moeda diferente de 9 retorna null (a 2.4.0 o decodificava).

Parâmetro	Tipo	Obrigatório
`value`	`string`	sim
`options`	`GetBoletoInfoOptions`	não
`options.referenceDate`	`Date`	não
retorna	`BoletoInfo \| null`

Extrai informações de um boleto (valor, data de vencimento, código do banco). Retorna null quando o valor não é um boleto válido.

Opções (GetBoletoInfoOptions): referenceDate resolve o ciclo do "fator de vencimento" a partir dessa data em vez de agora.
Lê a linha digitável de 47 dígitos e o código de barras de 44 dígitos de um boleto de cobrança bancária, e as formas de arrecadação, do mesmo modo que isValidBoleto as aceita.
Retorna um BoletoInfo: amount em centavos, expirationDate e o bankCode de três dígitos. expirationDate é null quando o boleto não traz fator de vencimento (um fator abaixo de 1000).
O ciclo do fator de vencimento reiniciou em 22/02/2025, então um fator pode significar uma de duas datas separadas por 9000 dias. Não há comunicado da FEBRABAN publicado sobre o reinício; a regra está em manuais de banco, como o do Bradesco (Versão 17). referenceDate escolhe entre elas; informe-a sempre que a resposta precisar ser estável.
As janelas são de 3000 dias para trás e 5500 dias para a frente de referenceDate: um boleto que venceu até 3499 dias (cerca de 9,5 anos) antes dela mantém a data, e um que venceu 3500 dias (cerca de 9,6 anos) ou mais antes dela é lido como o próximo ciclo (uma data no futuro), então, para ler um boleto antigo, informe uma referenceDate próxima da data de emissão. Uma referenceDate que não seja um Date válido é ignorada e usa-se agora.
Um boleto de arrecadação tem bankCode: '' e expirationDate: null, mais type: 'arrecadacao', segment, value (o valor em reais) e hasEffectiveValue.
O boleto da "Situação 2" da Convenção da Cobrança da FEBRABAN (código de banco 988, código de moeda 0) traz o ISPB do emissor no lugar do valor: ele volta como ispb, com amount: 0.

import { getBoletoInfo } from '@brazilian-utils/brazilian-utils';

getBoletoInfo('00190000090114971860168524522114675860000102656');
// { amount: 102656, expirationDate: Date, bankCode: '001' }

getBoletoInfo('00196758600001026560000001149718606852452211');
// o mesmo boleto lido do código de barras de 44 dígitos

getBoletoInfo('00190000090114971860168524522114675860000102656', {
  referenceDate: new Date(2018, 6, 1)
});
// Resolve o ciclo do fator de vencimento a partir de 01/07/2018

getBoletoInfo('98800000060114971860168524522114100000018236120');
// { amount: 0, expirationDate: null, bankCode: '988', ispb: '18236120' }

getBoletoInfo('846100000005246100291102005460339004695895061080');
// { amount: 2461, expirationDate: null, bankCode: '', type: 'arrecadacao', segment: 4, value: 24.61, hasEffectiveValue: true }

getBoletoInfo('invalid'); // null