Brazilian Utils for Go / Utilitários Brasileiros para Go

Português

📖 Sobre

Brazilian Utils for Go é uma biblioteca abrangente que fornece utilitários para trabalhar com formatos de dados e documentos específicos do Brasil. Inclui validadores, formatadores e geradores para vários documentos e tipos de dados brasileiros.

🚀 Instalação

go get -u github.com/brazilian-utils/go

📦 Pacotes

A biblioteca está organizada em pacotes especializados, cada um lidando com um tipo específico de dado brasileiro:

CPF - Cadastro de Pessoas Físicas
CNPJ - Cadastro Nacional da Pessoa Jurídica
CEP - Código de Endereçamento Postal
Phone - Números de Telefone Brasileiros
Currency - Real Brasileiro (R$)
Boleto - Boleto de Pagamento
Email - Endereço de Email
PIS - Programa de Integração Social
CNH - Carteira Nacional de Habilitação
RENAVAM - Registro Nacional de Veículos Automotores
License Plate - Placas de Veículos
Date - Utilitários de Data Brasileira
Legal Nature - Natureza Jurídica
Legal Process - Números de Processos Judiciais
Voter ID - Título de Eleitor

CPF

CPF (Cadastro de Pessoas Físicas) é o número de identificação do contribuinte individual brasileiro.

import "github.com/brazilian-utils/go/cpf"

// Validar CPF
cpf.IsValid("40364478829")  // true
cpf.IsValid("403.644.788-29")  // true
cpf.IsValid("00000000000")  // false (na lista negra)

// Formatar CPF
cpf.Format("40364478829")  // "403.644.788-29"
cpf.Format("403644788")  // "403.644.788" (incompleto)

// Gerar CPF válido aleatório
cpf.Generate()  // "12345678909" (aleatório)

CNPJ

CNPJ (Cadastro Nacional da Pessoa Jurídica) é o número de identificação de empresa brasileiro.

import "github.com/brazilian-utils/go/cnpj"

// Validar CNPJ
cnpj.IsValid("11222333000181")  // true
cnpj.IsValid("11.222.333/0001-81")  // true
cnpj.IsValid("00000000000000")  // false (na lista negra)

// Formatar CNPJ
cnpj.Format("11222333000181")  // "11.222.333/0001-81"

// Gerar CNPJ válido aleatório
cnpj.Generate()  // "12345678000190" (aleatório)

CEP

CEP (Código de Endereçamento Postal) é o código postal brasileiro.

import "github.com/brazilian-utils/go/cep"

// Validar CEP
cep.IsValid("01310100")  // true
cep.IsValid("01310-100")  // false (deve conter apenas dígitos)

// Formatar CEP
cep.Format("01310100")  // "01310-100"
cep.Format("0131010")  // "" (inválido, retorna vazio)

// Gerar CEP aleatório
cep.Generate()  // "12345678" (aleatório)

// Buscar endereço pelo CEP (usa a API ViaCEP)
addr, err := cep.GetAddressFromCEP("01310100")
if err == nil {
    fmt.Println(addr.Logradouro)  // "Avenida Paulista"
    fmt.Println(addr.Bairro)      // "Bela Vista"
    fmt.Println(addr.Localidade)  // "São Paulo"
    fmt.Println(addr.UF)          // "SP"
}

// Buscar CEP pelo endereço
ceps, err := cep.GetCEPFromAddress("SP", "São Paulo", "Paulista")
if err == nil {
    for _, c := range ceps {
        fmt.Println(c.CEP, c.Logradouro)
    }
}

Phone

Utilitários para números de telefone brasileiros (celular e fixo).

import "github.com/brazilian-utils/go/phone"

// Validar números de telefone
phone.IsValid("11987654321", "mobile")    // true
phone.IsValid("1133334444", "landline")   // true
phone.IsValid("11987654321", "")          // true (qualquer tipo)

// Formatar números de telefone
phone.Format("11987654321")  // "(11)98765-4321"
phone.Format("1133334444")   // "(11)3333-4444"

// Remover símbolos
phone.RemoveSymbols("(11) 98765-4321")  // "11987654321"

// Remover código internacional
phone.RemoveInternationalDialingCode("5511987654321")  // "11987654321"

// Gerar telefone aleatório
phone.Generate("mobile")    // "11987654321" (celular aleatório)
phone.Generate("landline")  // "1133334444" (fixo aleatório)
phone.Generate("")          // celular ou fixo aleatório

Currency

Formatar e converter valores em Real Brasileiro (R$).

import "github.com/brazilian-utils/go/currency"

// Formatar moeda
currency.FormatCurrency(1234.56)  // "R$ 1.234,56"
currency.FormatCurrency(1000000.00)  // "R$ 1.000.000,00"

// Converter para texto (português)
currency.ConvertRealToText(1234.56)  // "Mil duzentos e trinta e quatro reais e cinquenta e seis centavos"
currency.ConvertRealToText(1.00)     // "Um real"
currency.ConvertRealToText(0.50)     // "Cinquenta centavos"
currency.ConvertRealToText(-100.00)  // "Menos cem reais"

Boleto

Validar boletos bancários brasileiros.

import "github.com/brazilian-utils/go/boleto"

// Validar linha digitável do boleto (47 dígitos)
boleto.IsValid("34191790010104351004791020150008291070026000")  // true/false

Email

Validação de endereço de email.

import "github.com/brazilian-utils/go/email"

// Validar email
email.IsValid("user@example.com")  // true
email.IsValid("invalid.email")     // false
email.IsValid(".user@example.com") // false (começa com ponto)

PIS

PIS (Programa de Integração Social) é um número do programa de integração social brasileiro.

import "github.com/brazilian-utils/go/pis"

// Validar PIS
pis.IsValid("12345678901")  // true/false

// Formatar PIS
pis.Format("12345678901")  // "123.45678.90-1"

// Gerar PIS válido aleatório
pis.Generate()  // "12345678901" (aleatório)

CNH

CNH (Carteira Nacional de Habilitação) é a carteira de motorista nacional brasileira.

import "github.com/brazilian-utils/go/cnh"

// Validar CNH (11 dígitos)
cnh.IsValid("12345678901")  // true/false
cnh.IsValid("00000000000")  // false (na lista negra)

RENAVAM

RENAVAM é o número do registro nacional de veículos automotores brasileiro.

import "github.com/brazilian-utils/go/renavam"

// Validar RENAVAM (11 dígitos)
renavam.IsValid("12345678901")  // true/false
renavam.IsValid("11111111111")  // false (todos dígitos iguais)

License Plate

Utilitários para placas de veículos brasileiros (formato antigo e Mercosul).

import "github.com/brazilian-utils/go/licenseplate"

// Validar placas
licenseplate.IsValid("ABC1234", "old_format")  // true
licenseplate.IsValid("ABC1D34", "mercosul")    // true
licenseplate.IsValid("ABC1D34", "")            // true (qualquer formato)

// Obter formato
licenseplate.GetFormat("ABC1234")  // "LLLNNNN"
licenseplate.GetFormat("ABC1D34")  // "LLLNLNN"

// Formatar placa
licenseplate.Format("ABC1234")  // "ABC-1234" (formato antigo com traço)
licenseplate.Format("abc1d34")  // "ABC1D34" (Mercosul maiúsculo)

// Converter formato antigo para Mercosul
licenseplate.ConvertToMercosul("ABC1234")  // "ABC1B34"

// Gerar placa aleatória
licenseplate.Generate("LLLNNNN")  // "ABC1234" (formato antigo)
licenseplate.Generate("LLLNLNN")  // "ABC1D34" (Mercosul)

Date

Converter datas brasileiras para texto em português.

import "github.com/brazilian-utils/go/date"

// Converter data para texto
date.ConvertDateToText("25/12/2024")  // "Vinte e cinco de Dezembro de dois mil e vinte e quatro"
date.ConvertDateToText("01/01/2000")  // "Primeiro de Janeiro de dois mil"

Legal Nature

Códigos de Natureza Jurídica da Receita Federal Brasileira.

import "github.com/brazilian-utils/go/legalnature"

// Validar código de natureza jurídica
legalnature.IsValid("2062")  // true
legalnature.IsValid("206-2")  // true

// Obter descrição
legalnature.GetDescription("2062")  // "Sociedade Empresária Limitada"
legalnature.GetDescription("2046")  // "Sociedade Anônima Aberta"

Legal Process

Utilitários para números de processos judiciais brasileiros.

import "github.com/brazilian-utils/go/legalprocess"

// Validar processo judicial (20 dígitos)
legalprocess.IsValid("12345670820231234567")  // true/false

// Formatar processo judicial
legalprocess.Format("12345670820231234567")  // "1234567-08.2023.1.23.4567"

// Gerar processo judicial aleatório
legalprocess.Generate(2024, 1)  // "1234567082024123456" (aleatório, ano 2024, órgão 1)

Voter ID

Título de Eleitor (Voter ID) é o número de identificação do eleitor brasileiro.

import "github.com/brazilian-utils/go/voterid"

// Validar Título de Eleitor
voterid.IsValid("217633460930")  // true
voterid.IsValid("6908 4709 28 28")  // true (com espaços)
voterid.IsValid("123456789011")  // false (dígitos verificadores inválidos)

// Formatar Título de Eleitor
voterid.Format("217633460930")  // "2176 3346 09 30"
voterid.Format("3244567800167")  // "3244 5678 00 16" (13 dígitos para SP/MG)

// Gerar Título de Eleitor válido aleatório
voterid.Generate()       // "217633460930" (aleatório, padrão ZZ - estrangeiro)
voterid.Generate("SP")   // "149426030183" (São Paulo)
voterid.Generate("MG")   // "033568860230" (Minas Gerais)
voterid.Generate("RJ")   // "858224120973" (Rio de Janeiro)

Observações:

Títulos de eleitor têm normalmente 12 dígitos
Casos especiais: SP (01) e MG (02) podem ter 13 dígitos
Códigos de UF válidos: 01-28
Dois dígitos verificadores calculados usando módulo 11

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

📄 Licença

Este projeto está licenciado sob a Licença MIT.

English

📖 About

Brazilian Utils for Go is a comprehensive library that provides utilities for working with Brazilian-specific data formats and documents. It includes validators, formatters, and generators for various Brazilian documents and data types.

🚀 Installation

go get -u github.com/brazilian-utils/go

📦 Packages

The library is organized into specialized packages, each handling a specific Brazilian data type:

CPF - Individual Taxpayer Registry
CNPJ - National Registry of Legal Entities
CEP - Postal Code
Phone - Brazilian Phone Numbers
Currency - Brazilian Real (R$)
Boleto - Payment Slip
Email - Email Address
PIS - Social Integration Program
CNH - National Driver's License
RENAVAM - National Vehicle Registry
License Plate - Vehicle License Plates
Date - Brazilian Date Utilities
Legal Nature - Legal Entity Nature
Legal Process - Legal Process Numbers
Voter ID - Voter Registration ID

CPF

CPF (Cadastro de Pessoas Físicas) is the Brazilian individual taxpayer identification number.

import "github.com/brazilian-utils/go/cpf"

// Validate CPF
cpf.IsValid("40364478829")  // true
cpf.IsValid("403.644.788-29")  // true
cpf.IsValid("00000000000")  // false (blacklisted)

// Format CPF
cpf.Format("40364478829")  // "403.644.788-29"
cpf.Format("403644788")  // "403.644.788" (incomplete)

// Generate random valid CPF
cpf.Generate()  // "12345678909" (random)

CNPJ

CNPJ (Cadastro Nacional da Pessoa Jurídica) is the Brazilian company identification number.

import "github.com/brazilian-utils/go/cnpj"

// Validate CNPJ
cnpj.IsValid("11222333000181")  // true
cnpj.IsValid("11.222.333/0001-81")  // true
cnpj.IsValid("00000000000000")  // false (blacklisted)

// Format CNPJ
cnpj.Format("11222333000181")  // "11.222.333/0001-81"

// Generate random valid CNPJ
cnpj.Generate()  // "12345678000190" (random)

CEP

CEP (Código de Endereçamento Postal) is the Brazilian postal code.

import "github.com/brazilian-utils/go/cep"

// Validate CEP
cep.IsValid("01310100")  // true
cep.IsValid("01310-100")  // false (must be digits only)

// Format CEP
cep.Format("01310100")  // "01310-100"
cep.Format("0131010")  // "" (invalid, returns empty)

// Generate random CEP
cep.Generate()  // "12345678" (random)

// Fetch address from CEP (uses ViaCEP API)
addr, err := cep.GetAddressFromCEP("01310100")
if err == nil {
    fmt.Println(addr.Logradouro)  // "Avenida Paulista"
    fmt.Println(addr.Bairro)      // "Bela Vista"
    fmt.Println(addr.Localidade)  // "São Paulo"
    fmt.Println(addr.UF)          // "SP"
}

// Search CEP from address
ceps, err := cep.GetCEPFromAddress("SP", "São Paulo", "Paulista")
if err == nil {
    for _, c := range ceps {
        fmt.Println(c.CEP, c.Logradouro)
    }
}

Phone

Utilities for Brazilian phone numbers (mobile and landline).

import "github.com/brazilian-utils/go/phone"

// Validate phone numbers
phone.IsValid("11987654321", "mobile")    // true
phone.IsValid("1133334444", "landline")   // true
phone.IsValid("11987654321", "")          // true (any type)

// Format phone numbers
phone.Format("11987654321")  // "(11)98765-4321"
phone.Format("1133334444")   // "(11)3333-4444"

// Remove symbols
phone.RemoveSymbols("(11) 98765-4321")  // "11987654321"

// Remove international code
phone.RemoveInternationalDialingCode("5511987654321")  // "11987654321"

// Generate random phone
phone.Generate("mobile")    // "11987654321" (random mobile)
phone.Generate("landline")  // "1133334444" (random landline)
phone.Generate("")          // random mobile or landline

Currency

Format and convert Brazilian Real (R$) values.

import "github.com/brazilian-utils/go/currency"

// Format currency
currency.FormatCurrency(1234.56)  // "R$ 1.234,56"
currency.FormatCurrency(1000000.00)  // "R$ 1.000.000,00"

// Convert to text (Portuguese)
currency.ConvertRealToText(1234.56)  // "Mil duzentos e trinta e quatro reais e cinquenta e seis centavos"
currency.ConvertRealToText(1.00)     // "Um real"
currency.ConvertRealToText(0.50)     // "Cinquenta centavos"
currency.ConvertRealToText(-100.00)  // "Menos cem reais"

Boleto

Validate Brazilian bank payment slips (boletos).

import "github.com/brazilian-utils/go/boleto"

// Validate boleto digitable line (47 digits)
boleto.IsValid("34191790010104351004791020150008291070026000")  // true/false

Email

Email address validation.

import "github.com/brazilian-utils/go/email"

// Validate email
email.IsValid("user@example.com")  // true
email.IsValid("invalid.email")     // false
email.IsValid(".user@example.com") // false (starts with dot)

PIS

PIS (Programa de Integração Social) is a Brazilian social integration program number.

import "github.com/brazilian-utils/go/pis"

// Validate PIS
pis.IsValid("12345678901")  // true/false

// Format PIS
pis.Format("12345678901")  // "123.45678.90-1"

// Generate random valid PIS
pis.Generate()  // "12345678901" (random)

CNH

CNH (Carteira Nacional de Habilitação) is the Brazilian national driver's license.

import "github.com/brazilian-utils/go/cnh"

// Validate CNH (11 digits)
cnh.IsValid("12345678901")  // true/false
cnh.IsValid("00000000000")  // false (blacklisted)

RENAVAM

RENAVAM is the Brazilian national vehicle registration number.

import "github.com/brazilian-utils/go/renavam"

// Validate RENAVAM (11 digits)
renavam.IsValid("12345678901")  // true/false
renavam.IsValid("11111111111")  // false (all same digit)

License Plate

Utilities for Brazilian vehicle license plates (old format and Mercosul).

import "github.com/brazilian-utils/go/licenseplate"

// Validate license plates
licenseplate.IsValid("ABC1234", "old_format")  // true
licenseplate.IsValid("ABC1D34", "mercosul")    // true
licenseplate.IsValid("ABC1D34", "")            // true (any format)

// Get format
licenseplate.GetFormat("ABC1234")  // "LLLNNNN"
licenseplate.GetFormat("ABC1D34")  // "LLLNLNN"

// Format license plate
licenseplate.Format("ABC1234")  // "ABC-1234" (old format with dash)
licenseplate.Format("abc1d34")  // "ABC1D34" (Mercosul uppercase)

// Convert old format to Mercosul
licenseplate.ConvertToMercosul("ABC1234")  // "ABC1B34"

// Generate random license plate
licenseplate.Generate("LLLNNNN")  // "ABC1234" (old format)
licenseplate.Generate("LLLNLNN")  // "ABC1D34" (Mercosul)

Date

Convert Brazilian dates to Portuguese text.

import "github.com/brazilian-utils/go/date"

// Convert date to text
date.ConvertDateToText("25/12/2024")  // "Vinte e cinco de Dezembro de dois mil e vinte e quatro"
date.ConvertDateToText("01/01/2000")  // "Primeiro de Janeiro de dois mil"

Legal Nature

Legal Nature (Natureza Jurídica) codes from the Brazilian Federal Revenue.

import "github.com/brazilian-utils/go/legalnature"

// Validate legal nature code
legalnature.IsValid("2062")  // true
legalnature.IsValid("206-2")  // true

// Get description
legalnature.GetDescription("2062")  // "Sociedade Empresária Limitada"
legalnature.GetDescription("2046")  // "Sociedade Anônima Aberta"

Legal Process

Brazilian legal process number utilities.

import "github.com/brazilian-utils/go/legalprocess"

// Validate legal process (20 digits)
legalprocess.IsValid("12345670820231234567")  // true/false

// Format legal process
legalprocess.Format("12345670820231234567")  // "1234567-08.2023.1.23.4567"

// Generate random legal process
legalprocess.Generate(2024, 1)  // "1234567082024123456" (random, year 2024, orgao 1)

Voter ID

Voter ID (Título de Eleitor) is the Brazilian voter registration identification number.

import "github.com/brazilian-utils/go/voterid"

// Validate Voter ID
voterid.IsValid("217633460930")  // true
voterid.IsValid("6908 4709 28 28")  // true (with spaces)
voterid.IsValid("123456789011")  // false (invalid check digits)

// Format Voter ID
voterid.Format("217633460930")  // "2176 3346 09 30"
voterid.Format("3244567800167")  // "3244 5678 00 16" (13 digits for SP/MG)

// Generate random valid Voter ID
voterid.Generate()       // "217633460930" (random, default ZZ - foreigner)
voterid.Generate("SP")   // "149426030183" (São Paulo)
voterid.Generate("MG")   // "033568860230" (Minas Gerais)
voterid.Generate("RJ")   // "858224120973" (Rio de Janeiro)

Notes:

Voter IDs are typically 12 digits long
Special cases: SP (01) and MG (02) can have 13 digits
Valid UF codes: 01-28
Two check digits calculated using modulo 11

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/workflows		.github/workflows
boleto		boleto
cep		cep
cnh		cnh
cnpj		cnpj
cpf		cpf
currency		currency
date		date
email		email
helpers		helpers
legalnature		legalnature
legalprocess		legalprocess
licenseplate		licenseplate
phone		phone
pis		pis
renavam		renavam
voterid		voterid
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docs.go		docs.go
formatters.go		formatters.go
go.mod		go.mod
validators.go		validators.go

License

brazilian-utils/go

Folders and files

Latest commit

History

Repository files navigation

Brazilian Utils for Go / Utilitários Brasileiros para Go

Português

📖 Sobre

🚀 Instalação

📦 Pacotes

CPF

CNPJ

CEP

Phone

Currency

Boleto

Email

PIS

CNH

RENAVAM

License Plate

Date

Legal Nature

Legal Process

Voter ID

🤝 Contribuindo

📄 Licença

English

📖 About

🚀 Installation

📦 Packages

CPF

CNPJ

CEP

Phone

Currency

Boleto

Email

PIS

CNH

RENAVAM

License Plate

Date

Legal Nature

Legal Process

Voter ID

🤝 Contributing

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages