{"id":18193093,"url":"https://github.com/klawdyo/validation-br","last_synced_at":"2025-12-25T19:03:31.989Z","repository":{"id":48412720,"uuid":"407334927","full_name":"klawdyo/validation-br","owner":"klawdyo","description":"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, Processos Judiciais, Protocolo Unificado do Governo Federal, Renavam e Objetos registrados de rastreamento dos Correios.","archived":false,"fork":false,"pushed_at":"2025-03-26T21:34:24.000Z","size":988,"stargazers_count":59,"open_issues_count":0,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T20:08:38.385Z","etag":null,"topics":["br","brazil","cnh","cnpj","cpf","eleitor","javascript","js","nis","nit","pasep","pis","renavam","titulo","validation"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/validation-br","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/klawdyo.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-16T22:45:56.000Z","updated_at":"2025-02-27T17:19:39.000Z","dependencies_parsed_at":"2023-12-28T00:24:39.255Z","dependency_job_id":"596a4123-d8f8-4588-8d34-dca2d951a6ac","html_url":"https://github.com/klawdyo/validation-br","commit_stats":{"total_commits":168,"total_committers":4,"mean_commits":42.0,"dds":"0.15476190476190477","last_synced_commit":"e353fe1e3691715b8089d4d2dd218a0952a5a25b"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klawdyo%2Fvalidation-br","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klawdyo%2Fvalidation-br/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klawdyo%2Fvalidation-br/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klawdyo%2Fvalidation-br/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/klawdyo","download_url":"https://codeload.github.com/klawdyo/validation-br/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249526,"owners_count":20908212,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["br","brazil","cnh","cnpj","cpf","eleitor","javascript","js","nis","nit","pasep","pis","renavam","titulo","validation"],"created_at":"2024-11-03T07:04:26.524Z","updated_at":"2025-12-25T19:03:31.983Z","avatar_url":"https://github.com/klawdyo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# validation-br\n\n\u003e **A primeira biblioteca a inserir o suporte ao CNPJ alfanumérico**\n\nBiblioteca de validação de documentos pessoais do Brasil com suporte a CPF, CNPJ (numérico e **alfanumérico**), Título Eleitoral, PIS/PASEP, CNH. \n\n`Validation-BR` 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, além de permitir a criação de números fake para facilitar o desenvolvimento e testes, aplicar máscaras e calcular somente os dígitos verificadores.\n\n# Instalação\n\n```sh\n# Usando yarn\nyarn add validation-br\n\n# Usando npm\nnpm install validation-br\n\n```\n\n# Importação\n\n## Importação direta\n\n```js\n// Modules\nconst { isCPF, isCNPJ } = require('validation-br');\n\n// ES6 - Importação a partir do objeto principal\nimport { isCPF, isCNPJ } from 'validation-br';\n```\n\n## Importação de submódulos\n\nImportando os submódulos, é possível criar máscaras, números fake para testes de desenvolvimento e calcular dígitos verificadores.\n\n\u003e As funções dos exemplos abaixo se aplicam a todos os tipos de documentos.\n\n```js\n// Importação direta\nimport { isCPF } from 'validation-br';\nisCPF('01234567890'); // -\u003e true\nisCPF('01234567891'); // -\u003e false\n\n// Importe de submódulos\nimport { dv, fake, mask, validate } from 'validation-br/dist/cpf';\n\n// Calculo do dígito verificador de um CPF. Os métodos aceitam inteiros e strings, inclusive com máscaras.\ndv(906259666); // -\u003e '51'\ndv('906259666'); // -\u003e '51'\ndv('906.259.666'); // -\u003e '51'\n\n// Cria um número fake de CPF para fins de testes.\nfake(); // -\u003e 90625966651\n// Passe um parâmetro true para gerar o número com máscara\nfake(true); // -\u003e 906.259.666-51\n\n// Aplique uma máscara a um cpf\nmask(90625966651); // -\u003e 906.259.666-51\n\n// Normalize o número do documento\nnormalize('906.259.666-51'); // -\u003e 90625966651\n\n// Valida um número e retorna exceção se a validação falhar\nvalidateOrFail('01234567890'); // -\u003e true\n```\n\n## Tabela de Conteúdo\n\n### Funções de Validação\n\n- [CNH](#cnh) - Validação do CNH\n- [CPF](#cpf) - Validação do CPF\n- [CNPJ](#cnpj) - Validação do CNPJ\n- [NUP-17](#nup-17) - Validação de Número Unificado de Protocolo do Governo Federal\n- [Processo Judicial](#processos-judiciais) - Validação de Números de Processos Judiciais\n- [PIS](#pis) - Validação de PIS, PASEP, NIS e NIT\n- [Código de Rastreamento Postal](#código-de-rastreamento-postal-dos-correios) - Validação de Objetos Registrados dos Correios\n- [Renavam](#renavam) - Validação de RENAVAM\n- [Titulo de Eleitor](#título-de-eleitor) - Validação do Título de Eleitor\n\n## Usando em outras bibliotecas de validação\n\n`Validation-BR` pode ser utilizado em conjunto com quaisquer bibliotecas de validação que permita estender seus métodos.\nAbaixo seguem alguns exemplos. Sinta-se convidado a adicionar a sua biblioteca favorita em nosso wiki.\n\n- [Vuelidate](https://github.com/klawdyo/validation-br/wiki/Vuelidate) - Usado para validação de estado no vuejs\n- [Class-Validator](https://github.com/klawdyo/validation-br/wiki/ClassValidator) - Usado em nest, typeorm E mais uma infinidade de frameworks\n- [Indicative](https://github.com/klawdyo/validation-br/wiki/Indicative) - Indicative é a biblioteca padrão de validação usada no Adonis.\n- [Joi](https://github.com/klawdyo/validation-br/wiki/Joi) - Joi é um validador de esquemas usado em aplicações node, react, vue etc.\n- [Yup](https://github.com/klawdyo/validation-br/wiki/Yup) - Yup é usado para validar estado em aplicações react.\n\n## CNH\n\nValida o documento da carteira nacional de habilitação.\n\n```js\n// Importação direta\nimport { isCNH } from 'validation-br';\nisCNH('69044271146'); //-\u003e true\nisCNH('62472927637'); //-\u003e true\nisCNH('46190476839'); //-\u003e false\n\n// Importação do submódulo\nimport { validate, mask, normalize, fake, dv } from 'validation-br/dist/cnh';\n\n// Valida\nvalidate('624729276-37'); //-\u003e true\nvalidateOrFail('62472927637'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 62472927637\nfake(true); // -\u003e 624729276-37\n\n// Aplica uma máscara\nmask('62472927637'); // -\u003e 624729276-37\n\n// Normalize o número do documento\nnormalize('624729276-37'); // -\u003e 62472927637\n\n// Calcula o DV\ndv('624729276'); // -\u003e '37'\n```\n\n## CNPJ\n\nValida um CNPJ **numérico** e **alfanumérico**.\n\n\u003e **Primeira biblioteca a inserir o suporte ao CNPJ alfanumérico.**\n\u003e\n\u003e A partir da [Nota Técnica conjunta COCAD/SUARA/RFB nº 49 de 14 de maio de 2024](https://github.com/user-attachments/files/15851229/Nota.COCAD.SUARA.2024.05.49.CNPJ.Alfanumerico-1.pdf), os números de CNPJ poderão ser alfanuméricos. A alteração entra em uso em 2026.\n\n```js\n// Importação direta\nimport { isCNPJ } from 'validation-br';\nisCNPJ('73.797.980/0001-79'); //-\u003e true\nisCNPJ('55585709000198'); //-\u003e true\nisCNPJ('99362238000180'); //-\u003e false\n\n// ou\n// Importação do submódulo\nimport { validate, mask, dv, normalize, fake, validateOrFail } from 'validation-br/dist/cnpj';\n\n// Valida\n\nvalidate('99362238000180'); //-\u003e true\nvalidateOrFail('99362238000180'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 55585709000198\nfake(true); // -\u003e 55.585.709/0001-98\nfake({ withMask: true }); // -\u003e 55.585.709/0001-98\nfake({ withMask: true, alphanumeric: true }); // -\u003e A1.222.333/0001-50\nfake({ withMask: false, alphanumeric: true }); // -\u003e A1222333/0001-50\n\n// Aplica uma máscara\nmask('99362238000180'); // -\u003e 99.362.238/0001-80\n\n// Normalize o número do documento\nnormalize('99.362.238/0001-80'); // -\u003e 99362238000180\n\n// Calcula o DV\ndv('993622380001'); // -\u003e '80'\n```\n\n## CPF\n\nValida um CPF\n\n```js\n// Importação direta\nimport { isCPF } from 'validation-br';\nisCPF('01234567890'); //-\u003e true\nisCPF('012.345.678-90'); //-\u003e true\nisCPF('01234567891'); //-\u003e false\n\n// ou\n// Importação do submódulo\nimport { validate, mask, dv, normalize, fake, validateOrFail } from 'validation-br/dist/cpf';\n\n// Valida\nvalidate('01234567890'); //-\u003e true\nvalidateOrFail('01234567890'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 01234567891\nfake(true); // -\u003e 012.345.678-91\n\n// Aplica uma máscara\nmask('01234567890'); // -\u003e 012.345.678-90\n\n// Normalize o número do documento\nnormalize('012.345.678-90'); // -\u003e 01234567890\n\n// Calcula o DV\ndv('012345678'); // -\u003e '90'\n```\n\n## Processos Judiciais\n\nValida 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.\n\nO número é composto por 6 partes:\n\n1. Número sequencial dado pelo órgão de registro, reiniciado a cada ano, com até 7 caracteres\n2. Dígito verificador com 2 caracteres\n3. Ano de registro com 4 caracteres\n4. Órgão do poder judiciário com 1 caractere, sendo eles:\n\n   - 1 - Supremo Tribunal Federal\n   - 2 - Conselho Nacional de Justiça\n   - 3 - Superior Tribunal de Justiça\n   - 4 - Justiça Federal\n   - 5 - Justiça do Trabalho\n   - 6 - Justiça Eleitoral\n   - 7 - Justiça Militar da União\n   - 8 - Justiça dos Estados e do Distrito Federal e Territórios\n   - 9 - Justiça Militar Estadual\n\n5. Tribunal do segmento do poder judiciário com 2 caracteres\n6. Código da unidade de origem do processo com 4 caracteres\n\n```js\n// Importação direta\nimport { isJudicialProcess } from 'validation-br';\nisJudicialProcess('20802520125150049'); //-\u003e true\nisJudicialProcess('0011006-07.2016.8.20.0100'); //-\u003e true\nisJudicialProcess('00110060720168200101'); //-\u003e false\n\n// Importação do submódulo\nimport {\n  validate,\n  mask,\n  dv,\n  normalize,\n  fake,\n  validateOrFail,\n} from 'validation-br/dist/judicialProcess';\n\nvalidate('00110060720168200100'); //-\u003e true\nvalidateOrFail('00110060720168200100'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 00110060720168200100\nfake(true); // -\u003e 0011006-07.2016.8.20.0100\n\n// Aplica uma máscara\nmask('00110060720168200100'); // -\u003e 0011006-07.2016.8.20.0100\n\n// Normalize o número do documento\nnormalize('0011006-07.2016.8.20.0100'); // -\u003e 00110060720168200100\n\n// Calcula o DV.\n// 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.\ndv('001100620168200100'); // -\u003e '07'\n```\n\n## NUP-17\n\nVá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.\n\n1. Os primeiros 5 dígitos correspondem código do órgão\n2. 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\n3. Os dígitos 12 a 15 representam o ano de registro do protocolo\n4. Os caracteres 16 a 17 são o dígito verificador\n\n```js\n// Importação direta\nimport { isNUP17 } from 'validation-br';\nisNUP17('23037001462202165'); //-\u003e true\nisNUP17('23037.001462/2021-65'); //-\u003e true\nisNUP17('23037.001462/2021-66'); //-\u003e false\n\n// ou\n// Importação do submódulo\nimport { validate, mask, dv, normalize, fake, validateOrFail } from 'validation-br/dist/nup17';\n\n// Valida\nvalidate('23037.001462/2021-65'); //-\u003e true\nvalidateOrFail('23037.001462/2021-65'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 23037001462202165\nfake(true); // -\u003e 23037.001462/2021-65\n\n// Aplica uma máscara\nmask('23037001462202165'); // -\u003e 23037.001462/2021-65\n\n// Normalize o número do documento\nnormalize('23037.001462/2021-65'); // -\u003e 23037001462202165\n\n// Calcula o DV\ndv('230370014622021'); // -\u003e '65'\n```\n\n## PIS\n\nValida códigos PIS, PASEP, NIS e NIT, que usam o mesmo algoritmo. Aceita números com e sem pontos e traços.\n\n```js\n// Importação direta\nimport { isPIS } from 'validation-br';\nisPIS('71282677380'); //-\u003e true\nisPIS('237.95126.95-5'); //-\u003e true\nisPIS('500.12973.80-1'); //-\u003e false\n\n// ou\n// Importação do submódulo\nimport { validate, mask, dv, normalize, fake, validateOrFail } from 'validation-br/dist/pisPasep';\n\n// Valida\nvalidate('71282677380'); //-\u003e true\nvalidateOrFail('71282677380'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 71282677380\nfake(true); // -\u003e 712.82677.38-0\n\n// Normalize o número do documento\nnormalize('712.82677.38-0'); // -\u003e 71282677380\n\n// Aplica uma máscara\nmask('71282677380'); // -\u003e 712.82677.38-0\n\n// Calcula o DV\ndv('7128267738'); // -\u003e '0'\n```\n\n## Código de Rastreamento Postal dos Correios\n\nValida um código de rastreamento de objetos postais no formato XX00000000DYY, onde:\n\n- XX: O código do objeto postal com 2 dígitos;\n- 00000000: Número sequencial do objeto com 8 dígitos;\n- D: Dígito Verificador\n- YY: País de origem do objeto com 2 dígitos.\n\n```js\n// Importação direta\nimport { isPostalCode } from 'validation-br';\nisPostalCode('PN718252423BR'); //-\u003e true\nisPostalCode('RY728187035CN'); //-\u003e true\nisPostalCode('JT194624698BR'); //-\u003e false\n\n// ou\n// Importação do submódulo\nimport { validate, mask, dv, normalize, fake, validateOrFail } from 'validation-br/dist/postalCode';\n\n// Valida\nvalidate('PN718252423BR'); //-\u003e true\nvalidateOrFail('PN718252423BR'); //-\u003e true\n\n// Número fake com e sem máscara.\nfake(); // -\u003e PN718252423BR\nfake(true); // -\u003e PN718252423BR\n\n// Aplica uma máscara\n// No caso de PostalCode, a máscara apenas coloca as letras em maiúsculas, servindo como normalização\nmask('pn718252423br'); // -\u003e PN718252423BR\n\n// Normalize o número do documento\nnormalize('pn718252423br'); // -\u003e PN718252423BR\n\n// Calcula o DV\ndv('PN718252423BR'); // -\u003e '3'\n```\n\n## RENAVAM\n\nValida o número de um RENAVAM de 11 dígitos\n\n```js\n// Importação direta\nimport { isRenavam } from 'validation-br';\nisRenavam('14283256656'); //-\u003e true\nisRenavam('95059845976'); //-\u003e true\nisRenavam('67747331626'); //-\u003e false\n\n// ou\n// Importação do submódulo\nimport { validate, mask, dv, normalize, fake, validateOrFail } from 'validation-br/dist/renavam';\n\n// Valida\nvalidate('95059845976'); //-\u003e true\nvalidateOrFail('95059845976'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 95059845976\nfake(true); // -\u003e 9505984597-6\n\n// Normaliza o número do documento\nnormalize('9505984597-6'); // -\u003e 95059845976\n\n// Aplica uma máscara\nmask('95059845976'); // -\u003e 9505984597-6\n\n// Calcula o DV\ndv('950598459'); // -\u003e '76'\n```\n\n## Título de Eleitor\n\nValida um título eleitoral\n\n```js\n// Importação direta\nimport { isTituloEleitor } from 'validation-br';\nisTituloEleitor('743650641660'); //-\u003e true\nisTituloEleitor('525028881694'); //-\u003e true\nisTituloEleitor('153016161686'); //-\u003e false\n\n// Importação do submódulo\nimport {\n  validate,\n  mask,\n  dv,\n  normalize,\n  fake,\n  validateOrFail,\n} from 'validation-br/dist/tituloEleitor';\n\n// Valida\nvalidate('01234567890'); //-\u003e true\nvalidateOrFail('01234567890'); //-\u003e true\n\n// Número fake com e sem máscara\nfake(); // -\u003e 153016161686\nfake(true); // -\u003e 1530.1616.1686\n\n// Normalize o número do documento\nnormalize('1530.1616.1686'); // -\u003e 153016161686\n\n// Aplica uma máscara\nmask('525028881694'); // -\u003e 5250.2888.1694\n\n// Calcula o DV\ndv('5250288816'); // -\u003e '94'\n```\n\n# Testes\n\nTodos os testes passando com 100% de cobertura\n\n![Testes passando com 100% de cobertura](https://github.com/user-attachments/assets/195a6acb-3a8a-4370-b503-184b8240fe66)\n\n# Github Actions\n\nGithub actions executados nas versões 18, 20 e 22 do Node.\n\n![Github actions executados nas versões 18, 20 e 22 do Node](https://github.com/user-attachments/assets/72799ba2-757c-497a-b958-b2de948fd666)\n\n# Changelog\n\n- **25/12/2025**:\n  - 1.6.0\n    - Incluída a função normalize() que retorna o valor normalizado, somente números (ou letras maiúsculas quando couber).\n- **16/12/2023**:\n  - 1.5.0\n    - CNPJ alfanumérico\n    - Removidos github actions dos node 12, 14 e 16 e acrescentado o 22\n- **16/12/2023**:\n  - 1.4.5\n    - Corrige o caminho da definição dos types. (Thanks @ishigami)\n- **30/12/2022**:\n  - 1.4.4\n    - Correção de bug quando o documento válido tinha caracteres adicionais\n    - Refatoração de `clearValue()` para comportar configurações opcionais\n- **01/10/2022**:\n  - 1.4.1\n    - Correção na importação principal dos módulos\n    - Refatoração do isJudicialProcess para permitir 100% de cobertura dos testes\n    - Inclusão de mais testes unitários para atingir 100% de cobertura\n- **10/01/2022**:\n  - 1.1.0 - Adicionado NUP17 - Número Unificado de Protocolo de 17 dígitos do Governo Federal\n- **09/01/2022**:\n  - 1.0.0 - Biblioteca convertida para Typescript e testes convertidos para Jest\n- **08/01/2022**:\n  - 0.21.1 - Adicionadas as funções isRenavam e isJudicialProcess\n- **16/09/2021**:\n  - 0.5.0 - Adicionadas as funções isCPF, isCNPJ e isTituloEleitor\n  - 0.7.0 - Adicionadas as funções isPostalCode e isCNH\n  - 0.8.0 - Adicionada a função isPIS\n\n# Referências\n\n- [Cálculo do DV do CPF](http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-cpf/)\n- [Cálculo do DV do CNPJ](http://www.macoratti.net/alg_cnpj.htm)\n- [Cálculo do DV do Título Eleitoral](http://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/)\n- [Cálculo do PIS](http://www.macoratti.net/alg_pis.htm)\n- [Diferença entre PIS, PASEP, NIS e NIT](https://www.jornalcontabil.com.br/entenda-de-uma-vez-a-diferenca-entre-pis-pasep-nit-e-nis/#:~:text=NIS%20%E2%80%93%20N%C3%BAmero%20de%20Identifica%C3%A7%C3%A3o%20Social,do%20Patrim%C3%B4nio%20do%20Servidor%20P%C3%BAblico)\n- [Documentação Oficial de Numeração de Processos Judiciais](https://juslaboris.tst.jus.br/bitstream/handle/20.500.12178/30318/2008_res0065_cnj_rep01.pdf?sequence=2)\n- [Cálculos de DV](http://ghiorzi.org/DVnew.htm)\n- [Cálculo do NUP17](https://www.gov.br/compras/pt-br/acesso-a-informacao/legislacao/portarias/portaria-interministerial-no-11-de-25-de-novembro-de-2019)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklawdyo%2Fvalidation-br","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklawdyo%2Fvalidation-br","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklawdyo%2Fvalidation-br/lists"}