cpf-cnpj-utils

Utility library to validate, format, parse, generate and look up Brazilian CPF and CNPJ values in JavaScript and TypeScript.

Installation

npm install cpf-cnpj-utils

Usage

import {
  formatCPF,
  fetchCNPJ,
  generateCPF,
  generateCNPJ,
  parseDocument,
  validateCPF,
  validateCNPJ,
} from "cpf-cnpj-utils";

validateCPF("529.982.247-25"); // true
validateCNPJ("04.252.011/0001-10"); // true

formatCPF("52998224725"); // "529.982.247-25"
generateCPF(); // "12345678909"
generateCNPJ(); // "12ABC34501DE35" or "04252011000110"

parseDocument("04.252.011/0001-10");
await fetchCNPJ("04.252.011/0001-10");

CommonJS is also supported:

const { validateCPF } = require("cpf-cnpj-utils");

validateCPF("529.982.247-25");

Test Data Generation

Generated values are mathematically valid and intended for tests, fixtures and development environments only. They do not represent issued documents.

By default, generateCNPJ() can return either a numeric or alphanumeric CNPJ. You can control the output:

import { generateCPF, generateCNPJ, generateDocument } from "cpf-cnpj-utils";

generateCPF();
generateCPF({ formatted: true });

generateCNPJ({ alphanumeric: false });
generateCNPJ({ alphanumeric: true });
generateCNPJ({ alphanumeric: true, formatted: true });

generateDocument("CPF");
generateDocument("CNPJ", { alphanumeric: true });

Alphanumeric CNPJ values use A-Z and 0-9 in the first 12 positions, while the last 2 positions remain numeric check digits.

CNPJ Lookup

fetchCNPJ() fetches company data from the public Minha Receita API.

import { fetchCNPJ, lookupCNPJ } from "cpf-cnpj-utils";

const company = await fetchCNPJ("04.252.011/0001-10");

company.cnpj;
company.razao_social;
company.descricao_situacao_cadastral;
company.qsa;
company.cnaes_secundarios;

// Alias:
await lookupCNPJ("04.252.011/0001-10");

The default API base URL is https://minhareceita.org. You can point the client to a self-hosted Minha Receita instance or pass a custom fetch implementation:

await fetchCNPJ("04.252.011/0001-10", {
  baseUrl: "http://localhost:8000",
  timeoutMs: 5000,
});

The public Minha Receita API does not provide an availability SLA. For production workloads or high-volume usage, consider running your own Minha Receita server.

Utilities

import {
  detectDocumentType,
  formatCNPJ,
  formatCPF,
  normalizeDocument,
  parseDocument,
  stripDocument,
  validateDocument,
} from "cpf-cnpj-utils";

stripDocument("04.252.011/0001-10"); // "04252011000110"
normalizeDocument("\u00e1-b.c/123"); // "ABC123"

formatCPF("52998224725"); // "529.982.247-25"
formatCNPJ("04252011000110"); // "04.252.011/0001-10"

detectDocumentType("529.982.247-25"); // "CPF"
validateDocument("04.252.011/0001-10"); // true

parseDocument("12.ABC.345/01DE-35");
// {
//   type: "CNPJ",
//   normalized: "12ABC34501DE35",
//   formatted: "12.ABC.345/01DE-35",
//   valid: true,
//   alphanumeric: true
// }

Validator Classes

import { CPFValidator, CNPJValidator } from "cpf-cnpj-utils";

CPFValidator.validate("52998224725");
CNPJValidator.validate("04252011000110");

API

• validateCPF(cpf: string): boolean
• validateCNPJ(cnpj: string): boolean
• validateDocument(data: string): boolean
• isValidCPF(cpf: string): boolean
• isValidCNPJ(cnpj: string): boolean
• generateCPF(options?: { formatted?: boolean }): string
• generateCNPJ(options?: { formatted?: boolean; alphanumeric?: boolean }): string
• generateDocument(type: "CPF" | "CNPJ" | "cpf" | "cnpj", options?: object): string
• fetchCNPJ(cnpj: string, options?: FetchCNPJOptions): Promise<MinhaReceitaCNPJData>
• lookupCNPJ(cnpj: string, options?: FetchCNPJOptions): Promise<MinhaReceitaCNPJData>
• formatCPF(cpf: string): string
• formatCNPJ(cnpj: string): string
• stripDocument(data: string): string
• normalizeDocument(data: string): string
• detectDocumentType(data: string): "CPF" | "CNPJ" | null
• parseDocument(data: string): ParsedDocument
• CPFValidator.validate(cpf: string): boolean
• CNPJValidator.validate(cnpj: string): boolean

Development

npm install
npm test
npm run pack:check

License

ISC