steuer 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecfb962a41af7819208aaf3938a9534f9c80b17ccb596e96dfaf0fb02a267d15
-  data.tar.gz: 7a6c99cd8e357c641d55dfc3be85e9ada4425b62b00e12e0890b5510c0f66e94
+  metadata.gz: 863fdced4e04e4b16dede0b398b94c18030ee491cedad54a9102ab8edce36e56
+  data.tar.gz: 1d4c71d61915bb0e9602e9951ac54c0a5c43e82dfe787b5c02c651252c130732
 SHA512:
-  metadata.gz: 1ef79e5aa9d45bd9d379d39156c2c3291c005c078f66cded75fe22a896d03e5b00e95fd2826c871e272f81651cc7eddde287f8f7c170daea0df711795f1c6e6c
-  data.tar.gz: 309aabc613b97fe54337e86f0620b90356b1bd25859cdd2a5e6b352cd4b0509481b2cc2f1091719cbb3250588c04b264d44098a0b89d1fd66c15f48a469a8e23
+  metadata.gz: ea68e3f2161a8fb3ba83484b8df22fa5e3d96e9fe8cbf1a0329b03adb3aa76636eb3a7dd6340b6a6f6c0b909e3c04b99ec2977f8c1bcc8f802658dcdf680691e
+  data.tar.gz: 3b5484057bb269391df4b49e9b7015b5cf0dfb756638e3f8ddad2a1d9afcd8fe85bc7d3e2831146589b8262ce70221d0cc686fe66cc068e76ec86268805d7def

data/README.md

@@ -58,6 +58,10 @@ puts tax_number.format_type   # => :standard
 puts tax_number.to_federal_12  # => "289381508152"
 puts tax_number.to_federal_13  # => "2893081508152"
 puts tax_number.to_standard    # => "93/815/08152"
+
+# Identify the issuing Finanzamt
+puts tax_number.finanzamt_code  # => "2893"
+puts tax_number.finanzamt_name  # => "Stuttgart I"
 ```
 
 ### Auto-Detection vs Explicit State
@@ -170,6 +174,52 @@ Creates a new `Steuer::Steuernummer` object.
 - `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
+- `finanzamt_code` - Returns the four-digit Bundesfinanzamtsnummer (BUFA-Nr)
+- `finanzamt_name` - Returns the Finanzamt's name, or `nil` if the code is not in the bundled table
+
+## Finanzamt Lookup
+
+The first four digits of the 13-digit federal form are the **Bundesfinanzamtsnummer** (BUFA-Nr), identifying the issuing tax office — the `Empfaenger` in an ELSTER transmission.
+
+```ruby
+tax_number = Steuer.steuernummer('010/815/08182', state: 'SL')
+
+tax_number.finanzamt_code  # => "1010"
+tax_number.finanzamt_name  # => "Saarlouis"
+```
+
+`finanzamt_code` is derived arithmetically and always available for a valid number. `finanzamt_name` is a lookup against a bundled copy of the BZSt **GemFA** directory (Gesamtverzeichnis der Finanzämter).
+
+### Direct registry access
+
+```ruby
+Steuer::FinanzamtRegistry.name_for('1010')   # => "Saarlouis"
+Steuer::FinanzamtRegistry.state_for('1010')  # => "SL"
+Steuer::FinanzamtRegistry.known?('9999')     # => false
+Steuer::FinanzamtRegistry.revision           # => "2026-09-02"
+```
+
+### Data freshness
+
+Unlike the structural state data, Finanzamt names go stale — offices merge, split and get renamed, and **BZSt republishes GemFA on the 1st and 15th of every month**.
+
+Lookups therefore return `nil` rather than raising, so a number issued after the bundled revision still converts and validates; only the name is missing. Check `FinanzamtRegistry.revision` to see the bundled snapshot date, and fall back where a name is required:
+
+```ruby
+label = tax_number.finanzamt_name || tax_number.finanzamt_code
+```
+
+To refresh the bundled table from BZSt:
+
+```bash
+bundle exec rake update_finanzaemter
+```
+
+The same refresh can be run from GitHub Actions (**Update Finanzamt table** → *Run workflow*), which opens a pull request when the data has actually changed, summarising which offices were added, removed or renamed.
+
+BZSt publishes GemFA only as a bulk XML export — there is no per-office lookup API — so the table is bundled rather than fetched at runtime. Lookups stay a local hash read with no network dependency.
+
+`state_for` returns `nil` where a federal prefix is shared between states (`3` → BB/SN/ST, `4` → MV/TH), consistent with how the gem treats ambiguous prefixes elsewhere.
 
 ## Development