Steuer

A Ruby gem for German tax system utilities, including Steuernummer (tax number) conversion between different formats and validation.

Based on the official specifications from the German Wikipedia page on Steuernummer.

• Format Detection: Automatically detects the format of German tax numbers
• Format Conversion: Convert between three different formats:
  • Standard scheme (state-specific format, e.g., 93/815/08152)
  • Unified federal scheme (12-digit, e.g., 289381508152)
  • Unified federal scheme for electronic transmission (13-digit, e.g., 2893081508152)
• State Detection: Automatically detects the German state (Bundesland) from tax numbers
• Validation: Validates tax numbers according to official patterns
• Object-Oriented: Clean, object-oriented API design
• Extensible: Designed to be extended with additional German tax utilities (VAT validation, etc.)

Add this line to your application's Gemfile:

gem 'steuer'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install steuer

require 'steuer'

# Create a tax number object (auto-detects state from unambiguous formats)
tax_number = Steuer.steuernummer('93/815/08152')  # Auto-detects Baden-Württemberg

# Check if valid
puts tax_number.valid?  # => true

# Get information
puts tax_number.state_code    # => "BW"
puts tax_number.state_name    # => "Baden-Württemberg"
puts tax_number.format_type   # => :standard

# Convert between formats
puts tax_number.to_federal_12  # => "289381508152"
puts tax_number.to_federal_13  # => "2893081508152"
puts tax_number.to_standard    # => "93/815/08152"

# ✅ Auto-detects from standard format (each state has unique pattern)
standard = Steuer.steuernummer('181/815/08155')  # Auto-detects Bayern
puts standard.state_code  # => "BY"

# ✅ Auto-detects from unambiguous federal prefixes
federal_12 = Steuer.steuernummer('289381508152')  # Prefix '28' is unique to BW
puts federal_12.state_name  # => "Baden-Württemberg"

# ❌ Requires explicit state for ambiguous prefixes
begin
  Steuer.steuernummer('304881508155')  # Prefix '3' shared by BB, SN, ST
rescue Steuer::UnsupportedStateError => e
  puts e.message  # => "Cannot determine state from tax number..."
end

# ✅ Works with explicit state for ambiguous cases
ambiguous = Steuer.steuernummer('304881508155', state: 'BB')
puts ambiguous.state_code  # => "BB"

✅ Unambiguous prefixes (auto-detected):

• 28 → Baden-Württemberg
• 9 → Bayern
• 11 → Berlin
• 24 → Bremen
• 22 → Hamburg
• 26 → Hessen
• 23 → Niedersachsen
• 5 → Nordrhein-Westfalen
• 27 → Rheinland-Pfalz
• 1 → Saarland
• 21 → Schleswig-Holstein

❌ Ambiguous prefixes (require explicit state):

• 3 → Brandenburg, Sachsen, or Sachsen-Anhalt
• 4 → Mecklenburg-Vorpommern or Thüringen

begin
  # Invalid format
  Steuer.steuernummer('invalid')
rescue Steuer::InvalidTaxNumberError => e
  puts "Invalid format: #{e.message}"
end

begin
  # Unsupported state or undetectable
  Steuer.steuernummer('99/999/99999')
rescue Steuer::UnsupportedStateError => e
  puts "Unsupported state: #{e.message}"
end

The gem supports all 16 German states (Bundesländer):

Creates a new Steuer::Steuernummer object.

Parameters:

• tax_number (String): The tax number in any supported format
• state_code (String, optional): The German state code (auto-detected if not provided)

Returns: Steuer::Steuernummer instance

• valid? - Returns true if the tax number is valid
• to_federal_12 - Converts to 12-digit unified federal scheme
• to_federal_13 - Converts to 13-digit electronic transmission format
• to_standard - Converts to standard state-specific format
• state_code - Returns the German state code (e.g., "BW")
• state_name - Returns the full state name (e.g., "Baden-Württemberg")
• format_type - Returns the detected format (:standard, :federal_12, or :federal_13)
• original_input - Returns the original input string

After checking out the repo, run:

bundle install

To run the tests:

bundle exec rspec

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

This gem is designed to be extensible. Planned features include:

• German VAT number validation
• Steuer-ID (tax identification number) handling
• Wirtschafts-Identifikationsnummer support
• Additional German tax system utilities

• German Steuernummer Wikipedia Page
• Bundeszentralamt für Steuern

The gem is available as open source under the terms of the MIT License.