validation-br

Biblioteca de validação de documentos pessoais do Brasil com suporte a CPF, CNPJ (numérico e alfanumérico), Título Eleitoral, PIS/PASEP, CNH. Também valida numerações de outros tipos de registros como RENAVAM, Processos Judiciais, Número de Protocolo do Governo Federal e Objetos registrados de Rastreamento dos Correios.

Validation-BR também permite criação de números fake para facilitar o desenvolvimento e testes, além de aplicar máscaras e calcular somente os dígitos verificadores.

Instalação

1# Usando yarn
2yarn add validation-br
3
4## OU
5# Usando npm
6npm install validation-br
7

Importação

Importação direta

Permite realizar diretamente uma validação a partir do objeto principal

1// Modules
2const { isCPF, isCNPJ } = require('validation-br')
3
4// ES6
5import { isCPF, isCNPJ } from 'validation-br'

Importação de submódulos

Importando os submódulos, é possível criar máscaras, números fake para testes de desenvolvimento e calcular dígitos verificadores.

Exemplos

1// ES6
2import { dv, fake, mask, validate } from 'validation-br/dist/cpf'
3// ou
4import * as cpf from 'validation-br/dist/cpf'
5
6// CommonJS
7const cpf = require('validation-br/dist/cpf')
8const { dv, fake, mask, validate } = require('validation-br/dist/cpf')
9
10// Calculo do dígito verificador de um CPF. Os métodos aceitam inteiros e strings, inclusive com máscaras.
11cpf.dv(906259666) // -> '51'
12cpf.dv('906259666') // -> '51'
13cpf.dv('906.259.666') // -> '51'
14
15// Cria um número fake de CPF para fins de testes.
16cpf.fake() // -> 90625966651
17// Passe um parâmetro true para gerar o número com máscara
18cpf.fake(true) // -> 906.259.666-51
19
20// Aplique uma máscara a um cpf
21cpf.mask(90625966651) // -> 906.259.666-51
22
23// Valida um número
24cpf.validate('01234567890') // -> true
25
26// Valida um número e retorna exceção se a validação falhar
27cpf.validateOrFail('01234567890') // -> true

Tabela de Conteúdo

Funções de Validação

• isCNH - Validação do CNH
• isCPF - Validação do CPF
• isCNPJ - Validação do CNPJ
• isNUP17 - Validação de Número Unificado de Protocolo do Governo Federal
• isJudicialProcess - Validação de Números de Processos Judiciais
• isPIS - Validação de PIS, PASEP, NIS e NIT
• isPostalCode - Validação de Objetos Registrados dos Correios
• isRenavam - Validação de RENAVAM
• isTituloEleitor - Validação do Título de Eleitor

Usando em outras bibliotecas de validação

Validation-BR pode ser utilizado em conjunto com quaisquer bibliotecas de validação que permita estender seus métodos. Abaixo seguem alguns exemplos. Sinta-se convidado a adicionar a sua biblioteca favorita em nosso wiki.

• Vuelidate - Usado para validação de estado no vuejs
• Class-Validator - Usado em nest, typeorm E mais uma infinidade de frameworks
• Indicative - Indicative é a biblioteca padrão de validação usada no Adonis.
• Joi - Joi é um validador de esquemas usado em aplicações node, react, vue etc.
• Yup - Yup é usado para validar estado em aplicações react.

isCNH( value )

Valida o documento da carteira nacional de habilitação.

1// Importação somente da validação
2import { isCNH } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/cnh'
6// ou
7import * as cnh from 'validation-br/dist/cnh'
8
9// Valida
10isCNH('69044271146') //-> true
11isCNH('62472927637') //-> true
12isCNH('46190476839') //-> false
13cnh.validate('62472927637') //-> true
14cnh.validateOrFail('62472927637') //-> true
15
16// Número fake com e sem máscara
17cnh.fake() // -> 62472927637
18cnh.fake(true) // -> 624729276-37
19
20// Aplica uma máscara
21cnh.mask('62472927637') // -> 624729276-37
22
23// Calcula o DV
24cnh.dv('624729276') // -> '37'

isCNPJ( value )

Valida um CNPJ

A partir da Nota Técnica conjunta COCAD/SUARA/RFB nº 49 de 14 de maio de 2024, os números de CNPJ poderão ser alfanuméricos. A alteração entra em uso em 2026.

1// Importação somente da validação
2import { isCNPJ } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/cnpj'
6// ou
7import * as cnpj from 'validation-br/dist/cnpj'
8
9// Valida
10isCNPJ('73.797.980/0001-79') //-> true
11isCNPJ('55585709000198') //-> true
12isCNPJ('99362238000180') //-> false
13cnpj.validate('99362238000180') //-> true
14cnpj.validateOrFail('99362238000180') //-> true
15
16// Número fake com e sem máscara
17cnpj.fake() // -> 55585709000198
18cnpj.fake(true) // -> 55.585.709/0001-98
19cnpj.fake({ withMask: true}) // -> 55.585.709/0001-98
20cnpj.fake({ withMask: true, alphanumeric: true}) // -> A1.222.333/0001-50
21cnpj.fake({ withMask: false, alphanumeric: true}) // -> A1222333/0001-50
22
23// Aplica uma máscara
24cnpj.mask('99362238000180') // -> 99.362.238/0001-80
25
26// Calcula o DV
27cnpj.dv('993622380001') // -> '80'

isCPF( value )

Valida um CPF

1// Importação somente da validação
2import { isCPF } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/cpf'
6// ou
7import * as cpf from 'validation-br/dist/cpf'
8
9// Valida
10isCPF('01234567890') //-> true
11isCPF('012.345.678-90') //-> true
12isCPF('01234567891') //-> false
13cpf.validate('01234567890') //-> true
14cpf.validateOrFail('01234567890') //-> true
15
16// Número fake com e sem máscara
17cpf.fake() // -> 01234567891
18cpf.fake(true) // -> 012.345.678-91
19
20// Aplica uma máscara
21cpf.mask('01234567890') // -> 012.345.678-90
22
23// Calcula o DV
24cpf.dv('012345678') // -> '90'

isJudicialProcess( value )

Valida números de processo da esfera judicial. Esta padronização foi adotada em 2010 e de lá para cá todos os processos judiciais abertos no país seguem o mesmo padrão, seja eleitoral, cível, militar etc.

O número é composto por 6 partes:

1. Número sequencial dado pelo órgão de registro, reiniciado a cada ano, com até 7 caracteres

2. Dígito verificador com 2 caracteres

3. Ano de registro com 4 caracteres

4. Órgão do poder judiciário com 1 caractere, sendo eles:

   • 1 - Supremo Tribunal Federal
   • 2 - Conselho Nacional de Justiça
   • 3 - Superior Tribunal de Justiça
   • 4 - Justiça Federal
   • 5 - Justiça do Trabalho
   • 6 - Justiça Eleitoral
   • 7 - Justiça Militar da União
   • 8 - Justiça dos Estados e do Distrito Federal e Territórios
   • 9 - Justiça Militar Estadual

5. Tribunal do segmento do poder judiciário com 2 caracteres

6. Código da unidade de origem do processo com 4 caracteres

1// Importação somente da validação
2import { isJudicialProcess } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/judicialProcess'
6// ou
7import * as judicialProcess from 'validation-br/dist/judicialProcess'
8
9// Valida
10isJudicialProcess('20802520125150049') //-> true
11isJudicialProcess('0011006-07.2016.8.20.0100') //-> true
12isJudicialProcess('00110060720168200101') //-> false
13judicialProcess.validate('00110060720168200100') //-> true
14judicialProcess.validateOrFail('00110060720168200100') //-> true
15
16// Número fake com e sem máscara
17judicialProcess.fake() // -> 00110060720168200100
18judicialProcess.fake(true) // -> 0011006-07.2016.8.20.0100
19
20// Aplica uma máscara
21judicialProcess.mask('00110060720168200100') // -> 0011006-07.2016.8.20.0100
22
23// Calcula o DV.
24// Obs.: Antes do cálculo, é necessário que o número do processo não possua o dígito verificador para que o resultado seja correto. Isso é necessário pois o DV fica no meio da numeração, na posição 8 e 9.
25judicialProcess.dv('001100620168200100') // -> '07'

isNUP17( value )

Válida um Número Unificado de Protocolo de 17 dígitos. Esta numeração é usada pelo Governo Federal como forma única de numerar processos em todas os órgãos do executivo.

1. Os primeiros 5 dígitos correspondem código do órgão
2. Os dígitos de 6 a 11 são um número sequencial dado pelo órgão em questão e é reiniciado a cada ano
3. Os dígitos 12 a 15 representam o ano de registro do protocolo
4. Os caracteres 16 a 17 são o dígito verificador

1// Importação somente da validação
2import { isNUP17 } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/nup17'
6// ou
7import * as nup from 'validation-br/dist/nup17'
8
9// Valida
10isNUP17('23037001462202165') //-> true
11isNUP17('23037.001462/2021-65') //-> true
12isNUP17('23037.001462/2021-66') //-> false
13nup.validate('23037.001462/2021-65') //-> true
14nup.validateOrFail('23037.001462/2021-65') //-> true
15
16// Número fake com e sem máscara
17nup.fake() // -> 71282677380
18nup.fake(true) // -> 712.82677.38-0
19
20// Aplica uma máscara
21nup.mask('23037001462202165') // -> 23037.001462/2021-65
22
23// Calcula o DV
24nup.dv('230370014622021') // -> '65'

isPIS( value )

Valida códigos PIS, PASEP, NIS e NIT, que usam o mesmo algoritmo. Aceita números com e sem pontos e traços.

1// Importação somente da validação
2import { isPIS } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/pisPasep'
6// ou
7import * as pis from 'validation-br/dist/pisPasep'
8
9// Valida
10isPIS('71282677380') //-> true
11isPIS('237.95126.95-5') //-> true
12isPIS('500.12973.80-1') //-> false
13pis.validate('71282677380') //-> true
14pis.validateOrFail('71282677380') //-> true
15
16// Número fake com e sem máscara
17pis.fake() // -> 71282677380
18pis.fake(true) // -> 712.82677.38-0
19
20// Aplica uma máscara
21pis.mask('71282677380') // -> 712.82677.38-0
22
23// Calcula o DV
24pis.dv('7128267738') // -> '0'

isPostalCode( value )

Valida um código de rastreamento de objetos postais no formato XX00000000DYY, onde:

• XX: O código do objeto postal com 2 dígitos;
• 00000000: Número sequencial do objeto com 8 dígitos;
• D: Dígito Verificador
• YY: País de origem do objeto com 2 dígitos.

1// Importação somente da validação
2import { isPostalCode } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/postalCode'
6// ou
7import * as postalCode from 'validation-br/dist/postalCode'
8
9// Valida
10isPostalCode('PN718252423BR') //-> true
11isPostalCode('RY728187035CN') //-> true
12isPostalCode('JT194624698BR') //-> false
13postalCode.validate('PN718252423BR') //-> true
14postalCode.validateOrFail('PN718252423BR') //-> true
15
16// Número fake com e sem máscara.
17postalCode.fake() // -> PN718252423BR
18postalCode.fake(true) // -> PN718252423BR
19
20// Aplica uma máscara
21// No caso de PostalCode, a máscara apenas coloca as letras em maiúsculas
22postalCode.mask('pn718252423br') // -> PN718252423BR
23
24// Calcula o DV
25postalCode.dv('PN718252423BR') // -> '3'

isRenavam( value )

Valida o número de um RENAVAM de 11 dígitos

1// Importação somente da validação
2import { isRenavam } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/renavam'
6// ou
7import * as renavam from 'validation-br/dist/renavam'
8
9// Valida
10isRenavam('14283256656') //-> true
11isRenavam('95059845976') //-> true
12isRenavam('67747331626') //-> false
13renavam.validate('95059845976') //-> true
14renavam.validateOrFail('95059845976') //-> true
15
16// Número fake com e sem máscara
17renavam.fake() // -> 95059845976
18renavam.fake(true) // -> 9505984597-6
19
20// Aplica uma máscara
21renavam.mask('95059845976') // -> 9505984597-6
22
23// Calcula o DV
24renavam.dv('950598459') // -> '76'

isTituloEleitor( value )

Valida um título eleitoral

1// Importação somente da validação
2import { isTituloEleitor } from 'validation-br'
3// ou
4// Importação do submódulo
5import { validate, mask } from 'validation-br/dist/tituloEleitor'
6// ou
7import * as titulo from 'validation-br/dist/tituloEleitor'
8
9// Valida
10isTituloEleitor('743650641660') //-> true
11isTituloEleitor('525028881694') //-> true
12isTituloEleitor('153016161686') //-> false
13titulo.validate('01234567890') //-> true
14titulo.validateOrFail('01234567890') //-> true
15
16// Número fake com e sem máscara
17titulo.fake() // -> 153016161686
18titulo.fake(true) // -> 1530.1616.1686
19
20// Aplica uma máscara
21titulo.mask('525028881694') // -> 5250.2888.1694
22
23// Calcula o DV
24titulo.dv('5250288816') // -> '94'

Testes

Todos os testes passando com 100% de cobertura

Github Actions

Github actions executados nas versões 18, 20 e 22 do Node.

Changelog

• 16/12/2023:
  • 1.5.0
    • CNPJ alfanumérico
    • Removidos github actions dos node 12, 14 e 16 e acrescentado o 22
• 16/12/2023:
  • 1.4.5
    • Corrige o caminho da definição dos types. (Thanks @ishigami)
• 30/12/2022:
  • 1.4.4
    • Correção de bug quando o documento válido tinha caracteres adicionais
    • Refatoração de clearValue() para comportar configurações opcionais
• 01/10/2022:
  • 1.4.1
    • Correção na importação principal dos módulos
    • Refatoração do isJudicialProcess para permitir 100% de cobertura dos testes
    • Inclusão de mais testes unitários para atingir 100% de cobertura
• 10/01/2022:
  • 1.1.0 - Adicionado NUP17 - Número Unificado de Protocolo de 17 dígitos do Governo Federal
• 09/01/2022:
  • 1.0.0 - Biblioteca convertida para Typescript e testes convertidos para Jest
• 08/01/2022:
  • 0.21.1 - Adicionadas as funções isRenavam e isJudicialProcess
• 16/09/2021:
  • 0.5.0 - Adicionadas as funções isCPF, isCNPJ e isTituloEleitor
  • 0.7.0 - Adicionadas as funções isPostalCode e isCNH
  • 0.8.0 - Adicionada a função isPIS

Referências

• Cálculo do DV do CPF
• Cálculo do DV do CNPJ
• Cálculo do DV do Título Eleitoral
• Cálculo do PIS
• Diferença entre PIS, PASEP, NIS e NIT
• Documentação Oficial de Numeração de Processos Judiciais
• Cálculos de DV
• Cálculo do NUP17