### Add Elekto.BrazilianDocuments Package

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Install the library using the .NET CLI. This command adds the NuGet package to your project.

```bash
dotnet add package Elekto.BrazilianDocuments
```

--------------------------------

### CNPJ Format Specifiers

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Provides examples of different format specifiers for CNPJ output, including General, Bare, Short, and Bare Small formats.

```csharp
// Example usage (assuming 'cnpj' is a valid Cnpj object)
// Console.WriteLine(cnpj.ToString("G")); // 09.358.105/0001-91
// Console.WriteLine(cnpj.ToString("B")); // 09358105000191
// Console.WriteLine(cnpj.ToString("S")); // 9358105000191
// Console.WriteLine(cnpj.ToString("BS")); // 09358105
```

--------------------------------

### Parse Alphanumeric CNPJ

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Demonstrates parsing both traditional numeric and new alphanumeric CNPJ formats, including examples of "fun" CNPJs.

```csharp
// Traditional numeric CNPJ
var numeric = Cnpj.Parse("09.358.105/0001-91");

// New alphanumeric CNPJ
var alpha = Cnpj.Parse("12.ABC.345/01DE-35");

// "Fun" CNPJs are valid!
var elekto = Cnpj.Create("ELEKTO", "0001");   // 00.ELE.KTO/0001-40
var motto  = Cnpj.Create("BEUNGOVE", "RNBL"); // BE.UNG.OVE/RNBL-36 (Even if doing taxes...)
var molon  = Cnpj.Create("MOLONLAB", "E001"); // MO.LON.LAB/E001-06 (Μολὼν λαβέ)
```

--------------------------------

### Use Parse and TryParse for CPF and CNPJ

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Illustrates the difference between `Parse` (throws on error) and `TryParse` (returns null on error) for both CPF and CNPJ.

```csharp
var cpf = Cpf.Parse("123.456.789-09");
var cnpj = Cnpj.Parse("09.358.105/0001-91");

Cpf? maybeCpf = Cpf.TryParse("123.456.789-09");
Cnpj? maybeCnpj = Cnpj.TryParse("09.358.105/0001-91");
```

--------------------------------

### Create and Convert CPF

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Demonstrates creating a CPF with automatic check digit calculation and converting it to a numeric value.

```csharp
// Create with automatic check digit calculation
var newCpf = Cpf.Create(123456789L);
Console.WriteLine(newCpf.ToString("G")); // 123.456.789-09

// Convert to numeric value
long value = cpf.ToLong(); // 12345678909
```

--------------------------------

### Parsing Helpers: Parse vs. TryParse

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Explains the difference between `Parse` (throws on error) and `TryParse` (returns null on error) methods.

```APIDOC
## Parsing Helpers

Use `Parse` for throwing behavior and `TryParse` for non-throwing behavior:

```csharp
var cpf = Cpf.Parse("123.456.789-09");
var cnpj = Cnpj.Parse("09.358.105/0001-91");

Cpf? maybeCpf = Cpf.TryParse("123.456.789-09");
Cnpj? maybeCnpj = Cnpj.TryParse("09.358.105/0001-91");
```
```

--------------------------------

### Create and Access CNPJ Parts

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Shows how to create a CNPJ with automatic check digit calculation and how to access its root, branch, and check digits.

```csharp
// Create with automatic check digit calculation
var newCnpj = Cnpj.Create("ELEKTO", "0001");
Console.WriteLine(newCnpj.ToString("B")); // 00ELEKTO000140

// Create from 12-character base (root + branch)
var cnpjFromBase = Cnpj.Create("ELEKTO0001");

// Access parts
Console.WriteLine(cnpj.Root);        // First 8 characters
Console.WriteLine(cnpj.Branch);      // Characters 9-12 (branch/order)
Console.WriteLine(cnpj.CheckDigits); // Last 2 characters
```

--------------------------------

### Parse and Validate CNPJ

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Demonstrates parsing CNPJ from various string formats, validating its correctness, and safe parsing with `TryParse`.

```csharp
using Elekto.BrazilianDocuments;

// Parse from string (various formats accepted)
var cnpj = Cnpj.Parse("12.ABC.345/01DE-35");

// Validate without throwing
if (Cnpj.IsValid("00.ELE.KTO/0001-40"))
{
    Console.WriteLine("Valid!");
}

// Safe parsing
if (Cnpj.TryParse("ELEKTO000140", out var parsed))
{
    Console.WriteLine(parsed.ToString("G")); // 00.ELE.KTO/0001-40
}
```

--------------------------------

### Parse and Validate CPF

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Illustrates parsing CPF from both string and numeric inputs, and validating its correctness.

```csharp
using Elekto.BrazilianDocuments;

// Parse from string
var cpf = Cpf.Parse("123.456.789-09");

// Parse from number
var cpf2 = Cpf.Parse(12345678909L);

// Validate
if (Cpf.IsValid("123.456.789-09"))
{
    Console.WriteLine("Valid!");
}
```

--------------------------------

### CPF Parsing and Validation

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Shows how to parse CPF strings and numbers, validate them, and create new CPF instances.

```APIDOC
## CPF (Individual Registration Number)

```csharp
using Elekto.BrazilianDocuments;

// Parse from string
var cpf = Cpf.Parse("123.456.789-09");

// Parse from number
var cpf2 = Cpf.Parse(12345678909L);

// Validate
if (Cpf.IsValid("123.456.789-09"))
{
    Console.WriteLine("Valid!");
}

// Create with automatic check digit calculation
var newCpf = Cpf.Create(123456789L);
Console.WriteLine(newCpf.ToString("G")); // 123.456.789-09

// Convert to numeric value
long value = cpf.ToLong(); // 12345678909
```
```

--------------------------------

### CNPJ Parsing and Validation

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Demonstrates how to parse CNPJ strings in various formats, validate their correctness, and create new CNPJ instances.

```APIDOC
## CNPJ (Company Registration Number)

```csharp
using Elekto.BrazilianDocuments;

// Parse from string (various formats accepted)
var cnpj = Cnpj.Parse("12.ABC.345/01DE-35");

// Validate without throwing
if (Cnpj.IsValid("00.ELE.KTO/0001-40"))
{
    Console.WriteLine("Valid!");
}

// Safe parsing
if (Cnpj.TryParse("ELEKTO000140", out var parsed))
{
    Console.WriteLine(parsed.ToString("G")); // 00.ELE.KTO/0001-40
}

// Create with automatic check digit calculation
var newCnpj = Cnpj.Create("ELEKTO", "0001");
Console.WriteLine(newCnpj.ToString("B")); // 00ELEKTO000140

// Create from 12-character base (root + branch)
var cnpjFromBase = Cnpj.Create("ELEKTO0001");

// Access parts
Console.WriteLine(cnpj.Root);        // First 8 characters
Console.WriteLine(cnpj.Branch);      // Characters 9-12 (branch/order)
Console.WriteLine(cnpj.CheckDigits); // Last 2 characters
```
```

--------------------------------

### JSON Serialization

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Shows how to use the built-in JSON converters for `Cpf` and `Cnpj` types.

```APIDOC
## JSON Serialization

Both types include built-in JSON converters:

```csharp
var company = new Company
{
    Name = "Elekto",
    Cnpj = Cnpj.Parse("09.358.105/0001-91")
};

var json = JsonSerializer.Serialize(company);
// {"Name":"Elekto","Cnpj":"09.358.105/0001-91"}

var deserialized = JsonSerializer.Deserialize<Company>(json);
```
```

--------------------------------

### CPF Format Specifiers

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Shows the available format specifiers for CPF output, namely General, Bare, and Short formats.

```csharp
// Example usage (assuming 'cpf' is a valid Cpf object)
// Console.WriteLine(cpf.ToString("G")); // 123.456.789-09
// Console.WriteLine(cpf.ToString("B")); // 12345678909
// Console.WriteLine(cpf.ToString("S")); // 12345678909
```

--------------------------------

### Error Handling with BadDocumentException

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Illustrates how to catch `BadDocumentException` for invalid CPF and CNPJ inputs.

```APIDOC
## Error Handling

When parsing or constructing invalid documents, the library throws a unified exception:

- BadDocumentException: for both CPF and CNPJ invalid inputs
- DocumentType: indicates which document triggered the exception (Cpf, Cnpj, Unknown)

```csharp
try
{
    var cpf = Cpf.Parse("invalid");
}
catch (BadDocumentException ex) when (ex.SourceType == DocumentType.Cpf)
{
    Console.WriteLine(ex.Message);
    Console.WriteLine(ex.InvalidDocument);
}

try
{
    var cnpj = Cnpj.Parse("invalid");
}
catch (BadDocumentException ex) when (ex.SourceType == DocumentType.Cnpj)
{
    Console.WriteLine(ex.Message);
}
```
```

--------------------------------

### Handle BadDocumentException for CPF

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Shows how to catch `BadDocumentException` specifically for invalid CPF inputs using a `try-catch` block.

```csharp
try
{
    var cpf = Cpf.Parse("invalid");
}
catch (BadDocumentException ex) when (ex.SourceType == DocumentType.Cpf)
{
    Console.WriteLine(ex.Message);
    Console.WriteLine(ex.InvalidDocument);
}
```

--------------------------------

### JSON Serialization of CNPJ

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Demonstrates how to serialize and deserialize a `Company` object containing a `Cnpj` property using `System.Text.Json`.

```csharp
public class Company
{
    public string Name { get; set; }
    public Cnpj Cnpj { get; set; }
}

var company = new Company
{
    Name = "Elekto",
    Cnpj = Cnpj.Parse("09.358.105/0001-91")
};

var json = JsonSerializer.Serialize(company);
// {"Name":"Elekto","Cnpj":"09.358.105/0001-91"}

var deserialized = JsonSerializer.Deserialize<Company>(json);
```

--------------------------------

### TryParse Method

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Attempts to parse a document string into either a CPF or CNPJ object. It returns the detected DocumentType and populates the corresponding out-parameter.

```APIDOC
## TryParse

### Description
Attempts to parse a document string into either a CPF or CNPJ object. It returns the detected DocumentType and populates the corresponding out-parameter. The other out-parameter will be set to its default value.

### Method Signature
`DocumentType TryParse(string input, out Cpf cpf, out Cnpj cnpj)`

### Parameters
- **input** (string) - The document string to parse.
- **cpf** (out Cpf) - Output parameter for the parsed CPF object if the input is a valid CPF.
- **cnpj** (out Cnpj) - Output parameter for the parsed CNPJ object if the input is a valid CNPJ.

### Return Value
- **DocumentType**: The type of document successfully parsed (DocumentType.Cpf or DocumentType.Cnpj). Returns DocumentType.Unknown if the input is invalid or ambiguous.

### Examples
```csharp
var found = BrazilianDocument.TryParse(input, out Cpf cpf, out Cnpj cnpj);

switch (found)
{
    case DocumentType.Cpf:
        HandleCpf(cpf);
        break;
    case DocumentType.Cnpj:
        HandleCnpj(cnpj);
        break;
    case DocumentType.Unknown:
        // Handle invalid or ambiguous input
        break;
}
```
```

--------------------------------

### Handle BadDocumentException for CNPJ

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Illustrates catching `BadDocumentException` for invalid CNPJ inputs, accessing the error message and invalid document.

```csharp
try
{
    var cnpj = Cnpj.Parse("invalid");
}
catch (BadDocumentException ex) when (ex.SourceType == DocumentType.Cnpj)
{
    Console.WriteLine(ex.Message);
}
```

--------------------------------

### Strict Document Parsing

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Use `Parse` for strict validation. It throws a `BadDocumentException` if the input is invalid or ambiguous. Provide a `DocumentType` hint to resolve ambiguity if necessary.

```csharp
// Resolves unambiguously or throws
var found = BrazilianDocument.Parse(input, out Cpf cpf, out Cnpj cnpj);

// If ambiguous, pass a hint to resolve — throws if still invalid
var found = BrazilianDocument.Parse(input, out cpf, out cnpj, DocumentType.Cpf);
```

--------------------------------

### Parse Document with Type Discrimination

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Use `TryParse` to attempt parsing a document string into either a CPF or CNPJ object. The return value indicates which type was successfully parsed, allowing for type-specific handling.

```csharp
var found = BrazilianDocument.TryParse(input, out Cpf cpf, out Cnpj cnpj);

switch (found)
{
    case DocumentType.Cpf:     HandleCpf(cpf);   break;
    case DocumentType.Cnpj:    HandleCnpj(cnpj); break;
    case DocumentType.Unknown: // invalid or ambiguous — ask the user
                               break;
}
```

--------------------------------

### Alphanumeric CNPJ Support

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Demonstrates the library's support for the new alphanumeric CNPJ format.

```APIDOC
## Alphanumeric CNPJ

Starting in 2026, the Brazilian Federal Revenue Service will issue alphanumeric CNPJs. This library fully supports the new format:

```csharp
// Traditional numeric CNPJ
var numeric = Cnpj.Parse("09.358.105/0001-91");

// New alphanumeric CNPJ
var alpha = Cnpj.Parse("12.ABC.345/01DE-35");

// "Fun" CNPJs are valid!
var elekto = Cnpj.Create("ELEKTO", "0001");   // 00.ELE.KTO/0001-40
var motto  = Cnpj.Create("BEUNGOVE", "RNBL"); // BE.UNG.OVE/RNBL-36 (Even if doing taxes...)
var molon  = Cnpj.Create("MOLONLAB", "E001"); // MO.LON.LAB/E001-06 (Μολὼν λαβέ)
```

The validation algorithm correctly handles:
- Mixed alphanumeric characters (A-Z, 0-9)
- Case-insensitive input
- Leading zero omission (e.g., `1/0001-36` is valid)
- Various punctuation formats
```

--------------------------------

### Check Document Validity and Type

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Use `IsValid` to determine if a string is a valid CPF or CNPJ and to identify its type. For ambiguous inputs, provide a `DocumentType` hint to resolve the type; otherwise, it returns false.

```csharp
var (ok, type) = BrazilianDocument.IsValid("123.456.789-09");
// ok=true, type=DocumentType.Cpf

var (ok, type) = BrazilianDocument.IsValid("09.358.105/0001-91");
// ok=true, type=DocumentType.Cnpj

// Ambiguous — must supply a hint
var (ok, type) = BrazilianDocument.IsValid("00970938900");
// ok=false, type=DocumentType.Unknown  ← caller must decide

var (ok, type) = BrazilianDocument.IsValid("00970938900", DocumentType.Cpf);
// ok=true, type=DocumentType.Cpf       ← CPF wins
```

--------------------------------

### Parse Method

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Parses a document string into either a CPF or CNPJ object. Throws a BadDocumentException on failure or ambiguity. An optional hint can be provided to resolve ambiguity.

```APIDOC
## Parse

### Description
Parses a document string into either a CPF or CNPJ object. Throws a BadDocumentException on failure or ambiguity. An optional hint can be provided to resolve ambiguity.

### Method Signature
`DocumentType Parse(string input, out Cpf cpf, out Cnpj cnpj, DocumentType hint = DocumentType.Unknown)`

### Parameters
- **input** (string) - The document string to parse.
- **cpf** (out Cpf) - Output parameter for the parsed CPF object if the input is a valid CPF.
- **cnpj** (out Cnpj) - Output parameter for the parsed CNPJ object if the input is a valid CNPJ.
- **hint** (DocumentType) - Optional. The preferred document type to attempt first (DocumentType.Cpf or DocumentType.Cnpj). Defaults to DocumentType.Unknown.

### Return Value
- **DocumentType**: The type of document successfully parsed (DocumentType.Cpf or DocumentType.Cnpj).

### Throws
- **BadDocumentException**: If the input is invalid or ambiguous and cannot be resolved by the provided hint.

### Examples
```csharp
// Resolves unambiguously or throws
var found = BrazilianDocument.Parse(input, out Cpf cpf, out Cnpj cnpj);

// If ambiguous, pass a hint to resolve — throws if still invalid
var found = BrazilianDocument.Parse(input, out cpf, out cnpj, DocumentType.Cpf);
```
```

--------------------------------

### Ambiguous Input Handling with BrazilianDocument

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Introduces `BrazilianDocument` for handling cases where a single field might contain either a CPF or a CNPJ.

```APIDOC
## Ambiguous Input

Some systems use a single field to hold either a CPF or a CNPJ — think of a generic "document number"
column in a database or a free-text form field. `BrazilianDocument` is the helper for that scenario.

### Why ambiguity can occur

A CPF is an 11-digit number, while a numeric CNPJ has 14 digits. They are almost always distinct.
However, because `Cnpj` supports leading-zero omission, an 11-character string can be valid as *both*
a CPF **and** as a CNPJ with three implied leading zeros — e.g. `"00970938900"` is simultaneously a
valid CPF and a valid CNPJ (interpreted as `00009709389​00`). This is rare, but real.
```

--------------------------------

### CPF Format Specifiers

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Details the available format specifiers for displaying CPF numbers.

```APIDOC
### CPF Formats

| Format | Description | Example |
|--------|-------------|---------|
| `"G"` | General (with punctuation) | `123.456.789-09` |
| `"B"` | Bare (11 digits) | `12345678909` |
| `"S"` | Short (no leading zeros) | `12345678909` |
```

--------------------------------

### IsValid Method

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Checks if a given string is a valid CPF or CNPJ. It returns a boolean indicating validity and the detected DocumentType. An optional hint can be provided to prioritize checking either CPF or CNPJ.

```APIDOC
## IsValid

### Description
Checks if a given string is a valid CPF or CNPJ. It returns a boolean indicating validity and the detected DocumentType. An optional hint can be provided to prioritize checking either CPF or CNPJ.

### Method Signature
`(bool IsValid, DocumentType Type) IsValid(string input, DocumentType hint = DocumentType.Unknown)`

### Parameters
- **input** (string) - The document string to validate.
- **hint** (DocumentType) - Optional. The preferred document type to attempt first (DocumentType.Cpf or DocumentType.Cnpj). Defaults to DocumentType.Unknown, which tries both.

### Return Value
A tuple containing:
- **IsValid** (bool): True if the input is a valid document of the determined type, false otherwise.
- **Type** (DocumentType): The type of document detected (DocumentType.Cpf, DocumentType.Cnpj, or DocumentType.Unknown).

### Examples
```csharp
// Unambiguous validation
var (ok, type) = BrazilianDocument.IsValid("123.456.789-09");
// ok=true, type=DocumentType.Cpf

var (ok, type) = BrazilianDocument.IsValid("09.358.105/0001-91");
// ok=true, type=DocumentType.Cnpj

// Ambiguous validation without hint (fails)
var (ok, type) = BrazilianDocument.IsValid("00970938900");
// ok=false, type=DocumentType.Unknown

// Ambiguous validation with hint (succeeds)
var (ok, type) = BrazilianDocument.IsValid("00970938900", DocumentType.Cpf);
// ok=true, type=DocumentType.Cpf
```
```

--------------------------------

### CNPJ Format Specifiers

Source: https://github.com/elekto-com-br/cnpj-cpf/blob/master/README.md

Details the available format specifiers for displaying CNPJ numbers.

```APIDOC
## Format Specifiers

### CNPJ Formats

| Format | Description | Example |
|--------|-------------|---------|
| `"G"` | General (with punctuation) | `09.358.105/0001-91` |
| `"B"` | Bare (14 chars, no punctuation) | `09358105000191` |
| `"S"` | Short (no leading zeros) | `9358105000191` |
| `"BS"` | Bare Small (root only) | `09358105` |
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.