CPF CNPJ Plus

cpf_cnpj_plus é uma biblioteca Ruby para validar, gerar e formatar números de CPF e CNPJ brasileiros. Funciona em Ruby puro (sem dependências de runtime), tem um validador opcional para Rails/ActiveModel, e oferece ferramentas de linha de comando.

🚀 Novidade: Suporte a CNPJ Alfanumérico

Atenção: Esta gem já está atualizada para validar e formatar os novos CNPJs alfanuméricos, conforme a alteração anunciada pela Receita Federal para julho de 2026.
Assim, seu sistema estará pronto para lidar tanto com o formato tradicional quanto com o novo padrão de CNPJ.

Instalação

Adicione esta linha ao seu Gemfile:

gem "cpf_cnpj_plus"

E execute:

bundle install

Ou instale diretamente com:

gem install cpf_cnpj_plus

Uso Básico

API Ruby

A gem oferece uma API unificada para CPF e CNPJ. Exemplos:

require "cpf_cnpj_plus"

# CPF
CpfCnpjPlus.valid_cpf?("123.456.789-09") # => true ou false
CpfCnpjPlus.format_cpf("12345678909") # => "123.456.789-09"
CpfCnpjPlus.generate_cpf # => Gera um CPF válido

# CNPJ
CpfCnpjPlus.valid_cnpj?("12.345.678/0001-95") # => true ou false
CpfCnpjPlus.format_cnpj("12345678000195") # => "12.345.678/0001-95"
CpfCnpjPlus.generate_cnpj # => Gera um CNPJ válido

# CNPJ Alfanumérico (novo formato)
CpfCnpjPlus.valid_cnpj?("12.ABC.345/01DE-35") # => true
CpfCnpjPlus.format_cnpj("12ABC34501DE35") # => "12.ABC.345/01DE-35"
CpfCnpjPlus.generate_cnpj(alphanumeric: true) # => Gera um CNPJ alfanumérico válido
CpfCnpjPlus.alphanumeric_cnpj?("12ABC34501DE35") # => true (identifica se já usa o novo padrão)

# API unificada (detecta CPF ou CNPJ pelo tamanho do documento)
CpfCnpjPlus.valid?("123.456.789-09")   # => true ou false
CpfCnpjPlus.valid?("12.345.678/0001-95") # => true ou false
CpfCnpjPlus.format("12345678909")      # => "123.456.789-09"
CpfCnpjPlus.format("12345678000195")   # => "12.345.678/0001-95"
CpfCnpjPlus.generate(:cpf)             # => Gera um CPF válido
CpfCnpjPlus.generate(:cnpj, alphanumeric: true) # => Gera um CNPJ alfanumérico válido

# Formatação estrita (retorna nil se os dígitos verificadores forem inválidos)
CpfCnpjPlus.format_cpf("12345678900", strict: true)   # => nil (dígitos verificadores errados)
CpfCnpjPlus.format_cnpj("12345678000199", strict: true) # => nil (dígitos verificadores errados)

Validação em Rails/ActiveModel

A gem também traz um validador opcional para uso com ActiveModel::Validations (inclusive em models Rails). Ele não é carregado junto com require "cpf_cnpj_plus" — é preciso requerê-lo explicitamente, e activemodel precisa estar disponível na sua aplicação:

require "cpf_cnpj_plus/active_model_validator"

class Empresa
  include ActiveModel::Model
  attr_accessor :cnpj, :cpf

  validates :cnpj, cpf_cnpj: { type: :cnpj }  # aceita CNPJ numérico ou alfanumérico
  validates :cpf, cpf_cnpj: { type: :cpf }
  # ou, para detectar o tipo automaticamente pelo tamanho:
  # validates :documento, cpf_cnpj: true
end

Suporta as opções padrão do Rails (allow_nil, allow_blank, message).

Linha de comando

A gem fornece comandos CLI:

$ cpf_plus --check 123.456.789-09
$ cpf_plus --format 12345678909
$ cpf_plus --generate
$ cnpj_plus --check 12.345.678/0001-95
$ cnpj_plus --check 12.ABC.345/01DE-35
$ cnpj_plus --generate

Compatibilidade

Ruby >= 3.1.0 (testado em CI nas versões 3.1, 3.2, 3.3, 3.4 e 4.0).
Sem dependências de runtime — funciona em qualquer projeto Ruby puro.
Uso com Rails/ActiveModel é opcional: só é necessário se você requerer cpf_cnpj_plus/active_model_validator (veja a seção "Validação em Rails/ActiveModel" acima).

Contribuição

Faça um fork do projeto
Crie sua branch (git checkout -b minha-feature)
Rode bundle install e depois bundle exec rake (specs + rubocop) para garantir que tudo continua passando
Commit suas alterações (git commit -am 'Adiciona nova feature')
Faça push para a branch (git push origin minha-feature)
Abra um Pull Request

Licença

MIT

Para dúvidas ou sugestões, abra uma issue ou envie um pull request!

cpf_cnpj_plus

Development