@mrmgomes/boleto-utils NPM

boleto-utils

Biblioteca com funções úteis para a validação de todos os tipos de boleto

É a minha primeira publicação no NPM, portanto sintam-se à vontade para colaborar, adicionando e/ou modificando qualquer funcionalidade da lib!

Índice

1. Instalação

2. Funções

3. Exemplos de uso

4. Regras de numeração dos boletos

1. Instalação

Para utilizar o boleto-utils, baixe-o pelo repositório npm através do comando: npm install --save @mrmgomes/boleto-utils. Depois importe-o em seu projeto javascript através do require (ES5) ou import (ES6) e já pode utilizar as funções da biblioteca.

2. Funções

Função	Definição
`identificarTipoCodigo(codigo: string)`	Verifica a numeração e retorna o tipo do código inserido. CODIGO_DE_BARRAS ou LINHA_DIGITAVEL. Requer numeração completa (com ou sem formatação).
`identificarTipoBoleto(codigo: string)`	Verifica a numeração e retorna o tipo do boleto inserido. Se boleto bancário, convênio ou arrecadação. Requer numeração completa (com ou sem formatação).
`identificarReferencia(codigo: string)`	Valida o terceiro campo da numeração inserida para definir como será calculado o Dígito Verificador. Requer numeração completa (com ou sem formatação).
`identificarData(codigo: string, tipoCodigo: string)`	Verifica a numeração, o tipo de código inserido e o tipo de boleto e retorna a data de vencimento. Requer numeração completa (com ou sem formatação) e tipo de código que está sendo inserido (CODIGO_DE_BARRAS ou LINHA_DIGITAVEL).
`identificarValorCodBarrasArrecadacao(codigo: string, tipoCodigo: string)`	Verifica a numeração e o tipo de código inserido e retorna o valor do CÓDIGO DE BARRAS do tipo Arrecadação. Requer numeração completa (com ou sem formatação) e tipo de código que está sendo inserido (CODIGO_DE_BARRAS ou LINHA_DIGITAVEL).
`identificarValor(codigo: string, tipoCodigo: string)`	Verifica a numeração, o tipo de código inserido e o tipo de boleto e retorna o valor do título. Requer numeração completa (com ou sem formatação) e tipo de código que está sendo inserido (CODIGO_DE_BARRAS ou LINHA_DIGITAVEL).
`digitosVerificadores(codigo: string, mod: int)`	Verifica a numeração e o módulo a ser utilizado (Mod 10 ou Mod 11) e retorna o DV (Dígito Verificador). Requer numeração completa (com ou sem formatação) e caracteres numéricos que representam o módulo a ser usado (valores aceitos: 10 ou 11).
`codBarras2LinhaDigitavel(codigo: string, formatada: boolean)`	Transforma a numeração no formato de código de barras em linha digitável. Requer numeração completa (com ou sem formatação) e valor `true` ou `false` que representam a forma em que o código convertido será exibido. Com (true) ou sem (false) formatação.
`linhaDigitavel2CodBarras(codigo: string)`	Transforma a numeração no formato linha digitável em código de barras. Requer numeração completa (com ou sem formatação).
`calculaDVCodBarras(codigo: string, posicaoCodigo: int, mod: int)`	Verifica a numeração do código de barras, extrai o DV (dígito verificador) presente na posição indicada, realiza o cálculo do dígito utilizando o módulo indicado e retorna o dígito verificador. Serve para validar o código de barras. Requer numeração completa (com ou sem formatação), caracteres numéricos que representam a posição do dígito verificador no código de barras e caracteres numéricos que representam o módulo a ser usado (valores aceitos: 10 ou 11).
`validarCodigoComDV(codigo: string)`	Calcula o dígito verificador de toda a numeração do código de barras. Retorno `true` para numeração válida e `false` para inválida.
`geraCodBarras(codigo: string)`	Transforma a linha digitável em código de barras inserindo o DV.
`calculaMod10(numero: string)`	Realiza o cálculo Módulo 10 do número inserido.
`calculaMod11(numero: string)`	Realiza o cálculo Módulo 11 do número inserido.
`validarBoleto(codigo: string)`	Verifica a numeração e utiliza várias das funções acima para retornar um objeto JSON contendo informações sobre a numeração inserida: `Tipo de código inserido`, `Tipo de boleto inserido`, `Código de barras`, `Linha digitável`, `Vencimento` e `Valor`

3. Exemplos de uso

A princípio, a função validarBoleto(codigo: string, tipoCodigo: string) é a única que poderia ser utilizada para validar e trazer informações de um código de barras/linha digitável, portanto mostrarei apenas este exemplo. As demais funções estão documentadas acima e são autoexplicativas.

Exemplo #1:

validarBoleto('23790448095616862379336011058009740430000124020', 'LINHA_DIGITAVEL');

Retorno #1:

{
    "sucesso": true,
    "mensagem": "Boleto validado com sucesso",
    "tipoCodigoInput": "LINHA_DIGITAVEL",
    "tipoBoleto": "BANCO",
    "codigoBarras": "23799336051105800974404300001247044809561686237",
    "linhaDigitavel": "23790448095616862379336011058009740430000124020",
    "vencimento": "2008-11-01T23:54:59.923Z",
    "valor": 1240.2
}

Exemplo #2:

validarBoleto('34196790600001000002220000005566385101214000', 'CODIGO_DE_BARRAS');

Retorno #2:

{
    "sucesso": true,
    "mensagem": "Boleto validado com sucesso",
    "tipoCodigoInput": "CODIGO_DE_BARRAS",
    "tipoBoleto": "BANCO",
    "codigoBarras": "34196790600001000002220000005566385101214000",
    "linhaDigitavel": "34192220090000556638551012140003679060000100000",
    "vencimento": "2019-05-31T23:54:59.373Z",
    "valor": 1000
}

4. Regras de numeração dos boletos

4.1 `BOLETO COBRANÇA`

IMPORTANTE: As posições aqui mencionadas partem do número 0 e não do 1, a fim de facilitar o entendimento lógico

4.1.1 TIPO: CÓDIGO DE BARRAS (44 POSIÇÕES NUMÉRICAS)

EXEMPLO: 11123444455555555556666666666666666666666666

Bloco	Posições	Definição
1	0 a 2	`Código do Banco na Câmara de Compensação`
2	3 a 3	`Código da Moeda = 9 (Real)`
3	4 a 4	`Digito Verificador (DV) do código de Barras`
4	5 a 8	`Fator de Vencimento`
5	9 a 18	`Valor com 2 casas de centavos`
6	19 a 43	`Campo Livre (De uso da instituição bancária)`

4.1.2 TIPO: LINHA DIGITÁVEL (47 POSIÇÕES NUMÉRICAS)

EXEMPLO: AAABC.CCCCX DDDDD.DDDDDY EEEEE.EEEEEZ K UUUUVVVVVVVVVV

Campo	Posições linha dig.	Definição
A	0 a 2 (0 a 2 do cód. barras)	`Código do Banco na Câmara de compensação`
B	3 a 3 (3 a 3 do cód. barras)	`Código da moeda`
C	4 a 8 (19 a 23 do cód. barras)	`Campo Livre`
X	9 a 9	`Dígito verificador do Bloco 1 (Módulo 10)`
D	10 a 19 (24 a 33 do cód. barras)	`Campo Livre`
Y	20 a 20	`Dígito verificador do Bloco 2 (Módulo 10)`
E	21 a 30 (24 a 43 do cód. barras)	`Campo Livre`
Z	31 a 31	`Dígito verificador do Bloco 3 (Módulo 10)`
K	32 a 32 (4 a 4 do cód. barras)	`Dígito verificador do código de barras`
U	33 a 36 (5 a 8 do cód. barras)	`Fator de Vencimento`
V	37 a 43 (9 a 18 do cód. barras)	`Valor`

4.2 `CONTA CONVÊNIO / ARRECADAÇÃO`

4.2.1 TIPO: CÓDIGO DE BARRAS (44 POSIÇÕES NUMÉRICAS)

EXEMPLO: 12345555555555566667777777777777777777777777

Campo	Posições	Definição
1	0 a 0	`"8" Identificação da Arrecadação/convênio`
2	1 a 1	`Identificação do segmento`
3	2 a 2	`Identificação do valor real ou referência`
4	3 a 3	`Dígito verificador geral (módulo 10 ou 11)`
5	4 a 14	`Valor efetivo ou valor referência`
6	15 a 18	`Identificação da empresa/órgão`
7	19 a 43	`Campo livre de utilização da empresa/órgão`

4.2.2 TIPO: LINHA DIGITÁVEL (48 POSIÇÕES NUMÉRICAS)

EXEMPLO: ABCDEEEEEEE-W EEEEFFFFGGG-X GGGGGGGGGGG-Y GGGGGGGGGGG-Z

Campo	Posições	Definição
A	0 a 0	`"8" Identificação da Arrecadação/convênio`
B	1 a 1	`Identificação do segmento`
C	2 a 2	`Identificação do valor real ou referência`
D	3 a 3	`Dígito verificador geral (módulo 10 ou 11)`
E	4 a 14	`Valor efetivo ou valor referência`
W	11 a 11	`Dígito verificador do Bloco 1`
F	15 a 18	`Identificação da empresa/órgão`
G	19 a 43	`Campo livre de utilização da empresa/órgão`
X	23 a 23	`Dígito verificador do Bloco 2`
Y	35 a 35	`Dígito verificador do Bloco 3`
Z	47 a 47	`Dígito verificador do Bloco 4`