🇧🇷 Brazilian Utils

Biblioteca de utilitários para dados específicos do Brasil / Utils library for Brazilian-specific data

🇧🇷 Português | 🇺🇸 English

---

Português

📋 Recursos

Utilitários para trabalhar com formatos de dados brasileiros:

• CPF - Validação, formatação e geração
• CNH - Validação de Carteira Nacional de Habilitação
• CNPJ - Validação, formatação e geração
• CEP - Validação, formatação e busca via API ViaCEP
• Moeda - Formatação de Real (R$) e conversão para extenso
• Data - Verificação de feriados e conversão para texto
• Email - Validação (RFC 5322)
• Natureza Jurídica - Validação de códigos oficiais
• Processos Judiciais - Validação, formatação e geração
• Placas de Veículos - Validação e conversão (antigo/Mercosul)
• Telefone - Validação e formatação (móvel/fixo)
• PIS - Validação, formatação e geração (PIS/PASEP)
• RENAVAM - Validação de registro de veículos
• Título de Eleitor - Validação, formatação e geração

💾 Instalação

gem 'brazilian-utils'

bundle install

🚀 Uso Rápido

# CPF
require 'brazilian-utils/cpf-utils'
BrazilianUtils::CPFUtils.is_valid('11144477735')  # => true
BrazilianUtils::CPFUtils.format_cpf('11144477735')  # => "111.444.777-35"
BrazilianUtils::CPFUtils.generate  # => "12345678901"

# CNPJ
require 'brazilian-utils/cnpj-utils'
BrazilianUtils::CNPJUtils.is_valid('34665388000161')  # => true
BrazilianUtils::CNPJUtils.format_cnpj('34665388000161')  # => "34.665.388/0001-61"

# CEP
require 'brazilian-utils/cep-utils'
BrazilianUtils::CEPUtils.format_cep('01310100')  # => "01310-100"
BrazilianUtils::CEPUtils.get_address('01310100')  # => {...endereço completo...}

# Telefone
require 'brazilian-utils/phone-utils'
BrazilianUtils::PhoneUtils.is_valid('11987654321')  # => true
BrazilianUtils::PhoneUtils.format('11987654321')  # => "(11)98765-4321"

# Placa de Veículo
require 'brazilian-utils/license-plate-utils'
BrazilianUtils::LicensePlateUtils.is_valid('ABC1234')  # => true
BrazilianUtils::LicensePlateUtils.convert_to_mercosul('ABC1234')  # => "ABC1C34"

# Título de Eleitor
require 'brazilian-utils/voter-id-utils'
BrazilianUtils::VoterIdUtils.is_valid_voter_id('690847092828')  # => true
BrazilianUtils::VoterIdUtils.format('690847092828')  # => "6908 4709 28 28"
BrazilianUtils::VoterIdUtils.generate('SP')  # => "123456780140"

# Moeda
require 'brazilian-utils/currency-utils'
BrazilianUtils::CurrencyUtils.format_currency(1234.56)  # => "R$ 1.234,56"
BrazilianUtils::CurrencyUtils.number_to_text(1234.56)  # => "mil duzentos e trinta e quatro reais..."

📚 Documentação Detalhada

Para exemplos completos de cada utilitário, consulte a pasta examples/.

Principais Módulos:

• CPFUtils - Validação e formatação de CPF
• CNPJUtils - Validação e formatação de CNPJ
• CEPUtils - Validação de CEP e busca de endereços
• PhoneUtils - Validação de telefones
• LicensePlateUtils - Placas de veículos
• VoterIdUtils - Títulos de eleitor
• CurrencyUtils - Formatação de moeda
• DateUtils - Feriados e datas por extenso
• EmailUtils - Validação de email
• LegalNatureUtils - Natureza jurídica
• LegalProcessUtils - Processos judiciais
• PISUtils - PIS/PASEP
• RENAVAMUtils - RENAVAM
• CNHUtils - CNH

---

English

📋 Features

Utilities for working with Brazilian data formats:

• CPF - Validation, formatting, and generation
• CNH - Driver's license validation
• CNPJ - Company tax ID validation, formatting, and generation
• CEP - Postal code validation, formatting, and address lookup (ViaCEP API)
• Currency - Brazilian Real (R$) formatting and text conversion
• Date - Holiday checking and date-to-text conversion
• Email - Email validation (RFC 5322)
• Legal Nature - Official business entity code validation
• Legal Process - Judicial process ID validation, formatting, and generation
• License Plate - Vehicle plate validation and format conversion (old/Mercosul)
• Phone - Mobile and landline validation and formatting
• PIS - Social security number validation, formatting, and generation
• RENAVAM - Vehicle registration validation
• Voter ID - Voter registration validation, formatting, and generation

💾 Installation

gem 'brazilian-utils'

bundle install

🚀 Quick Start

# CPF
require 'brazilian-utils/cpf-utils'
BrazilianUtils::CPFUtils.is_valid('11144477735')  # => true
BrazilianUtils::CPFUtils.format_cpf('11144477735')  # => "111.444.777-35"
BrazilianUtils::CPFUtils.generate  # => "12345678901"

# CNPJ
require 'brazilian-utils/cnpj-utils'
BrazilianUtils::CNPJUtils.is_valid('34665388000161')  # => true
BrazilianUtils::CNPJUtils.format_cnpj('34665388000161')  # => "34.665.388/0001-61"

# CEP (Postal Code)
require 'brazilian-utils/cep-utils'
BrazilianUtils::CEPUtils.format_cep('01310100')  # => "01310-100"
BrazilianUtils::CEPUtils.get_address('01310100')  # => {...complete address...}

# Phone
require 'brazilian-utils/phone-utils'
BrazilianUtils::PhoneUtils.is_valid('11987654321')  # => true
BrazilianUtils::PhoneUtils.format('11987654321')  # => "(11)98765-4321"

# License Plate
require 'brazilian-utils/license-plate-utils'
BrazilianUtils::LicensePlateUtils.is_valid('ABC1234')  # => true
BrazilianUtils::LicensePlateUtils.convert_to_mercosul('ABC1234')  # => "ABC1C34"

# Voter ID
require 'brazilian-utils/voter-id-utils'
BrazilianUtils::VoterIdUtils.is_valid_voter_id('690847092828')  # => true
BrazilianUtils::VoterIdUtils.format('690847092828')  # => "6908 4709 28 28"
BrazilianUtils::VoterIdUtils.generate('SP')  # => "123456780140"

# Currency
require 'brazilian-utils/currency-utils'
BrazilianUtils::CurrencyUtils.format_currency(1234.56)  # => "R$ 1.234,56"
BrazilianUtils::CurrencyUtils.number_to_text(1234.56)  # => "mil duzentos e trinta e quatro reais..."

📚 Full Documentation

For detailed examples of each utility, check the examples/ folder.

Main Modules:

• CPFUtils - CPF validation and formatting
• CNPJUtils - CNPJ validation and formatting
• CEPUtils - CEP validation and address lookup
• PhoneUtils - Phone validation
• LicensePlateUtils - Vehicle plates
• VoterIdUtils - Voter IDs
• CurrencyUtils - Currency formatting
• DateUtils - Holidays and date text
• EmailUtils - Email validation
• LegalNatureUtils - Legal nature codes
• LegalProcessUtils - Legal process IDs
• PISUtils - PIS/PASEP
• RENAVAMUtils - Vehicle registration
• CNHUtils - Driver's license

---

🧪 Development

# Install dependencies
bundle install

# Run tests
bundle exec rspec

# Run specific test
bundle exec rspec spec/cpf_utils_spec.rb

📖 API Reference

Common Patterns

Most utilities follow these patterns:

Validation:

.is_valid(value)      # Main validation method
.valid?(value)        # Alias for is_valid

Formatting:

.format(value)        # Format with standard symbols
.remove_symbols(value) # Remove formatting symbols

Generation:

.generate             # Generate random valid value

Utility-Specific Methods

CEP:

• get_address(cep) - Fetch address from CEP
• get_cep_information_from_address(uf, city, street) - Find CEPs

Phone:

• is_valid(phone, type:) - Validate with type (:mobile or :landline)
• remove_international_dialing_code(phone) - Remove +55/55

License Plate:

• convert_to_mercosul(plate) - Convert old format to Mercosul
• get_format(plate) - Detect format ("LLLNNNN" or "LLLNLNN")

Voter ID:

• generate(uf) - Generate for specific state

Currency:

• format_currency(value) - Format as R$ X.XXX,XX
• number_to_text(value) - Convert to Brazilian Portuguese text

Date:

• is_holiday(date, uf) - Check if date is holiday
• convert_date_to_text(date) - Convert to Portuguese text

Legal Nature:

• get_description(code) - Get description for code
• list_by_category(category) - List codes by category (1-5)

Legal Process:

• generate(year, orgao) - Generate for specific year and judicial segment

📊 Examples by Use Case

Form Validation

# Validate user input
cpf = params[:cpf]
if BrazilianUtils::CPFUtils.valid?(cpf)
  # Process valid CPF
else
  errors.add(:cpf, "inválido")
end

Display Formatting

# Format for display
cpf = "11144477735"
formatted = BrazilianUtils::CPFUtils.format_cpf(cpf)
puts formatted  # => "111.444.777-35"

Test Data Generation

# Generate test data
10.times do
  cpf = BrazilianUtils::CPFUtils.generate
  puts BrazilianUtils::CPFUtils.format_cpf(cpf)
end

API Integration

# Lookup address from CEP
address = BrazilianUtils::CEPUtils.get_address('01310100')
if address
  puts "#{address.logradouro}, #{address.bairro}"
  puts "#{address.localidade} - #{address.uf}"
end

---

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests.

Como contribuir / How to contribute:

1. Fork o projeto / Fork the project
2. Crie seu branch (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para o branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request / Open a Pull Request

📄 License

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE.txt para detalhes.

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

🙏 Acknowledgments

Baseado na implementação Python: brazilian-utils/python

Based on the Python implementation: brazilian-utils/python

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: examples/ folder
• 💬 Discussions: GitHub Discussions

---

Made with ❤️ for the Brazilian Ruby community