steuer 1.0.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7fadede920ad3e8a9eb408ebd3280e512361c0c5fb2ada38c5b92a0158c4366
-  data.tar.gz: 5d467d91346d63b6955150b796b7534dd3f2108bb7aae4f7f94043257c145ea0
+  metadata.gz: 863fdced4e04e4b16dede0b398b94c18030ee491cedad54a9102ab8edce36e56
+  data.tar.gz: 1d4c71d61915bb0e9602e9951ac54c0a5c43e82dfe787b5c02c651252c130732
 SHA512:
-  metadata.gz: 88fc14d81125482ff3773b09c9a2dda68fb33d62510b9354f8de6c51b7377d43a2ddb1c245d76fb7aa1f26a351c4cec8d68d1186b0e49ac12c6e1d0cc27c0dc7
-  data.tar.gz: 53dbea1af2ad55112107b898cbd8d31a0ae3c28c9e867a87d781b5fc62710ae1012df5a524621e3d505088e9bb43ad65ae4a6d4e1ab6cdecc7c779b3a901568e
+  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