sat_rfc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d546b4ca5245b4d86c98325bf2872a14268e945b8b51c0f6bee2c26e7dc9b1af
-  data.tar.gz: 6e129b4c04bfc6bb2ec397609bc408c8368094a49bc4a292fb561ff0f9bc9088
+  metadata.gz: d4c2e78c0e8c7490a0cc48c4f10c775d7061e6734ca28502c8c01d28ab8fd193
+  data.tar.gz: d192b112b798c0a9337d3261b61627e481630e3f5420d9748bd042212a8021a0
 SHA512:
-  metadata.gz: 69a47948fcfa654cacfe91d7abd919704b44be4e3fa1690a078ca48a90dec715e5635b9781103b4e3f5e8944b891063361746567b9368d14ad2267e64411fcb9
-  data.tar.gz: 928596bf9a5c0fcfd3426b839e8db8254e90c76b892ed785159a688e3d721ccc0771308f057fd04ea06daacf76e52fbd8be5cdf04a9b65c667be073e695180d6
+  metadata.gz: 4f6469fc80b3cd16c0a5b007bc04970217af152a220675a73054887b1f2392b65593f875a6c36c933372acf6debd6098b1dd4706bfe1a913b9a8fb3aab04702b
+  data.tar.gz: 6e4eb8bb3fe4548f46959ac830bae2701c67e21e1bbeee5e913fe5b5b34a0fcbde88a289ed09becb8764ccecd32bde5d9d952607528075d88e8f90636b4a516c

data/README.md

@@ -1,8 +1,6 @@
 # sat_rfc
 
-Ruby gem to generate Mexican **RFC** tax identifiers for **natural persons** (personas físicas), following the [SAT](https://www.sat.gob.mx/) algorithm.
-
-Legal entity support (personas morales) is planned for a future release.
+Ruby gem to generate Mexican **RFC** tax identifiers for **natural persons** (personas físicas) and **legal entities** (personas morales), following the SAT algorithm documented by the IFAI (Instituto Federal de Acceso a la Información). Natural person support is inspired by [rfc-facil](https://github.com/josketres/rfc-facil) and [rfc_facil](https://github.com/acrogenesis/rfc_facil).
 
 ## Installation
 
@@ -39,6 +37,32 @@ rfc = Rfc::Generator.new.for_natural_person(
 puts rfc # => "PEGJ900315PE9"
 ```
 
+To inspect individual RFC parts, use the calculators directly:
+
+```ruby
+name = "Juan Carlos"
+first_last_name = "Perez"
+second_last_name = "Garcia"
+
+ten_digits = Rfc::NaturalTenDigitsCodeCalculator.new(
+  name: name,
+  first_last_name: first_last_name,
+  second_last_name: second_last_name,
+  day: 15, month: 3, year: 1990
+).calculate
+# => "PEGJ900315"
+
+homoclave = Rfc::HomoclaveCalculator.new(
+  name: name,
+  first_last_name: first_last_name,
+  second_last_name: second_last_name
+).calculate
+# => "PE"
+
+verification_digit = Rfc::VerificationDigitCalculator.new("#{ten_digits}#{homoclave}").calculate
+# => "9"
+```
+
 You can also pass the birth date as separate values:
 
 ```ruby
@@ -54,6 +78,37 @@ Rfc::Generator.new.for_natural_person(
 
 `date_of_birth` accepts `DD/MM/YYYY` format or any string parseable by Ruby's `Date`.
 
+### Legal entity (persona moral)
+
+```ruby
+rfc = Rfc::Generator.new.for_legal_entity(
+  legal_name: "Mu Networks S.A.P.I. de C.V.",
+  constitution_date: "10/07/2014"
+)
+
+puts rfc # => "MNP1407108U7"
+```
+
+To inspect individual RFC parts:
+
+```ruby
+legal_name = "Mu Networks S.A.P.I. de C.V."
+
+ten_digits = Rfc::LegalEntityTenDigitsCodeCalculator.new(
+  legal_name: legal_name,
+  day: 10, month: 7, year: 2014
+).calculate
+# => "MNP140710"
+
+homoclave = Rfc::HomoclaveCalculator.new(legal_name: legal_name).calculate
+# => "8U"
+
+verification_digit = Rfc::VerificationDigitCalculator.new("#{ten_digits}#{homoclave}").calculate
+# => "7"
+```
+
+`constitution_date` accepts `DD/MM/YYYY` format or any string parseable by Ruby's `Date`.
+
 ### Errors
 
 ```ruby
@@ -83,6 +138,19 @@ Rfc::Generator.new.for_natural_person(
 )
 ```
 
+## Algorithm reference
+
+This gem implements the RFC generation algorithm with homoclave for natural persons and legal entities, based on official documentation obtained through the IFAI.
+
+- **INFOMEX folio:** `0610100135506`
+- **Document:** [Algoritmo para generar el RFC con homoclave para personas físicas y morales (PDF)](https://www.mariovaldez.net/files/IFAI%200610100135506%20065%20Algoritmo%20para%20generar%20el%20RFC%20con%20homoclave%20para%20personas%20fisicas%20y%20morales.pdf)
+
+## Acknowledgments
+
+### Natural person (persona física)
+
+Natural person support is inspired by [rfc-facil](https://github.com/josketres/rfc-facil) by [josketres](https://github.com/josketres) and [rfc_facil](https://github.com/acrogenesis/rfc_facil) by [acrogenesis](https://github.com/acrogenesis), following the SAT algorithm documented by the IFAI.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [elosnaya/rfc](https://github.com/elosnaya/rfc).

data/lib/rfc/discardable_terms/legal_entity.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rfc
+  module DiscardableTerms
+    # Dictionary of discardable terms for legal entities (personas morales).
+    # Based on SAT specification.
+    #
+    # After normalization, terms like "S.A. de C.V." become "SA DE CV" (separate words),
+    # so individual abbreviations and words are listed here.
+    module LegalEntity
+      ARTICLES_AND_PREPOSITIONS = %w[
+        DE LA LAS DEL LOS Y EL
+        PARA POR AL E EN CON SUS
+        OF THE AND
+      ].freeze
+
+      COMPANY_TYPE_ABBREVIATIONS = %w[
+        SA SC SRL SCL SNC SCS CIA COOP SOC CO COMPANY
+        CV RL
+      ].freeze
+
+      SINGLE_LETTER_ABBREVIATIONS = %w[S A C V].freeze
+
+      COMPANY_TYPE_WORDS = %w[
+        COMPAÑIA SOCIEDAD COOPERATIVA
+        ANONIMA COMANDITA RESPONSABILIDAD LIMITADA
+        PROMOTORA INVERSION CAPITAL VARIABLE NOMBRE COLECTIVO
+      ].freeze
+
+      DISCARDABLE_TERMS = %w[MC VON MAC VAN MI].freeze
+
+      ALL = (
+        ARTICLES_AND_PREPOSITIONS +
+        COMPANY_TYPE_ABBREVIATIONS +
+        SINGLE_LETTER_ABBREVIATIONS +
+        COMPANY_TYPE_WORDS +
+        DISCARDABLE_TERMS
+      ).freeze
+    end
+  end
+end

data/lib/rfc/generator.rb

@@ -8,10 +8,12 @@ module Rfc
 
     def initialize(
       natural_ten_digits_calculator: NaturalTenDigitsCodeCalculator,
+      legal_entity_ten_digits_calculator: LegalEntityTenDigitsCodeCalculator,
       homoclave_calculator: HomoclaveCalculator,
       verification_digit_calculator: VerificationDigitCalculator
     )
       @natural_ten_digits_calculator = natural_ten_digits_calculator
+      @legal_entity_ten_digits_calculator = legal_entity_ten_digits_calculator
       @homoclave_calculator = homoclave_calculator
       @verification_digit_calculator = verification_digit_calculator
     end
@@ -47,6 +49,29 @@ module Rfc
       raise InvalidDateError, "Invalid date parameters: #{e.message}"
     end
 
+    def for_legal_entity(
+      legal_name:,
+      day: nil,
+      month: nil,
+      year: nil,
+      constitution_date: nil
+    )
+      normalized_day, normalized_month, normalized_year = normalize_date(day, month, year, constitution_date)
+
+      ten_digits_code = @legal_entity_ten_digits_calculator.new(
+        legal_name: legal_name,
+        day: normalized_day,
+        month: normalized_month,
+        year: normalized_year
+      ).calculate
+
+      homoclave = @homoclave_calculator.new(legal_name: legal_name).calculate
+
+      build_rfc(ten_digits_code, homoclave)
+    rescue ArgumentError => e
+      raise InvalidDateError, "Invalid date parameters: #{e.message}"
+    end
+
     private
 
     def build_rfc(ten_digits_code, homoclave)

data/lib/rfc/homoclave_calculator.rb

@@ -15,10 +15,11 @@ module Rfc
       "Y" => "38", "Z" => "39", "Ñ" => "40"
     }.freeze
 
-    def initialize(name:, first_last_name:, second_last_name:)
+    def initialize(name: nil, first_last_name: nil, second_last_name: nil, legal_name: nil)
       @name = name
       @first_last_name = first_last_name
       @second_last_name = second_last_name
+      @legal_name = legal_name
     end
 
     def calculate
@@ -73,9 +74,15 @@ module Rfc
     end
 
     def full_name_string
+      return @legal_name if present?(@legal_name)
+
       "#{@first_last_name} #{@second_last_name} #{@name}"
     end
 
+    def present?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+
     def add_missing_char_to_full_name(raw_full_name, missing_char)
       index = raw_full_name.index(missing_char)
       until index.nil?

data/lib/rfc/legal_entity_ten_digits_code_calculator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "i18n"
+
+module Rfc
+  class LegalEntityTenDigitsCodeCalculator
+    DISCARDABLE_TERMS = DiscardableTerms::LegalEntity::ALL
+
+    def initialize(legal_name:, day:, month:, year:)
+      @legal_name = legal_name
+      @day = day
+      @month = month
+      @year = year
+    end
+
+    def calculate
+      name_code + birthday_code
+    end
+
+    private
+
+    def name_code
+      normalized_name = normalize(@legal_name)
+      all_words = normalized_name.split(/\s+/).reject(&:empty?)
+      significant_words = all_words.reject { |word| DISCARDABLE_TERMS.include?(word) }
+
+      words_to_use = significant_words.empty? ? all_words : significant_words
+
+      case words_to_use.length
+      when 0
+        raise ArgumentError, "Legal name is blank or invalid"
+      when 1
+        words_to_use[0][0..2]
+      when 2
+        "#{words_to_use[0][0]}#{words_to_use[1][0..1]}"
+      else
+        "#{words_to_use[0][0]}#{words_to_use[1][0]}#{words_to_use[2][0]}"
+      end
+    end
+
+    def birthday_code
+      "#{last_two_digits_of(@year)}#{formatted_in_two_digits(@month)}#{formatted_in_two_digits(@day)}"
+    end
+
+    def normalize(legal_name)
+      return legal_name if legal_name.nil? || legal_name.empty?
+
+      normalized = I18n.transliterate(legal_name).upcase
+      normalized.gsub(/[^A-Z0-9\s]/, " ")
+    end
+
+    def formatted_in_two_digits(number)
+      format("%02d", number)
+    end
+
+    def last_two_digits_of(number)
+      formatted_in_two_digits(number % 100)
+    end
+  end
+end

data/lib/rfc/natural_ten_digits_code_calculator.rb

@@ -81,7 +81,11 @@ module Rfc
     end
 
     def filter_name(name)
-      normalize(name).strip.sub(/^(MA|MA\.|MARIA|JOSE)\s+/, "")
+      return name if name.nil? || name.empty?
+
+      normalized = I18n.transliterate(name).upcase.strip
+      normalized = normalized.sub(/^(MA|MA\.|MARIA|JOSE)\s+/, "")
+      remove_discardable_terms(normalized, DISCARDABLE_TERMS)
     end
 
     def first_letter_of(word)

data/lib/rfc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rfc
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/sat_rfc.rb

@@ -7,9 +7,11 @@ I18n.default_locale = :en
 
 require_relative "rfc/version"
 require_relative "rfc/discardable_terms/natural_person"
+require_relative "rfc/discardable_terms/legal_entity"
 require_relative "rfc/verification_digit_calculator"
 require_relative "rfc/homoclave_calculator"
 require_relative "rfc/natural_ten_digits_code_calculator"
+require_relative "rfc/legal_entity_ten_digits_code_calculator"
 
 module Rfc
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sat_rfc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - elOsnaya
@@ -24,8 +24,10 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 description: Ruby library that generates RFC tax identifiers for Mexican natural persons
-  using the SAT algorithm. Supports name normalization, homoclave, and verification
-  digit calculation.
+  and legal entities using the SAT algorithm documented by the IFAI (INFOMEX folio
+  0610100135506). Natural person support is inspired by rfc-facil (josketres) and
+  rfc_facil (acrogenesis). Legal entity support is an original implementation by elOsnaya.
+  Supports name normalization, homoclave, and verification digit calculation.
 email:
 - luisosnet@gmail.com
 executables: []
@@ -36,9 +38,11 @@ files:
 - README.md
 - Rakefile
 - lib/rfc.rb
+- lib/rfc/discardable_terms/legal_entity.rb
 - lib/rfc/discardable_terms/natural_person.rb
 - lib/rfc/generator.rb
 - lib/rfc/homoclave_calculator.rb
+- lib/rfc/legal_entity_ten_digits_code_calculator.rb
 - lib/rfc/natural_ten_digits_code_calculator.rb
 - lib/rfc/verification_digit_calculator.rb
 - lib/rfc/version.rb
@@ -50,6 +54,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/elosnaya/rfc
   source_code_uri: https://github.com/elosnaya/rfc
+  documentation_uri: https://www.mariovaldez.net/files/IFAI%200610100135506%20065%20Algoritmo%20para%20generar%20el%20RFC%20con%20homoclave%20para%20personas%20fisicas%20y%20morales.pdf
 rdoc_options: []
 require_paths:
 - lib
@@ -66,5 +71,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Generate Mexican RFC codes for natural persons (personas físicas).
+summary: Generate Mexican RFC codes for natural persons and legal entities.
 test_files: []