Module: BrazilianUtils::LegalProcessUtils

Defined in:
lib/brazilian-utils/legal-process-utils.rb

Overview

Utilities for formatting, validating, and generating Brazilian Legal Process IDs.

A legal process ID (Número de Processo Judicial) is a 20-digit code that identifies a legal case in the Brazilian judiciary system. The format is: NNNNNNN-DD.AAAA.J.TR.OOOO

Where:

  • NNNNNNN: Sequential number (7 digits)
  • DD: Verification digits (2 digits) - checksum
  • AAAA: Year the process was filed (4 digits)
  • J: Judicial segment (1 digit) - Orgão
  • TR: Court (2 digits) - Tribunal
  • OOOO: Court of origin (4 digits) - Foro

This module does not verify if a legal process ID corresponds to a real case; it only validates the format and structure of the ID.

Constant Summary collapse

DATA_FILE =

Path to the JSON file containing valid tribunal and foro IDs

File.join(File.dirname(__FILE__), 'data', 'legal_process_ids.json')

Class Method Summary collapse

Class Method Details

Formats a legal process ID into the standard format.

Takes a 20-digit string and formats it as: NNNNNNN-DD.AAAA.J.TR.OOOO

Examples:

format_legal_process("12345678901234567890")
#=> "1234567-89.0123.4.56.7890"

format_legal_process("98765432109876543210")
#=> "9876543-21.0987.6.54.3210"

format_legal_process("123")
#=> nil

Parameters:

  • legal_process_id (String) —

    A 20-digit string representing the legal process ID

Returns:

  • (String, nil) —

    The formatted legal process ID, or nil if the input is invalid



65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/brazilian-utils/legal-process-utils.rb', line 65

def self.format_legal_process(legal_process_id)
  return nil unless legal_process_id.is_a?(String)
  return nil unless legal_process_id =~ /^\d{20}$/

  # Extract fields: NNNNNNN DD AAAA J TR OOOO
  nnnnnnn = legal_process_id[0, 7]
  dd = legal_process_id[7, 2]
  aaaa = legal_process_id[9, 4]
  j = legal_process_id[13, 1]
  tr = legal_process_id[14, 2]
  oooo = legal_process_id[16, 4]

  "#{nnnnnnn}-#{dd}.#{aaaa}.#{j}.#{tr}.#{oooo}"
end

.generate(year = Time.now.year, orgao = nil) ⇒ String?

Generates a random legal process ID.

Examples:

generate(2023, 5)
#=> "51659517020235080562" (example, actual value is random)

generate()
#=> "88031888120233030000" (uses current year and random orgao)

generate(year: 2023, court: 5)
#=> "51659517020235080562" (contract-style options Hash)

generate(2022, 10)
#=> nil (year in the past, orgao out of range)

Parameters:

  • year (Integer, Hash) (defaults to: Time.now.year) —

    The year for the legal process ID (default is current year), or a single options Hash (as the contract's GenerateProcessoJuridicoParams) with :year and :court. The year should not be in the past.

  • orgao (Integer) (defaults to: nil) —

    The judicial segment code (1-9) for the legal process ID (default is random). Ignored when year is a Hash.

Returns:

  • (String, nil) —

    A randomly generated legal process ID (20 digits), or nil if arguments are invalid



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/brazilian-utils/legal-process-utils.rb', line 156

def self.generate(year = Time.now.year, orgao = nil)
  if year.is_a?(Hash)
    options = year
    year = options[:year] || options['year'] || Time.now.year
    orgao = options[:court] || options[:orgao] || options['court'] || options['orgao']
  end
  orgao ||= rand(1..9)

  return nil if year < Time.now.year
  return nil unless (1..9).include?(orgao)

  data = load_legal_process_data
  return nil unless data

  orgao_data = data["orgao_#{orgao}"]
  return nil unless orgao_data

  # Get random tribunal and foro
  tribunals = orgao_data['id_tribunal']
  foros = orgao_data['id_foro']
  
  tr = tribunals[rand(tribunals.length)].to_s.rjust(2, '0')
  oooo = foros[rand(foros.length)].to_s.rjust(4, '0')
  
  # Generate random sequential number
  nnnnnnn = rand(0..9999999).to_s.rjust(7, '0')
  
  # Calculate checksum
  base_for_checksum = nnnnnnn + year.to_s + orgao.to_s + tr + oooo
  dd = checksum(base_for_checksum.to_i)
  
  "#{nnnnnnn}#{dd}#{year}#{orgao}#{tr}#{oooo}"
end

.is_valid(legal_process_id) ⇒ Boolean Also known as: valid?

Checks if a legal process ID is valid.

This function validates:

  1. The format (20 digits)
  2. The checksum (DD verification digits)
  3. The tribunal (TR) and foro (OOOO) combination against the official table

This function does not verify if the legal process ID corresponds to a real case; it only validates the format and structure of the ID.

Examples:

is_valid("68476506020233030000")
#=> true

is_valid("5180823-36.2023.3.03.0000")
#=> true

is_valid("123")
#=> false

Parameters:

  • legal_process_id (String) —

    A digit-only or formatted string representing the legal process ID

Returns:

  • (Boolean) —

    Returns true if the legal process ID is valid, false otherwise



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/brazilian-utils/legal-process-utils.rb', line 104

def self.is_valid(legal_process_id)
  return false unless legal_process_id.is_a?(String)

  clean_id = remove_symbols(legal_process_id)
  return false unless clean_id =~ /^\d{20}$/

  # Extract fields
  nnnnnnn = clean_id[0, 7]
  dd = clean_id[7, 2]
  aaaa = clean_id[9, 4]
  j = clean_id[13, 1]
  tr = clean_id[14, 2]
  oooo = clean_id[16, 4]

  # Validate checksum
  base_for_checksum = nnnnnnn + aaaa + j + tr + oooo
  expected_dd = checksum(base_for_checksum.to_i)
  return false unless dd == expected_dd

  # Validate tribunal and foro against JSON data
  validate_tribunal_and_foro(j.to_i, tr.to_i, oooo.to_i)
end

.parse(value) ⇒ String

Removes legal process formatting and keeps only digits, capped to 20 digits.

Examples:

parse("0002080-25.2012.5.15.0049")  #=> "00020802520125150049"
parse("00020802520125150049123")    #=> "00020802520125150049"

Parameters:

  • value (String, Integer) —

    A legal process number, with or without the CNJ mask.

Returns:

  • (String) —

    The parsed digits.



264
265
266
267
268
 
# File 'lib/brazilian-utils/legal-process-utils.rb', line 264

def self.parse(value)
  return '' unless value.is_a?(String) || value.is_a?(Integer)

  value.to_s.gsub(/\D/, '')[0, 20]
end

.remove_symbols(legal_process) ⇒ String

Removes specific symbols (dots and hyphens) from a legal process ID.

This function takes a legal process ID as input and removes all occurrences of the '.' and '-' characters from it.

Examples:

remove_symbols("123.45-678.901.234-56.7890")
#=> "12345678901234567890"

remove_symbols("9876543-21.0987.6.54.3210")
#=> "98765432109876543210"

remove_symbols("1234567890123456789012345")
#=> "1234567890123456789012345"

Parameters:

  • legal_process (String) —

    A legal process ID containing symbols to be removed

Returns:

  • (String) —

    The legal process ID string with the specified symbols removed



42
43
44
45
46
 
# File 'lib/brazilian-utils/legal-process-utils.rb', line 42

def self.remove_symbols(legal_process)
  return '' unless legal_process.is_a?(String)
  
  legal_process.gsub('.', '').gsub('-', '')
end