# Öffentlicher Dienst Gehaltsrechner API – Vollständige Spezifikation (llms-full.txt)
> Detaillierte Dokumentation für KI-Modelle, autonome Agenten und API-Entwickler.
> Bereitgestellt vom unabhängigen ÖD-Infoportal (https://infos-oeffentlicher-dienst.de).

---

## 1. Systemübersicht & Transparenz

Diese API liefert tabellen- und regelbasierte Gehaltsberechnungen für Beschäftigte im Öffentlichen Dienst in Deutschland. 

### Wichtiger Hinweis
Alle Berechnungen basieren auf den aktuell veröffentlichten Besoldungstabellen, Tarifverträgen und dem offiziellen Programmablaufplan (PAP) für die Lohnsteuer. Aufgrund der hohen Komplexität und individueller Dienstvereinbarungen erfolgen alle Auskünfte ohne Gewähr auf Rechtsverbindlichkeit. Für verbindliche Bescheide sind stets die zuständigen Landesämter für Besoldung oder Personalstellen maßgeblich.

### Unterstützte Entitäten
- **Beamte (17 Dienstherren):**
  - `bund`, `baden-wuerttemberg`, `bayern`, `berlin`, `brandenburg`, `bremen`, `hamburg`, `hessen`, `mecklenburg-vorpommern`, `niedersachsen`, `nordrhein-westfalen`, `rheinland-pfalz`, `saarland`, `sachsen`, `sachsen-anhalt`, `schleswig-holstein`, `thueringen`.
- **Besoldungsordnungen (variieren je nach Dienstherr):**
  - möglich: A (A1-A16), B (B1–B11), C (C1–C4, auslaufend), R (R1–R10), W (W1–W3), Anwärter (AW). Verfügbare Gruppen und Stufen für jeden Dienstherrn können dynamisch über `GET /api/v1/agent/options` oder `GET /api/v1/options` abgefragt werden.
- **Tarifverträge (Bezeichnungen & Kategorien gemäß ÖD-Infoportal):**
  - **Bund & Kommunen (22 Verträge):** `tvoed-bund` (TVöD-Bund), `tvoed-vka` (TVöD-VKA), `tvoed-e` (TVöD-Entsorgung), `tvoed-f` (TVöD-Flughäfen), `tvoed-bt-k` (TVöD-BT-K), `tvoed-bt-b` (TVöD-BT-B), `tvoed-p` (TVöD-Pflege), `tvoed-sue` (TVöD-SuE), `tvoed-v` (TVöD-Verwaltung), `tvoed-s` (TVöD-Sparkassen), `tv-v` (TV-Versorgung), `tv-ba` (TV-BA), `tv-drv` (TV-DRV), `tv-dguv` (TV-DGUV), `tv-itzbund` (TV-ITZBund), `tv-n-bayern` (TV-N Bayern), `tv-n-berlin` (TV-N Berlin), `tv-n-nrw` (TV-N NRW), `mtv-autobahn` (MTV-Autobahn), `tvaoed` (Ausbildung TVAöD), `tvpoed` (Praktikum TVPöD), `tvsoed` (Studium TVSöD).
  - **Länder (8 Verträge):** `tv-l` (TV-L), `tv-l-kr` (TV-L KR Pflege), `tv-l-sue` (TV-L SuE), `tv-h` (TV-H), `tv-h-kr` (TV-H KR Pflege), `tv-h-sue` (TV-H SuE), `tv-dataport` (TV-Dataport), `tv-itdz-berlin` (TV-ITDZ Berlin).
  - **Ärzte (7 Verträge):** `tv-aerzte-vka` (TV-Ärzte/VKA), `tv-aerzte-uni` (TV-Ärzte Uni), `tvoed-bt-k-aerzte` (TVöD-BT-K Ärzte), `tvoed-bt-b-aerzte` (TVöD-BT-B Ärzte), `tv-l-aerzte` (TV-L Ärzte), `tv-h-aerzte` (TV-H Ärzte), `tv-h-zahnaerzte` (TV-H Zahnärzte).

---

## 2. Authentifizierung & Tiers

Der Discovery-Endpunkt `GET /api/v1/options` ist **öffentlich und ohne API-Key** nutzbar.
Alle geschützten Berechnungs- und Agenten-Endpunkte (`/api/v1/agent/*`, `/api/v1/calculate`) erfordern einen API-Key im HTTP-Header:
```http
Authorization: Bearer sk_live_...
```

- **Free Tier:** 30 Requests/Monat kostenlos (ideal für Tests und eigene Prototypen).
- **Pro Tier:** 2.500 Requests/Monat (für intensivere Nutzung & Agenten).
- **Business Tier:** 50.000 Requests/Monat (für Portale & Plattformen).
- Keys können unter `https://infos-oeffentlicher-dienst.de/api` generiert werden.

---

## 3. Endpunkte im Detail

### A. Übersicht abrufen: `GET /api/v1/options`
Gibt alle verfügbaren Dienstherren (mit Kürzeln wie `by`, `bw`, `nw`, `bund`), Tarifverträge, verfügbare Perioden und Besoldungs-/Entgeltgruppen zurück.

---

### B. Agentic Discovery: `GET /api/v1/agent/options`
Liefert alle Stufen, Grundgehälter und wählbaren Zulagen für einen Dienstherrn oder Tarifvertrag inklusive aller Informationstexte (bezeichnet als `short`- und `info`-Texte) sowie landesspezifischer Familienzuschlagskriterien (z. B. bayerische Ortsklassen I–VII, NRW Mietenstufen I–VII).

**Query-Parameter:**
- `employmentType` (string, default: `"beamte"`): `"beamte"`, `"tarif"`, `"aerzte"`, `"sonstige"`.
- `dienstherr` (string, required wenn `employmentType="beamte"`): z. B. `"by"`, `"bw"`, `"nw"`, `"bund"` (oder Langformen wie `"bayern"`).
- `tarifvertrag` (string, required wenn `employmentType="tarif"` oder `"aerzte"`): z. B. `"tvoed-vka"`, `"tv-l"`, `"tv-aerzte-vka"`.
- `gruppe` (string, default: `"A9"`): z. B. `"A9"`, `"A13"`, `"E11"`, `"B2"`.
- `period_key` (string, optional): Spezifischer Gültigkeitszeitraum (z. B. `"20260501_20270331"`). Standard: Aktuellste gültige Periode.

---

### C. Agentic Berechnung: `POST /api/v1/agent/calculate`
Führt die vollständige Berechnung inklusive ausgewählter Zulagen-IDs und bundeslandspezifischem Familienzuschlag aus.

**Request Body (JSON-Beispiel):**
```json
{
  "employmentType": "beamte",
  "dienstherr": "by",
  "gruppe": "A9",
  "stufe": "4",
  "selected_zulage_keys": [
    "amtszulagen_art_34_abs_2_satz_1_nr_2_4_5_nach_einer_dienstzeit_von_zwei_jahren"
  ],
  "familienstand": "verheiratet",
  "ortsklasse": "iii",
  "kinder": "ja",
  "kinderfreibetraege": 2.0,
  "kinderpflege": 1,
  "steuerklasse": 3,
  "bundesland": "by",
  "kirchensteuer": "ja",
  "insuranceType": "pkvOhne",
  "pkvBeitrag": 500.0,
  "rentenversicherung": "nein",
  "arbeitslosenversicherung": "nein",
  "zusatzversorgung": "nein"
}
```

---

### D. Standard Direktberechnung: `POST /api/v1/calculate`
Für Jobportale, Widgets und Schnellberechnungen aus Kerndaten (ohne manuelle Zulagenauswahl und ohne beamtenrechtlichen Familienzuschlag).

**Request Body (JSON-Beispiel):**
```json
{
  "employmentType": "tarif",
  "tarifvertrag": "tvoed-vka",
  "gruppe": "E11",
  "stufe": "3",
  "steuerklasse": 1,
  "bundesland": "by",
  "kinder": "ja",
  "kinderfreibetraege": 1.0,
  "kinderpflege": 0,
  "kirchensteuer": "nein",
  "insuranceType": "gkv",
  "gkvZusatz": 2.9,
  "rentenversicherung": "gRV",
  "arbeitslosenversicherung": "gAV",
  "zusatzversorgung": "vbl"
}
```

---

## 4. Vollständige Parameter-Referenz (100% BNR-kompatibel)

### A. Standard-Parameter (Brutto-Netto-, Steuer- & PV-Berechnung)
Alle Parameter entsprechen 1:1 den Bezeichnungen und Werten des Brutto-Netto-Rechners (BNR):

| BNR-Parameter (Alias) | Typ | Standard | Wertebereich / BNR-Werte | Beschreibung |
| :--- | :--- | :--- | :--- | :--- |
| `employmentType` | string | `"beamte"` | `"beamte"`, `"tarif"`, `"aerzte"`, `"sonstige"` | Art des Beschäftigungsverhältnisses. |
| `dienstherr` | string | `null` | `"bund"`, `"bw"`, `"by"`, `"be"`, `"bb"`, `"hb"`, `"hh"`, `"he"`, `"mv"`, `"ni"`, `"nrw"`, `"nw"`, `"rp"`, `"sl"`, `"sn"`, `"st"`, `"sh"`, `"th"` (auch Slugs wie `"bayern"`) | Dienstherr / Bundesland (Beamte). |
| `tarifvertrag` | string | `null` | z. B. `"tvoed-bund"`, `"tvoed-vka"`, `"tv-l"`, `"tv-aerzte-vka"`, ... | Tarifvertrag (Tarifbeschäftigte & Ärzte). |
| `gruppe` | string | `"A9"` / `"E11"` | Beamte: `A3`–`A16`, `B1`–`B11`, `R1`–`R10`, `W1`–`W3`, `C1`–`C4`, Anwärter<br>Tarif: `E1`–`E15`, `E2ü`, `E9a`–`E9c`, `E13ü`, `E15ü`, `E16`<br>SuE: `S2`–`S18`<br>Pflege/KR: `P5`–`P16`, `KR5`–`KR17`<br>Ärzte: `Ä1`–`Ä4`, `I`–`IV`, `FA`, `OA`, `CA`, `Z1`–`Z5` | Besoldungs- oder Entgeltgruppe. |
| `stufe` | string | `"3"` | z. B. `"1"`, `"2"`, `"3"`, `"4"`, `"5"`, `"6"` | Erfahrungs- / Dienstaltersstufe. |
| `period_key` | string | `null` | z. B. `"20260501_20270331"` | Spezifische Tabelle (Standard: aktuellste Periode). |
| `employmentPercentage` | float | `100.0` | `0.0` – `100.0` | Teilzeit-Beschäftigungsgrad in %. |
| `steuerjahr` | int | `2026` | `2025`, `2026` | Steuerjahr für PAP-Lohnsteuerberechnung. |
| `steuerklasse` | int | `1` | `1`, `2`, `3`, `4`, `5`, `6` | Steuerklasse. |
| `steuervier` | float | `1.0` | z. B. `0.955`, `1.0` | Faktor bei Steuerklasse 4 Faktorverfahren. |
| `bundesland` | string | `"bayern"` | Kürzel (`"by"`, `"bw"`, `"nrw"`, ...) oder Slugs | Wohnort (bestimmt KiSt-Satz 8%/9% & PV Sachsen). |
| `geburtsjahr` | int | `1992` | z. B. `1990` | Geburtsjahr (für Altersentlastung & PV-Zuschlag). |
| `alter` | string | `"ja"` | `"ja"`, `"nein"` | PV-Zuschlag wenn Alter genau 23 Jahre beträgt. |
| `kirchensteuer` | string / bool | `"nein"` | `"ja"`, `"nein"` oder `true`, `false` | Kirchensteuerpflicht (Berechnung autom. nach Bundesland). |
| `kinder` (`pgKinder`) | string / bool | `"nein"` | `"ja"`, `"nein"` | Gibt an, ob Kinder vorhanden sind (befreit vom kinderlosen PV-Zuschlag). |
| `kinderfreibetraege` (`pgKinderfreibetraege`) | float / str | `0.0` | `0.0`, `0.5`, `1.0`, `1.5`, `2.0`, ... bzw. `"0"`, `"0_5"`, `"1_5"` | Kinderfreibetrag auf der Lohnsteuerkarte. |
| `kinderpflege` (`pgKinderpflege`) | int | `0` | `0` (0-1 Kind), `1` (2 Kinder), `2` (3 Kinder), `3` (4 Kinder), `4` (5+ Kinder) | Kinder für gesetzliche PV-Beitragsstaffelung. |
| `insuranceType` | string | `"pkvOhne"` | `"pkvOhne"`, `"pkvMit"`, `"gkv"`, `"gkvMitBeihilfe"` | Krankenversicherungsart. |
| `gkvZusatz` | float | `2.9` | z. B. `2.9`, `2.5` | GKV-Zusatzbeitrag in % (Standard 2026: 2,9%). |
| `pkvBeitrag` | float | `0.0` | Betrag in € | Monatlicher Beitrag zur privaten Basis-KV/Pflicht-PV. |
| `profiGesamtprivBasisKvPv` | float | `0.0` | Betrag in € | Gesamter privater KV/PV-Monatsbeitrag (Profi-Modus). |
| `pkvZuschussArbeitgeber` | float | `0.0` | Betrag in € | Arbeitgeberzuschuss zur privaten KV/PV. |
| `profiSettingsCheckbox` | bool | `false` | `true`, `false` | Aktiviert erweiterte PKV-Nettoabzüge. |
| `rentenversicherung` | string | `"gRV"` / `"nein"` | `"gRV"`, `"nein"` | RV-Pflicht (Standard bei Beamten: `"nein"`, bei Tarif: `"gRV"`). |
| `arbeitslosenversicherung` | string | `"gAV"` / `"nein"` | `"gAV"`, `"nein"` | AV-Pflicht (Standard bei Beamten: `"nein"`, bei Tarif: `"gAV"`). |
| `zusatzversorgung` | string | `"nein"` | `"vbl"`, `"vbl-ost"`, `"nein"` | VBL-Zusatzversorgung (nur echte Kassen aus CSV-Tabelle). |
| `zeitraumGehalt` | string | `"monat"` | `"monat"`, `"jahr"` | Zeitraum für manuelles Brutto (nur bei `employmentType="sonstige"`). |
| `bruttoGehalt` | float | `0.0` | Betrag in € | Manuelles Bruttogehalt (nur bei `employmentType="sonstige"`). |
| `sonstigeZulagen` | float | `0.0` | Betrag in € | Zusätzliche monatliche Brutto-Zulage (z. B. Ministerialzulage, IT-Zulage etc.), die direkt auf das monatliche Grundgehalt aufgeschlagen wird. |

---

### B. Agentic Zulagen & Beamten-Familienzuschlag (exklusiv `POST /api/v1/agent/calculate`)
Diese Parameter werden in Step 1 (`GET /api/v1/agent/options`) dynamisch für den jeweiligen Dienstherrn und Tarifvertrag abgefragt:

| Parameter | Typ | Standard | Wertebereich | Beschreibung |
| :--- | :--- | :--- | :--- | :--- |
| `selected_zulage_keys` | list[str] | `[]` | Keys aus `zulage_options` | Liste ausgewählter Amts-, Funktions- und Stellenzulagen. |
| `familienstand` | string | `"ledig"` | `"ledig"`, `"verheiratet"`, `"in_lebenspartnerschaft"` | Familienstand für Familienzuschlag Stufe 1 (wird in `familienzuschlag_info` signalisiert). |
| `ortsklasse` | string | `"i"` | `"i"`, `"ii"`, `"iii"`, `"iv"`, `"v"`, `"vi"`, `"vii"` | Ortsklasse des Hauptwohnsitzes (nur bei Dienstherr Bayern, signalisiert in `familienzuschlag_info`). |
| `mietenstufe` | string | `"i"` | `"i"`, `"ii"`, `"iii"`, `"iv"`, `"v"`, `"vi"`, `"vii"` | Mietenstufe des Hauptwohnsitzes (nur bei Dienstherr NRW, signalisiert in `familienzuschlag_info`). |

---

## 5. Antwortstruktur (Fein säuberlich getrennt in Monat & Jahr)

Die API liefert die Berechnungsdaten analog zum Brutto-Netto-Rechner in zwei klar separierten Blöcken `monat` und `jahr` sowie einer `sonderzahlung`-Zusammenfassung:

```json
{
  "entity": "bayern",
  "employment_type": "beamte",
  "period_key": "20260401_20270228",
  "gruppe": "A9",
  "stufe": "4",
  "monat": {
    "brutto": 3574.95,
    "netto": 2987.35,
    "grundgehalt": 3574.95,
    "zulagen_summe": 0.0,
    "familienzuschlag": 0.0,
    "lohnsteuer": 587.60,
    "solidaritaetszuschlag": 0.0,
    "kirchensteuer": 0.0,
    "krankenversicherung_an": "o.A.",
    "pflegeversicherung_an": "o.A.",
    "rentenversicherung_an": 0.0,
    "arbeitslosenversicherung_an": 0.0,
    "zusatzversorgung_an": 0.0,
    "summe_steuern": 587.60,
    "summe_sozialabgaben": 0.0
  },
  "jahr": {
    "brutto": 44899.40,
    "netto": 37248.20,
    "grundgehalt": 42899.40,
    "sonderzahlung": 2000.00,
    "zulagen_summe": 0.0,
    "familienzuschlag": 0.0,
    "lohnsteuer": 7651.20,
    "solidaritaetszuschlag": 0.0,
    "kirchensteuer": 0.0,
    "krankenversicherung_an": "o.A.",
    "pflegeversicherung_an": "o.A.",
    "rentenversicherung_an": 0.0,
    "arbeitslosenversicherung_an": 0.0,
    "zusatzversorgung_an": 0.0,
    "summe_steuern": 7651.20,
    "summe_sozialabgaben": 0.0
  },
  "sonderzahlung": {
    "total_annual": 2000.00,
    "details": ["Jahressonderzahlung: 2.000,00 €"],
    "paid_monthly": false
  }
}
```