Finanzamts-Schnittstelle für Programme

Zwei Zusagen, auf die man sich verlassen kann — und muss

1. Die Antwort ist immer eine Liste, nie ein einzelnes Amt

Von den — Postleitzahlen im Verzeichnis führen — zu mehreren Ämtern, von den — Gemeindeschlüsseln —. In Berlin sind 17 Ämter für dieselbe Gemeinde zuständig, in Hamburg 10, in Köln 7. Was dort entscheidet — Bezirk, Straße oder Anfangsbuchstabe des Nachnamens — steht im amtlichen Verzeichnis nicht. Eine Schnittstelle, die in diesen Fällen eines der Ämter zurückgibt, liefert mit hoher Wahrscheinlichkeit das falsche.

Deshalb: aemter ist stets ein Array, und eindeutig sagt ausdrücklich, ob genau ein Amt zuständig ist. Bei eindeutig: false erklärt hinweis den Grund. Aufrufende Programme sollten in diesem Fall nachfragen statt zu wählen — die verlässliche Auskunft steht im letzten Steuerbescheid.

2. Der Gemeindeschlüssel ist der belastbare Schlüssel, die Postleitzahl ein Behelf

Der achtstellige amtliche Gemeindeschlüssel bezeichnet die Gemeinde eindeutig. Eine Postleitzahl kann dagegen bis zu 39 Gemeinden umfassen und über Gemeindegrenzen hinweg reichen. Wer den Schlüssel führt, sollte ags benutzen; plz ist für die Fälle gedacht, in denen nur die Anschrift bekannt ist.

Zugang

Ein Nachschlagen ohne Treffer ist kein Fehler: es antwortet mit 200, anzahl_aemter: 0 und einem hinweis.

Endpunkte

GET /api/finanzamt?ags=10044111

{
  "stand": "03.08.2026",
  "stand_quelle": "20260803_0846",
  "frage": { "ags": "10044111" },
  "eindeutig": true,
  "anzahl_aemter": 1,
  "anzahl_gemeinden": 1,
  "hinweis": null,
  "aemter": [ { "bufa_nr": "1010", "name": "Saarlouis", … } ],
  "gemeinden": [
    { "ags": "10044111", "name": "Dillingen/ Saar, Stadt",
      "plz": "66763", "kreis": "Saarlouis", "bufa_nr": "1010" }
  ]
}

GET /api/finanzamt/1010

{ "stand": "03.08.2026", …, "amt": { "bufa_nr": "1010", … } }

GET /api/finanzamt/1010/bezirk

{ "stand": "03.08.2026", "bufa_nr": "1010",
  "bezeichnung": "Finanzamt Saarlouis", "bundesland": "Saarland",
  "ohne_bezirk": false, "anzahl": 13,
  "gemeinden": [ { "ags": "10044111", "name": "Dillingen/ Saar, Stadt",
                   "plz": "66763", "kreis": "Saarlouis" }, … ] }

GET /api/finanzaemter?gemeinden=1

{
  "stand": "03.08.2026",
  "vollstaendig": true,
  "gesamt": 593,
  "anzahl": 593,
  "anzahl_gemeinden": 10818,
  "aemter": [
    { "bufa_nr": "1010", "bezeichnung": "Finanzamt Saarlouis", …,
      "gemeinden": [ { "ags": "10044111", "name": "Dillingen/ Saar, Stadt",
                       "plz": "66763", "kreis": "Saarlouis" }, … ] }, …
  ]
}

Den ganzen Bestand abholen

Für eine eigene Zuordnungstabelle genügt ein Abruf. Er liefert alle — Ämter samt ihren — Gemeinden:

curl --compressed -H "X-API-Key: $STS_FA_KEY" \
     "https://tools.steuersoft.de/api/finanzaemter?gemeinden=1"

Etwa 1,4 MB unkomprimiert, rund 200 KB übertragen. Ohne gemeinden=1 sind es nur die Ämter ohne Bezirke (deutlich kleiner). Die Antwort ist je Datenstand unverändert dieselbe und wird in wenigen Millisekunden ausgeliefert.

Nachsehen, ob sich etwas geändert hat — ohne alles erneut zu laden

Der Bestand wird monatlich fortgeschrieben. Die Antwort trägt ein ETag; wer es beim nächsten Mal mitschickt, bekommt bei unverändertem Stand 304 Not Modified ohne Rumpf zurück:

# erster Abruf: ETag merken
curl -sD - -o bestand.json -H "X-API-Key: $STS_FA_KEY" \
     "https://tools.steuersoft.de/api/finanzaemter?gemeinden=1" | grep -i ^etag
# ETag: W/"20260803_0846-mit_gemeinden"

# spaeter: nur pruefen, ob es etwas Neues gibt
curl -s -o /dev/null -w "%{http_code}\n" -H "X-API-Key: $STS_FA_KEY" \
     -H 'If-None-Match: W/"20260803_0846-mit_gemeinden"' \
     "https://tools.steuersoft.de/api/finanzaemter?gemeinden=1"
# 304  -> unveraendert, nichts zu tun
# 200  -> neuer Stand, Rumpf enthaelt ihn

Noch einfacher geht es mit HEAD: das liefert nur die Kopfzeilen samt ETag und Content-Length, ganz ohne Rumpf — auch ohne dass der Aufrufer bedingte Anfragen beherrschen muss.

curl -sI -H "X-API-Key: $STS_FA_KEY" \
     "https://tools.steuersoft.de/api/finanzaemter?gemeinden=1" | grep -i etag
# ETag: W/"20260803_0846-mit_gemeinden"

Wer kein ETag auswerten will, vergleicht das Feld stand (bzw. stand_quelle) mit dem selbst vorgehaltenen Wert — es steht in jeder Antwort der Schnittstelle.

PowerShell

$kopf = @{ "X-API-Key" = $env:STS_FA_KEY }
$b = Invoke-RestMethod "https://tools.steuersoft.de/api/finanzaemter?gemeinden=1" -Headers $kopf
"{0} Ämter, {1} Gemeinden, Stand {2}" -f $b.gesamt, $b.anzahl_gemeinden, $b.stand

# Zuordnungstabelle Gemeindeschlüssel -> Amtsnummer aufbauen
$zuordnung = @{}
foreach ($amt in $b.aemter) {
  foreach ($g in $amt.gemeinden) { $zuordnung[$g.ags] = $amt.bufa_nr }
}
$zuordnung["10044111"]   # 1010

Achtung bei der eigenen Tabelle: ein Gemeindeschlüssel kann zu mehreren Ämtern gehören (Berlin, Hamburg, Köln und weitere Großstädte). Wer wie oben stumpf zuweist, behält je Schlüssel nur das zuletzt gesehene Amt. Für diese Fälle eine Liste je Schlüssel führen — oder sie an der Zahl der Ämter erkennen und zurückfragen.

Selbst ausprobieren

Noch nichts abgerufen.

Beispiele zum Einsetzen: /api/finanzamt?ags=10044111 · /api/finanzamt?plz=10178 (mehrere Ämter) · /api/finanzamt?ort=Dillingen · /api/finanzamt/1010?gemeinden=1 · /api/finanzamt/1010/bezirk · /api/finanzaemter?bundesland=Saarland · /api/finanzaemter (ganzer Bestand) · /api/finanzaemter?gemeinden=1 (mit allen Gemeinden)

Felder eines Amtes

Felder können hinzukommen; vorhandene Felder werden nicht umbenannt und nicht in ihrer Bedeutung geändert. Ein aufrufendes Programm sollte unbekannte Felder überlesen.

Beispiele

Kommandozeile

curl -s -H "X-API-Key: $STS_FA_KEY" \
     "https://tools.steuersoft.de/api/finanzamt?ags=10044111"

Den Schlüssel nicht in Skripte schreiben, sondern aus einer Umgebungsvariablen oder einer nur für den Dienstnutzer lesbaren Datei ziehen.

PowerShell

$kopf = @{ "X-API-Key" = $env:STS_FA_KEY }
$a = Invoke-RestMethod "https://tools.steuersoft.de/api/finanzamt?plz=66740" -Headers $kopf
if ($a.eindeutig) { $a.aemter[0].bezeichnung } else { Write-Warning $a.hinweis }

Delphi

uses System.Net.HttpClient, System.JSON, System.NetEncoding;

function ZustaendigesAmt(const AGemeindeschluessel: string): string;
var
  Client: THTTPClient;
  Antwort: IHTTPResponse;
  Wurzel: TJSONObject;
  Aemter: TJSONArray;
begin
  Result := '';
  Client := THTTPClient.Create;
  try
    // Zugangsschluessel als Kopfzeile, nie als Adressbestandteil.
    Client.CustomHeaders['X-API-Key'] := SchluesselAusKonfiguration;
    Antwort := Client.Get('https://tools.steuersoft.de/api/finanzamt?ags=' +
                          TNetEncoding.URL.Encode(AGemeindeschluessel));
    if Antwort.StatusCode <> 200 then Exit;
    Wurzel := TJSONObject.ParseJSONValue(Antwort.ContentAsString(TEncoding.UTF8)) as TJSONObject;
    try
      // Mehrere zustaendige Aemter sind moeglich (Berlin, Hamburg, Koeln).
      // Dann NICHT eines auswaehlen, sondern zurueckfragen.
      if not Wurzel.GetValue<Boolean>('eindeutig') then Exit;
      Aemter := Wurzel.GetValue<TJSONArray>('aemter');
      if Aemter.Count > 0 then
        Result := (Aemter.Items[0] as TJSONObject).GetValue<string>('bufa_nr');
    finally
      Wurzel.Free;
    end;
  finally
    Client.Free;
  end;
end;

JavaScript

// Serverseitig aufrufen — im Browser waere der Schluessel oeffentlich.
const r = await fetch('https://tools.steuersoft.de/api/finanzamt?plz=66740',
                      { headers: { 'X-API-Key': process.env.STS_FA_KEY } });
const a = await r.json();
if (!a.eindeutig) console.warn(a.hinweis);
console.log(a.aemter.map(x => `${x.bufa_nr} ${x.bezeichnung}`));

Was das Verzeichnis nicht enthält

• Die Zuordnung innerhalb einer Großstadt. Welcher Bezirk, welche Straße oder welcher Anfangsbuchstabe zu welchem der 17 Berliner Ämter gehört, ist nicht Bestandteil des Verzeichnisses und kann über diese Schnittstelle nicht beantwortet werden.
• Die Aufgabenverteilung. Das Verzeichnis führt kein befülltes Aufgabenfeld. Welches Amt die Grundsteuer-Bewertung oder die Erbschaftsteuer eines Bezirks bearbeitet, lässt sich daher nur über den Amtsnamen erschließen, nicht sicher zuordnen.
• Ortsteile. Zugeordnet sind Gemeinden; Ortsteile stehen unter dem Namen ihrer Gemeinde.
• Postleitzahlen gemeindefreier Gebiete. Fünf Einträge — unbewohnte Gutsbezirke und Forstflächen — haben keine Postleitzahl; das Feld ist dort null.
• Zuständigkeit für andere Steuerarten. Die Zuordnung gibt den regionalen Bezirk wieder. Für Umsatzsteuer, Körperschaften, Lohnsteuer, gesonderte Feststellungen und Realsteuermessbeträge gelten eigene Vorschriften — siehe unten.

Rechtlicher Rahmen