BrDocuments 1.0.1

BrDocuments

BrDocuments is a fast, zero-dependency .NET library for validating, formatting, and generating Brazilian documents — CPF, CNPJ (including the new alphanumeric format), CEP, PIS/PASEP, CNH, Título de Eleitor, RENAVAM, and Inscrição Estadual.

It targets .NET 10 and .NET Standard 2.0, so it runs on modern .NET as well as older .NET Framework and Xamarin/Unity projects.

Why BrDocuments?

• ⚡ Zero dependencies — nothing else gets pulled into your app.
• 🔤 Alphanumeric CNPJ ready — supports the new format issued from July 2026 (Nota Técnica COCAD/SUARA/RFB nº 49/2024), which most libraries still don't.
• 🧱 Tiny, consistent API — every document is a static class with the same four methods.
• 🧪 Well tested & benchmarked — xUnit test suite plus BenchmarkDotNet benchmarks.
• 🛡️ Safe by default — IsValid never throws; it returns false for null, empty, or malformed input.

Installation

dotnet add package BrDocuments

Quick start

using BrDocuments;

// Validation accepts formatted or unformatted input
Cpf.IsValid("529.982.247-25");   // true
Cpf.IsValid("52998224725");      // true

// Formatting and stripping
Cpf.Format("52998224725");       // "529.982.247-25"
Cpf.Unformat("529.982.247-25");  // "52998224725"

// Generation (valid, random, unformatted)
string cpf = Cpf.Generate();     // e.g. "97987556343"

// The new alphanumeric CNPJ just works
Cnpj.IsValid("12.ABC.345/01DE-35");   // true
Cnpj.Format("12ABC34501DE35");        // "12.ABC.345/01DE-35"

// Inscrição Estadual is validated per state (UF)
InscricaoEstadual.IsValid("314611116426", "SP");

API

Every document (except InscricaoEstadual) exposes the same static surface:

bool   IsValid(string? value);   // accepts formatted or unformatted; never throws
string Format(string value);     // applies the canonical mask
string Unformat(string value);   // strips formatting
string Generate();               // returns a valid, random, unformatted document

InscricaoEstadual is state-specific and exposes:

bool IsValid(string? value, string? state);          // state = "SP", "RJ", ...
IReadOnlyCollection<string> SupportedStates;          // implemented UFs

Supported documents

Alphanumeric CNPJ

From July 2026 the Receita Federal issues CNPJs whose 12-character body may contain letters A–Z in addition to digits; the two trailing check digits remain numeric. BrDocuments validates both the legacy numeric format and the new alphanumeric one with the same Cnpj.IsValid call:

Cnpj.IsValid("04.252.011/0001-10");   // legacy numeric  -> true
Cnpj.IsValid("12.ABC.345/01DE-35");   // alphanumeric    -> true

Cnpj.Generate() produces numeric CNPJs only.

Inscrição Estadual coverage

Version 1.0 implements the ten most commonly required states: SP, RJ, MG, RS, PR, SC, BA, PE, CE, GO. Any other UF currently returns false (see InscricaoEstadual.SupportedStates). Contributions adding the remaining states are very welcome.

Targets

• net10.0
• netstandard2.0

Building & testing

dotnet build -c Release
dotnet test -c Release
dotnet run -c Release --project benchmarks/BrDocuments.Benchmarks

Contributing

Issues and pull requests are welcome — especially additional Inscrição Estadual state algorithms (each one should ship with tests). Please keep the library dependency-free and make sure dotnet build is warning-free and dotnet test is green before opening a PR.

License

MIT