Doku-Navigation: REST-APIBasis-URL
Zugänge

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:

Schema
GET https://api.quellenkontor.dev/v1/hr/<datensatz>?<parameter>=<wert>&…
Authorization: Bearer <schluessel>
TypSchreibweiseBeispiel
DatumJJJJ-MM-TTdatum=2027-01-15
Jahrvierstelligjahr=2027
ZahlPunkt oder Komma als Dezimaltrennernetto=2500.50
Wahrheitswerttrue, false, 1, 0, ja oder neinprobezeit=true
Auswahleiner der erlaubten Werte, Groß- und Kleinschreibung egalland=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

#
EndpunktParameterReferenz
GET /hr/mindestlohndatumMindestlohn
GET /hr/mindestlohn/verlaufvon, bisVerlauf
GET /hr/mindestausbildungsverguetungbeginn, ausbildungsjahr, bestandteilAusbildungsvergütung
GET /hr/mindestausbildungsverguetung/verlaufvon, bis, bestandteilVerlauf
GET /hr/pflegemindestlohndatum, bestandteilPflegemindestlohn
GET /hr/pflegemindestlohn/verlaufvon, bis, bestandteilVerlauf
GET /hr/rechengroessenjahr, datumBeitragsbemessungsgrenzen
GET /hr/rechengroessen/verlaufvon, bisVerlauf
GET /hr/beitragssaetzedatumBeitragssätze
GET /hr/beitragssaetze/verlaufvon, bisVerlauf
GET /hr/sachbezugswertejahr, datumSachbezugswerte
GET /hr/sachbezugswerte/verlaufvon, bisVerlauf
GET /hr/pfaendungsfreigrenzendatum, unterhaltspflichten, nettoPfändungsfreigrenzen
GET /hr/pfaendungsfreigrenzen/verlaufvon, bisVerlauf
GET /hr/uebergangsbereichdatumÜbergangsbereich
GET /hr/uebergangsbereich/verlaufvon, bisVerlauf
GET /hr/minijob-abgabendatum, bestandteilMinijob-Abgaben
GET /hr/minijob-abgaben/verlaufvon, bis, bestandteilVerlauf
GET /hr/kuenstlersozialabgabejahr, datum, bestandteilKünstlersozialabgabe
GET /hr/kuenstlersozialabgabe/verlaufvon, bis, bestandteilVerlauf
GET /hr/ausgleichsabgabejahr, datum, arbeitsplaetze, besetzt, bestandteilAusgleichsabgabe
GET /hr/ausgleichsabgabe/verlaufvon, bis, bestandteilVerlauf
GET /hr/steuerfreie-betraegedatum, bestandteilFreibeträge und Pauschalen
GET /hr/steuerfreie-betraege/verlaufvon, bis, bestandteilVerlauf
GET /hr/reisekosten-inlanddatum, bestandteilReisekosten
GET /hr/reisekosten-inland/verlaufvon, bis, bestandteilVerlauf
GET /hr/sfn-zuschlaegedatum, grundlohn_stunde, bestandteilSFN-Zuschläge
GET /hr/sfn-zuschlaege/verlaufvon, bis, bestandteilVerlauf
GET /hr/dienstwagenlistenpreis*, antrieb, anschaffung, ueberlassung, entfernung_km, fahrten_monat, zuzahlung_monat, co2_g_km, reichweite_km, batterie_kwh, datumDienstwagen
GET /hr/einkommensteuer-eckwertejahr, datum, bestandteilGrundfreibetrag
GET /hr/einkommensteuer-eckwerte/verlaufvon, bis, bestandteilVerlauf
GET /hr/kuendigungsfristeintritt*, zugang*, seite, probezeitKündigungsfrist
GET /hr/urlaubsansprucharbeitstage_pro_woche*, jahr, eintritt, austrittUrlaubsanspruch
GET /hr/mutterschutztermin, geburt, fall, sswMutterschutz
GET /hr/feiertagejahr, landFeiertage
GET /hr/arbeitstagevon*, bis*, land*, samstag, regionaleArbeitstage
GET /hr/regelaltersgrenzegeburtsdatum, geburtsjahr, vertrauensschutzRegelaltersgrenze
GET /hr/pausenarbeitszeit_stunden*, jugendlichPausenregelung
GET /datensaetzeohne SchlüsselKatalog aller Datensätze
GET /aenderungenohne SchlüsselÄnderungsprotokoll
GET /statusohne SchlüsselPrüfstand je Datensatz: letzte Prüfung, gesichert bis, erwartete Änderung
GET /openapi.jsonohne SchlüsselOpenAPI-Beschreibung
GET /exportkeineKomplettexport, 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

Terminal
curl "https://api.quellenkontor.dev/v1/hr/kuendigungsfrist?eintritt=2017-03-01&zugang=2026-11-10" \
  -H "Authorization: Bearer $QK_KEY"

JavaScript (fetch)

JavaScript
const url = new URL("https://api.quellenkontor.dev/v1/hr/kuendigungsfrist");
url.search = new URLSearchParams({ eintritt: "2017-03-01", zugang: "2026-11-10" }).toString();

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.QK_KEY}` },
  signal: AbortSignal.timeout(15000),
});
const daten = await res.json();
if (!res.ok) throw new Error(`${daten.fehler.code}: ${daten.fehler.nachricht}`);
console.log(daten.ende);

Python (requests)

Python
import os
import requests

r = requests.get(
    "https://api.quellenkontor.dev/v1/hr/kuendigungsfrist",
    params={"eintritt": "2017-03-01", "zugang": "2026-11-10"},
    headers={"Authorization": f"Bearer {os.environ['QK_KEY']}"},
    timeout=15,
)
daten = r.json()
if not r.ok:
    raise RuntimeError(f"{daten['fehler']['code']}: {daten['fehler']['nachricht']}")
print(daten["ende"])

PHP

PHP
<?php
$url = "https://api.quellenkontor.dev/v1/hr/kuendigungsfrist?" . http_build_query([
    "eintritt" => "2017-03-01",
    "zugang" => "2026-11-10",
]);
$kontext = stream_context_create(["http" => [
    "header" => "Authorization: Bearer " . getenv("QK_KEY"),
    "ignore_errors" => true,
    "timeout" => 15,
]]);
$daten = json_decode(file_get_contents($url, false, $kontext), true);
echo $daten["ende"] ?? $daten["fehler"]["nachricht"];

C# (.NET)

C#
using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.quellenkontor.dev/v1/") };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("QK_KEY"));

var antwort = await http.GetAsync("hr/kuendigungsfrist?eintritt=2017-03-01&zugang=2026-11-10");
using var daten = JsonDocument.Parse(await antwort.Content.ReadAsStringAsync());
Console.WriteLine(antwort.IsSuccessStatusCode
    ? daten.RootElement.GetProperty("ende").GetString()
    : daten.RootElement.GetProperty("fehler").GetProperty("nachricht").GetString());

Java (ab 11)

Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Kuendigungsfrist {
    public static void main(String[] args) throws Exception {
        HttpRequest anfrage = HttpRequest.newBuilder(URI.create("https://api.quellenkontor.dev/v1/hr/kuendigungsfrist?eintritt=2017-03-01&zugang=2026-11-10"))
            .header("Authorization", "Bearer " + System.getenv("QK_KEY"))
            .timeout(Duration.ofSeconds(15))
            .GET()
            .build();
        HttpResponse<String> antwort = HttpClient.newHttpClient()
            .send(anfrage, HttpResponse.BodyHandlers.ofString());
        System.out.println(antwort.statusCode() + " " + antwort.body());
    }
}

Antwort

Antwort
{
  "datensatz": "kuendigungsfrist",
  "eintritt": "2017-03-01",
  "zugang": "2026-11-10",
  "seite": "arbeitgeber",
  "probezeit": false,
  "betriebszugehoerigkeit_jahre": 9,
  "frist": "3 Monate zum Ende eines Kalendermonats",
  "frist_code": "monate_3_zum_monatsende",
  "fristende": "2027-02-10",
  "ende": "2027-02-28",
  "rechtsgrundlage": "§ 622 Abs. 2 Satz 1 Nr. 3 BGB",
  "hinweise": [
    "Schematische Berechnung der gesetzlichen Frist. Abweichende Fristen aus einem Tarifvertrag, auch kürzere (§ 622 Abs. 4 BGB), und längere Fristen aus dem Arbeitsvertrag sind nicht berücksichtigt.",
    "Besteht ein Betriebsrat, ist er vor jeder Kündigung anzuhören, sonst ist sie unwirksam (§ 102 Abs. 1 BetrVG). Bei einer ordentlichen Kündigung hat er eine Woche Zeit; das bei der Planung des Zugangs einrechnen.",
    "Maßgeblich ist der Tag, an dem die Kündigung zugeht. Die Kündigung braucht die Schriftform (§ 623 BGB)."
  ],
  "quelle": {
    "titel": "§ 622 BGB (Kündigungsfristen bei Arbeitsverhältnissen)",
    "url": "https://www.gesetze-im-internet.de/bgb/__622.html"
  },
  "quellen": [
    {
      "titel": "§ 622 BGB (Kündigungsfristen bei Arbeitsverhältnissen)",
      "url": "https://www.gesetze-im-internet.de/bgb/__622.html"
    },
    {
      "titel": "§ 187 BGB (Fristbeginn)",
      "url": "https://www.gesetze-im-internet.de/bgb/__187.html"
    },
    {
      "titel": "§ 188 BGB (Fristende)",
      "url": "https://www.gesetze-im-internet.de/bgb/__188.html"
    }
  ],
  "stand": "2026-09-23",
  "lizenz": "Berechnung nach den genannten Normen. Nutzung nach den Nutzungsbedingungen von Quellenkontor.",
  "zitat": "Gesetzliche Kündigungsfrist bei Eintritt am 01.03.2017 und Zugang der Kündigung am 10.11.2026, Kündigung durch den Arbeitgeber: 3 Monate zum Ende eines Kalendermonats, das Arbeitsverhältnis endet am 28.02.2027. Schematische Berechnung ohne vertragliche oder tarifliche Fristen. Rechtsgrundlage: § 622 Abs. 2 Satz 1 Nr. 3 BGB. Quelle: § 622 BGB (Kündigungsfristen bei Arbeitsverhältnissen), https://www.gesetze-im-internet.de/bgb/__622.html. Daten: Quellenkontor (quellenkontor.dev).",
  "datenstand": "2026-09-23.1"
}

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:

Terminal
npx @openapitools/openapi-generator-cli generate \
  -i https://api.quellenkontor.dev/v1/openapi.json -g csharp -o ./quellenkontor-client

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.

Ein Schlüssel im Frontend-Code ist ein öffentlicher Schlüssel. Sperre ihn im Konto, falls das passiert ist.

Fehlt etwas oder ist etwas unklar? Schreib uns, wir ergänzen die Doku.