br_validators 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f48e272ba459e1e9962ac199162b257eea94025b41c02c64501a663c71058b3
-  data.tar.gz: 3c194886a75d84f28c23b4a62414383735ba70509ef25f2d960fc23996efdcc7
+  metadata.gz: 7297d8bd1acfbea15d3f7ef85f6bbb6cd5cc5555129c6a83bfade0e69358c14b
+  data.tar.gz: 9eab13d77a0a931e3c7a6dc34542dc9a0a069f67f5b9c72f38b9517f457e8336
 SHA512:
-  metadata.gz: 1fa44a6062e29f87a87fdca434a07b7cada13d7b091b06cfc21c1cb98de331ef0c44add691368d2d651703f209349d41478cdae03736e6bd566358caf26298f9
-  data.tar.gz: cd6d9864713501561878ceff7c9a505de1f6791dcd6fb61001a224dbe762bf8c863b40d1f9414f891634c540ba19c149524547ee612372616cfbbf8cff59854a
+  metadata.gz: c8de53e6d4904f91915313b8f3f68ccfbe2b4e9269cff2bc0ea2f26c5cc87d2e13b3660cbd6130e4297a8d94d249758d4f1a5e5199b188882f16307413f37e7b
+  data.tar.gz: 6d948e9f10e7acd07d35c8e773f770931681afe19976fc447cbe29c6f37969a012629dac68ca187eb6b3f55fa8131cae69a0fd23d646eea250e2f8a719c085d7

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 As mudanças de cada versão ficam aqui. O projeto segue o
 [versionamento semântico](https://semver.org/lang/pt-BR/).
 
+## [0.2.0] - 2026-10-26
+
+### Novo
+
+- `BrValidators::Consulta` (opcional, `require "br_validators/consulta"`): consultas online
+  pela BrasilAPI de CEP (endereço), CNPJ (dados da Receita), banco (código de compensação)
+  e DDD (UF e cidades). Só usa a biblioteca padrão do Ruby; valida o dado antes de
+  consultar, devolve `nil` quando não acha e levanta `BrValidators::Consulta::Erro` quando
+  a BrasilAPI não responde.
+
+- `BrValidators::CEP`: formato do CEP.
+- `BrValidators::Telefone`: fixo e celular, com os 67 DDDs da Anatel; `type`, `format` e `ddd`.
+- `BrValidators::Placa`: placa antiga e Mercosul; `type`, `mercosul` e `antiga` para converter.
+- `BrValidators::RENAVAM`: 11 dígitos com dígito verificador.
+- `BrValidators::TituloEleitor`: 12 dígitos, dígitos verificadores e `uf`.
+- `BrValidators::ProcessoCNJ`: numeração única do CNJ (módulo 97) e `segmento`.
+- `BrValidators::ChaveAcesso`: chave de NF-e, NFC-e, CT-e e MDF-e, inclusive com CNPJ
+  alfanumérico, e `modelo`.
+- Validadores do ActiveModel para todos eles (`cep: true`, `telefone: true`, `placa: true`,
+  `renavam: true`, `titulo_eleitor: true`, `processo_cnj: true`, `chave_acesso: true`),
+  com mensagens em pt-BR e en.
+
 ## [0.1.1] - 2026-10-25
 
 ### Corrigido

data/README.md

@@ -15,13 +15,25 @@ Ou direto: `gem install br_validators`. A gem está publicada no
 
 ## O que tem
 
-| Documento | Observação |
-| --- | --- |
-| CPF | |
-| CNPJ | numérico e alfanumérico (o formato novo da Receita Federal, a partir de julho de 2026) |
-| CNS | Cartão Nacional de Saúde |
-| Chave Pix | CPF, CNPJ, e-mail, celular e chave aleatória |
-| Boleto | linha digitável de cobrança e de arrecadação |
+| Documento | Módulo | Observação |
+| --- | --- | --- |
+| CPF | `CPF` | |
+| CNPJ | `CNPJ` | numérico e alfanumérico (o formato novo da Receita Federal, a partir de julho de 2026) |
+| CNS | `CNS` | Cartão Nacional de Saúde |
+| Título de eleitor | `TituloEleitor` | 12 dígitos, com a UF de emissão |
+| Chave Pix | `Pix` | CPF, CNPJ, e-mail, celular e chave aleatória |
+| Boleto | `Boleto` | linha digitável de cobrança e de arrecadação |
+| CEP | `CEP` | só o formato (o CEP não tem dígito verificador) |
+| Telefone | `Telefone` | fixo e celular, com os 67 DDDs da Anatel |
+| Placa | `Placa` | antiga e Mercosul, com conversão entre as duas |
+| RENAVAM | `RENAVAM` | 11 dígitos |
+| Chave de acesso | `ChaveAcesso` | NF-e, NFC-e, CT-e e MDF-e, inclusive com CNPJ alfanumérico |
+| Processo judicial | `ProcessoCNJ` | numeração única do CNJ |
+
+A regra de cada um está no comentário do módulo, com o link da fonte oficial (Receita
+Federal, Ministério da Saúde, Banco Central, FEBRABAN, Anatel, CONTRAN, CNJ...). O
+título de eleitor é a exceção: o TSE não publica o cálculo, e a regra usada é a que a
+OBMEP documenta.
 
 Cada documento tem os mesmos três métodos:
 
@@ -59,6 +71,48 @@ BrValidators::Boleto.type("00190.00009 02345.678904 12345.678176 1 1000000001234
 BrValidators::Boleto.valid?("826700000019000000000000000000000000000000000000")      # => true
 ```
 
+Os documentos novos seguem o mesmo jeito, com alguns métodos a mais:
+
+```ruby
+BrValidators::Telefone.type("+55 11 98765-4321")   # => :celular
+BrValidators::Telefone.format("1134567890")        # => "(11) 3456-7890"
+
+BrValidators::Placa.type("ABC1C34")                 # => :mercosul
+BrValidators::Placa.mercosul("ABC-1234")            # => "ABC1C34"
+BrValidators::Placa.antiga("ABC1C34")               # => "ABC1234"
+
+BrValidators::TituloEleitor.uf("1023 8501 0671")    # => "PR"
+BrValidators::ProcessoCNJ.segmento("0000456-41.2023.5.02.9999") # => "Justiça do Trabalho"
+BrValidators::ChaveAcesso.modelo("3526 1011 2223 3300 0181 5500 1000 0001 2311 2345 6783") # => "55" (NF-e)
+
+BrValidators::CEP.format("01001000")                # => "01001-000"
+BrValidators::RENAVAM.valid?("00123456789")         # => true
+```
+
+## Consultas online
+
+Validar não diz se o documento existe. Para isso há consultas pela
+[BrasilAPI](https://brasilapi.com.br), um serviço gratuito, de código aberto e sem chave.
+Elas são opcionais (a validação continua funcionando sem internet):
+
+```ruby
+require "br_validators/consulta"
+
+BrValidators::Consulta.cep("01001-000")
+# => {"cep"=>"01001000", "state"=>"SP", "city"=>"São Paulo", "street"=>..., ...}
+BrValidators::Consulta.cnpj("11.222.333/0001-81") # => dados da Receita Federal (razao_social, uf, ...)
+BrValidators::Consulta.banco("001")                # => {"code"=>1, "name"=>"BCO DO BRASIL S.A.", ...}
+BrValidators::Consulta.ddd("11")                   # => {"state"=>"SP", "cities"=>[...]}
+```
+
+- Dado inválido devolve `nil` sem chamar a internet; dado que a BrasilAPI não encontra
+  também devolve `nil`.
+- Se a BrasilAPI não responder em 5 segundos ou der erro, levanta
+  `BrValidators::Consulta::Erro`.
+- Para usar cache ou outro cliente HTTP, troque o `BrValidators::Consulta.cliente` por um
+  objeto com `get(uri)` que devolva `[status, corpo]`.
+- A resposta é o JSON da BrasilAPI como `Hash`. Os campos são os dela e podem mudar.
+
 ## Rails e ActiveModel
 
 Em projetos com ActiveModel (todo app Rails tem), os validadores entram sozinhos:
@@ -70,19 +124,32 @@ class Cliente < ApplicationRecord
   validates :cartao_sus, cns: true
   validates :chave_pix, pix: { message: "não parece uma chave Pix" }
   validates :linha_digitavel, boleto: true
+  validates :cep, cep: true
+  validates :celular, telefone: true
+  validates :titulo, titulo_eleitor: true
+end
+
+class Veiculo < ApplicationRecord
+  validates :placa, placa: true
+  validates :renavam, renavam: true
+end
+
+class Nota < ApplicationRecord
+  validates :chave, chave_acesso: true
+  validates :processo, processo_cnj: true
 end
 ```
 
 As mensagens de erro vêm em português (`pt-BR`) e inglês (`en`). Para trocar o texto,
-sobrescreva as chaves `errors.messages.cpf_invalid`, `cnpj_invalid`, `cns_invalid`,
-`pix_invalid` e `boleto_invalid` no seu arquivo de tradução.
+sobrescreva as chaves `errors.messages.<documento>_invalid` (`cpf_invalid`, `cep_invalid`,
+`titulo_eleitor_invalid`...) no seu arquivo de tradução.
 
-Os validadores se chamam `CpfValidator`, `CnpjValidator`, `CnsValidator`, `PixValidator` e
-`BoletoValidator`, no nível de cima, porque é assim que o Rails encontra `cpf: true`.
+Os validadores ficam no nível de cima (`CpfValidator`, `TelefoneValidator`,
+`TituloEleitorValidator`...), porque é assim que o Rails encontra `cpf: true`.
 
 Já existem boas gems para CPF e CNPJ. A ideia aqui é juntar num lugar só os documentos
-que costumam aparecer em sistemas brasileiros (inclusive CNS, Pix e boleto), com
-mensagens de erro em português e inglês.
+que costumam aparecer em sistemas brasileiros (inclusive CNS, Pix, boleto, placa, NF-e e
+processo judicial), com mensagens de erro em português e inglês.
 
 ## Página de teste
 

data/lib/br_validators/active_model.rb

@@ -31,3 +31,10 @@ require_relative "validators/cnpj_validator"
 require_relative "validators/cns_validator"
 require_relative "validators/pix_validator"
 require_relative "validators/boleto_validator"
+require_relative "validators/cep_validator"
+require_relative "validators/telefone_validator"
+require_relative "validators/placa_validator"
+require_relative "validators/renavam_validator"
+require_relative "validators/titulo_eleitor_validator"
+require_relative "validators/processo_cnj_validator"
+require_relative "validators/chave_acesso_validator"

data/lib/br_validators/cep.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # CEP (Código de Endereçamento Postal): 8 dígitos, escritos como 00000-000.
+  #
+  # Os 5 primeiros dígitos dizem a região, a sub-região, o setor, o subsetor e o
+  # divisor de subsetor; os 3 últimos (o sufixo) identificam a rua, a localidade
+  # ou a unidade dos Correios.
+  #
+  # O CEP não tem dígito verificador: aqui só dá para conferir o formato. Para
+  # saber se o CEP existe (e qual é o endereço), use a consulta online da gem
+  # (BrValidators::Consulta.cep).
+  #
+  # Fonte: "Tudo sobre CEP", dos Correios.
+  # https://www.correios.com.br/enviar/precisa-de-ajuda/imagens/tudo-sobre-cep
+  module CEP
+    # Pontos, hífens e espaços (inclusive os Unicode, como o não separável).
+    MASK = /[.\-[:space:]]/
+
+    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "")
+    end
+
+    # 8 dígitos. "00000-000" é o CEP que sistemas usam como "não informado";
+    # nenhuma região dos Correios começa com 00000.
+    def self.valid?(value)
+      cep = strip(value)
+      cep.match?(/\A\d{8}\z/) && cep != "00000000"
+    end
+
+    # Devolve "01001-000", ou nil se o CEP for inválido.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      cep = strip(value)
+      "#{cep[0, 5]}-#{cep[5, 3]}"
+    end
+  end
+end

data/lib/br_validators/chave_acesso.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Chave de acesso dos documentos fiscais eletrônicos (NF-e, NFC-e, CT-e, MDF-e):
+  # 44 caracteres.
+  #
+  #   cUF (2)    código IBGE da UF do emitente
+  #   AAMM (4)   ano e mês de emissão
+  #   CNPJ (14)  CNPJ do emitente (ou CPF com zeros à esquerda)
+  #   mod (2)    modelo do documento: 55 NF-e, 65 NFC-e, 57 CT-e, 58 MDF-e...
+  #   serie (3), nNF (9), tpEmis (1), cNF (8) e o dígito verificador (1)
+  #
+  # Com o CNPJ alfanumérico, os 12 primeiros caracteres do CNPJ podem ter letras;
+  # todo o resto continua só com números.
+  #
+  # O dígito verificador usa módulo 11 com pesos de 2 a 9, da direita para a
+  # esquerda, sobre os 43 primeiros caracteres. Cada caractere vale o código ASCII
+  # dele menos 48 (como no CNPJ alfanumérico: "0" vale 0, "A" vale 17). Se o resto
+  # for 0 ou 1, o dígito é 0; senão, é 11 menos o resto.
+  #
+  # Fontes: Manual de Orientação do Contribuinte da NF-e e Nota Técnica Conjunta
+  # 2025.001 (CNPJ alfanumérico nos documentos fiscais eletrônicos), publicados no
+  # Portal da NF-e. https://www.nfe.fazenda.gov.br/portal/
+  module ChaveAcesso
+    # 6 números (cUF e AAMM), 12 letras ou números (raiz e ordem do CNPJ) e 26
+    # números (dígitos do CNPJ e o resto da chave).
+    PATTERN = /\A\d{6}[0-9A-Z]{12}\d{26}\z/
+
+    # O DANFE imprime a chave em grupos de 4, separados por espaço.
+    MASK = /[.\-[:space:]]/
+
+    # Tira a máscara e passa as letras do CNPJ para maiúsculas.
+    # upcase(:ascii) e scrub estão explicados no CNPJ e no CPF.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "").upcase(:ascii)
+    end
+
+    def self.valid?(value)
+      chave = strip(value)
+      return false unless chave.match?(PATTERN)
+
+      chave[43] == check_digit(chave[0, 43])
+    end
+
+    # Devolve a chave em 11 grupos de 4 ("3526 1011 2223 ..."), ou nil se for inválida.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      strip(value).scan(/.{4}/).join(" ")
+    end
+
+    # O código do modelo ("55" para NF-e, "65" para NFC-e...), ou nil se for inválida.
+    def self.modelo(value)
+      valid?(value) ? strip(value)[20, 2] : nil
+    end
+
+    def self.check_digit(chars)
+      sum = chars.reverse.chars.each_with_index.sum { |char, index| (char.ord - 48) * ((index % 8) + 2) }
+      rest = sum % 11
+      (rest < 2 ? 0 : 11 - rest).to_s
+    end
+
+    private_class_method :check_digit
+  end
+end

data/lib/br_validators/consulta.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require_relative "../br_validators"
+
+module BrValidators
+  # Consultas online pela BrasilAPI (https://brasilapi.com.br), um serviço gratuito,
+  # de código aberto e sem chave de acesso. É opcional: não vem com o
+  # require "br_validators" (a validação continua sem rede); carregue com
+  #
+  #   require "br_validators/consulta"
+  #
+  #   BrValidators::Consulta.cep("01001-000")
+  #   # => {"cep"=>"01001000", "state"=>"SP", "city"=>"São Paulo", "street"=>..., ...}
+  #   BrValidators::Consulta.cnpj("11.222.333/0001-81")  # dados da Receita Federal
+  #   BrValidators::Consulta.banco("001")                # => {"code"=>1, "name"=>"BCO DO BRASIL S.A.", ...}
+  #   BrValidators::Consulta.ddd("11")                   # => {"state"=>"SP", "cities"=>[...]}
+  #
+  # Cada método:
+  #   - valida o dado antes (documento inválido devolve nil sem chamar a internet);
+  #   - devolve o JSON da BrasilAPI como Hash (chaves em texto), ou nil se não achar;
+  #   - levanta BrValidators::Consulta::Erro se a BrasilAPI não responder ou der erro.
+  module Consulta
+    BASE = "https://brasilapi.com.br/api"
+
+    # Segundos de espera para conectar e para receber a resposta.
+    TIMEOUT = 5
+
+    # A BrasilAPI não respondeu, demorou demais ou respondeu com erro.
+    class Erro < StandardError; end
+
+    class << self
+      # Quem faz a requisição: qualquer objeto com get(uri) que devolva
+      # [status, corpo]. O padrão é o HTTP abaixo; os testes trocam por um falso,
+      # e quem usa a gem pode trocar por um com cache, por exemplo.
+      attr_writer :cliente
+
+      def cliente
+        @cliente ||= HTTP
+      end
+    end
+
+    # Endereço do CEP: cep, state, city, neighborhood, street e service.
+    def self.cep(valor)
+      return nil unless CEP.valid?(valor)
+
+      buscar("/cep/v1/#{CEP.strip(valor)}")
+    end
+
+    # Dados do CNPJ na Receita Federal (razao_social, nome_fantasia,
+    # descricao_situacao_cadastral, uf, municipio...). O CNPJ alfanumérico só é
+    # encontrado quando a BrasilAPI passar a aceitá-lo.
+    def self.cnpj(valor)
+      return nil unless CNPJ.valid?(valor)
+
+      buscar("/cnpj/v1/#{CNPJ.strip(valor)}")
+    end
+
+    # Banco pelo código de compensação ("001", "237", 341): code, name, fullName e ispb.
+    def self.banco(codigo)
+      codigo = codigo.to_s.strip
+      return nil unless codigo.match?(/\A\d{1,3}\z/)
+
+      buscar("/banks/v1/#{codigo.to_i}")
+    end
+
+    # UF e cidades de um DDD: state e cities.
+    def self.ddd(valor)
+      ddd = valor.to_s.strip
+      return nil unless Telefone::DDDS.include?(ddd)
+
+      buscar("/ddd/v1/#{ddd}")
+    end
+
+    # 200 vira Hash; 400 e 404 (não achou) viram nil; o resto é erro.
+    def self.buscar(caminho)
+      status, corpo = cliente.get(URI("#{BASE}#{caminho}"))
+      case status
+      when 200 then JSON.parse(corpo)
+      when 400, 404 then nil
+      else raise Erro, "A BrasilAPI respondeu #{status} em #{caminho}."
+      end
+    rescue JSON::ParserError
+      raise Erro, "A BrasilAPI respondeu algo que não é JSON em #{caminho}."
+    end
+
+    private_class_method :buscar
+
+    # Cliente padrão, só com a biblioteca padrão do Ruby (Net::HTTP).
+    module HTTP
+      HEADERS = { "Accept" => "application/json", "User-Agent" => "br_validators/#{VERSION}" }.freeze
+
+      # Problemas de rede: não conectou, a conexão caiu, demorou demais ou o
+      # certificado falhou. Viram Consulta::Erro, para quem chama tratar um erro só.
+      ERROS_DE_REDE = [Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError].freeze
+
+      def self.get(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = TIMEOUT
+        http.read_timeout = TIMEOUT
+        resposta = http.get(uri.request_uri, HEADERS)
+        [resposta.code.to_i, resposta.body]
+      rescue *ERROS_DE_REDE => e
+        raise Erro, "Não deu para falar com a BrasilAPI (#{e.class})."
+      end
+    end
+  end
+end

data/lib/br_validators/locale/en.yml

@@ -6,3 +6,10 @@ en:
       cns_invalid: "is not a valid CNS"
       pix_invalid: "is not a valid Pix key"
       boleto_invalid: "is not a valid boleto line"
+      cep_invalid: "is not a valid CEP"
+      telefone_invalid: "is not a valid phone number"
+      placa_invalid: "is not a valid license plate"
+      renavam_invalid: "is not a valid RENAVAM"
+      titulo_eleitor_invalid: "is not a valid voter ID"
+      processo_cnj_invalid: "is not a valid case number"
+      chave_acesso_invalid: "is not a valid access key"

data/lib/br_validators/locale/pt-BR.yml

@@ -6,3 +6,10 @@ pt-BR:
       cns_invalid: "não é um CNS válido"
       pix_invalid: "não é uma chave Pix válida"
       boleto_invalid: "não é uma linha digitável de boleto válida"
+      cep_invalid: "não é um CEP válido"
+      telefone_invalid: "não é um telefone válido"
+      placa_invalid: "não é uma placa válida"
+      renavam_invalid: "não é um RENAVAM válido"
+      titulo_eleitor_invalid: "não é um título de eleitor válido"
+      processo_cnj_invalid: "não é um número de processo válido"
+      chave_acesso_invalid: "não é uma chave de acesso válida"

data/lib/br_validators/placa.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Placa de veículo, nos dois modelos que circulam:
+  #
+  # - Antiga (cinza): 3 letras e 4 números, escrita "ABC-1234".
+  # - Mercosul: LLLNLNN (letra, letra, letra, número, letra, número, número),
+  #   escrita "ABC1D23".
+  #
+  # Para converter a placa antiga, troca-se só o quinto caractere (o segundo
+  # número) por uma letra: 0 vira A, 1 vira B... 9 vira J. Ex.: ABC-1234 → ABC1C34.
+  # As letras de A a J nessa posição existem justamente para essa conversão, e os
+  # dois formatos valem para buscar o mesmo veículo.
+  #
+  # Fonte: Resolução CONTRAN nº 780/2019, Anexo I (item 1.2) e Anexo II.
+  module Placa
+    ANTIGA = /\A[A-Z]{3}\d{4}\z/
+    MERCOSUL = /\A[A-Z]{3}\d[A-Z]\d{2}\z/
+
+    # Pontos, hífens e espaços.
+    MASK = /[.\-[:space:]]/
+
+    # Tira a máscara e passa as letras para maiúsculas: "abc-1234" vira "ABC1234".
+    # upcase(:ascii) e scrub estão explicados no CNPJ e no CPF.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "").upcase(:ascii)
+    end
+
+    # :antiga, :mercosul ou nil se a placa for inválida.
+    def self.type(value)
+      placa = strip(value)
+      return :antiga if placa.match?(ANTIGA)
+      return :mercosul if placa.match?(MERCOSUL)
+
+      nil
+    end
+
+    def self.valid?(value)
+      !type(value).nil?
+    end
+
+    # Devolve "ABC-1234" (antiga) ou "ABC1D23" (Mercosul), ou nil se for inválida.
+    def self.format(value)
+      placa = strip(value)
+      case type(placa)
+      when :antiga then "#{placa[0, 3]}-#{placa[3, 4]}"
+      when :mercosul then placa
+      end
+    end
+
+    # A placa no modelo Mercosul: converte a antiga e devolve a Mercosul como está.
+    #   mercosul("ABC-1234") # => "ABC1C34"
+    def self.mercosul(value)
+      placa = strip(value)
+      case type(placa)
+      when :antiga then placa[0, 4] + ("A".ord + placa[4].to_i).chr + placa[5, 2]
+      when :mercosul then placa
+      end
+    end
+
+    # A placa no modelo antigo: desfaz a conversão (só para letras de A a J na
+    # quinta posição) e devolve a antiga como está. Placa Mercosul emitida já no
+    # modelo novo, com outra letra, não tem placa antiga: devolve nil.
+    #   antiga("ABC1C34") # => "ABC1234"
+    def self.antiga(value)
+      placa = strip(value)
+      return placa if type(placa) == :antiga
+      return nil unless type(placa) == :mercosul && placa[4].between?("A", "J")
+
+      placa[0, 4] + (placa[4].ord - "A".ord).to_s + placa[5, 2]
+    end
+  end
+end

data/lib/br_validators/processo_cnj.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Número de processo judicial na numeração única do CNJ:
+  #
+  #   NNNNNNN-DD.AAAA.J.TR.OOOO  (20 dígitos)
+  #   NNNNNNN  número sequencial do processo no ano
+  #   DD       dígito verificador
+  #   AAAA     ano em que o processo começou
+  #   J        segmento do Judiciário (1 a 9, ver SEGMENTOS)
+  #   TR       tribunal dentro do segmento
+  #   OOOO     unidade de origem
+  #
+  # O dígito verificador usa módulo 97 (norma ISO 7064). Para conferir, junta-se
+  # NNNNNNN AAAA J TR OOOO e coloca-se o DD no fim; o número de 20 dígitos que sai
+  # dividido por 97 precisa deixar resto 1.
+  #
+  # Fonte: Resolução CNJ nº 65/2008, art. 1º e Anexo VIII.
+  # https://atos.cnj.jus.br/files/resolucao_comp_65_16122008_26032019140041.pdf
+  module ProcessoCNJ
+    SEGMENTOS = {
+      "1" => "Supremo Tribunal Federal",
+      "2" => "Conselho Nacional de Justiça",
+      "3" => "Superior Tribunal de Justiça",
+      "4" => "Justiça Federal",
+      "5" => "Justiça do Trabalho",
+      "6" => "Justiça Eleitoral",
+      "7" => "Justiça Militar da União",
+      "8" => "Justiça dos Estados e do Distrito Federal",
+      "9" => "Justiça Militar Estadual"
+    }.freeze
+
+    # Pontos, hífens e espaços.
+    MASK = /[.\-[:space:]]/
+
+    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "")
+    end
+
+    def self.valid?(value)
+      numero = strip(value)
+      return false unless numero.match?(/\A\d{20}\z/)
+      return false unless SEGMENTOS.key?(numero[13])
+
+      # NNNNNNN + AAAA J TR OOOO + DD
+      (numero[0, 7] + numero[9, 11] + numero[7, 2]).to_i % 97 == 1
+    end
+
+    # Devolve "0000123-45.2024.8.26.0100", ou nil se o número for inválido.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      numero = strip(value)
+      "#{numero[0, 7]}-#{numero[7, 2]}.#{numero[9, 4]}.#{numero[13]}.#{numero[14, 2]}.#{numero[16, 4]}"
+    end
+
+    # O nome do segmento do Judiciário ("Justiça do Trabalho"), ou nil se o número
+    # for inválido.
+    def self.segmento(value)
+      valid?(value) ? SEGMENTOS[strip(value)[13]] : nil
+    end
+  end
+end

data/lib/br_validators/renavam.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # RENAVAM (Registro Nacional de Veículos Automotores): 11 dígitos, sendo 10 de
+  # número e 1 dígito verificador.
+  #
+  # O dígito verificador usa módulo 11 com pesos de 2 a 9 ("peso 9"), da direita
+  # para a esquerda, voltando ao 2 depois do 9. Se o resto da divisão por 11 for
+  # 0 ou 1, o dígito é 0; senão, é 11 menos o resto.
+  #
+  # Os códigos antigos tinham 9 dígitos. Para validar um deles, complete com
+  # zeros à esquerda até ficar com 11 ("123456789" vira "00123456789"): os zeros
+  # não mudam a conta.
+  #
+  # Fonte: Portaria DENATRAN nº 27/2013 (11 dígitos, "dígito verificador,
+  # calculado através do módulo 11, peso 9"), válida desde abril de 2013.
+  module RENAVAM
+    # O RENAVAM não tem máscara oficial; aceitamos pontos, hífens e espaços.
+    MASK = /[.\-[:space:]]/
+
+    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "")
+    end
+
+    def self.valid?(value)
+      renavam = strip(value)
+      return false unless renavam.match?(/\A\d{11}\z/)
+
+      # 00000000000, 11111111111... não são códigos reais.
+      return false if renavam.squeeze.size == 1
+
+      renavam[10] == check_digit(renavam[0, 10])
+    end
+
+    # O RENAVAM não tem máscara: devolve os 11 dígitos, ou nil se for inválido.
+    def self.format(value)
+      valid?(value) ? strip(value) : nil
+    end
+
+    def self.check_digit(digits)
+      sum = digits.reverse.chars.each_with_index.sum { |digit, index| digit.to_i * ((index % 8) + 2) }
+      rest = sum % 11
+      (rest < 2 ? 0 : 11 - rest).to_s
+    end
+
+    private_class_method :check_digit
+  end
+end

data/lib/br_validators/telefone.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Telefone brasileiro, fixo ou celular, com DDD.
+  #
+  # - DDD: um dos 67 códigos nacionais da Anatel.
+  # - Celular: 9 dígitos começando com 9 (o "nono dígito", Resolução Anatel
+  #   553/2010).
+  # - Fixo: 8 dígitos começando com 2, 3, 4 ou 5 (faixa da telefonia fixa no
+  #   Regulamento de Numeração, Resolução Anatel 86/1998, art. 19, com a redação da
+  #   Resolução 553/2010; a 86/1998 foi revogada pela 749/2022 e os números em uso
+  #   continuam nesse formato).
+  #
+  # Aceita o código do país (+55) e o zero antes do DDD ("011..."). Não aceita o
+  # código da operadora (0 XX DDD ...) nem números especiais, como 0800 e 190.
+  #
+  # Fontes:
+  # - Lista dos 67 códigos nacionais (DDD): perguntas frequentes da Anatel sobre
+  #   áreas locais, 2026.
+  #   https://sistemas.anatel.gov.br/anexar-api/publico/anexos/download/a8c6650c72539ff2334c327ab5c169e4
+  # - Resolução 86/1998 (Regulamento de Numeração do STFC) e Resolução 553/2010.
+  module Telefone
+    # Os 67 DDDs em uso. Os que faltam na sequência (20, 23, 25, 26, 29, 30,
+    # 36, 39, 40, 50, 52, 56 a 60, 70, 72, 76, 78, 80 e 90) não existem.
+    DDDS = %w[
+      11 12 13 14 15 16 17 18 19
+      21 22 24 27 28
+      31 32 33 34 35 37 38
+      41 42 43 44 45 46 47 48 49
+      51 53 54 55
+      61 62 63 64 65 66 67 68 69
+      71 73 74 75 77 79
+      81 82 83 84 85 86 87 88 89
+      91 92 93 94 95 96 97 98 99
+    ].freeze
+
+    CELULAR = /\A9\d{8}\z/
+    FIXO = /\A[2-5]\d{7}\z/
+
+    # Parênteses, "+", pontos, hífens e espaços.
+    MASK = /[()+.\-[:space:]]/
+
+    # Tira a máscara: "+55 (11) 98765-4321" vira "5511987654321".
+    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "")
+    end
+
+    # :celular, :fixo ou nil se o número for inválido.
+    def self.type(value)
+      numero = nacional(value)
+      return nil unless numero && DDDS.include?(numero[0, 2])
+
+      assinante = numero[2..]
+      return :celular if assinante.match?(CELULAR)
+      return :fixo if assinante.match?(FIXO)
+
+      nil
+    end
+
+    def self.valid?(value)
+      !type(value).nil?
+    end
+
+    # Devolve "(11) 98765-4321" ou "(11) 3456-7890", ou nil se for inválido.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      numero = nacional(value)
+      "(#{numero[0, 2]}) #{numero[2...-4]}-#{numero[-4..]}"
+    end
+
+    # O DDD ("11"), ou nil se o número for inválido.
+    def self.ddd(value)
+      valid?(value) ? nacional(value)[0, 2] : nil
+    end
+
+    # O número só com DDD e assinante (10 ou 11 dígitos), sem o código do país
+    # (55) nem o zero antes do DDD. Devolve nil se não sobrar um número desse tamanho.
+    def self.nacional(value)
+      digits = strip(value)
+      return nil unless digits.match?(/\A\d+\z/)
+
+      # Com o código do país: 55 + 10 ou 11 dígitos.
+      digits = digits.delete_prefix("55") if digits.start_with?("55") && digits.size.between?(12, 13)
+      # O DDD nunca começa com 0; um zero na frente é o prefixo de chamada nacional.
+      digits = digits.delete_prefix("0") if digits.start_with?("0")
+
+      digits.size.between?(10, 11) ? digits : nil
+    end
+
+    private_class_method :nacional
+  end
+end

data/lib/br_validators/titulo_eleitor.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module BrValidators
+  # Título de eleitor: 12 dígitos.
+  #   - 8 primeiros: número sequencial;
+  #   - 9º e 10º: código da UF onde foi emitido (01 a 28; 28 é o exterior, "ZZ");
+  #   - 11º e 12º: dígitos verificadores.
+  #
+  # 1º dígito: soma dos 8 primeiros com pesos de 2 a 9, da esquerda para a
+  # direita; o dígito é o resto da divisão por 11.
+  # 2º dígito: soma dos 2 dígitos da UF e do 1º dígito, com pesos 7, 8 e 9;
+  # também é o resto da divisão por 11.
+  # Nos dois casos, resto 10 vira 0. Em títulos de São Paulo (01) e Minas Gerais
+  # (02), resto 0 vira 1.
+  #
+  # Alguns títulos antigos de SP e MG têm 13 dígitos (9 no número sequencial).
+  # Eles não são aceitos aqui: a regra pública só cobre os de 12.
+  #
+  # Fonte: o TSE não publica o cálculo. A regra é a usada pelos sistemas e
+  # explicada pela OBMEP em "A Matemática nos Documentos: Título de Eleitor".
+  # https://clubes.obmep.org.br/blog/a-matematica-nos-documentos-titulo-de-eleitor/
+  module TituloEleitor
+    UFS = {
+      "01" => "SP", "02" => "MG", "03" => "RJ", "04" => "RS", "05" => "BA", "06" => "PR",
+      "07" => "CE", "08" => "PE", "09" => "SC", "10" => "GO", "11" => "MA", "12" => "PB",
+      "13" => "PA", "14" => "ES", "15" => "PI", "16" => "RN", "17" => "AL", "18" => "MT",
+      "19" => "MS", "20" => "DF", "21" => "SE", "22" => "AM", "23" => "RO", "24" => "AC",
+      "25" => "AP", "26" => "RR", "27" => "TO", "28" => "ZZ"
+    }.freeze
+
+    # O título impresso mostra o número em grupos separados por espaço.
+    MASK = %r{[./\-[:space:]]}
+
+    # O scrub está explicado no CPF: texto corrompido vira inválido, sem erro.
+    def self.strip(value)
+      value.to_s.scrub.gsub(MASK, "")
+    end
+
+    def self.valid?(value)
+      titulo = strip(value)
+      return false unless titulo.match?(/\A\d{12}\z/)
+
+      uf = titulo[8, 2]
+      return false unless UFS.key?(uf)
+
+      first = check_digit(weighted_sum(titulo[0, 8], 2..9), uf)
+      second = check_digit(weighted_sum("#{uf}#{first}", 7..9), uf)
+      titulo[10, 2] == "#{first}#{second}"
+    end
+
+    # Devolve "1023 8501 0671", ou nil se o título for inválido.
+    def self.format(value)
+      return nil unless valid?(value)
+
+      titulo = strip(value)
+      "#{titulo[0, 4]} #{titulo[4, 4]} #{titulo[8, 4]}"
+    end
+
+    # A sigla da UF onde o título foi emitido ("SP", "ZZ" para o exterior), ou nil.
+    def self.uf(value)
+      valid?(value) ? UFS[strip(value)[8, 2]] : nil
+    end
+
+    def self.weighted_sum(digits, weights)
+      digits.chars.zip(weights.to_a).sum { |digit, weight| digit.to_i * weight }
+    end
+
+    # codigo_uf: "01" (SP) e "02" (MG) têm a regra especial do resto 0.
+    def self.check_digit(sum, codigo_uf)
+      rest = sum % 11
+      return 1 if rest.zero? && %w[01 02].include?(codigo_uf)
+
+      rest == 10 ? 0 : rest
+    end
+
+    private_class_method :weighted_sum, :check_digit
+  end
+end

data/lib/br_validators/validators/cep_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :cep, cep: true
+class CepValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::CEP
+  ERROR = :cep_invalid
+end

data/lib/br_validators/validators/chave_acesso_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :chave_nfe, chave_acesso: true
+class ChaveAcessoValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::ChaveAcesso
+  ERROR = :chave_acesso_invalid
+end

data/lib/br_validators/validators/placa_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :placa, placa: true
+class PlacaValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::Placa
+  ERROR = :placa_invalid
+end

data/lib/br_validators/validators/processo_cnj_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :processo, processo_cnj: true
+class ProcessoCnjValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::ProcessoCNJ
+  ERROR = :processo_cnj_invalid
+end

data/lib/br_validators/validators/renavam_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :renavam, renavam: true
+class RenavamValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::RENAVAM
+  ERROR = :renavam_invalid
+end

data/lib/br_validators/validators/telefone_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :celular, telefone: true
+class TelefoneValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::Telefone
+  ERROR = :telefone_invalid
+end

data/lib/br_validators/validators/titulo_eleitor_validator.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# validates :titulo, titulo_eleitor: true
+class TituloEleitorValidator < BrValidators::DocumentValidator
+  DOCUMENT = BrValidators::TituloEleitor
+  ERROR = :titulo_eleitor_invalid
+end

data/lib/br_validators/version.rb

@@ -2,5 +2,5 @@
 
 # Versão da gem, lida também pelo gemspec.
 module BrValidators
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/br_validators.rb

@@ -6,6 +6,13 @@ require_relative "br_validators/cnpj"
 require_relative "br_validators/cns"
 require_relative "br_validators/pix"
 require_relative "br_validators/boleto"
+require_relative "br_validators/cep"
+require_relative "br_validators/telefone"
+require_relative "br_validators/placa"
+require_relative "br_validators/renavam"
+require_relative "br_validators/titulo_eleitor"
+require_relative "br_validators/processo_cnj"
+require_relative "br_validators/chave_acesso"
 
 # Validação e formatação de documentos brasileiros.
 #
@@ -15,7 +22,9 @@ require_relative "br_validators/boleto"
 #   format(valor)  -> o documento com a máscara, ou nil se for inválido
 #   strip(valor)   -> o documento sem a máscara
 # A chave Pix é a exceção: tem valid? e type, mas não format nem strip, porque
-# precisa estar exatamente como o Banco Central guarda. Pix e Boleto têm type.
+# precisa estar exatamente como o Banco Central guarda.
+# Alguns têm métodos a mais: type (Pix, Boleto, Telefone, Placa), uf (TituloEleitor),
+# segmento (ProcessoCNJ), modelo (ChaveAcesso), ddd (Telefone), mercosul e antiga (Placa).
 module BrValidators
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: br_validators
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Pedro Pedrassolli
@@ -21,17 +21,32 @@ files:
 - lib/br_validators.rb
 - lib/br_validators/active_model.rb
 - lib/br_validators/boleto.rb
+- lib/br_validators/cep.rb
+- lib/br_validators/chave_acesso.rb
 - lib/br_validators/cnpj.rb
 - lib/br_validators/cns.rb
+- lib/br_validators/consulta.rb
 - lib/br_validators/cpf.rb
 - lib/br_validators/locale/en.yml
 - lib/br_validators/locale/pt-BR.yml
 - lib/br_validators/pix.rb
+- lib/br_validators/placa.rb
+- lib/br_validators/processo_cnj.rb
+- lib/br_validators/renavam.rb
+- lib/br_validators/telefone.rb
+- lib/br_validators/titulo_eleitor.rb
 - lib/br_validators/validators/boleto_validator.rb
+- lib/br_validators/validators/cep_validator.rb
+- lib/br_validators/validators/chave_acesso_validator.rb
 - lib/br_validators/validators/cnpj_validator.rb
 - lib/br_validators/validators/cns_validator.rb
 - lib/br_validators/validators/cpf_validator.rb
 - lib/br_validators/validators/pix_validator.rb
+- lib/br_validators/validators/placa_validator.rb
+- lib/br_validators/validators/processo_cnj_validator.rb
+- lib/br_validators/validators/renavam_validator.rb
+- lib/br_validators/validators/telefone_validator.rb
+- lib/br_validators/validators/titulo_eleitor_validator.rb
 - lib/br_validators/version.rb
 homepage: https://github.com/PedroPedrassolli/br_validators
 licenses:
@@ -57,5 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Valida e formata CPF, CNPJ (inclusive alfanumérico), CNS, chave Pix e boleto.
+summary: 'Valida e formata documentos brasileiros: CPF, CNPJ alfanumérico, CNS, Pix,
+  boleto, CEP, telefone, placa, RENAVAM, título de eleitor, chave de NF-e e processo
+  do CNJ.'
 test_files: []