cnpj-val 1.0.0

Utility function to validate CNPJ (Brazilian employer ID)

Utility function/class to validate CNPJ (Brazilian employer ID).

Python Support

Passing ✔	Passing ✔	Passing ✔	Passing ✔	Passing ✔

Installation

$ pip install cnpj-val

Import

# Using class-based resource
from cnpj_val import CnpjValidator

# Or using function-based one
from cnpj_val import cnpj_val

Usage

Object-Oriented Usage

validator = CnpjValidator()
cnpj = '98765432000198'

print('Valid' if validator.is_valid(cnpj) else 'Invalid')  # returns 'Valid'

cnpj = '98.765.432/0001-98'
print('Valid' if validator.is_valid(cnpj) else 'Invalid')  # returns 'Valid'

cnpj = '98765432000199'
print('Valid' if validator.is_valid(cnpj) else 'Invalid')  # returns 'Invalid'

Functional programming

The helper function cnpj_val() is just a functional abstraction. Internally it creates an instance of CnpjValidator and calls the is_valid() method right away.

cnpj = '98765432000198'

print('Valid' if cnpj_val(cnpj) else 'Invalid')      # returns 'Valid'

print('Valid' if cnpj_val('98.765.432/0001-98') else 'Invalid')  # returns 'Valid'

print('Valid' if cnpj_val('98765432000199') else 'Invalid')      # returns 'Invalid'

Validation Examples

# Valid CNPJ numbers
cnpj_val('98765432000198')      # returns True
cnpj_val('98.765.432/0001-98')  # returns True
cnpj_val('03603568000195')      # returns True

# Invalid CNPJ numbers
cnpj_val('98765432000199')      # returns False
cnpj_val('12345678901234')      # returns False
cnpj_val('00000000000000')      # returns False
cnpj_val('11111111111111')      # returns False
cnpj_val('123')                 # returns False (too short)
cnpj_val('')                    # returns False (empty)

Features

• ✅ Format Agnostic: Accepts CNPJ with or without formatting (dots, slashes, dashes)
• ✅ Strict Validation: Validates both check digits according to Brazilian CNPJ algorithm
• ✅ Type Safety: Built with Python 3.10+ type hints
• ✅ Lightweight: Minimal dependencies, only requires cnpj-gen for check digit calculation
• ✅ Dual API: Both object-oriented and functional programming styles supported

API Reference

CnpjValidator Class

is_valid(cnpj_string: str) -> bool

Validates a CNPJ string and returns True if valid, False otherwise.

Parameters:

• cnpj_string (str): The CNPJ to validate (with or without formatting)

Returns:

• bool: True if the CNPJ is valid, False otherwise

cnpj_val() Function

cnpj_val(cnpj_string: str) -> bool

Functional wrapper around CnpjValidator.is_valid().

Parameters:

• cnpj_string (str): The CNPJ to validate (with or without formatting)

Returns:

• bool: True if the CNPJ is valid, False otherwise

Validation Algorithm

The package validates CNPJ using the official Brazilian algorithm:

1. Length Check: Ensures the CNPJ has exactly 14 digits
2. First Check Digit: Calculates and validates the 13th digit
3. Second Check Digit: Calculates and validates the 14th digit
4. Format Tolerance: Automatically strips non-numeric characters before validation

Error Handling

The validator is designed to be forgiving with input format but strict with validation:

• Invalid formats (too short, too long) return False
• Invalid check digits return False
• Empty strings return False
• Non-numeric strings (after stripping formatting) return False

Dependencies

• Python: >= 3.10
• cnpj-gen: >= 1.0.0 (for check digit calculation)

Contribution & Support

We welcome contributions! Please see our Contributing Guidelines for details. But if you find this project helpful, please consider:

• ⭐ Starring the repository
• 🤝 Contributing to the codebase
• 💡 Suggesting new features
• 🐛 Reporting bugs

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG for a list of changes and version history.

---

Made with ❤️ by Lacus Solutions