SDK für Python

Das Paket quellenkontor läuft ab Python 3.9 und nutzt nur die Standardbibliothek. Es gibt also keine Abhängigkeiten, die mit deinem Projekt in Konflikt geraten.

pip install quellenkontor

uv add quellenkontor
poetry add quellenkontor

from quellenkontor import Quellenkontor

# liest den Schlüssel aus QK_KEY
qk = Quellenkontor()

# oder ausdrücklich, mit Optionen
qk = Quellenkontor(api_key="qk_live_…", timeout=10.0, wiederholungen=3)

Zwischenspeicher und ETag

Innerhalb von cache_ttl Sekunden kommt eine wiederholte Anfrage mit denselben Parametern ohne jeden Netzwerkaufruf aus dem Zwischenspeicher der Instanz zurück. Danach fragt das SDK mit der gemerkten ETag im Header If-None-Match nach: Hat sich der Wert nicht geändert, antwortet die API mit 304, das SDK reicht die gecachte Antwort weiter, und die Abfrage zählt nicht gegen dein Kontingent. Mehr zum Sparen von Abfragen unter Kontingente und Limits.

qk = Quellenkontor(cache=False)  # immer eine frische Anfrage

# oder den Zwischenspeicher gezielt leeren, etwa nach einem Webhook
qk2 = Quellenkontor()
qk2.cache_leeren()

Offline-Stand

Ist die API nach allen Wiederholungen nicht erreichbar, weicht das SDK auf einen mitgelieferten Offline-Stand aus: den Verlauf jeder Tabelle mit Verlauf, im Paket erzeugt aus dem aktuellen Bestand (derselbe Stand wie /export). Die Antwort trägt dann offline: True und den datenstand des Pakets statt des amtlich aktuellen, ohne die berechneten Zusatzfelder wie zitat. Reine Rechner ohne Tabelle, etwa Kündigungsfrist, Urlaubsanspruch oder Dienstwagen, haben keinen Offline-Stand und bleiben ohne Verbindung ein QuellenkontorFehler mit Code netzwerk.

qk = Quellenkontor(offline=False)  # stattdessen immer den Netzwerkfehler werfen

# mit Offline-Stand (Standard): erkennbar am Feld offline
qk_mit_fallback = Quellenkontor()
ml = qk_mit_fallback.hr.mindestlohn(datum="2027-01-15")
if ml.get("offline"):
    print("Offline-Stand vom", ml["datenstand"])

Jeder Datensatz ist eine Methode unter qk.hr. Sie liefert ein dict mit denselben Feldern wie die API. Optionale Parameter lässt du weg oder übergibst None.

Wahrheitswerte übergibst du als True oder False, das SDK schreibt sie für die API als true und false.

Kündigungsfrist

frist = qk.hr.kuendigungsfrist(eintritt="2017-03-01", zugang="2026-11-10")
print(frist["ende"])  # 2027-02-28

Urlaubsanspruch bei Teilzeit

urlaub = qk.hr.urlaubsanspruch(arbeitstage_pro_woche=3, jahr=2027)
print(urlaub["anspruch_tage_jahr"])

Beitragssätze an einem Stichtag

saetze = qk.hr.beitragssaetze(datum="2026-07-01")
for b in saetze["bestandteile"]:
    print(b["name"], b["satz_prozent"])

Antwortet die API mit einem Fehler, löst das SDK QuellenkontorFehler aus, mit den Attributen status, code und parameter. Ohne Verbindung ist der Status 0 und der Code netzwerk.

from quellenkontor import Quellenkontor, QuellenkontorFehler

try:
    r = qk.hr.rechengroessen(jahr=2030)
except QuellenkontorFehler as e:
    if e.code == "kein_wert":
        print("Noch nicht verkündet:", e)
    elif e.status == 429:
        print("Kontingent aufgebraucht")
    else:
        raise

Mit format="csv" liefert anfrage den CSV-Text. Das Byte-Order-Mark entfernt das SDK, du kannst den Text direkt einlesen:

import io
import pandas as pd

csv = qk.anfrage("/hr/mindestlohn/verlauf", {}, format="csv")
df = pd.read_csv(io.StringIO(csv), parse_dates=["gueltig_ab"])
print(df[["gueltig_ab", "mindestlohn_brutto_stunde"]].tail())