REST-API
Die HTTP-Schnittstelle für jede Programmiersprache. Alle Datensätze antworten auf GET mit JSON, Listen auf Wunsch als CSV.
Basis-URL
#Alle Endpunkte liegen unter https://api.quellenkontor.dev/v1. Die API spricht nur HTTPS und antwortet auf GET, dazu auf OPTIONS für Aufrufe aus dem Browser. Die Version steht im Pfad. Ein Aufruf der Basis-URL ohne Pfad liefert eine kurze Übersicht mit Links auf Katalog, OpenAPI und Doku.
Aufbau einer Anfrage
#Jeder Datensatz hat einen Pfad unter /hr/, die Parameter stehen in der Adresse:
| Typ | Schreibweise | Beispiel |
|---|---|---|
| Datum | JJJJ-MM-TT | datum=2027-01-15 |
| Jahr | vierstellig | jahr=2027 |
| Zahl | Punkt oder Komma als Dezimaltrenner | netto=2500.50 |
| Wahrheitswert | true, false, 1, 0, ja oder nein | probezeit=true |
| Auswahl | einer der erlaubten Werte, Groß- und Kleinschreibung egal | land=HE |
Unbekannte Parameter lehnt die API mit unbekannter_parameter ab, statt sie still zu übergehen. So fällt ein Tippfehler sofort auf. Neben den Parametern des Datensatzes gibt es format (json oder csv) und trennzeichen (komma oder semikolon, nur mit CSV).
Alle Endpunkte
#| Endpunkt | Parameter | Referenz |
|---|---|---|
GET /hr/mindestlohn | datum | Mindestlohn |
GET /hr/mindestlohn/verlauf | von, bis | Verlauf |
GET /hr/mindestausbildungsverguetung | beginn, ausbildungsjahr, bestandteil | Ausbildungsvergütung |
GET /hr/mindestausbildungsverguetung/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/pflegemindestlohn | datum, bestandteil | Pflegemindestlohn |
GET /hr/pflegemindestlohn/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/rechengroessen | jahr, datum | Beitragsbemessungsgrenzen |
GET /hr/rechengroessen/verlauf | von, bis | Verlauf |
GET /hr/beitragssaetze | datum | Beitragssätze |
GET /hr/beitragssaetze/verlauf | von, bis | Verlauf |
GET /hr/sachbezugswerte | jahr, datum | Sachbezugswerte |
GET /hr/sachbezugswerte/verlauf | von, bis | Verlauf |
GET /hr/pfaendungsfreigrenzen | datum, unterhaltspflichten, netto | Pfändungsfreigrenzen |
GET /hr/pfaendungsfreigrenzen/verlauf | von, bis | Verlauf |
GET /hr/uebergangsbereich | datum | Übergangsbereich |
GET /hr/uebergangsbereich/verlauf | von, bis | Verlauf |
GET /hr/minijob-abgaben | datum, bestandteil | Minijob-Abgaben |
GET /hr/minijob-abgaben/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/kuenstlersozialabgabe | jahr, datum, bestandteil | Künstlersozialabgabe |
GET /hr/kuenstlersozialabgabe/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/ausgleichsabgabe | jahr, datum, arbeitsplaetze, besetzt, bestandteil | Ausgleichsabgabe |
GET /hr/ausgleichsabgabe/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/steuerfreie-betraege | datum, bestandteil | Freibeträge und Pauschalen |
GET /hr/steuerfreie-betraege/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/reisekosten-inland | datum, bestandteil | Reisekosten |
GET /hr/reisekosten-inland/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/sfn-zuschlaege | datum, grundlohn_stunde, bestandteil | SFN-Zuschläge |
GET /hr/sfn-zuschlaege/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/dienstwagen | listenpreis*, antrieb, anschaffung, ueberlassung, entfernung_km, fahrten_monat, zuzahlung_monat, co2_g_km, reichweite_km, batterie_kwh, datum | Dienstwagen |
GET /hr/einkommensteuer-eckwerte | jahr, datum, bestandteil | Grundfreibetrag |
GET /hr/einkommensteuer-eckwerte/verlauf | von, bis, bestandteil | Verlauf |
GET /hr/kuendigungsfrist | eintritt*, zugang*, seite, probezeit | Kündigungsfrist |
GET /hr/urlaubsanspruch | arbeitstage_pro_woche*, jahr, eintritt, austritt | Urlaubsanspruch |
GET /hr/mutterschutz | termin, geburt, fall, ssw | Mutterschutz |
GET /hr/feiertage | jahr, land | Feiertage |
GET /hr/arbeitstage | von*, bis*, land*, samstag, regionale | Arbeitstage |
GET /hr/regelaltersgrenze | geburtsdatum, geburtsjahr, vertrauensschutz | Regelaltersgrenze |
GET /hr/pausen | arbeitszeit_stunden*, jugendlich | Pausenregelung |
GET /datensaetze | ohne Schlüssel | Katalog aller Datensätze |
GET /aenderungen | ohne Schlüssel | Änderungsprotokoll |
GET /status | ohne Schlüssel | Prüfstand je Datensatz: letzte Prüfung, gesichert bis, erwartete Änderung |
GET /openapi.json | ohne Schlüssel | OpenAPI-Beschreibung |
GET /export | keine | Komplettexport, eine Abfrage |
Mit * markierte Parameter sind Pflicht.
Beispiele in sechs Sprachen
#Alle Beispiele fragen dieselbe Kündigungsfrist ab: Eintritt am 01.03.2017, Kündigung durch den Arbeitgeber, zugegangen am 10.11.2026. Wer lieber mit fertigen Methoden arbeitet, nimmt das SDK für JavaScript oder für Python.
curl
JavaScript (fetch)
Python (requests)
PHP
C# (.NET)
Java (ab 11)
Antwort
OpenAPI 3.1
#Die vollständige Beschreibung liegt ohne Schlüssel unter https://api.quellenkontor.dev/v1/openapi.json. Sie enthält jeden Endpunkt mit Parametern, Typen und Beispielen. Du kannst sie in Postman, Insomnia oder Bruno importieren oder dir mit dem OpenAPI Generator einen Client für deine Sprache erzeugen:
Versionen und Stabilität
#Die Version steht im Pfad, aktuell /v1. Innerhalb von v1 kommen nur Dinge dazu: neue Datensätze, neue optionale Parameter, neue Felder in Antworten. Felder umbenennen, entfernen oder ihre Bedeutung ändern würden wir nur in einer neuen Version, mit Ankündigung im Änderungsprotokoll. Schreib deinen Code deshalb so, dass er unbekannte Felder ignoriert.
Zeitlimits und Wiederholungen
#- Setz ein Zeitlimit von etwa 15 Sekunden je Anfrage.
- Wiederhole nur bei Netzfehlern und den Status 502, 503 und 504, mit wachsender Pause, zum Beispiel 0,3 und 0,6 Sekunden. So machen es auch die SDKs.
- Wiederhole keine Antworten mit 4xx. Die Anfrage ist dann fehlerhaft, oder das Kontingent ist aufgebraucht, eine Wiederholung ändert daran nichts.
Aufrufe aus dem Browser
#Die API erlaubt Aufrufe von jeder Herkunft (CORS), damit du Beispiele schnell im Browser ausprobieren kannst. Für eine echte Anwendung gehört der Schlüssel auf deinen Server: Leite Anfragen dort weiter oder speichere die Werte zwischen. Alles, was im Browser steht, kann jeder Besucher auslesen.
Fehlt etwas oder ist etwas unklar? Schreib uns, wir ergänzen die Doku.