Ist die Lohnfluss-API schon produktiv nutzbar?

Rechnen, Dokumente erzeugen und SV-Meldungen bauen laufen bereits und sind amtlich verprobt. Der verschlüsselte Versand an die Sozialversicherung und das Abholen der Rückmeldungen werden mit dem ITSG-Zertifikat aus der laufenden Systemuntersuchung scharfgeschaltet.

Was bedeutet der Status „In Zertifizierung"?

Der Baustein ist fertig entwickelt, braucht aber ein externes Zertifikat bzw. einen Behörden-Zugang, um live Daten zu übertragen. Das ist ein regulatorischer Schritt, kein offener Entwicklungsstand.

Was passiert mit den Rückmeldungen der Sozialversicherung?

Sie laufen in einen Posteingang — Verarbeitungsprotokolle, eAU-Antworten, ELStAM-Änderungslisten. Die Endpunkte dafür sind gebaut und in der Sandbox testbar. Befüllt wird der Posteingang echt, sobald derselbe verschlüsselte Kanal freigeschaltet ist, über den auch gesendet wird.

Ist diese Liste aktuell?

Sie wird nicht von Hand gepflegt, sondern aus der OpenAPI-Spec des Dienstes erzeugt. Ein Wächter vergleicht die Spec bei jedem Stand beidseitig mit dem Code: eine Route ohne Doku blockt genauso wie ein dokumentierter Endpunkt ohne Code.

Können wir vorab auf einer Testumgebung entwickeln?

Ja. Partner der Warteliste erhalten zuerst Sandbox-Zugang gegen die verfügbaren Endpunkte und die vollständige Referenz.

Transparenz

API-Referenz & Baustand

Wir zeigen offen, wie weit wir sind — Endpunkt für Endpunkt. Kein Marketing-Nebel: jede Zeile trägt ihren echten Status, direkt aus der Spec des Dienstes.

Verfügbar gebaut, liefert echte Ergebnisse · In Zertifizierung fertig, wartet auf ITSG-Zertifikat / Behörden-Zugang

Drei Richtungen — ehrlich getrennt

Die komplette deutsche Entgeltabrechnung teilt sich in Rechnen, Melden, Senden und Abholen. Rechnen und Dokumente sind fertig; die drei Melde-Richtungen stehen so:

① Verfügbar

Melden — erzeugen

Jeder SV-Pflichtdatensatz wird korrekt gebaut: DEÜV, Beitragsnachweis, AAG (U1/U2), EEL, eAU, A1-Entsendung, DSVV. Acht Datensätze, alle grün gegen die amtliche GKV-Kernprüfung.

② In Zertifizierung

Senden — übertragen

Der Transportweg (verschlüsseln, ITSG-signieren, an den GKV-Kommunikationsserver) ist als sauberer Baustein fertig. Scharf wird er mit dem ITSG-Zertifikat aus der Systemuntersuchung.

③ In Zertifizierung

Abholen — empfangen

Rückläufe landen in einem Posteingang: Verarbeitungsprotokolle der Annahmestellen, eAU-Antwort, ELStAM-Änderungslisten. Ablage und Endpunkte sind gebaut und testbar — echte Post kommt durch denselben Kanal, den auch der Versand braucht.

Schlüssel: Senden und Abholen hängen an einem externen Schloss — dem ITSG-Zertifikat aus der Systemuntersuchung. Es öffnet beide Richtungen zugleich.

Endpunkte

Basis-URL https://api.lohnfluss.de/v1 · Auth Authorization: Bearer lk_live_… · Beträge als Cent-Integer.

146 Endpunkte, erzeugt aus der OpenAPI-3.1-Spec (Version 1.0) — Spec als JSON laden. Davon tragen 60 eine vollständig beschriebene Form (Felder und Beispiel); bei den übrigen 86 steht es an der jeweiligen Stelle. Wir schreiben das lieber hin, als es den Leser beim zwanzigsten Endpunkt merken zu lassen.

Zeile anklicken öffnet Parameter, Anfrage, Antworten und einen Aufruf zum Kopieren.

Stammdaten

Arbeitgeber, Mitarbeiter mit Zeitscheiben, Bankverbindung, Kassenverzeichnis.

POST /v1/mandanten Verfügbar Arbeitgeber (Mandant) anlegen partner:mandanten

Anfrage application/json · Pflicht

`typ`	string	`cuvio` = über die Cuvio-Partnerschaft, `direkt` = eigener Vertrag. Werte: `cuviodirekt`
`name`	string
`bundesland`	string	Länderkürzel wie im ELSTER-Header.
`extern_ref`	string	Ihre eigene Id für diesen Arbeitgeber.
`betriebsnummer`	string	Betriebsnummer der Bundesagentur für Arbeit (8-stellig).
`steuernummer`	string	13-stellige bundeseinheitliche Steuernummer.
`finanzamt_nr`	string	Bundesfinanzamtsnummer (4-stellig).
`uv_mitgliedsnr`	string
`uv_bg_ik`	string
`uv_unternehmensnummer`	string	Unternehmensnummer beim UV-Träger. Wird vom Stammdatenabruf bevorzugt vor `uv_mitgliedsnr` gelesen.
`uv_bbnr`	string	Betriebsnummer des UV-Trägers; bevorzugt vor `uv_bg_ik`.
`uv_pin`	string	Zugangskennung für den UV-Stammdatendienst (DSAS/DSSD).
`uv_arbeitgeber_ist_traeger`	boolean	Der Arbeitgeber ist selbst ein Unternehmen eines UV-Trägers (Anlage 19c). Dann gilt UV-Grund A07, und es findet kein Stammdatenabruf statt. Trifft auf gewöhnliche Betriebe nicht zu; steht in keiner amtlichen Liste und ist deshalb ein Stammdatum.
`umlage_u1_teilnahme`	boolean	Nimmt der Betrieb am U1-Verfahren teil (≤ 30 Mitarbeiter)?
`erstattungssatz_u1`	number	Gewählter U1-Erstattungssatz in Prozent.
`zahltag`	integer	Tag im Monat, an dem ausgezahlt wird.
`paragraf_23c_vorlaeufig`	string	Wie werden arbeitgeberseitige Leistungen (z. B. Zuschuss zum Krankengeld) behandelt, solange der Sozialleistungsträger Brutto und Netto nicht mitgeteilt hat? * `vorlaeufig_pflichtig` — voll beitragspflichtig, Korrektur nach der Rückmeldung (Vorgabe; so rechnet die amtliche Lösung) * `beitragsfrei` — mit 0 SV-Tagen beitragsfrei, bis die Rückmeldung kommt (Pflichtenheft S. 82 erlaubt das ausdrücklich) Beide Wege enden am selben Punkt — mit der Rückmeldung wird korrigiert. Der Unterschied ist, wer bis dahin in Vorleistung geht. Werte: `vorlaeufig_pflichtigbeitragsfrei`
`teilmonatsmethode`	string	Wie wird das Gehalt aufgeteilt, wenn jemand mitten im Monat ein- oder austritt? * `dreissigstel` — Gehalt ÷ 30 × SV-Tage (Vorgabe) * `kalendertage` — Gehalt ÷ tatsächliche Tage des Monats × bezahlte Kalendertage Beispiel Eintritt am 16.10. bei 3.100,00 € Monatsgehalt: 1.653,33 € nach Dreißigsteln, 1.600,00 € nach Kalendertagen. ⚠️ Das ist eine arbeitsrechtliche Frage; welches Verfahren gilt, steht im Arbeitsvertrag. Das Pflichtenheft schreibt 1/30 nur für die Beitragsbemessungsgrenze vor — die bleibt in beiden Fällen unberührt, und auch die SV-Tage sind immer Dreißigstel. Werte: `dreissigstelkalendertage`
`aag_zahlungsweg`	string	Wie die Umlagekasse die AAG-Erstattung leistet (DBBV UEBVER). Ohne Angabe gilt der amtliche Regelfall Überweisung. Werte: `ueberweisungverrechnunggutschrift`
`aag_umlagepflicht`	integer	Nimmt der Arbeitgeber am Ausgleichsverfahren U1/U2 teil? `null`/`1` ist der Regelfall; `0` nur für die nach § 11 AAG ausgenommenen Arbeitgeber (Bund, Länder, Gemeinden und weitere öffentliche Arbeitgeber). ⚠️ Das ist NICHT `umlage_u1_teilnahme`: jene hängt an der Betriebsgröße (§ 1 Abs. 1 AAG, i. d. R. ≤ 30 Arbeitnehmer), am U2-Verfahren nimmt jeder Arbeitgeber teil (§ 1 Abs. 2 AAG). ⚠️ Privathaushalte sind hier NICHT ausgenommen — für sie zieht die Minijob-Zentrale U1 und U2 ein. Werte: `01`
`insolvenzgeldumlage_frei`	integer	Befreiung von der Insolvenzgeldumlage nach § 358 Abs. 1 S. 2 SGB III: öffentlicher Dienst (soweit ein Insolvenzverfahren unzulässig ist) und Privathaushalte. `null`/`0` = umlagepflichtig (Regelfall). ⚠️ Ein anderer Kreis als bei `aag_umlagepflicht` — die beiden fallen nur beim öffentlichen Dienst zusammen. Werte: `01`
`betriebsstaette_id`	integer	Der Beschäftigungsbetrieb (Mig. 170, Kriterien ec586c06 · e0b8a69d). `null` = Hauptbetrieb des Mandanten — der Regelfall; gepflegt wird nur, wer in einer ANDEREN Betriebsstätte arbeitet. Die Meldung trägt dann deren Betriebsnummer als BBNRVU, während die HABBNR die des Unternehmens bleibt.
`rechtskreis`	string	Rechtskreis der Betriebsstätte (`W` alte Länder, `O` Beitrittsgebiet). `null` = aus dem Bundesland abgeleitet — für 15 der 16 Länder eindeutig; bei einer Berliner Betriebsstätte ist die Angabe nötig, weil die Grenze historisch durch die Stadt lief. ⚠️ Im Meldefeld KENNZRK ist der Rechtskreis ab dem 01.01.2025 Grundstellung; in den Entgeltunterlagen bleibt er zu führen. Werte: `WO`
`umlage_ausnahme_grund`	string	Begründung der Umlage-Ausnahme (welcher Tatbestand, seit wann). Für die Betriebsprüfung: eine Ausnahme ohne Begründung sieht im Nachhinein wie ein Versehen aus.
`ansprechpartner_anrede`	string	Anrede der Ansprechperson im Meldeverfahren (DXBD, ab 01.01.2027 Pflicht). ⚠️ Ohne Vorgabewert — eine Anrede ist eine Aussage über einen Menschen; fehlt sie, entsteht keine Betriebsdatenmeldung, sondern eine benannte Hürde. Werte: `MWXD`
`postanschrift_name_1`	string	Abweichende Postanschrift — Name. ⚠️ Ausschließlich eine Anschrift des ARBEITGEBERS; Postanschriften Dritter (Steuerberater, Lohnbüro) sind in DSBD und DXBD unzulässig und werden anhand von Signalwörtern erkannt.
`postanschrift_name_2`	string
`postanschrift_name_3`	string
`postanschrift_plz`	string
`postanschrift_ort`	string
`postanschrift_strasse`	string
`postanschrift_hausnummer`	string
`postanschrift_zusatz`	string
`postanschrift_postfach`	string
`postanschrift_land`	string	Länderkennzeichen bei Auslandsanschrift.
`postanschrift_art`	string	Art der Postanschrift (amtlicher Schlüssel). ⚠️ Ohne ihn wird die Postanschrift nicht übertragen — eine unvollständige Anschrift ist schlechter als keine. Bei `dxbd_sondersachverhalt` 1 oder 2 ist die Postanschrift Pflicht. Werte: `1234`
`dienstleister_name_1`	string	Name des Dienstleisters, der die Entgeltabrechnung im Auftrag führt (DSAK-Baustein DBDL). ⚠️ NICHT dasselbe wie `abrechnungsstelle_bbnr`: die sagt, wer SENDET; hier steht, WER abrechnet — ein Steuerberater ohne eigene Betriebsnummer ist Dienstleister und keine Abrechnungsstelle. Eine Änderung löst einen DSAK mit Abgabegrund 02 aus (Pflichtenheft S. 139).
`dienstleister_name_2`	string
`dienstleister_name_3`	string
`dienstleister_ansprechpartner_name`	string	Ansprechpartner beim Dienstleister — ein anderer Mensch als der des Arbeitgebers.
`dienstleister_ansprechpartner_telefon`	string
`dienstleister_ansprechpartner_email`	string
`dienstleister_plz`	string
`dienstleister_ort`	string
`dienstleister_strasse`	string
`dienstleister_hausnummer`	string
`dienstleister_postfach`	string
`dienstleister_land`	string	Länderkennzeichen nach Anlage 8.
`dienstleister_geloescht_am`	string	Tag, an dem der Dienstleister entfallen ist. ⚠️ Ein entfallener Dienstleister wird gemeldet (DBDL mit Kennzeichen Löschen „J"), nicht stillschweigend entfernt — sonst führte die Kasse weiter einen Ansprechpartner, den es nicht mehr gibt.
`dxbd_sondersachverhalt`	string	Kennzeichen_Sondersachverhalte des DXBD. `1` = Arbeitgeber ohne Standort in Deutschland — dann ist die abweichende Postanschrift Pflicht. Werte: `1234`
`dxbd_rechtsform`	string	Rechtsformschlüssel der BA-Codeliste (fünfstellig, DXBD). ⚠️ NICHT dasselbe wie `rechtsform`: das ist der dreistellige Schlüssel des DSBD-Verfahrens.
`dxbd_absendernummer`	string	BBNR, von der der DXBD technisch übermittelt wird (Verfahrensanforderung DXBD/DXBE Ziffer 5.2.1.1). ⚠️ NICHT dasselbe wie `abrechnungsstelle_bbnr`: beide sind eigene Steuerungsdaten mit VERSCHIEDENEN Abgabegründen — eine Änderung der Abrechnungsstelle verlangt A01 „Bestandsmeldung", die alleinige Änderung der Absendernummer A09 „Absenderänderung". Leer ist der Normalfall; dann gilt die eigene Betriebsnummer, die nach der Verfahrensanforderung ohnehin Vorrang hat. Gesetzt nur im Ausnahmefall des § 18n Abs. 2 SGB IV.
`wukl`	string	Wirtschaftsunterklasse des Beschäftigungsbetriebs (DXBD; über A05 abfragbar).
`aag_verwendungszweck`	string	Verwendungszweck der Erstattung (DBBV). ⚠️ Darf KEINE personenbezogenen Daten tragen (Name, Versicherungs-, Personalnummer) — er läuft durch den Zahlungsverkehr. Ein unzulässiger Text wird beim Bauen des Antrags sichtbar durch „Erstattung AAG" ersetzt.
`anschrift_strasse`	string
`anschrift_hausnummer`	string
`anschrift_plz`	string
`anschrift_ort`	string
`ansprechpartner_name`	string
`ansprechpartner_telefon`	string
`ansprechpartner_email`	string
`rechtsform`	string	Schlüssel der Rechtsform (DSBD-Katalog).
`rechtsform_ergaenzung`	string
`abrechnungsstelle_bbnr`	string	Betriebsnummer der Abrechnungsstelle (Steuerberater u. Ä.), mit Prüfziffer. Geht in euBP (DSST BBNRAS), DSBD (BBNR-AS) und löst beim DXBD bei AUSSCHLIESSLICHER Änderung eine Bestandsmeldung A01 aus. Leer = keine Abrechnungsstelle, dann gilt die eigene.
`deuev_systembeginn`	string	DEÜV-Systembeginn (Migration 088, Pflichtenheft 0104 S. 127): erster Tag, ab dem Lohnfluss die DEÜV-Meldungen erstattet. Eintritte davor → Anmeldung GD 13 zu diesem Tag (POST /deuev/bestandsanmeldung); Läufe davor lösen keine DEÜV-Meldungen aus; Rückrechnungen in Monate davor sind gesperrt.
`kug_bewilligung_von`	string	Beginn des von der Agentur für Arbeit bewilligten Arbeitsausfalls. Die Bewilligung trifft den BETRIEB — die einzelne Person hat keinen eigenen Bewilligungszeitraum. Kurzarbeits-Bewegungen außerhalb dieses Zeitraums werden abgewiesen.
`kug_bewilligung_bis`	string
`kug_aktenzeichen`	string	Kug-Aktenzeichen bzw. Stammnummer der Agentur für Arbeit.
`insolvenz_ereignis`	string	Tag des Insolvenzereignisses (§ 165 SGB III). Er trifft den Betrieb und löst je Person die DEÜV-Meldekette aus: freigestellte Beschäftigte bekommen GD 71 zum Vortag, danach die Jahresmeldung GD 70 und zum rechtlichen Ende GD 72; weiterbeschäftigte eine gewöhnliche Abmeldung GD 33. Die Freistellung selbst steht am Mitarbeiter (`insolvenz_freistellung_ab`).
`inso_einzugsstelle_ik`	string	Einzugsstelle (IK) für Beschäftigte OHNE Krankenkasse. Privat Versicherte schulden die Insolvenzgeldumlage nach § 358 SGB III, haben aber keine Kasse; zuständig ist die vom Arbeitgeber gewählte Einzugsstelle (§ 28i Satz 2 SGB IV i. V. m. § 175 Abs. 3 Satz 2 SGB V). Ohne diesen Wert entsteht für den Monat KEIN Beitragsnachweis — bewusst, denn ein Nachweis ohne diese Beiträge wäre zu klein und fiele erst der Betriebsprüfung auf.
`zuschlagsregeln`	object	Betriebliche Regeln für SFN-Zuschläge.
`status`	string	Betriebsstatus. `beendet` = vollständige Einstellung des Beschäftigungsbetriebs → DSBD mit Beendigungskennzeichen „B" (Pflichtenheft S. 146). Wird nur die Abrechnung in diesem Programm beendet (Mandatsabgabe, Systemwechsel) und der Betrieb fortgesetzt, ist `ruhend` richtig. Werte: `aktivruhendbeendet`
`datum_ereignis`	string	Ereignisdatum für den DSBD (Tag, ab dem die Änderung gilt bzw. Tag der vollständigen Einstellung). Nicht vorbelegt (S. 145) — ohne Angabe entsteht eine Hürde statt eines Entwurfs.
`beendigung_bestaetigt`	boolean	Sicherheitsabfrage (S. 153, Mechanismus C) — Pflicht bei `status = beendet`.
`beendigung_trotz_offener_anmeldungen`	boolean	Plausibilisierungshinweis (S. 153, Mechanismus B) ausdrücklich übergehen, wenn noch Beschäftigte angemeldet sind.
`systemwechsel`	boolean	Pflicht, sobald eine Betriebsnummer erstmals erfasst wird (Anlegen oder erster PATCH mit Betriebsnummer): Liegt ein Systemwechsel oder eine Ersterfassung wegen Dienstleisterwechsels vor (Pflichtenheft S. 142)? Bei `true` entsteht der DSBD mit Grund 06 — dann ist `datum_ereignis` (Tag der Übernahme) ebenfalls Pflicht.

{
  "typ": "direkt",
  "name": "Muster Pflegedienst GmbH",
  "bundesland": "NW",
  "betriebsnummer": "12345678",
  "steuernummer": "5133081508159",
  "finanzamt_nr": "5133"
}

Antwort

201 Angelegt.

`id`	integer
`typ`	string
`name`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 name oder typ fehlt bzw. typ ist weder cuvio noch direkt.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "typ": "direkt",
       "name": "Muster Pflegedienst GmbH",
       "bundesland": "NW",
       "betriebsnummer": "12345678",
       "steuernummer": "5133081508159",
       "finanzamt_nr": "5133"
     }'

GET /v1/mandanten Verfügbar Mandanten des Partners auflisten partner:mandanten

Für das Mapping der eigenen extern_ref. Ein Mandanten-Key sieht hier nur sich selbst.

Antwort

200 Liste.

mandanten array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId} Verfügbar Mandant lesen mandant:stammdaten

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Stammdaten.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId} Verfügbar Mandant ändern mandant:stammdaten

Nur die mitgeschickten Felder werden geändert.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`typ`	string	`cuvio` = über die Cuvio-Partnerschaft, `direkt` = eigener Vertrag. Werte: `cuviodirekt`
`name`	string
`bundesland`	string	Länderkürzel wie im ELSTER-Header.
`extern_ref`	string	Ihre eigene Id für diesen Arbeitgeber.
`betriebsnummer`	string	Betriebsnummer der Bundesagentur für Arbeit (8-stellig).
`steuernummer`	string	13-stellige bundeseinheitliche Steuernummer.
`finanzamt_nr`	string	Bundesfinanzamtsnummer (4-stellig).
`uv_mitgliedsnr`	string
`uv_bg_ik`	string
`uv_unternehmensnummer`	string	Unternehmensnummer beim UV-Träger. Wird vom Stammdatenabruf bevorzugt vor `uv_mitgliedsnr` gelesen.
`uv_bbnr`	string	Betriebsnummer des UV-Trägers; bevorzugt vor `uv_bg_ik`.
`uv_pin`	string	Zugangskennung für den UV-Stammdatendienst (DSAS/DSSD).
`uv_arbeitgeber_ist_traeger`	boolean	Der Arbeitgeber ist selbst ein Unternehmen eines UV-Trägers (Anlage 19c). Dann gilt UV-Grund A07, und es findet kein Stammdatenabruf statt. Trifft auf gewöhnliche Betriebe nicht zu; steht in keiner amtlichen Liste und ist deshalb ein Stammdatum.
`umlage_u1_teilnahme`	boolean	Nimmt der Betrieb am U1-Verfahren teil (≤ 30 Mitarbeiter)?
`erstattungssatz_u1`	number	Gewählter U1-Erstattungssatz in Prozent.
`zahltag`	integer	Tag im Monat, an dem ausgezahlt wird.
`paragraf_23c_vorlaeufig`	string	Wie werden arbeitgeberseitige Leistungen (z. B. Zuschuss zum Krankengeld) behandelt, solange der Sozialleistungsträger Brutto und Netto nicht mitgeteilt hat? * `vorlaeufig_pflichtig` — voll beitragspflichtig, Korrektur nach der Rückmeldung (Vorgabe; so rechnet die amtliche Lösung) * `beitragsfrei` — mit 0 SV-Tagen beitragsfrei, bis die Rückmeldung kommt (Pflichtenheft S. 82 erlaubt das ausdrücklich) Beide Wege enden am selben Punkt — mit der Rückmeldung wird korrigiert. Der Unterschied ist, wer bis dahin in Vorleistung geht. Werte: `vorlaeufig_pflichtigbeitragsfrei`
`teilmonatsmethode`	string	Wie wird das Gehalt aufgeteilt, wenn jemand mitten im Monat ein- oder austritt? * `dreissigstel` — Gehalt ÷ 30 × SV-Tage (Vorgabe) * `kalendertage` — Gehalt ÷ tatsächliche Tage des Monats × bezahlte Kalendertage Beispiel Eintritt am 16.10. bei 3.100,00 € Monatsgehalt: 1.653,33 € nach Dreißigsteln, 1.600,00 € nach Kalendertagen. ⚠️ Das ist eine arbeitsrechtliche Frage; welches Verfahren gilt, steht im Arbeitsvertrag. Das Pflichtenheft schreibt 1/30 nur für die Beitragsbemessungsgrenze vor — die bleibt in beiden Fällen unberührt, und auch die SV-Tage sind immer Dreißigstel. Werte: `dreissigstelkalendertage`
`aag_zahlungsweg`	string	Wie die Umlagekasse die AAG-Erstattung leistet (DBBV UEBVER). Ohne Angabe gilt der amtliche Regelfall Überweisung. Werte: `ueberweisungverrechnunggutschrift`
`aag_umlagepflicht`	integer	Nimmt der Arbeitgeber am Ausgleichsverfahren U1/U2 teil? `null`/`1` ist der Regelfall; `0` nur für die nach § 11 AAG ausgenommenen Arbeitgeber (Bund, Länder, Gemeinden und weitere öffentliche Arbeitgeber). ⚠️ Das ist NICHT `umlage_u1_teilnahme`: jene hängt an der Betriebsgröße (§ 1 Abs. 1 AAG, i. d. R. ≤ 30 Arbeitnehmer), am U2-Verfahren nimmt jeder Arbeitgeber teil (§ 1 Abs. 2 AAG). ⚠️ Privathaushalte sind hier NICHT ausgenommen — für sie zieht die Minijob-Zentrale U1 und U2 ein. Werte: `01`
`insolvenzgeldumlage_frei`	integer	Befreiung von der Insolvenzgeldumlage nach § 358 Abs. 1 S. 2 SGB III: öffentlicher Dienst (soweit ein Insolvenzverfahren unzulässig ist) und Privathaushalte. `null`/`0` = umlagepflichtig (Regelfall). ⚠️ Ein anderer Kreis als bei `aag_umlagepflicht` — die beiden fallen nur beim öffentlichen Dienst zusammen. Werte: `01`
`betriebsstaette_id`	integer	Der Beschäftigungsbetrieb (Mig. 170, Kriterien ec586c06 · e0b8a69d). `null` = Hauptbetrieb des Mandanten — der Regelfall; gepflegt wird nur, wer in einer ANDEREN Betriebsstätte arbeitet. Die Meldung trägt dann deren Betriebsnummer als BBNRVU, während die HABBNR die des Unternehmens bleibt.
`rechtskreis`	string	Rechtskreis der Betriebsstätte (`W` alte Länder, `O` Beitrittsgebiet). `null` = aus dem Bundesland abgeleitet — für 15 der 16 Länder eindeutig; bei einer Berliner Betriebsstätte ist die Angabe nötig, weil die Grenze historisch durch die Stadt lief. ⚠️ Im Meldefeld KENNZRK ist der Rechtskreis ab dem 01.01.2025 Grundstellung; in den Entgeltunterlagen bleibt er zu führen. Werte: `WO`
`umlage_ausnahme_grund`	string	Begründung der Umlage-Ausnahme (welcher Tatbestand, seit wann). Für die Betriebsprüfung: eine Ausnahme ohne Begründung sieht im Nachhinein wie ein Versehen aus.
`ansprechpartner_anrede`	string	Anrede der Ansprechperson im Meldeverfahren (DXBD, ab 01.01.2027 Pflicht). ⚠️ Ohne Vorgabewert — eine Anrede ist eine Aussage über einen Menschen; fehlt sie, entsteht keine Betriebsdatenmeldung, sondern eine benannte Hürde. Werte: `MWXD`
`postanschrift_name_1`	string	Abweichende Postanschrift — Name. ⚠️ Ausschließlich eine Anschrift des ARBEITGEBERS; Postanschriften Dritter (Steuerberater, Lohnbüro) sind in DSBD und DXBD unzulässig und werden anhand von Signalwörtern erkannt.
`postanschrift_name_2`	string
`postanschrift_name_3`	string
`postanschrift_plz`	string
`postanschrift_ort`	string
`postanschrift_strasse`	string
`postanschrift_hausnummer`	string
`postanschrift_zusatz`	string
`postanschrift_postfach`	string
`postanschrift_land`	string	Länderkennzeichen bei Auslandsanschrift.
`postanschrift_art`	string	Art der Postanschrift (amtlicher Schlüssel). ⚠️ Ohne ihn wird die Postanschrift nicht übertragen — eine unvollständige Anschrift ist schlechter als keine. Bei `dxbd_sondersachverhalt` 1 oder 2 ist die Postanschrift Pflicht. Werte: `1234`
`dienstleister_name_1`	string	Name des Dienstleisters, der die Entgeltabrechnung im Auftrag führt (DSAK-Baustein DBDL). ⚠️ NICHT dasselbe wie `abrechnungsstelle_bbnr`: die sagt, wer SENDET; hier steht, WER abrechnet — ein Steuerberater ohne eigene Betriebsnummer ist Dienstleister und keine Abrechnungsstelle. Eine Änderung löst einen DSAK mit Abgabegrund 02 aus (Pflichtenheft S. 139).
`dienstleister_name_2`	string
`dienstleister_name_3`	string
`dienstleister_ansprechpartner_name`	string	Ansprechpartner beim Dienstleister — ein anderer Mensch als der des Arbeitgebers.
`dienstleister_ansprechpartner_telefon`	string
`dienstleister_ansprechpartner_email`	string
`dienstleister_plz`	string
`dienstleister_ort`	string
`dienstleister_strasse`	string
`dienstleister_hausnummer`	string
`dienstleister_postfach`	string
`dienstleister_land`	string	Länderkennzeichen nach Anlage 8.
`dienstleister_geloescht_am`	string	Tag, an dem der Dienstleister entfallen ist. ⚠️ Ein entfallener Dienstleister wird gemeldet (DBDL mit Kennzeichen Löschen „J"), nicht stillschweigend entfernt — sonst führte die Kasse weiter einen Ansprechpartner, den es nicht mehr gibt.
`dxbd_sondersachverhalt`	string	Kennzeichen_Sondersachverhalte des DXBD. `1` = Arbeitgeber ohne Standort in Deutschland — dann ist die abweichende Postanschrift Pflicht. Werte: `1234`
`dxbd_rechtsform`	string	Rechtsformschlüssel der BA-Codeliste (fünfstellig, DXBD). ⚠️ NICHT dasselbe wie `rechtsform`: das ist der dreistellige Schlüssel des DSBD-Verfahrens.
`dxbd_absendernummer`	string	BBNR, von der der DXBD technisch übermittelt wird (Verfahrensanforderung DXBD/DXBE Ziffer 5.2.1.1). ⚠️ NICHT dasselbe wie `abrechnungsstelle_bbnr`: beide sind eigene Steuerungsdaten mit VERSCHIEDENEN Abgabegründen — eine Änderung der Abrechnungsstelle verlangt A01 „Bestandsmeldung", die alleinige Änderung der Absendernummer A09 „Absenderänderung". Leer ist der Normalfall; dann gilt die eigene Betriebsnummer, die nach der Verfahrensanforderung ohnehin Vorrang hat. Gesetzt nur im Ausnahmefall des § 18n Abs. 2 SGB IV.
`wukl`	string	Wirtschaftsunterklasse des Beschäftigungsbetriebs (DXBD; über A05 abfragbar).
`aag_verwendungszweck`	string	Verwendungszweck der Erstattung (DBBV). ⚠️ Darf KEINE personenbezogenen Daten tragen (Name, Versicherungs-, Personalnummer) — er läuft durch den Zahlungsverkehr. Ein unzulässiger Text wird beim Bauen des Antrags sichtbar durch „Erstattung AAG" ersetzt.
`anschrift_strasse`	string
`anschrift_hausnummer`	string
`anschrift_plz`	string
`anschrift_ort`	string
`ansprechpartner_name`	string
`ansprechpartner_telefon`	string
`ansprechpartner_email`	string
`rechtsform`	string	Schlüssel der Rechtsform (DSBD-Katalog).
`rechtsform_ergaenzung`	string
`abrechnungsstelle_bbnr`	string	Betriebsnummer der Abrechnungsstelle (Steuerberater u. Ä.), mit Prüfziffer. Geht in euBP (DSST BBNRAS), DSBD (BBNR-AS) und löst beim DXBD bei AUSSCHLIESSLICHER Änderung eine Bestandsmeldung A01 aus. Leer = keine Abrechnungsstelle, dann gilt die eigene.
`deuev_systembeginn`	string	DEÜV-Systembeginn (Migration 088, Pflichtenheft 0104 S. 127): erster Tag, ab dem Lohnfluss die DEÜV-Meldungen erstattet. Eintritte davor → Anmeldung GD 13 zu diesem Tag (POST /deuev/bestandsanmeldung); Läufe davor lösen keine DEÜV-Meldungen aus; Rückrechnungen in Monate davor sind gesperrt.
`kug_bewilligung_von`	string	Beginn des von der Agentur für Arbeit bewilligten Arbeitsausfalls. Die Bewilligung trifft den BETRIEB — die einzelne Person hat keinen eigenen Bewilligungszeitraum. Kurzarbeits-Bewegungen außerhalb dieses Zeitraums werden abgewiesen.
`kug_bewilligung_bis`	string
`kug_aktenzeichen`	string	Kug-Aktenzeichen bzw. Stammnummer der Agentur für Arbeit.
`insolvenz_ereignis`	string	Tag des Insolvenzereignisses (§ 165 SGB III). Er trifft den Betrieb und löst je Person die DEÜV-Meldekette aus: freigestellte Beschäftigte bekommen GD 71 zum Vortag, danach die Jahresmeldung GD 70 und zum rechtlichen Ende GD 72; weiterbeschäftigte eine gewöhnliche Abmeldung GD 33. Die Freistellung selbst steht am Mitarbeiter (`insolvenz_freistellung_ab`).
`inso_einzugsstelle_ik`	string	Einzugsstelle (IK) für Beschäftigte OHNE Krankenkasse. Privat Versicherte schulden die Insolvenzgeldumlage nach § 358 SGB III, haben aber keine Kasse; zuständig ist die vom Arbeitgeber gewählte Einzugsstelle (§ 28i Satz 2 SGB IV i. V. m. § 175 Abs. 3 Satz 2 SGB V). Ohne diesen Wert entsteht für den Monat KEIN Beitragsnachweis — bewusst, denn ein Nachweis ohne diese Beiträge wäre zu klein und fiele erst der Betriebsprüfung auf.
`zuschlagsregeln`	object	Betriebliche Regeln für SFN-Zuschläge.
`status`	string	Betriebsstatus. `beendet` = vollständige Einstellung des Beschäftigungsbetriebs → DSBD mit Beendigungskennzeichen „B" (Pflichtenheft S. 146). Wird nur die Abrechnung in diesem Programm beendet (Mandatsabgabe, Systemwechsel) und der Betrieb fortgesetzt, ist `ruhend` richtig. Werte: `aktivruhendbeendet`
`datum_ereignis`	string	Ereignisdatum für den DSBD (Tag, ab dem die Änderung gilt bzw. Tag der vollständigen Einstellung). Nicht vorbelegt (S. 145) — ohne Angabe entsteht eine Hürde statt eines Entwurfs.
`beendigung_bestaetigt`	boolean	Sicherheitsabfrage (S. 153, Mechanismus C) — Pflicht bei `status = beendet`.
`beendigung_trotz_offener_anmeldungen`	boolean	Plausibilisierungshinweis (S. 153, Mechanismus B) ausdrücklich übergehen, wenn noch Beschäftigte angemeldet sind.
`systemwechsel`	boolean	Pflicht, sobald eine Betriebsnummer erstmals erfasst wird (Anlegen oder erster PATCH mit Betriebsnummer): Liegt ein Systemwechsel oder eine Ersterfassung wegen Dienstleisterwechsels vor (Pflichtenheft S. 142)? Bei `true` entsteht der DSBD mit Grund 06 — dann ist `datum_ereignis` (Tag der Übernahme) ebenfalls Pflicht.

{
  "zahltag": 28,
  "erstattungssatz_u1": 70
}

Antwort

200 Geändert — geaendert nennt die tatsächlich geschriebenen Felder.

`ok`	boolean
`geaendert`	array<string>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Kein einziges änderbares Feld im Body.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "zahltag": 28,
       "erstattungssatz_u1": 70
     }'

PUT /v1/mandanten/{mandantId}/bank Verfügbar Auftraggeber-Bankverbindung setzen mandant:stammdaten

Pflicht, bevor beim Festschreiben eine SEPA-Datei entstehen kann. Die bisherige Verbindung wird inaktiv gesetzt, die neue angelegt — die Historie bleibt erhalten. bic ist SEPA-Pflichtfeld (DbtrAgt), auch wenn Banken es im Alltag oft weglassen.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`kontoinhaber`*	string
`iban`*	string	Wird auf Prüfsumme geprüft; Leerzeichen sind erlaubt.
`bic`*	string
`zweck_praefix`	string	Vorspann im Verwendungszweck jeder Zeile.

Antwort

200 Gesetzt.

`ok`	boolean
`id`	integer

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 kontoinhaber fehlt, IBAN ungültig oder BIC nicht 8/11 Zeichen — fehler.feld nennt das Feld.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/bank" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/sepa-mandat Verfügbar SEPA-Lastschriftmandat gegenüber einer Einzugsstelle erteilen oder widerrufen mandant:stammdaten

Nicht die Bankverbindung des Mandanten (die ist die Zahlstelle für pain.001): das Mandat ist die Ermächtigung der KRANKENKASSE, Beiträge einzuziehen. Gläubiger ist die Kasse — sie vergibt Gläubiger-ID und Mandatsreferenz, und ein Arbeitgeber mit fünf Kassen hat fünf Mandate. Deshalb ist kasse_ik Pflicht.

Jede Änderung löst einen DSAK mit Abgabegrund 02 aus (Pflichtenheft S. 139 · 66596d3b). Der Widerruf ist dort ein eigener meldepflichtiger Sachverhalt: er wird gemeldet, nicht gelöscht — die Kasse muss wissen, dass sie nicht mehr einziehen darf. Dafür widerrufen_am setzen; das Mandat bleibt stehen.

Die Antwort trägt bei der Erteilung den Hinweis, den das Pflichtenheft empfiehlt (S. 140 · cedc0577): „Das SEPA-Lastschriftmandat gilt für alle fälligen Beiträge inklusive etwaiger Mahngebühren und Säumniszuschläge."

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`kasse_ik`*	string	Institutionskennzeichen der einziehenden Einzugsstelle (9 Ziffern).
`glaeubiger_id`*	string	SEPA-Gläubiger-Identifikationsnummer der Kasse. Kein Ersatzwert — ohne sie entsteht kein DBSL.
`mandatsreferenz`	string	Von der Kasse vergeben; für den Anwender geführt, nicht im DBSL.
`kontoinhaber`*	string
`iban`*	string
`erteilt_am`*	string
`widerrufen_am`	string?	Gesetzt = Widerruf (eigener meldepflichtiger Sachverhalt). Muss ab `erteilt_am` liegen.

Antwort

200 Gesetzt. Bei der Erteilung mit dem empfohlenen Hinweistext.

`ok`	boolean
`id`	integer
`hinweis`	string	Nur bei der Erteilung.
`dsak`	array<object>	Erzeugte DSAK-Entwürfe.
`hinweise`	array<string>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 kasse_ik, glaeubiger_id, kontoinhaber, IBAN oder Datum fehlerhaft — fehler.feld nennt das Feld.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/sepa-mandat" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/lohnarten Verfügbar Lohnarten-Stamm lesen mandant:stammdaten

Alle Lohnarten des Mandanten und die mitgelieferten (Auslieferungs-Set, eigene: false).

Die Lohnart trägt die beitragsrechtliche Steuerung des Entgeltbestandteils: steuer_pflicht, sv_pflicht, uv_pflicht und ega (einmalig gezahltes Arbeitsentgelt, § 23a SGB IV).

⚠️ uv_pflicht ist eigenständig, nicht aus sv_pflicht abgeleitet. Was ins Wertguthaben eingebracht wird, mindert das sv-pflichtige Entgelt — das uv-pflichtige nicht (Entstehungsprinzip).

⚠️ Der Stamm steuert die Rechnung noch nicht. Er begleitet sie: weicht eine gepflegte Lohnart von dem ab, was gerechnet wurde, erscheint das als Warnung am Lauf.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`stichtag`	string · Query	Ohne Angabe der heutige Tag.

Antwort

200 Liste.

`stichtag`	string
`lohnarten`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnarten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/lohnarten Verfügbar Eigene Lohnart anlegen oder ändern mandant:stammdaten

Legt eine Lohnart des Mandanten an. Eine eigene Lohnart geht der mitgelieferten mit derselben Nummer vor — das Auslieferungs-Set bleibt unangetastet.

⚠️ Änderungen entstehen als ZEITSCHEIBE, nicht als Überschreiben: ein anderes gueltig_ab legt eine neue Zeile an, die alte bleibt. Nur so ist beantwortbar, wie ein zurückliegender Monat gerechnet wurde (Pflichtenheft S. 102: „Die Lohnarten und deren Änderungen — sofern sie sv-rechtliche Auswirkungen haben — werden historisch dokumentiert.").

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`nummer`*	string
`bezeichnung`*	string
`bewegungsart`	string?	Bewegungsart aus `lohn_bewegungen.art`; wird gegen deren Werte geprüft. NULL bei Lohnarten aus der Zeitscheibe (Grundgehalt, VWL, bAV).
`steuer_pflicht`	boolean
`sv_pflicht`	boolean
`uv_pflicht`	boolean
`ega`	boolean
`gueltig_ab`*	string
`gueltig_bis`	string?

Antwort

200 Angelegt oder geändert.

`ok`	boolean
`id`	integer?

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 nummer, bezeichnung, gueltig_ab fehlen oder bewegungsart gibt es nicht.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnarten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter Verfügbar Mitarbeiter mit erster Zeitscheibe anlegen mandant:stammdaten

Legt Stammdaten und die erste Zeitscheibe in einem Aufruf an. Ohne gueltig_ab beginnt die Scheibe am eintritt.

Der taetigkeitsschluessel wird gegen den amtlichen Katalog geprüft, sofern er mitgeschickt wird — ein falscher Schlüssel fiele sonst erst Monate später bei der Einzugsstelle auf, mit Korrekturmeldung.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`gueltig_ab`	string	Beginn der Zeitscheibe. Beim Anlegen optional (dann `eintritt`), beim Ändern Pflicht, sobald ein Zeitscheiben-Feld dabei ist.
`extern_ref`	string
`vorname`	string
`nachname`	string
`geburtsdatum`	string
`geburtsname`	string
`geschlecht`	string	Werte: `mwdx`
`anschrift_strasse`	string
`anschrift_hausnummer`	string
`anschrift_plz`	string
`anschrift_ort`	string
`anschrift_land`	string
`staatsangehoerigkeit`	string
`sv_nummer`	string	Versicherungsnummer der Rentenversicherung.
`insolvenz_freistellung_ab`	string	Im Insolvenzfall ab diesem Tag freigestellt. Leer heißt weiterbeschäftigt — und dieser Unterschied entscheidet die Meldung: Freigestellte bekommen GD 71/70/72, Weiterbeschäftigte eine gewöhnliche Abmeldung GD 33. Wirkt nur zusammen mit `insolvenz_ereignis` am Mandanten.
`rentenbezieher`	boolean?	Bezieht eine Rente (euBP DSAN KENNZRBZ, Mussfeld J/N). null = nicht erfasst — dann entsteht keine euBP-Lieferung, sondern eine Hürde, die die Person nennt; aus der Beitragsgruppe ableitbar ist nur der Altersvollrentner mit RV „3" (Mig. 083).
`steuer_id`	string	Steuer-Identifikationsnummer (11-stellig).
`iban`	string
`bic`	string
`eintritt`	string
`austritt`	string
`personengruppe`	string	Amtlicher Personengruppenschlüssel, z. B. `101`, `106` (Werkstudent), `109` (geringfügig).
`taetigkeitsschluessel`	string	9-stellig; wird gegen den amtlichen Katalog geprüft.
`taetigkeitsbezeichnung`	string	Tätigkeit im Klartext für die Einzelaufstellung der Beitragsabrechnung-UV (Pflichtenheft Unfallversicherung 0115, S. 412 Nr. 3a). ⚠️ Ausdrücklich „keine Übernahme aus dem Tätigkeitsschlüssel": der neunstellige BA-Schlüssel ist eine Klassifikation, kein Berufsname. Leer heißt „nicht erfasst" — im Dokument steht dann ein Strich, keine erfundene Bezeichnung (Mig. 162).
`beitragsgruppe`	string	Beitragsgruppenschlüssel KV/RV/AV/PV, z. B. `1111` oder `0100` (Werkstudent).
`kasse_ik`	string	Institutionskennzeichen der Krankenkasse.
`steuerklasse`	integer
`faktor`	number	Faktorverfahren in Steuerklasse IV.
`kinderfreibetraege`	number
`kist_merkmal`	string	Kirchensteuer-Merkmal, z. B. `rk`, `ev`.
`pv_kinder`	integer	Zahl der Kinder unter 25 — steuert die Abschläge in der Pflegeversicherung.
`vertrag`	string	Entlohnungsform, nicht Vertragsdauer: `gehalt` (fester Monatsbetrag), `stundenlohn` (Satz mal geleistete Stunden) oder `sonstiges` (Akkord, Stücklohn, Provision). Steuert, welches Feld die Engine heranzieht — `grundgehalt_cent` oder `stundenlohn_cent`. ⚠️ Bei `sonstiges` gibt es weder ein Grundgehalt noch einen Stundensatz: der Betrag steht an der Bewegung und wird nicht gerechnet. Eine Bewegung ohne Betrag ergibt einen benannten Hinweis, keine geschätzte Zahlung. Die Entgeltfortzahlung im Krankheitsfall entsteht wie beim Stundenlohn aus dem Durchschnitt der Referenzmonate (§ 4 Abs. 1a EFZG). Die Entlohnungsform bestimmt zugleich das Feld ENTGART der Entgeltbescheinigung (1 = Stundenlohn · 2 = festes Monatsentgelt · 3 = Sonstiges). Sie entscheidet damit mit, ob der Datenbaustein Arbeitszeit (DBZA) entsteht. ⚠️ Die Spalte ist ein ENUM. Ein anderer Wert wurde bis 08.08.2026 als „Data truncated" mit HTTP 500 quittiert; heute antwortet die API mit 422 und nennt das Feld. Werte: `gehaltstundenlohnsonstiges`
`wochenstunden`	number
`arbeitszeitmodell`	string?	Wertguthaben-Arbeitszeitmodell § 7 Abs. 1a SGB IV (EEL, DBAL ARBZEITMOD).
`pv_elterneigenschaft`	boolean\|integer?	Elterneigenschaft nach § 55 Abs. 3 SGB XI. ⚠️ Dreiwertig: `true`/`1` = Elternteil (kein Zuschlag für Kinderlose, lebenslang und unabhängig vom Alter der Kinder), `false`/`0` = kinderlos, `null` = nicht bekannt. `null` ist ausdrücklich nicht „kinderlos": ohne Nachweis wird der Zuschlag weder unterstellt noch erlassen. Eine Angabe hier schlägt die DaBPV-Rückmeldung des BZSt.
`bei_lkk_versichert`	boolean\|integer?	Versicherung bei der landwirtschaftlichen Krankenkasse (LKK). Dreiwertig, `null` = nicht angegeben. Die Personengruppen 112 und 114 setzen sie voraus.
`hauptberuflich_landwirt`	boolean\|integer?	Hauptberuflich selbständige Erwerbstätigkeit als Landwirt. Dann ist die Krankenversicherungspflicht in dieser Beschäftigung ausgeschlossen (BGR-KV muss 0 sein); für den Einzug der RV-/AV-Beiträge ist die LKK zuständig.
`befristung_wochen`	integer?	Voraussichtliche Dauer einer befristeten Beschäftigung. PGS 114 gilt nur bis 26 Wochen.
`freiwillig_ohne_krankengeld`	boolean\|integer?	In der LKK freiwillig und ohne Anspruch auf Krankengeld versichert. Dann wird der Beitrag nicht nach Beitragssatz gerechnet, sondern nach der Beitragsklasse der LKK-Satzung — ohne `lkv_beitrag_kv_cent` wird gar nicht gerechnet.
`lkv_beitrag_kv_cent`	integer?	Nach Beitragsklasse der LKK-Satzung vorgegebener KV-Beitrag, in Cent.
`lkv_beitrag_pv_cent`	integer?	Vorgegebener PV-Beitrag (Zuschlag zum KV-Beitrag der LKK), in Cent.
`beitragsherabsetzung_ab`	string?	Tag der Antragstellung auf Beitragsherabsetzung bei Kurzarbeit (freiwillig gesetzlich Versicherte). ⚠️ Ein Datum, kein Kennzeichen: die Wirkung reicht ab Antragstellung bis zum Ende des Kalenderjahres — und nur in Monaten mit tatsächlichem Kug-Bezug. Ohne Antrag bleibt es beim Höchstbeitrag aus der Beitragsbemessungsgrenze.
`pauschsteuer_abgewaelzt`	boolean	Die Pauschsteuer wird auf den geringfügig Beschäftigten abgewälzt (§ 40a Abs. 5 in Verbindung mit § 40 Abs. 3 EStG, Migration 138). Schuldner der pauschalen Lohnsteuer bleibt der Arbeitgeber; die Abwälzung im Innenverhältnis ist zulässig, wenn sie vereinbart ist. ⚠️ Sie mindert das Arbeitsentgelt nicht: beitragspflichtig bleibt der volle Betrag, und die Pauschsteuer selbst wird weiter vom vollen Entgelt berechnet. Sie ist ein reiner Netto-Abzug und mindert zugleich die Arbeitgeberkosten. Zweiwertig mit Vorgabe `false` — wer nichts vereinbart hat, hat nicht abgewälzt.
`u1_pflicht`	boolean?	Übersteuerung der U1-Umlagepflicht für diese Person (Pflichtenheft S. 79, Migration 140). ⚠️ Dreiwertig: `null` heißt wie im Unternehmen — nicht „nein". Die Regel gilt für den Betrieb, nicht für die Person; es gibt aber Fälle, in denen der Anwender sie einzeln setzen muss. Die Übersteuerung wird verworfen, wenn im Unternehmen überhaupt keine Umlagepflicht besteht — dann trägt die Abrechnung eine Begründung, statt still zu rechnen.
`u2_pflicht`	boolean?	Übersteuerung der U2-Umlagepflicht für diese Person (Pflichtenheft S. 79, Migration 140). ⚠️ Dreiwertig wie `u1_pflicht`; `null` = wie im Unternehmen.
`saisonarbeitnehmer`	boolean\|integer?	Kennzeichen SAISONARBEITNEHMER im DBME der Anmeldung. Eine Änderung erzeugt Storno + Neuanmeldung.
`arbeitnehmer_status`	string?	Arbeitnehmereigenschaft für die Insolvenzgeldumlage (§ 358 Abs. 1 SGB III). Ein beherrschender Gesellschafter-Geschäftsführer ist keiner. ⚠️ `null` = nicht festgelegt; das Programm entscheidet es nicht, es macht den Fall sichtbar. Werte: `arbeitnehmerkein_arbeitnehmernull`
`statuskennzeichen`	string?	KENNZSTA im DSME (Angehöriger/Ehegatte/Gesellschafter-Geschäftsführer).
`einzugsstelle_ik`	string?	Einzugsstelle für Beschäftigte ohne gesetzliche Krankenkasse (privat versichert, versicherungsfrei).
`umlagekasse_ik`	string?	Vom Arbeitgeber gewählte Umlagekasse (U1/U2), wenn die Krankenkasse keine ist — etwa bei der SVLFG.
`ausgleichseinrichtung_ik`	string?	Ausgleichseinrichtung nach dem AAG, sofern abweichend.
`kug_leistungssatz`	integer?	Kug-Leistungssatz in Prozent, je Zeitraum individuell (eine Nachberechnung muss den damals geltenden treffen).
`kv_gesetzlich`	boolean\|integer?	Krankenversicherungsschutz bei kurzfristig Beschäftigten (DSME-Feld KENNZKV, seit 2022 Pflicht bei PGR 110). ⚠️ Dreiwertig — „nicht angegeben" ist etwas anderes als „privat".
`sollarbeitszeit`	number?	Tarifliche/vertragliche Sollarbeitszeit — Grundlage des Lohnnachweises beim UV-Beitragsmaßstab „Arbeitsstunden".
`sollarbeitszeit_einheit`	string?	Einheit der Sollarbeitszeit (Woche/Monat/Jahr).
`urlaubstage`	number
`schwerbehinderung`	boolean
`mehrfachbeschaeftigt`	boolean
`privat_kv`	boolean	Privat krankenversichert. Setzt in der Lohnsteuer das Merkmal PKV und schaltet bei geringfügig Beschäftigten die 13-%-Pauschale ab.
`pkv_beitrag_cent`	integer	Monatsbeitrag zur privaten Kranken-/Pflegeversicherung, Grundlage des Zuschusses.
`keine_rv`	boolean	rentenversicherungsfrei
`arbeitstage_muster`	string	Die Arbeitstage als aufsteigende Ziffernfolge der Wochentage, 1 = Montag bis 7 = Sonntag: `12345` = Montag bis Freitag, `135` = Montag, Mittwoch, Freitag. Jeder Tag höchstens einmal und in dieser Reihenfolge — so verlangt es die CHECK-Regel der Datenbank. Grundlage der Arbeits- und Ausfalltage.
`gefahrtarifstelle`	string	Aus dem Veranlagungsbescheid der Berufsgenossenschaft (§ 159 Abs. 1 SGB VII). Geht in den DSME (Feld GT_STELLE) und in die UV-Jahresmeldung; ohne sie ist kein Lohnnachweis möglich.
`freiwillig_gkv`	boolean	Freiwilliges Mitglied der gesetzlichen Krankenversicherung als Selbstzahler — der Beschäftigte zahlt seine Beiträge selbst und bekommt den Zuschuss nach § 257 Abs. 1 SGB V. ⚠️ Nicht dasselbe wie das Firmenzahlerverfahren (Beitragsgruppe KV `9`): dort führt der Arbeitgeber die vollen Beiträge ab und zahlt keinen Zuschuss. Beides zusammen ist ein Widerspruch; der Lohnlauf meldet ihn und zahlt nichts.
`freiwillig_kv_beitrag_cent`	integer?	Tatsächlicher monatlicher KV-Beitrag des Beschäftigten — der Zuschuss beträgt höchstens die Hälfte davon.
`freiwillig_pv_beitrag_cent`	integer?	Tatsächlicher monatlicher PV-Beitrag. Ohne diese Angabe entfällt der Zuschuss zur Pflegeversicherung.
`pkv_pv_beitrag_cent`	integer?	Der private Pflegeversicherungsbeitrag, getrennt vom Gesamtbeitrag `pkv_beitrag_cent`. Ohne ihn wird der Gesamtbeitrag als KV-Beitrag angesetzt und der PV-Zuschuss entfällt — das ist die vorsichtige, aber tendenziell zu niedrige Variante.
`zuschuss_art`	string	Art der Bezuschussung bei freiwilliger GKV: am tatsächlichen Entgelt (gekappt auf die Beitragsbemessungsgrenze) oder immer an der BBG — dann der Höchstzuschuss. ⚠️ Ein Stammdatum, keine Rechenfrage: in jedem Teilentgelt-Monat kommt je nach Wahl ein anderer Betrag heraus. Werte: `entgeltbbg`
`rentenart`	string?	Kennzeichen Rentenart nach Anlage 04a zum Pflichtenheft. `null` = kein Rentenbezug. ⚠️ Sobald eine Vollrente wegen Alters oder eine Vollversorgung hier steht, ist `verzicht_rv_freiheit` ausdrücklich zu beantworten; bei allen anderen Werten muss es in Grundstellung bleiben (Prüfkriterien 001/002). ⚠️ Bei `altersteilrente`, `teilversorgung`, `altersvollrente_nicht_eu` und `erwerbsminderung_voll` sind die Personengruppen 119 und 120 unzulässig — eine Altersvollrente eines Nicht-EU/EWR/SVA-Staates ist der deutschen nicht gleichgestellt (Prüfkriterium 012). ⚠️ Liegen mehrere Arten vor, gilt die in dieser Aufzählung weiter oben stehende. Werte: `altersvollrenteberufsstaendischbeamtenrechtlichaltersteilrenteteilversorgungaltersvollrente_nicht_euerwerbsminderung_vollnull`
`rentenbeginn`	string?	Rentenbeginn laut Rentenbescheid — geht in die Prüfkriterien 009 und 010 ein.
`anpassungsgeld_bergbau`	boolean	Anpassungsgeld für entlassene Arbeitnehmer des Bergbaus vor Rentenbeginn bezogen. ⚠️ Dann gilt die Regelaltersgrenze schon in dem Monat als erreicht, in dem das 65. Lebensjahr vollendet wurde — das verschiebt alle Stichtagsprüfungen.
`in_ausbildung`	boolean\|integer?	Steht die Person in Berufsausbildung? `null` = keine Angabe (keine Prüfung). Bei `true` hat die Ausbildungs-Personengruppe Vorrang (102 Auszubildende · 105 Praktikanten · 121/122 außerbetriebliche Ausbildung); eine andere Personengruppe führt zu einem Prüfketten-Befund. ⚠️ Der Tätigkeitsschlüssel trägt den Ausbildungs-Abschluss, nicht den laufenden Ausbildungsvertrag — daraus lässt sich das Merkmal nicht ableiten.
`knappschaftlich_rv`	boolean\|integer?	Beschäftigung in einem knappschaftlichen Betrieb: die Rentenversicherung folgt dann einer eigenen Beitragsbemessungsgrenze (§ 159 SGB VI — 2026: 10.400 € im Monat statt 8.450 €) und einem eigenen Beitragssatz (§ 158 SGB VI), der sich nicht hälftig teilt (§ 168 Abs. 3 SGB VI). ⚠️ Die Arbeitslosenversicherung bleibt bei der allgemeinen Grenze (§ 341 Abs. 4 SGB III). ⚠️ Solange `sv_saetze.rv_knappschaftlich` und `…_an` nicht gepflegt sind, wird für diese Person nicht gerechnet (Prüfketten-Befund). Ein Rückfall auf den allgemeinen Satz wäre für beide Seiten falsch.
`verzicht_eingang_am`	string?	Verzichtserklärung beim Arbeitgeber eingegangen am. Nur bei `verzicht_rv_freiheit: true` zulässig — ohne Erklärung muss das Feld leer bleiben (Prüfkriterien 003/004).
`verzicht_gueltig_ab`	string?	Verzicht auf die RV-Freiheit gültig ab. Muss nach dem Eingangsdatum liegen — der Verzicht wirkt nur für die Zukunft und ist für die Dauer der Beschäftigung bindend (Prüfkriterien 005–010).
`verzicht_rv_freiheit`	boolean?	Verzicht auf Rentenversicherungsfreiheit. Dreiwertig: `null` = nicht angegeben, und das ist etwas anderes als `false`. ⚠️ „Das Feld darf nicht mit einer fachlichen Ausprägung vorbelegt sein." Ob jemand auf seine Versicherungsfreiheit verzichtet hat, kann die Software nicht entscheiden.
`freiwilligendienst_anschluss`	boolean?	Freiwilligendienst (Personengruppen 119, 120, 123): Schließt sich der Dienst unmittelbar — innerhalb von vier Wochen — an eine versicherungspflichtige Beschäftigung an? Historisiert an der Zeitscheibe (Migration 144). Tut er das, werden die Beiträge zur Arbeitslosenversicherung nicht aus dem Taschengeld, sondern aus der monatlichen Bezugsgröße berechnet (§ 345 Nr. 4 SGB III). Bei 400 € Taschengeld und rund 3.955 € Bezugsgröße ist das etwa das Zehnfache; die übrigen Zweige bleiben unberührt. Dreiwertig: `null` = nicht angegeben, `true` = schließt unmittelbar an, `false` = nicht. ⚠️ `null` ist kein neutraler Zustand: die Prüfkette meldet dann einen Fehler, und der Monat lässt sich nicht festschreiben. Ein Vorgabewert `false` wäre die stille Fortschreibung eines zu niedrigen Beitrags — auffallen würde er erst bei der Betriebsprüfung.
`uebergangsbereich_anwenden`	boolean?	Kennzeichen „Anwendung Übergangsbereich" (Midijob), historisiert an der Zeitscheibe. Dreiwertig: `null` = automatisch nach dem Entgelt (Vorgabe), `true` = erzwingen, `false` = ausschließen. ⚠️ Der Übergangsbereich gilt von Gesetzes wegen, sobald das Entgelt im Korridor liegt — er ist kein Wahlrecht. Die beiden ausdrücklichen Werte sind für die Fälle, die der Automatismus nicht entscheiden kann (Mehrfachbeschäftigung, Bestandsfälle); jede Abweichung vom Korridor meldet der Lohnlauf.
`rv_befreiung_antrag_am`	string?	Tag, an dem der Antrag auf Befreiung von der Rentenversicherungspflicht (§ 6 Abs. 1b SGB VI) beim Arbeitgeber einging — nur für Minijobs (PGS 109). ⚠️ Ein Datum, kein Häkchen: die Befreiung wirkt ab dem Beginn des Monats, in dem der Antrag einging, wenn der Arbeitgeber ihn der Minijob-Zentrale binnen sechs Wochen meldet — sonst erst ab dem Folgemonat der Meldung. Beim Altfall (Beschäftigungsbeginn vor dem 01.01.2013, Entgelterhöhung danach über 400 €) wird daraus die Anzeige an die Minijob-Zentrale: `POST /mandanten/{id}/mitarbeiter/{id}/minijob-befreiung` erzeugt die Meldungen 33/13.
`rechtskreis`	string?	Rechtskreis des Beschäftigungsortes (`W` = alte Länder, `O` = Beitrittsgebiet). ⚠️ `null` heißt „folgt dem Mandanten", nicht „unbekannt" — gepflegt wird nur der Beschäftigte, der woanders arbeitet als der Betrieb sitzt. ⚠️ Sein Wechsel ist ein Meldetatbestand (Abmeldung 33 / Anmeldung 13) — aber nur für Zeiträume vor dem 01.01.2025. Ab dann ist KENNZRK Grundstellung (DBME166); ein Meldepaar für einen späteren Wechsel wäre ein Fehler. Werte: `WOnull`
`betriebsstaette_id`	integer?	Der Beschäftigungsbetrieb (Mig. 170, Kriterien ec586c06 · 1721b032 · e0b8a69d). Ein Arbeitgeber darf für mehrere Beschäftigungsbetriebe mehrere Betriebsnummern führen; genau eine ist die Hauptbetriebsnummer (HABBNR), unter der die Beitragsnachweise abgegeben werden. Die Meldung dieser Person trägt als Verursacher (BBNRVU) die Nummer ihres Betriebs. ⚠️ `null` heißt „Hauptbetrieb", nicht „unbekannt" — wie beim `rechtskreis` darüber: gepflegt wird nur, wer in einer ANDEREN Betriebsstätte arbeitet. Die Betriebsstätten selbst stehen unter `/mandanten/{mandantId}/betriebsstaetten`.
`uv_frei`	string?	Grund, warum in diesem Zeitraum kein uv-pflichtiges Arbeitsentgelt entsteht. `null` (Vorgabe) = uv-pflichtig — wer nichts einträgt, wird gemeldet. * `ausland` — keine UV-Pflicht wegen Auslandsbeschäftigung * `sgb7` — Versicherungsfreiheit in der Unfallversicherung nach SGB VII * `freistellung` — unwiderrufliche Freistellung von der Arbeitsleistung * `duales_studium` — Theoriephase eines praxisorientierten dualen Studiengangs Wirkung: das UV-Entgelt des Monats ist 0, die Person steht im zweiten Teil der Beitragsabrechnung-UV statt im Lohnnachweis. Liegt der Sachverhalt ganzjährig vor, entsteht auch keine UV-Jahresmeldung. Werte: `auslandsgb7freistellungduales_studiumnull`
`hauptarbeitgeber`	boolean	ELStAM: `true` = erstes Dienstverhältnis (die Person erhält ihre erste Steuerklasse), `false` = Nebenarbeitgeber (Steuerklasse 6). ⚠️ Bis zum 09.08.2026 gab es dieses Stammdatum nicht — die Betriebsautomatik meldete deshalb jeden Beschäftigten als Hauptarbeitgeber an. Wer es falsch stehen lässt, bekommt die erste Steuerklasse und behält zu wenig Lohnsteuer ein; der Fehler steckt in den Abzugsmerkmalen, nicht in der Rechnung.
`sammelbefoerderung`	boolean	Steuerfreie Sammelbeförderung zwischen Wohnung und erster Tätigkeitsstätte nach § 3 Nr. 32 EStG. Wird als Großbuchstabe F auf der Lohnsteuerbescheinigung ausgewiesen — fehlt er, ist die Bescheinigung falsch.
`grenzgaenger_fr`	string?	Französischer Grenzgänger; ergibt den Großbuchstaben FR1/FR2/FR3. ⚠️ Das amtliche Muster kennt kein nacktes `FR` — die Ziffer ist Pflicht. Werte: `123null`
`kostenstelle`	string?	Kostenstelle für den Buchungsstapel. ⚠️ Wird noch nicht in die Buchungen übernommen — der DATEV-Stapel bucht heute aggregiert, nicht je Person.
`fremdentgelt_kv_cent`	integer?	Laufendes Entgelt aus anderer Beschäftigung, Zweig KV. Nur bei Mehrfachbeschäftigung, und je Zweig getrennt — die anteilige Beitragsbemessungsgrenze bildet sich für jeden Versicherungszweig eigen. ⚠️ Die Angabe ist nur nötig, wenn die Person eigene RV-Beiträge leistet. Bei pauschalen RV-Beiträgen (Beitragsgruppe 5) nicht. ⚠️ Wird derzeit erfasst, aber noch nicht gerechnet: die Regelmodule (`minijob_mindestbemessung`, `uebergangsbereich_anwendung`) sind fertig, ihre Verdrahtung in den Lohnlauf steht aus.
`fremdentgelt_rv_cent`	integer?	dito RV
`fremdentgelt_av_cent`	integer?	dito AV
`fremdentgelt_pv_cent`	integer?	dito PV
`fremdentgelt_mehrere_ag`	boolean	Es gibt mehr als einen weiteren Arbeitgeber. Dann sind die oben eingetragenen Beträge bereits vom Anwender auf die Beitragsbemessungsgrenze gekappt — bei mehreren Arbeitgebern kann kein Programm das selbst leisten.
`grundgehalt_cent`	integer
`stundenlohn_cent`	integer
`bav_umwandlung_cent`	integer	Monatliche Entgeltumwandlung.
`vwl_betrag_cent`	integer

{
  "vorname": "Erika",
  "nachname": "Musterfrau",
  "geburtsdatum": "1990-05-14",
  "geschlecht": "w",
  "eintritt": "2026-03-15",
  "sv_nummer": "65140590M123",
  "steuer_id": "20013456978",
  "personengruppe": "101",
  "beitragsgruppe": "1111",
  "kasse_ik": "103121137",
  "vertrag": "gehalt",
  "taetigkeitsschluessel": "821012911",
  "steuerklasse": 1,
  "grundgehalt_cent": 315000
}

Antwort

201 Angelegt.

id integer

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Pflichtfeld fehlt (fehler.feld nennt es) oder der Tätigkeitsschlüssel ist ungültig. Pflicht sind: vorname, nachname, geburtsdatum, geschlecht, eintritt, personengruppe, beitragsgruppe, kasse_ik, vertrag.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "vorname": "Erika",
       "nachname": "Musterfrau",
       "geburtsdatum": "1990-05-14",
       "geschlecht": "w",
       "eintritt": "2026-03-15",
       "sv_nummer": "65140590M123",
       "steuer_id": "20013456978",
       "personengruppe": "101",
       "beitragsgruppe": "1111",
       "kasse_ik": "103121137",
       "vertrag": "gehalt",
       "taetigkeitsschluessel": "821012911",
       "steuerklasse": 1,
       "grundgehalt_cent": 315000
     }'

GET /v1/mandanten/{mandantId}/mitarbeiter/{maId} Verfügbar Mitarbeiter lesen oder auflisten mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`	integer · im Pfad	Ohne Angabe kommt die Liste aller Mitarbeiter, mit Angabe der einzelne inklusive aller Zeitscheiben.

Antwort

200 Einzelner Mitarbeiter mit zeitscheiben[] — ohne maId stattdessen die Liste unter mitarbeiter.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/mitarbeiter/{maId} Verfügbar Mitarbeiter ändern (erzeugt eine neue Zeitscheibe) mandant:stammdaten

Reine Stammdaten (Name, Anschrift, IBAN …) werden direkt geändert.

Sobald ein zeitscheiben-Feld im Body steht (Gehalt, Steuerklasse, Kasse, Beitragsgruppe …), ist gueltig_ab Pflicht: die bisherige Scheibe wird zum Vortag geschlossen und eine neue angelegt — als Kopie der letzten plus den Änderungen. Ein gueltig_ab, das nicht nach der letzten Scheibe liegt, wird abgewiesen.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`	integer · im Pfad	Ohne Angabe kommt die Liste aller Mitarbeiter, mit Angabe der einzelne inklusive aller Zeitscheiben.

Anfrage application/json · Pflicht

`gueltig_ab`	string	Beginn der Zeitscheibe. Beim Anlegen optional (dann `eintritt`), beim Ändern Pflicht, sobald ein Zeitscheiben-Feld dabei ist.
`extern_ref`	string
`vorname`	string
`nachname`	string
`geburtsdatum`	string
`geburtsname`	string
`geschlecht`	string	Werte: `mwdx`
`anschrift_strasse`	string
`anschrift_hausnummer`	string
`anschrift_plz`	string
`anschrift_ort`	string
`anschrift_land`	string
`staatsangehoerigkeit`	string
`sv_nummer`	string	Versicherungsnummer der Rentenversicherung.
`insolvenz_freistellung_ab`	string	Im Insolvenzfall ab diesem Tag freigestellt. Leer heißt weiterbeschäftigt — und dieser Unterschied entscheidet die Meldung: Freigestellte bekommen GD 71/70/72, Weiterbeschäftigte eine gewöhnliche Abmeldung GD 33. Wirkt nur zusammen mit `insolvenz_ereignis` am Mandanten.
`rentenbezieher`	boolean?	Bezieht eine Rente (euBP DSAN KENNZRBZ, Mussfeld J/N). null = nicht erfasst — dann entsteht keine euBP-Lieferung, sondern eine Hürde, die die Person nennt; aus der Beitragsgruppe ableitbar ist nur der Altersvollrentner mit RV „3" (Mig. 083).
`steuer_id`	string	Steuer-Identifikationsnummer (11-stellig).
`iban`	string
`bic`	string
`eintritt`	string
`austritt`	string
`personengruppe`	string	Amtlicher Personengruppenschlüssel, z. B. `101`, `106` (Werkstudent), `109` (geringfügig).
`taetigkeitsschluessel`	string	9-stellig; wird gegen den amtlichen Katalog geprüft.
`taetigkeitsbezeichnung`	string	Tätigkeit im Klartext für die Einzelaufstellung der Beitragsabrechnung-UV (Pflichtenheft Unfallversicherung 0115, S. 412 Nr. 3a). ⚠️ Ausdrücklich „keine Übernahme aus dem Tätigkeitsschlüssel": der neunstellige BA-Schlüssel ist eine Klassifikation, kein Berufsname. Leer heißt „nicht erfasst" — im Dokument steht dann ein Strich, keine erfundene Bezeichnung (Mig. 162).
`beitragsgruppe`	string	Beitragsgruppenschlüssel KV/RV/AV/PV, z. B. `1111` oder `0100` (Werkstudent).
`kasse_ik`	string	Institutionskennzeichen der Krankenkasse.
`steuerklasse`	integer
`faktor`	number	Faktorverfahren in Steuerklasse IV.
`kinderfreibetraege`	number
`kist_merkmal`	string	Kirchensteuer-Merkmal, z. B. `rk`, `ev`.
`pv_kinder`	integer	Zahl der Kinder unter 25 — steuert die Abschläge in der Pflegeversicherung.
`vertrag`	string	Entlohnungsform, nicht Vertragsdauer: `gehalt` (fester Monatsbetrag), `stundenlohn` (Satz mal geleistete Stunden) oder `sonstiges` (Akkord, Stücklohn, Provision). Steuert, welches Feld die Engine heranzieht — `grundgehalt_cent` oder `stundenlohn_cent`. ⚠️ Bei `sonstiges` gibt es weder ein Grundgehalt noch einen Stundensatz: der Betrag steht an der Bewegung und wird nicht gerechnet. Eine Bewegung ohne Betrag ergibt einen benannten Hinweis, keine geschätzte Zahlung. Die Entgeltfortzahlung im Krankheitsfall entsteht wie beim Stundenlohn aus dem Durchschnitt der Referenzmonate (§ 4 Abs. 1a EFZG). Die Entlohnungsform bestimmt zugleich das Feld ENTGART der Entgeltbescheinigung (1 = Stundenlohn · 2 = festes Monatsentgelt · 3 = Sonstiges). Sie entscheidet damit mit, ob der Datenbaustein Arbeitszeit (DBZA) entsteht. ⚠️ Die Spalte ist ein ENUM. Ein anderer Wert wurde bis 08.08.2026 als „Data truncated" mit HTTP 500 quittiert; heute antwortet die API mit 422 und nennt das Feld. Werte: `gehaltstundenlohnsonstiges`
`wochenstunden`	number
`arbeitszeitmodell`	string?	Wertguthaben-Arbeitszeitmodell § 7 Abs. 1a SGB IV (EEL, DBAL ARBZEITMOD).
`pv_elterneigenschaft`	boolean\|integer?	Elterneigenschaft nach § 55 Abs. 3 SGB XI. ⚠️ Dreiwertig: `true`/`1` = Elternteil (kein Zuschlag für Kinderlose, lebenslang und unabhängig vom Alter der Kinder), `false`/`0` = kinderlos, `null` = nicht bekannt. `null` ist ausdrücklich nicht „kinderlos": ohne Nachweis wird der Zuschlag weder unterstellt noch erlassen. Eine Angabe hier schlägt die DaBPV-Rückmeldung des BZSt.
`bei_lkk_versichert`	boolean\|integer?	Versicherung bei der landwirtschaftlichen Krankenkasse (LKK). Dreiwertig, `null` = nicht angegeben. Die Personengruppen 112 und 114 setzen sie voraus.
`hauptberuflich_landwirt`	boolean\|integer?	Hauptberuflich selbständige Erwerbstätigkeit als Landwirt. Dann ist die Krankenversicherungspflicht in dieser Beschäftigung ausgeschlossen (BGR-KV muss 0 sein); für den Einzug der RV-/AV-Beiträge ist die LKK zuständig.
`befristung_wochen`	integer?	Voraussichtliche Dauer einer befristeten Beschäftigung. PGS 114 gilt nur bis 26 Wochen.
`freiwillig_ohne_krankengeld`	boolean\|integer?	In der LKK freiwillig und ohne Anspruch auf Krankengeld versichert. Dann wird der Beitrag nicht nach Beitragssatz gerechnet, sondern nach der Beitragsklasse der LKK-Satzung — ohne `lkv_beitrag_kv_cent` wird gar nicht gerechnet.
`lkv_beitrag_kv_cent`	integer?	Nach Beitragsklasse der LKK-Satzung vorgegebener KV-Beitrag, in Cent.
`lkv_beitrag_pv_cent`	integer?	Vorgegebener PV-Beitrag (Zuschlag zum KV-Beitrag der LKK), in Cent.
`beitragsherabsetzung_ab`	string?	Tag der Antragstellung auf Beitragsherabsetzung bei Kurzarbeit (freiwillig gesetzlich Versicherte). ⚠️ Ein Datum, kein Kennzeichen: die Wirkung reicht ab Antragstellung bis zum Ende des Kalenderjahres — und nur in Monaten mit tatsächlichem Kug-Bezug. Ohne Antrag bleibt es beim Höchstbeitrag aus der Beitragsbemessungsgrenze.
`pauschsteuer_abgewaelzt`	boolean	Die Pauschsteuer wird auf den geringfügig Beschäftigten abgewälzt (§ 40a Abs. 5 in Verbindung mit § 40 Abs. 3 EStG, Migration 138). Schuldner der pauschalen Lohnsteuer bleibt der Arbeitgeber; die Abwälzung im Innenverhältnis ist zulässig, wenn sie vereinbart ist. ⚠️ Sie mindert das Arbeitsentgelt nicht: beitragspflichtig bleibt der volle Betrag, und die Pauschsteuer selbst wird weiter vom vollen Entgelt berechnet. Sie ist ein reiner Netto-Abzug und mindert zugleich die Arbeitgeberkosten. Zweiwertig mit Vorgabe `false` — wer nichts vereinbart hat, hat nicht abgewälzt.
`u1_pflicht`	boolean?	Übersteuerung der U1-Umlagepflicht für diese Person (Pflichtenheft S. 79, Migration 140). ⚠️ Dreiwertig: `null` heißt wie im Unternehmen — nicht „nein". Die Regel gilt für den Betrieb, nicht für die Person; es gibt aber Fälle, in denen der Anwender sie einzeln setzen muss. Die Übersteuerung wird verworfen, wenn im Unternehmen überhaupt keine Umlagepflicht besteht — dann trägt die Abrechnung eine Begründung, statt still zu rechnen.
`u2_pflicht`	boolean?	Übersteuerung der U2-Umlagepflicht für diese Person (Pflichtenheft S. 79, Migration 140). ⚠️ Dreiwertig wie `u1_pflicht`; `null` = wie im Unternehmen.
`saisonarbeitnehmer`	boolean\|integer?	Kennzeichen SAISONARBEITNEHMER im DBME der Anmeldung. Eine Änderung erzeugt Storno + Neuanmeldung.
`arbeitnehmer_status`	string?	Arbeitnehmereigenschaft für die Insolvenzgeldumlage (§ 358 Abs. 1 SGB III). Ein beherrschender Gesellschafter-Geschäftsführer ist keiner. ⚠️ `null` = nicht festgelegt; das Programm entscheidet es nicht, es macht den Fall sichtbar. Werte: `arbeitnehmerkein_arbeitnehmernull`
`statuskennzeichen`	string?	KENNZSTA im DSME (Angehöriger/Ehegatte/Gesellschafter-Geschäftsführer).
`einzugsstelle_ik`	string?	Einzugsstelle für Beschäftigte ohne gesetzliche Krankenkasse (privat versichert, versicherungsfrei).
`umlagekasse_ik`	string?	Vom Arbeitgeber gewählte Umlagekasse (U1/U2), wenn die Krankenkasse keine ist — etwa bei der SVLFG.
`ausgleichseinrichtung_ik`	string?	Ausgleichseinrichtung nach dem AAG, sofern abweichend.
`kug_leistungssatz`	integer?	Kug-Leistungssatz in Prozent, je Zeitraum individuell (eine Nachberechnung muss den damals geltenden treffen).
`kv_gesetzlich`	boolean\|integer?	Krankenversicherungsschutz bei kurzfristig Beschäftigten (DSME-Feld KENNZKV, seit 2022 Pflicht bei PGR 110). ⚠️ Dreiwertig — „nicht angegeben" ist etwas anderes als „privat".
`sollarbeitszeit`	number?	Tarifliche/vertragliche Sollarbeitszeit — Grundlage des Lohnnachweises beim UV-Beitragsmaßstab „Arbeitsstunden".
`sollarbeitszeit_einheit`	string?	Einheit der Sollarbeitszeit (Woche/Monat/Jahr).
`urlaubstage`	number
`schwerbehinderung`	boolean
`mehrfachbeschaeftigt`	boolean
`privat_kv`	boolean	Privat krankenversichert. Setzt in der Lohnsteuer das Merkmal PKV und schaltet bei geringfügig Beschäftigten die 13-%-Pauschale ab.
`pkv_beitrag_cent`	integer	Monatsbeitrag zur privaten Kranken-/Pflegeversicherung, Grundlage des Zuschusses.
`keine_rv`	boolean	rentenversicherungsfrei
`arbeitstage_muster`	string	Die Arbeitstage als aufsteigende Ziffernfolge der Wochentage, 1 = Montag bis 7 = Sonntag: `12345` = Montag bis Freitag, `135` = Montag, Mittwoch, Freitag. Jeder Tag höchstens einmal und in dieser Reihenfolge — so verlangt es die CHECK-Regel der Datenbank. Grundlage der Arbeits- und Ausfalltage.
`gefahrtarifstelle`	string	Aus dem Veranlagungsbescheid der Berufsgenossenschaft (§ 159 Abs. 1 SGB VII). Geht in den DSME (Feld GT_STELLE) und in die UV-Jahresmeldung; ohne sie ist kein Lohnnachweis möglich.
`freiwillig_gkv`	boolean	Freiwilliges Mitglied der gesetzlichen Krankenversicherung als Selbstzahler — der Beschäftigte zahlt seine Beiträge selbst und bekommt den Zuschuss nach § 257 Abs. 1 SGB V. ⚠️ Nicht dasselbe wie das Firmenzahlerverfahren (Beitragsgruppe KV `9`): dort führt der Arbeitgeber die vollen Beiträge ab und zahlt keinen Zuschuss. Beides zusammen ist ein Widerspruch; der Lohnlauf meldet ihn und zahlt nichts.
`freiwillig_kv_beitrag_cent`	integer?	Tatsächlicher monatlicher KV-Beitrag des Beschäftigten — der Zuschuss beträgt höchstens die Hälfte davon.
`freiwillig_pv_beitrag_cent`	integer?	Tatsächlicher monatlicher PV-Beitrag. Ohne diese Angabe entfällt der Zuschuss zur Pflegeversicherung.
`pkv_pv_beitrag_cent`	integer?	Der private Pflegeversicherungsbeitrag, getrennt vom Gesamtbeitrag `pkv_beitrag_cent`. Ohne ihn wird der Gesamtbeitrag als KV-Beitrag angesetzt und der PV-Zuschuss entfällt — das ist die vorsichtige, aber tendenziell zu niedrige Variante.
`zuschuss_art`	string	Art der Bezuschussung bei freiwilliger GKV: am tatsächlichen Entgelt (gekappt auf die Beitragsbemessungsgrenze) oder immer an der BBG — dann der Höchstzuschuss. ⚠️ Ein Stammdatum, keine Rechenfrage: in jedem Teilentgelt-Monat kommt je nach Wahl ein anderer Betrag heraus. Werte: `entgeltbbg`
`rentenart`	string?	Kennzeichen Rentenart nach Anlage 04a zum Pflichtenheft. `null` = kein Rentenbezug. ⚠️ Sobald eine Vollrente wegen Alters oder eine Vollversorgung hier steht, ist `verzicht_rv_freiheit` ausdrücklich zu beantworten; bei allen anderen Werten muss es in Grundstellung bleiben (Prüfkriterien 001/002). ⚠️ Bei `altersteilrente`, `teilversorgung`, `altersvollrente_nicht_eu` und `erwerbsminderung_voll` sind die Personengruppen 119 und 120 unzulässig — eine Altersvollrente eines Nicht-EU/EWR/SVA-Staates ist der deutschen nicht gleichgestellt (Prüfkriterium 012). ⚠️ Liegen mehrere Arten vor, gilt die in dieser Aufzählung weiter oben stehende. Werte: `altersvollrenteberufsstaendischbeamtenrechtlichaltersteilrenteteilversorgungaltersvollrente_nicht_euerwerbsminderung_vollnull`
`rentenbeginn`	string?	Rentenbeginn laut Rentenbescheid — geht in die Prüfkriterien 009 und 010 ein.
`anpassungsgeld_bergbau`	boolean	Anpassungsgeld für entlassene Arbeitnehmer des Bergbaus vor Rentenbeginn bezogen. ⚠️ Dann gilt die Regelaltersgrenze schon in dem Monat als erreicht, in dem das 65. Lebensjahr vollendet wurde — das verschiebt alle Stichtagsprüfungen.
`in_ausbildung`	boolean\|integer?	Steht die Person in Berufsausbildung? `null` = keine Angabe (keine Prüfung). Bei `true` hat die Ausbildungs-Personengruppe Vorrang (102 Auszubildende · 105 Praktikanten · 121/122 außerbetriebliche Ausbildung); eine andere Personengruppe führt zu einem Prüfketten-Befund. ⚠️ Der Tätigkeitsschlüssel trägt den Ausbildungs-Abschluss, nicht den laufenden Ausbildungsvertrag — daraus lässt sich das Merkmal nicht ableiten.
`knappschaftlich_rv`	boolean\|integer?	Beschäftigung in einem knappschaftlichen Betrieb: die Rentenversicherung folgt dann einer eigenen Beitragsbemessungsgrenze (§ 159 SGB VI — 2026: 10.400 € im Monat statt 8.450 €) und einem eigenen Beitragssatz (§ 158 SGB VI), der sich nicht hälftig teilt (§ 168 Abs. 3 SGB VI). ⚠️ Die Arbeitslosenversicherung bleibt bei der allgemeinen Grenze (§ 341 Abs. 4 SGB III). ⚠️ Solange `sv_saetze.rv_knappschaftlich` und `…_an` nicht gepflegt sind, wird für diese Person nicht gerechnet (Prüfketten-Befund). Ein Rückfall auf den allgemeinen Satz wäre für beide Seiten falsch.
`verzicht_eingang_am`	string?	Verzichtserklärung beim Arbeitgeber eingegangen am. Nur bei `verzicht_rv_freiheit: true` zulässig — ohne Erklärung muss das Feld leer bleiben (Prüfkriterien 003/004).
`verzicht_gueltig_ab`	string?	Verzicht auf die RV-Freiheit gültig ab. Muss nach dem Eingangsdatum liegen — der Verzicht wirkt nur für die Zukunft und ist für die Dauer der Beschäftigung bindend (Prüfkriterien 005–010).
`verzicht_rv_freiheit`	boolean?	Verzicht auf Rentenversicherungsfreiheit. Dreiwertig: `null` = nicht angegeben, und das ist etwas anderes als `false`. ⚠️ „Das Feld darf nicht mit einer fachlichen Ausprägung vorbelegt sein." Ob jemand auf seine Versicherungsfreiheit verzichtet hat, kann die Software nicht entscheiden.
`freiwilligendienst_anschluss`	boolean?	Freiwilligendienst (Personengruppen 119, 120, 123): Schließt sich der Dienst unmittelbar — innerhalb von vier Wochen — an eine versicherungspflichtige Beschäftigung an? Historisiert an der Zeitscheibe (Migration 144). Tut er das, werden die Beiträge zur Arbeitslosenversicherung nicht aus dem Taschengeld, sondern aus der monatlichen Bezugsgröße berechnet (§ 345 Nr. 4 SGB III). Bei 400 € Taschengeld und rund 3.955 € Bezugsgröße ist das etwa das Zehnfache; die übrigen Zweige bleiben unberührt. Dreiwertig: `null` = nicht angegeben, `true` = schließt unmittelbar an, `false` = nicht. ⚠️ `null` ist kein neutraler Zustand: die Prüfkette meldet dann einen Fehler, und der Monat lässt sich nicht festschreiben. Ein Vorgabewert `false` wäre die stille Fortschreibung eines zu niedrigen Beitrags — auffallen würde er erst bei der Betriebsprüfung.
`uebergangsbereich_anwenden`	boolean?	Kennzeichen „Anwendung Übergangsbereich" (Midijob), historisiert an der Zeitscheibe. Dreiwertig: `null` = automatisch nach dem Entgelt (Vorgabe), `true` = erzwingen, `false` = ausschließen. ⚠️ Der Übergangsbereich gilt von Gesetzes wegen, sobald das Entgelt im Korridor liegt — er ist kein Wahlrecht. Die beiden ausdrücklichen Werte sind für die Fälle, die der Automatismus nicht entscheiden kann (Mehrfachbeschäftigung, Bestandsfälle); jede Abweichung vom Korridor meldet der Lohnlauf.
`rv_befreiung_antrag_am`	string?	Tag, an dem der Antrag auf Befreiung von der Rentenversicherungspflicht (§ 6 Abs. 1b SGB VI) beim Arbeitgeber einging — nur für Minijobs (PGS 109). ⚠️ Ein Datum, kein Häkchen: die Befreiung wirkt ab dem Beginn des Monats, in dem der Antrag einging, wenn der Arbeitgeber ihn der Minijob-Zentrale binnen sechs Wochen meldet — sonst erst ab dem Folgemonat der Meldung. Beim Altfall (Beschäftigungsbeginn vor dem 01.01.2013, Entgelterhöhung danach über 400 €) wird daraus die Anzeige an die Minijob-Zentrale: `POST /mandanten/{id}/mitarbeiter/{id}/minijob-befreiung` erzeugt die Meldungen 33/13.
`rechtskreis`	string?	Rechtskreis des Beschäftigungsortes (`W` = alte Länder, `O` = Beitrittsgebiet). ⚠️ `null` heißt „folgt dem Mandanten", nicht „unbekannt" — gepflegt wird nur der Beschäftigte, der woanders arbeitet als der Betrieb sitzt. ⚠️ Sein Wechsel ist ein Meldetatbestand (Abmeldung 33 / Anmeldung 13) — aber nur für Zeiträume vor dem 01.01.2025. Ab dann ist KENNZRK Grundstellung (DBME166); ein Meldepaar für einen späteren Wechsel wäre ein Fehler. Werte: `WOnull`
`betriebsstaette_id`	integer?	Der Beschäftigungsbetrieb (Mig. 170, Kriterien ec586c06 · 1721b032 · e0b8a69d). Ein Arbeitgeber darf für mehrere Beschäftigungsbetriebe mehrere Betriebsnummern führen; genau eine ist die Hauptbetriebsnummer (HABBNR), unter der die Beitragsnachweise abgegeben werden. Die Meldung dieser Person trägt als Verursacher (BBNRVU) die Nummer ihres Betriebs. ⚠️ `null` heißt „Hauptbetrieb", nicht „unbekannt" — wie beim `rechtskreis` darüber: gepflegt wird nur, wer in einer ANDEREN Betriebsstätte arbeitet. Die Betriebsstätten selbst stehen unter `/mandanten/{mandantId}/betriebsstaetten`.
`uv_frei`	string?	Grund, warum in diesem Zeitraum kein uv-pflichtiges Arbeitsentgelt entsteht. `null` (Vorgabe) = uv-pflichtig — wer nichts einträgt, wird gemeldet. * `ausland` — keine UV-Pflicht wegen Auslandsbeschäftigung * `sgb7` — Versicherungsfreiheit in der Unfallversicherung nach SGB VII * `freistellung` — unwiderrufliche Freistellung von der Arbeitsleistung * `duales_studium` — Theoriephase eines praxisorientierten dualen Studiengangs Wirkung: das UV-Entgelt des Monats ist 0, die Person steht im zweiten Teil der Beitragsabrechnung-UV statt im Lohnnachweis. Liegt der Sachverhalt ganzjährig vor, entsteht auch keine UV-Jahresmeldung. Werte: `auslandsgb7freistellungduales_studiumnull`
`hauptarbeitgeber`	boolean	ELStAM: `true` = erstes Dienstverhältnis (die Person erhält ihre erste Steuerklasse), `false` = Nebenarbeitgeber (Steuerklasse 6). ⚠️ Bis zum 09.08.2026 gab es dieses Stammdatum nicht — die Betriebsautomatik meldete deshalb jeden Beschäftigten als Hauptarbeitgeber an. Wer es falsch stehen lässt, bekommt die erste Steuerklasse und behält zu wenig Lohnsteuer ein; der Fehler steckt in den Abzugsmerkmalen, nicht in der Rechnung.
`sammelbefoerderung`	boolean	Steuerfreie Sammelbeförderung zwischen Wohnung und erster Tätigkeitsstätte nach § 3 Nr. 32 EStG. Wird als Großbuchstabe F auf der Lohnsteuerbescheinigung ausgewiesen — fehlt er, ist die Bescheinigung falsch.
`grenzgaenger_fr`	string?	Französischer Grenzgänger; ergibt den Großbuchstaben FR1/FR2/FR3. ⚠️ Das amtliche Muster kennt kein nacktes `FR` — die Ziffer ist Pflicht. Werte: `123null`
`kostenstelle`	string?	Kostenstelle für den Buchungsstapel. ⚠️ Wird noch nicht in die Buchungen übernommen — der DATEV-Stapel bucht heute aggregiert, nicht je Person.
`fremdentgelt_kv_cent`	integer?	Laufendes Entgelt aus anderer Beschäftigung, Zweig KV. Nur bei Mehrfachbeschäftigung, und je Zweig getrennt — die anteilige Beitragsbemessungsgrenze bildet sich für jeden Versicherungszweig eigen. ⚠️ Die Angabe ist nur nötig, wenn die Person eigene RV-Beiträge leistet. Bei pauschalen RV-Beiträgen (Beitragsgruppe 5) nicht. ⚠️ Wird derzeit erfasst, aber noch nicht gerechnet: die Regelmodule (`minijob_mindestbemessung`, `uebergangsbereich_anwendung`) sind fertig, ihre Verdrahtung in den Lohnlauf steht aus.
`fremdentgelt_rv_cent`	integer?	dito RV
`fremdentgelt_av_cent`	integer?	dito AV
`fremdentgelt_pv_cent`	integer?	dito PV
`fremdentgelt_mehrere_ag`	boolean	Es gibt mehr als einen weiteren Arbeitgeber. Dann sind die oben eingetragenen Beträge bereits vom Anwender auf die Beitragsbemessungsgrenze gekappt — bei mehreren Arbeitgebern kann kein Programm das selbst leisten.
`grundgehalt_cent`	integer
`stundenlohn_cent`	integer
`bav_umwandlung_cent`	integer	Monatliche Entgeltumwandlung.
`vwl_betrag_cent`	integer

{
  "gueltig_ab": "2026-07-01",
  "grundgehalt_cent": 330000
}

Antwort

200 Geändert.

ok boolean

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 ZEITSCHEIBE_KONFLIKT — gueltig_ab liegt nicht nach der letzten Scheibe.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Zeitscheiben-Felder ohne gueltig_ab, oder Tätigkeitsschlüssel ungültig.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "gueltig_ab": "2026-07-01",
       "grundgehalt_cent": 330000
     }'

GET /v1/mandanten/{mandantId}/mitarbeiter/{maId}/vortraege/{jahr} Verfügbar Vortragswerte eines Jahres lesen mandant:stammdaten

Die Jahres-Anfangsbestände beim Programm- oder Arbeitgeberwechsel. Höchstens ein Satz je Art.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad
`jahr`*	integer · im Pfad

Antwort

200 Vorhandene Vorträge des Jahres.

`jahr`	integer
`vortraege`	array<object>

{
  "jahr": 2026,
  "vortraege": [
    {
      "art": "eigene_firma",
      "quelle": "Lexware lohn+gehalt, Januar–April",
      "brutto_cent": 1200000,
      "lohnsteuer_cent": 150000,
      "soli_cent": 0,
      "kirchensteuer_cent": 4000,
      "svbrutto_laufend_cent": 1200000,
      "einmalzahlung_cent": 0,
      "sv_tage": 120
    }
  ]
}

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/vortraege/<jahr>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/mitarbeiter/{maId}/vortraege/{jahr} Verfügbar Vortragswerte setzen oder ersetzen mandant:stammdaten

Legt den Satz an oder überschreibt ihn (je Person, Jahr und Art höchstens einer — zwei Sätze derselben Art wären zwei Wahrheiten).

⚠️ Die beiden Arten wirken verschieden, und sie zu vermischen bescheinigt fremden Arbeitslohn als eigenen:

- eigene_firma — Wechsel des Abrechnungssystems. Derselbe Arbeitgeber, dasselbe Dienstverhältnis. Die Werte gehören in die Lohnsteuerbescheinigung, weil sie das ganze Jahr dieses Verhältnisses abdeckt, und in die SV-Luft nach § 23a. - fremdfirma — unterjähriger Eintritt von einem anderen Arbeitgeber. Die Werte gehören nicht in unsere Bescheinigung; der frühere Arbeitgeber stellt seine eigene aus. Sie dienen der Lohnsteuer auf sonstige Bezüge und entscheiden den Großbuchstaben S.

⚠️ SV-Werte bei fremdfirma werden mit 422 abgewiesen: die SV-Luft ist arbeitgeberbezogen, ein früherer Arbeitgeber verbraucht sie nicht mit. Sie stillschweigend zu ignorieren hieße, den Anwender im Glauben zu lassen, es wirke.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad
`jahr`*	integer · im Pfad

Anfrage application/json · Pflicht

Für diesen Endpunkt ist noch kein Anfrage-Schema hinterlegt.

{
  "art": "fremdfirma",
  "quelle": "Voriger Arbeitgeber, Januar–März",
  "brutto_cent": 900000,
  "lohnsteuer_cent": 110000
}

Antwort

200 Gesetzt.

`mitarbeiter_id`	integer
`jahr`	integer
`art`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Art unbekannt, Betrag negativ, oder SV-Werte an einem Fremdfirmen-Vortrag.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/vortraege/<jahr>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "art": "fremdfirma",
       "quelle": "Voriger Arbeitgeber, Januar–März",
       "brutto_cent": 900000,
       "lohnsteuer_cent": 110000
     }'

GET /v1/stammdaten/fehlzeitenschluessel Verfügbar Fehlzeitenkatalog (Anlage 03 zum Pflichtenheft)

Die amtlichen Fehlzeitenschlüssel mit Art der Fehlzeit und ihrer Wirkung im DEÜV-Meldewesen (aus referenz/itsg_pflichtenheft/anlage03_fehlzeitenkatalog.json, erzeugt von scripts/itsg/anlage03_extrakt.js). POST/PATCH …/fehlzeiten weist einen Schlüssel ab, der hier nicht steht. Braucht keinen Scope.

Antwort

200 Katalog.

`quelle`	string
`schluessel`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/stammdaten/fehlzeitenschluessel" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/stammdaten/kassen Verfügbar Krankenkassen-Verzeichnis

Die zum heutigen Tag gültigen Kassen aus der amtlichen GKV-Stammdatendatei, mit Institutionskennzeichen, Zusatzbeitrag und U2-Satz. Braucht keinen Scope — ein gültiger API-Key genügt.

Antwort

200 Kassen.

kassen array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/stammdaten/kassen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/mitarbeiter/{maId}/zeitscheiben/{zsId} Verfügbar Zeitscheibe berichtigen mandant:stammdaten

Berichtigung, nicht Änderung. PATCH .../mitarbeiter/{maId} legt bei jeder Änderung eine NEUE Zeitscheibe an — richtig, wenn sich etwas *geändert* hat („ab 1. Juli Steuerklasse III"). Falsch, wenn sich jemand *vertippt* hat: dann bliebe die falsche Angabe für den Zeitraum davor stehen und würde weiter gemeldet und abgerechnet.

⚠️ Der Gültigkeitszeitraum lässt sich hier nicht verschieben (das beträfe die Nachbarscheibe) und die Berichtigung wird abgewiesen, sobald der Zeitraum einen festgeschriebenen, gemeldeten oder abgeschlossenen Lauf berührt — dann ist der Korrekturlauf der richtige Weg.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad
`zsId`*	integer · im Pfad

Anfrage application/json · Pflicht

`gueltig_ab`	string	Beginn der Zeitscheibe. Beim Anlegen optional (dann `eintritt`), beim Ändern Pflicht, sobald ein Zeitscheiben-Feld dabei ist.
`extern_ref`	string
`vorname`	string
`nachname`	string
`geburtsdatum`	string
`geburtsname`	string
`geschlecht`	string	Werte: `mwdx`
`anschrift_strasse`	string
`anschrift_hausnummer`	string
`anschrift_plz`	string
`anschrift_ort`	string
`anschrift_land`	string
`staatsangehoerigkeit`	string
`sv_nummer`	string	Versicherungsnummer der Rentenversicherung.
`insolvenz_freistellung_ab`	string	Im Insolvenzfall ab diesem Tag freigestellt. Leer heißt weiterbeschäftigt — und dieser Unterschied entscheidet die Meldung: Freigestellte bekommen GD 71/70/72, Weiterbeschäftigte eine gewöhnliche Abmeldung GD 33. Wirkt nur zusammen mit `insolvenz_ereignis` am Mandanten.
`rentenbezieher`	boolean?	Bezieht eine Rente (euBP DSAN KENNZRBZ, Mussfeld J/N). null = nicht erfasst — dann entsteht keine euBP-Lieferung, sondern eine Hürde, die die Person nennt; aus der Beitragsgruppe ableitbar ist nur der Altersvollrentner mit RV „3" (Mig. 083).
`steuer_id`	string	Steuer-Identifikationsnummer (11-stellig).
`iban`	string
`bic`	string
`eintritt`	string
`austritt`	string
`personengruppe`	string	Amtlicher Personengruppenschlüssel, z. B. `101`, `106` (Werkstudent), `109` (geringfügig).
`taetigkeitsschluessel`	string	9-stellig; wird gegen den amtlichen Katalog geprüft.
`taetigkeitsbezeichnung`	string	Tätigkeit im Klartext für die Einzelaufstellung der Beitragsabrechnung-UV (Pflichtenheft Unfallversicherung 0115, S. 412 Nr. 3a). ⚠️ Ausdrücklich „keine Übernahme aus dem Tätigkeitsschlüssel": der neunstellige BA-Schlüssel ist eine Klassifikation, kein Berufsname. Leer heißt „nicht erfasst" — im Dokument steht dann ein Strich, keine erfundene Bezeichnung (Mig. 162).
`beitragsgruppe`	string	Beitragsgruppenschlüssel KV/RV/AV/PV, z. B. `1111` oder `0100` (Werkstudent).
`kasse_ik`	string	Institutionskennzeichen der Krankenkasse.
`steuerklasse`	integer
`faktor`	number	Faktorverfahren in Steuerklasse IV.
`kinderfreibetraege`	number
`kist_merkmal`	string	Kirchensteuer-Merkmal, z. B. `rk`, `ev`.
`pv_kinder`	integer	Zahl der Kinder unter 25 — steuert die Abschläge in der Pflegeversicherung.
`vertrag`	string	Entlohnungsform, nicht Vertragsdauer: `gehalt` (fester Monatsbetrag), `stundenlohn` (Satz mal geleistete Stunden) oder `sonstiges` (Akkord, Stücklohn, Provision). Steuert, welches Feld die Engine heranzieht — `grundgehalt_cent` oder `stundenlohn_cent`. ⚠️ Bei `sonstiges` gibt es weder ein Grundgehalt noch einen Stundensatz: der Betrag steht an der Bewegung und wird nicht gerechnet. Eine Bewegung ohne Betrag ergibt einen benannten Hinweis, keine geschätzte Zahlung. Die Entgeltfortzahlung im Krankheitsfall entsteht wie beim Stundenlohn aus dem Durchschnitt der Referenzmonate (§ 4 Abs. 1a EFZG). Die Entlohnungsform bestimmt zugleich das Feld ENTGART der Entgeltbescheinigung (1 = Stundenlohn · 2 = festes Monatsentgelt · 3 = Sonstiges). Sie entscheidet damit mit, ob der Datenbaustein Arbeitszeit (DBZA) entsteht. ⚠️ Die Spalte ist ein ENUM. Ein anderer Wert wurde bis 08.08.2026 als „Data truncated" mit HTTP 500 quittiert; heute antwortet die API mit 422 und nennt das Feld. Werte: `gehaltstundenlohnsonstiges`
`wochenstunden`	number
`arbeitszeitmodell`	string?	Wertguthaben-Arbeitszeitmodell § 7 Abs. 1a SGB IV (EEL, DBAL ARBZEITMOD).
`pv_elterneigenschaft`	boolean\|integer?	Elterneigenschaft nach § 55 Abs. 3 SGB XI. ⚠️ Dreiwertig: `true`/`1` = Elternteil (kein Zuschlag für Kinderlose, lebenslang und unabhängig vom Alter der Kinder), `false`/`0` = kinderlos, `null` = nicht bekannt. `null` ist ausdrücklich nicht „kinderlos": ohne Nachweis wird der Zuschlag weder unterstellt noch erlassen. Eine Angabe hier schlägt die DaBPV-Rückmeldung des BZSt.
`bei_lkk_versichert`	boolean\|integer?	Versicherung bei der landwirtschaftlichen Krankenkasse (LKK). Dreiwertig, `null` = nicht angegeben. Die Personengruppen 112 und 114 setzen sie voraus.
`hauptberuflich_landwirt`	boolean\|integer?	Hauptberuflich selbständige Erwerbstätigkeit als Landwirt. Dann ist die Krankenversicherungspflicht in dieser Beschäftigung ausgeschlossen (BGR-KV muss 0 sein); für den Einzug der RV-/AV-Beiträge ist die LKK zuständig.
`befristung_wochen`	integer?	Voraussichtliche Dauer einer befristeten Beschäftigung. PGS 114 gilt nur bis 26 Wochen.
`freiwillig_ohne_krankengeld`	boolean\|integer?	In der LKK freiwillig und ohne Anspruch auf Krankengeld versichert. Dann wird der Beitrag nicht nach Beitragssatz gerechnet, sondern nach der Beitragsklasse der LKK-Satzung — ohne `lkv_beitrag_kv_cent` wird gar nicht gerechnet.
`lkv_beitrag_kv_cent`	integer?	Nach Beitragsklasse der LKK-Satzung vorgegebener KV-Beitrag, in Cent.
`lkv_beitrag_pv_cent`	integer?	Vorgegebener PV-Beitrag (Zuschlag zum KV-Beitrag der LKK), in Cent.
`beitragsherabsetzung_ab`	string?	Tag der Antragstellung auf Beitragsherabsetzung bei Kurzarbeit (freiwillig gesetzlich Versicherte). ⚠️ Ein Datum, kein Kennzeichen: die Wirkung reicht ab Antragstellung bis zum Ende des Kalenderjahres — und nur in Monaten mit tatsächlichem Kug-Bezug. Ohne Antrag bleibt es beim Höchstbeitrag aus der Beitragsbemessungsgrenze.
`pauschsteuer_abgewaelzt`	boolean	Die Pauschsteuer wird auf den geringfügig Beschäftigten abgewälzt (§ 40a Abs. 5 in Verbindung mit § 40 Abs. 3 EStG, Migration 138). Schuldner der pauschalen Lohnsteuer bleibt der Arbeitgeber; die Abwälzung im Innenverhältnis ist zulässig, wenn sie vereinbart ist. ⚠️ Sie mindert das Arbeitsentgelt nicht: beitragspflichtig bleibt der volle Betrag, und die Pauschsteuer selbst wird weiter vom vollen Entgelt berechnet. Sie ist ein reiner Netto-Abzug und mindert zugleich die Arbeitgeberkosten. Zweiwertig mit Vorgabe `false` — wer nichts vereinbart hat, hat nicht abgewälzt.
`u1_pflicht`	boolean?	Übersteuerung der U1-Umlagepflicht für diese Person (Pflichtenheft S. 79, Migration 140). ⚠️ Dreiwertig: `null` heißt wie im Unternehmen — nicht „nein". Die Regel gilt für den Betrieb, nicht für die Person; es gibt aber Fälle, in denen der Anwender sie einzeln setzen muss. Die Übersteuerung wird verworfen, wenn im Unternehmen überhaupt keine Umlagepflicht besteht — dann trägt die Abrechnung eine Begründung, statt still zu rechnen.
`u2_pflicht`	boolean?	Übersteuerung der U2-Umlagepflicht für diese Person (Pflichtenheft S. 79, Migration 140). ⚠️ Dreiwertig wie `u1_pflicht`; `null` = wie im Unternehmen.
`saisonarbeitnehmer`	boolean\|integer?	Kennzeichen SAISONARBEITNEHMER im DBME der Anmeldung. Eine Änderung erzeugt Storno + Neuanmeldung.
`arbeitnehmer_status`	string?	Arbeitnehmereigenschaft für die Insolvenzgeldumlage (§ 358 Abs. 1 SGB III). Ein beherrschender Gesellschafter-Geschäftsführer ist keiner. ⚠️ `null` = nicht festgelegt; das Programm entscheidet es nicht, es macht den Fall sichtbar. Werte: `arbeitnehmerkein_arbeitnehmernull`
`statuskennzeichen`	string?	KENNZSTA im DSME (Angehöriger/Ehegatte/Gesellschafter-Geschäftsführer).
`einzugsstelle_ik`	string?	Einzugsstelle für Beschäftigte ohne gesetzliche Krankenkasse (privat versichert, versicherungsfrei).
`umlagekasse_ik`	string?	Vom Arbeitgeber gewählte Umlagekasse (U1/U2), wenn die Krankenkasse keine ist — etwa bei der SVLFG.
`ausgleichseinrichtung_ik`	string?	Ausgleichseinrichtung nach dem AAG, sofern abweichend.
`kug_leistungssatz`	integer?	Kug-Leistungssatz in Prozent, je Zeitraum individuell (eine Nachberechnung muss den damals geltenden treffen).
`kv_gesetzlich`	boolean\|integer?	Krankenversicherungsschutz bei kurzfristig Beschäftigten (DSME-Feld KENNZKV, seit 2022 Pflicht bei PGR 110). ⚠️ Dreiwertig — „nicht angegeben" ist etwas anderes als „privat".
`sollarbeitszeit`	number?	Tarifliche/vertragliche Sollarbeitszeit — Grundlage des Lohnnachweises beim UV-Beitragsmaßstab „Arbeitsstunden".
`sollarbeitszeit_einheit`	string?	Einheit der Sollarbeitszeit (Woche/Monat/Jahr).
`urlaubstage`	number
`schwerbehinderung`	boolean
`mehrfachbeschaeftigt`	boolean
`privat_kv`	boolean	Privat krankenversichert. Setzt in der Lohnsteuer das Merkmal PKV und schaltet bei geringfügig Beschäftigten die 13-%-Pauschale ab.
`pkv_beitrag_cent`	integer	Monatsbeitrag zur privaten Kranken-/Pflegeversicherung, Grundlage des Zuschusses.
`keine_rv`	boolean	rentenversicherungsfrei
`arbeitstage_muster`	string	Die Arbeitstage als aufsteigende Ziffernfolge der Wochentage, 1 = Montag bis 7 = Sonntag: `12345` = Montag bis Freitag, `135` = Montag, Mittwoch, Freitag. Jeder Tag höchstens einmal und in dieser Reihenfolge — so verlangt es die CHECK-Regel der Datenbank. Grundlage der Arbeits- und Ausfalltage.
`gefahrtarifstelle`	string	Aus dem Veranlagungsbescheid der Berufsgenossenschaft (§ 159 Abs. 1 SGB VII). Geht in den DSME (Feld GT_STELLE) und in die UV-Jahresmeldung; ohne sie ist kein Lohnnachweis möglich.
`freiwillig_gkv`	boolean	Freiwilliges Mitglied der gesetzlichen Krankenversicherung als Selbstzahler — der Beschäftigte zahlt seine Beiträge selbst und bekommt den Zuschuss nach § 257 Abs. 1 SGB V. ⚠️ Nicht dasselbe wie das Firmenzahlerverfahren (Beitragsgruppe KV `9`): dort führt der Arbeitgeber die vollen Beiträge ab und zahlt keinen Zuschuss. Beides zusammen ist ein Widerspruch; der Lohnlauf meldet ihn und zahlt nichts.
`freiwillig_kv_beitrag_cent`	integer?	Tatsächlicher monatlicher KV-Beitrag des Beschäftigten — der Zuschuss beträgt höchstens die Hälfte davon.
`freiwillig_pv_beitrag_cent`	integer?	Tatsächlicher monatlicher PV-Beitrag. Ohne diese Angabe entfällt der Zuschuss zur Pflegeversicherung.
`pkv_pv_beitrag_cent`	integer?	Der private Pflegeversicherungsbeitrag, getrennt vom Gesamtbeitrag `pkv_beitrag_cent`. Ohne ihn wird der Gesamtbeitrag als KV-Beitrag angesetzt und der PV-Zuschuss entfällt — das ist die vorsichtige, aber tendenziell zu niedrige Variante.
`zuschuss_art`	string	Art der Bezuschussung bei freiwilliger GKV: am tatsächlichen Entgelt (gekappt auf die Beitragsbemessungsgrenze) oder immer an der BBG — dann der Höchstzuschuss. ⚠️ Ein Stammdatum, keine Rechenfrage: in jedem Teilentgelt-Monat kommt je nach Wahl ein anderer Betrag heraus. Werte: `entgeltbbg`
`rentenart`	string?	Kennzeichen Rentenart nach Anlage 04a zum Pflichtenheft. `null` = kein Rentenbezug. ⚠️ Sobald eine Vollrente wegen Alters oder eine Vollversorgung hier steht, ist `verzicht_rv_freiheit` ausdrücklich zu beantworten; bei allen anderen Werten muss es in Grundstellung bleiben (Prüfkriterien 001/002). ⚠️ Bei `altersteilrente`, `teilversorgung`, `altersvollrente_nicht_eu` und `erwerbsminderung_voll` sind die Personengruppen 119 und 120 unzulässig — eine Altersvollrente eines Nicht-EU/EWR/SVA-Staates ist der deutschen nicht gleichgestellt (Prüfkriterium 012). ⚠️ Liegen mehrere Arten vor, gilt die in dieser Aufzählung weiter oben stehende. Werte: `altersvollrenteberufsstaendischbeamtenrechtlichaltersteilrenteteilversorgungaltersvollrente_nicht_euerwerbsminderung_vollnull`
`rentenbeginn`	string?	Rentenbeginn laut Rentenbescheid — geht in die Prüfkriterien 009 und 010 ein.
`anpassungsgeld_bergbau`	boolean	Anpassungsgeld für entlassene Arbeitnehmer des Bergbaus vor Rentenbeginn bezogen. ⚠️ Dann gilt die Regelaltersgrenze schon in dem Monat als erreicht, in dem das 65. Lebensjahr vollendet wurde — das verschiebt alle Stichtagsprüfungen.
`in_ausbildung`	boolean\|integer?	Steht die Person in Berufsausbildung? `null` = keine Angabe (keine Prüfung). Bei `true` hat die Ausbildungs-Personengruppe Vorrang (102 Auszubildende · 105 Praktikanten · 121/122 außerbetriebliche Ausbildung); eine andere Personengruppe führt zu einem Prüfketten-Befund. ⚠️ Der Tätigkeitsschlüssel trägt den Ausbildungs-Abschluss, nicht den laufenden Ausbildungsvertrag — daraus lässt sich das Merkmal nicht ableiten.
`knappschaftlich_rv`	boolean\|integer?	Beschäftigung in einem knappschaftlichen Betrieb: die Rentenversicherung folgt dann einer eigenen Beitragsbemessungsgrenze (§ 159 SGB VI — 2026: 10.400 € im Monat statt 8.450 €) und einem eigenen Beitragssatz (§ 158 SGB VI), der sich nicht hälftig teilt (§ 168 Abs. 3 SGB VI). ⚠️ Die Arbeitslosenversicherung bleibt bei der allgemeinen Grenze (§ 341 Abs. 4 SGB III). ⚠️ Solange `sv_saetze.rv_knappschaftlich` und `…_an` nicht gepflegt sind, wird für diese Person nicht gerechnet (Prüfketten-Befund). Ein Rückfall auf den allgemeinen Satz wäre für beide Seiten falsch.
`verzicht_eingang_am`	string?	Verzichtserklärung beim Arbeitgeber eingegangen am. Nur bei `verzicht_rv_freiheit: true` zulässig — ohne Erklärung muss das Feld leer bleiben (Prüfkriterien 003/004).
`verzicht_gueltig_ab`	string?	Verzicht auf die RV-Freiheit gültig ab. Muss nach dem Eingangsdatum liegen — der Verzicht wirkt nur für die Zukunft und ist für die Dauer der Beschäftigung bindend (Prüfkriterien 005–010).
`verzicht_rv_freiheit`	boolean?	Verzicht auf Rentenversicherungsfreiheit. Dreiwertig: `null` = nicht angegeben, und das ist etwas anderes als `false`. ⚠️ „Das Feld darf nicht mit einer fachlichen Ausprägung vorbelegt sein." Ob jemand auf seine Versicherungsfreiheit verzichtet hat, kann die Software nicht entscheiden.
`freiwilligendienst_anschluss`	boolean?	Freiwilligendienst (Personengruppen 119, 120, 123): Schließt sich der Dienst unmittelbar — innerhalb von vier Wochen — an eine versicherungspflichtige Beschäftigung an? Historisiert an der Zeitscheibe (Migration 144). Tut er das, werden die Beiträge zur Arbeitslosenversicherung nicht aus dem Taschengeld, sondern aus der monatlichen Bezugsgröße berechnet (§ 345 Nr. 4 SGB III). Bei 400 € Taschengeld und rund 3.955 € Bezugsgröße ist das etwa das Zehnfache; die übrigen Zweige bleiben unberührt. Dreiwertig: `null` = nicht angegeben, `true` = schließt unmittelbar an, `false` = nicht. ⚠️ `null` ist kein neutraler Zustand: die Prüfkette meldet dann einen Fehler, und der Monat lässt sich nicht festschreiben. Ein Vorgabewert `false` wäre die stille Fortschreibung eines zu niedrigen Beitrags — auffallen würde er erst bei der Betriebsprüfung.
`uebergangsbereich_anwenden`	boolean?	Kennzeichen „Anwendung Übergangsbereich" (Midijob), historisiert an der Zeitscheibe. Dreiwertig: `null` = automatisch nach dem Entgelt (Vorgabe), `true` = erzwingen, `false` = ausschließen. ⚠️ Der Übergangsbereich gilt von Gesetzes wegen, sobald das Entgelt im Korridor liegt — er ist kein Wahlrecht. Die beiden ausdrücklichen Werte sind für die Fälle, die der Automatismus nicht entscheiden kann (Mehrfachbeschäftigung, Bestandsfälle); jede Abweichung vom Korridor meldet der Lohnlauf.
`rv_befreiung_antrag_am`	string?	Tag, an dem der Antrag auf Befreiung von der Rentenversicherungspflicht (§ 6 Abs. 1b SGB VI) beim Arbeitgeber einging — nur für Minijobs (PGS 109). ⚠️ Ein Datum, kein Häkchen: die Befreiung wirkt ab dem Beginn des Monats, in dem der Antrag einging, wenn der Arbeitgeber ihn der Minijob-Zentrale binnen sechs Wochen meldet — sonst erst ab dem Folgemonat der Meldung. Beim Altfall (Beschäftigungsbeginn vor dem 01.01.2013, Entgelterhöhung danach über 400 €) wird daraus die Anzeige an die Minijob-Zentrale: `POST /mandanten/{id}/mitarbeiter/{id}/minijob-befreiung` erzeugt die Meldungen 33/13.
`rechtskreis`	string?	Rechtskreis des Beschäftigungsortes (`W` = alte Länder, `O` = Beitrittsgebiet). ⚠️ `null` heißt „folgt dem Mandanten", nicht „unbekannt" — gepflegt wird nur der Beschäftigte, der woanders arbeitet als der Betrieb sitzt. ⚠️ Sein Wechsel ist ein Meldetatbestand (Abmeldung 33 / Anmeldung 13) — aber nur für Zeiträume vor dem 01.01.2025. Ab dann ist KENNZRK Grundstellung (DBME166); ein Meldepaar für einen späteren Wechsel wäre ein Fehler. Werte: `WOnull`
`betriebsstaette_id`	integer?	Der Beschäftigungsbetrieb (Mig. 170, Kriterien ec586c06 · 1721b032 · e0b8a69d). Ein Arbeitgeber darf für mehrere Beschäftigungsbetriebe mehrere Betriebsnummern führen; genau eine ist die Hauptbetriebsnummer (HABBNR), unter der die Beitragsnachweise abgegeben werden. Die Meldung dieser Person trägt als Verursacher (BBNRVU) die Nummer ihres Betriebs. ⚠️ `null` heißt „Hauptbetrieb", nicht „unbekannt" — wie beim `rechtskreis` darüber: gepflegt wird nur, wer in einer ANDEREN Betriebsstätte arbeitet. Die Betriebsstätten selbst stehen unter `/mandanten/{mandantId}/betriebsstaetten`.
`uv_frei`	string?	Grund, warum in diesem Zeitraum kein uv-pflichtiges Arbeitsentgelt entsteht. `null` (Vorgabe) = uv-pflichtig — wer nichts einträgt, wird gemeldet. * `ausland` — keine UV-Pflicht wegen Auslandsbeschäftigung * `sgb7` — Versicherungsfreiheit in der Unfallversicherung nach SGB VII * `freistellung` — unwiderrufliche Freistellung von der Arbeitsleistung * `duales_studium` — Theoriephase eines praxisorientierten dualen Studiengangs Wirkung: das UV-Entgelt des Monats ist 0, die Person steht im zweiten Teil der Beitragsabrechnung-UV statt im Lohnnachweis. Liegt der Sachverhalt ganzjährig vor, entsteht auch keine UV-Jahresmeldung. Werte: `auslandsgb7freistellungduales_studiumnull`
`hauptarbeitgeber`	boolean	ELStAM: `true` = erstes Dienstverhältnis (die Person erhält ihre erste Steuerklasse), `false` = Nebenarbeitgeber (Steuerklasse 6). ⚠️ Bis zum 09.08.2026 gab es dieses Stammdatum nicht — die Betriebsautomatik meldete deshalb jeden Beschäftigten als Hauptarbeitgeber an. Wer es falsch stehen lässt, bekommt die erste Steuerklasse und behält zu wenig Lohnsteuer ein; der Fehler steckt in den Abzugsmerkmalen, nicht in der Rechnung.
`sammelbefoerderung`	boolean	Steuerfreie Sammelbeförderung zwischen Wohnung und erster Tätigkeitsstätte nach § 3 Nr. 32 EStG. Wird als Großbuchstabe F auf der Lohnsteuerbescheinigung ausgewiesen — fehlt er, ist die Bescheinigung falsch.
`grenzgaenger_fr`	string?	Französischer Grenzgänger; ergibt den Großbuchstaben FR1/FR2/FR3. ⚠️ Das amtliche Muster kennt kein nacktes `FR` — die Ziffer ist Pflicht. Werte: `123null`
`kostenstelle`	string?	Kostenstelle für den Buchungsstapel. ⚠️ Wird noch nicht in die Buchungen übernommen — der DATEV-Stapel bucht heute aggregiert, nicht je Person.
`fremdentgelt_kv_cent`	integer?	Laufendes Entgelt aus anderer Beschäftigung, Zweig KV. Nur bei Mehrfachbeschäftigung, und je Zweig getrennt — die anteilige Beitragsbemessungsgrenze bildet sich für jeden Versicherungszweig eigen. ⚠️ Die Angabe ist nur nötig, wenn die Person eigene RV-Beiträge leistet. Bei pauschalen RV-Beiträgen (Beitragsgruppe 5) nicht. ⚠️ Wird derzeit erfasst, aber noch nicht gerechnet: die Regelmodule (`minijob_mindestbemessung`, `uebergangsbereich_anwendung`) sind fertig, ihre Verdrahtung in den Lohnlauf steht aus.
`fremdentgelt_rv_cent`	integer?	dito RV
`fremdentgelt_av_cent`	integer?	dito AV
`fremdentgelt_pv_cent`	integer?	dito PV
`fremdentgelt_mehrere_ag`	boolean	Es gibt mehr als einen weiteren Arbeitgeber. Dann sind die oben eingetragenen Beträge bereits vom Anwender auf die Beitragsbemessungsgrenze gekappt — bei mehreren Arbeitgebern kann kein Programm das selbst leisten.
`grundgehalt_cent`	integer
`stundenlohn_cent`	integer
`bav_umwandlung_cent`	integer	Monatliche Entgeltumwandlung.
`vwl_betrag_cent`	integer

Antwort

200 Berichtigt.

`ok`	boolean
`id`	integer
`berichtigt`	array<string>	die tatsächlich geänderten Spalten

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 LAUF_FESTGESCHRIEBEN — für den Zeitraum ist bereits abgerechnet. Die betroffenen Monate stehen im Meldungstext.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Unzulässiger Wert oder Versuch, den Gültigkeitszeitraum zu verschieben.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/zeitscheiben/<zsId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/fehlzeiten Verfügbar Fehlzeiten des Mandanten mandant:stammdaten

Alle Fehlzeiten, mit monat gefiltert auf die, die den Monat berühren.

⚠️ Nicht „die im Monat beginnen": eine Krankheit vom 25.03. bis 14.04. gehört in beide Monate, weil sie in beiden Ausfalltage erzeugt. Wer nur nach dem Beginn filtert, übersieht in der Monatsansicht genau die langen Fälle.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`	string · Query	Nur Fehlzeiten, die diesen Monat berühren.

Antwort

200 Liste.

`monat`	string?
`fehlzeiten`	array<objekt>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 monat ist kein YYYY-MM.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/fehlzeiten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/mitarbeiter/{maId}/fehlzeiten Verfügbar Fehlzeiten eines Mitarbeiters mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad

Antwort

200 Liste

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/fehlzeiten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{maId}/fehlzeiten Verfügbar Fehlzeit erfassen mandant:stammdaten

An den Fehlzeiten hängen vier Fachblöcke: die Abmeldung mit Grund 34 nach einem Zeitmonat (spezifikation = ohne_entgeltfortzahlung_krankengeld), die Aussteuerung (nach_ablauf_krankengeld), die AAG-Erstattung (typ = mutterschutz bzw. beschaeftigungsverbot) und die Kurzarbeit.

typ = mutterschutz und beschaeftigungsverbot führen nie zu einer Abmeldung — wer nur auf die spezifikation schaut, meldet Beschäftigte mitten im Mutterschutz ab.

typ = kind_krank (EEL-Block E3, 23.08.2026): Freistellung wegen Erkrankung oder stationärer Mitaufnahme eines Kindes (§ 45 SGB V) → Entgeltbescheinigung KV bei Kinderkrankengeld (DSLW Grund 02, DBFR), sobald der Freistellungsmonat festgeschrieben ist. Pflicht: kind_id (Kinder: …/mitarbeiter/{maId}/kinder), vae_ersttag (am ersten Tag noch voll gearbeitet/bezahlt?), freistellung_anspruch (vollstaendig | teilweise | ausgeschlossen_tarifvertrag | ausgeschlossen_betriebsvereinbarung | ausgeschlossen_arbeitsvertrag) — bei teilweise zusätzlich bezahlt_von/bezahlt_bis; optional stationaer, bezahlt_tage_begrenzt (BEGRZFREIST). Nur der unbezahlte Teil kürzt das Entgelt; FREISTBRUTTO/-NETTO entstehen aus Brutto 1 − Brutto 2 mit dem Fiktivnetto der Abrechnung. Fehlt eine Angabe, entsteht keine Bescheinigung (Hürde), kein Ersatzwert.

typ = krankheit mit au = 1 löst — wenn die Regel es zulässt (GKV, frühere attestierte AU in der 6-Monats-Kette, zusammen ≥ 30 Tage; offenes Ende = heute + 7) — die Vorerkrankungsanfrage (EEL Grund 41) als Entwurf aus (vorerkrankungsanfrage in der Antwort; Pflichtenheft S. 226/227).

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad

Antwort

201 Angelegt (id); bei attestierter Krankheit ggf. vorerkrankungsanfrage (Entwurf 41 oder Hürden).

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/fehlzeiten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/fehlzeiten/{id} Verfügbar Fehlzeit ändern mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Geändert

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/fehlzeiten/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

DELETE /v1/mandanten/{mandantId}/fehlzeiten/{id} Verfügbar Fehlzeit löschen mandant:stammdaten

Zulässig — eine irrtümlich erfasste Fehlzeit ist kein Geschäftsvorfall. Der Vorgang wird aber protokolliert, sonst fällt in der Betriebsprüfung eine Lücke auf, die niemand mehr erklären kann.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

204 Gelöscht

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X DELETE "https://api.lohnfluss.de/v1/mandanten/<mandantId>/fehlzeiten/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/betriebsstaetten Verfügbar Beschäftigungsbetriebe des Mandanten (BBNRVU) mit Hauptbetriebsnummer mandant:stammdaten

Pflichtenheft S. 331 (ec586c06 · 1721b032 · e0b8a69d): ein Arbeitgeber darf für mehrere Beschäftigungsbetriebe mehrere Betriebsnummern führen; genau eine ist die Hauptbetriebsnummer (HABBNR), unter der die Beitragsnachweise abgegeben werden. In der Meldung steht als Verursacher (BBNRVU) die Nummer des Betriebs, in dem der Beschäftigte tatsächlich arbeitet — zugeordnet über betriebsstaette_id an der Zeitscheibe.

Ohne erfasste Betriebsstätten gilt die Betriebsnummer des Mandanten (quelle: mandant); das ist der Regelfall. befund ist gefüllt, wenn keine oder mehrere Nummern als Haupt gekennzeichnet sind — dann lässt sich kein Beitragsnachweis abgeben.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`	string · Query	Betriebsstätten können eröffnet und geschlossen werden — Stichmonat

Antwort

200 betriebsstaetten[], hauptbetriebsnummer, quelle, befund

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsstaetten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/betriebsstaetten Verfügbar Beschäftigungsbetrieb anlegen mandant:stammdaten

haupt: true nimmt der bisherigen Hauptbetriebsnummer ihre Kennzeichnung — genau eine je Mandant (1721b032). Die Betriebsnummer wird auf ihre Prüfziffer geprüft.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`betriebsnummer`*	string
`bezeichnung`*	string
`haupt`	boolean
`gueltig_ab`	string
`gueltig_bis`	string
`rechtskreis`	string	Werte: `WO`
`anschrift_plz`	string
`anschrift_ort`	string
`anschrift_strasse`	string
`anschrift_hausnummer`	string

Antwort

201 { id }

409 die Betriebsnummer ist für den Mandanten bereits erfasst

422 Prüfziffer oder Pflichtfeld

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsstaetten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/betriebsstaetten/{id} Verfügbar Beschäftigungsbetrieb ändern mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

Für diesen Endpunkt ist noch kein Anfrage-Schema hinterlegt.

Antwort

200 { id, geaendert }

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsstaetten/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

DELETE /v1/mandanten/{mandantId}/betriebsstaetten/{id} Verfügbar Beschäftigungsbetrieb löschen mandant:stammdaten

Nur, solange keine Zeitscheibe darauf zeigt. Wer einen Betrieb schließt, setzt gueltig_bis — sonst verlieren bereits gemeldete Zeiträume ihre Betriebsnummer.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 { geloescht }

409 Zeitscheiben zeigen auf diese Betriebsstätte

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X DELETE "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsstaetten/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/mitarbeiter/{maId}/kinder Verfügbar Kinder eines Mitarbeiters (kindbezogene Kinderkrankengeld-Freistellungen) mandant:stammdaten

Pflichtenheft S. 219: Freistellungen wegen Erkrankung eines Kindes sind je Kind zu führen (BEZFREIST-JAHR zählt die bezahlten Tage desselben Kindes im Kalenderjahr). gesetzlich_versichert leer = unbekannt → die Bescheinigung Grund 02 entsteht nicht, bis es beantwortet ist (Kinderkrankengeld setzt GKV-Versicherung des Kindes voraus).

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad

Antwort

200 kinder[] (id, vorname, geburtsdatum, verstorben_am, gesetzlich_versichert, bemerkung)

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/kinder" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{maId}/kinder Verfügbar Kind anlegen mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad

Anfrage application/json · Pflicht

`vorname`*	string
`geburtsdatum`	string
`verstorben_am`	string	Sterbetag des Kindes. Die Berücksichtigung beim PV-Abschlag endet mit Ablauf dieses Monats — dieselbe Grenze wie beim 25. Geburtstag (§ 188 BGB). Ohne Angabe zählt das Kind weiter.
`gesetzlich_versichert`	integer	Werte: `01`
`bemerkung`	string

Antwort

201 Angelegt (id)

422 Validierung

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/kinder" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/kinder/{id} Verfügbar Kind ändern mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Geändert

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/kinder/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

DELETE /v1/mandanten/{mandantId}/kinder/{id} Verfügbar Kind löschen (nur ohne Fehlzeiten-Bezug) mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

204 Gelöscht

409 An Fehlzeiten „Kind krank" hinterlegt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X DELETE "https://api.lohnfluss.de/v1/mandanten/<mandantId>/kinder/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/mitarbeiter/{maId}/pfaendungen Verfügbar Pfändungen eines Mitarbeiters mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad

Antwort

200 Liste

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/pfaendungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{maId}/pfaendungen Verfügbar Pfändung erfassen mandant:stammdaten

Der rang entscheidet die Reihenfolge der Befriedigung (§ 804 Abs. 3 ZPO). Zwei aktive Pfändungen mit demselben Rang werden angenommen, aber mit einem Hinweis quittiert — die Reihenfolge ist dann nicht eindeutig, und das ist eine Rechtsfrage, keine Rechenfrage.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`maId`*	integer · im Pfad

Antwort

201 Angelegt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<maId>/pfaendungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/pfaendungen/{id} Verfügbar Pfändung ändern mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Geändert

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/pfaendungen/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/u1-wahl Verfügbar U1-Erstattungssatz je Krankenkasse mandant:stammdaten

Der Erstattungssatz ist eine Wahl gegenüber jeder Kasse einzeln — jede regelt ihre Sätze in der eigenen Satzung, und ein Satz, den eine Kasse nicht anbietet, ist dort nicht wählbar. Geliefert werden nur die Kassen, die im Bestand tatsächlich vorkommen, je mit den angebotenen Sätzen, der Wahl und dem daraus folgenden Umlagesatz.

erstattungssatz_u1 am Mandanten bleibt als Vorgabewert bestehen und greift, solange für eine Kasse nichts gewählt ist. Passt auch er nicht, weist hinweis aus, mit welchem Satz stattdessen gerechnet wird.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Kassen mit angebotenen Sätzen und Wahl

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/u1-wahl" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/u1-wahl/{kasseIk} Verfügbar Erstattungssatz für eine Kasse wählen mandant:stammdaten

erstattungssatz: null nimmt die Wahl zurück — dann greift wieder der Vorgabewert des Mandanten. Die Wahl ist eine Zeitscheibe: gueltig_ab (Vorgabe: 1. Januar des laufenden Jahres) legt fest, ab wann sie gilt, damit eine Nachberechnung den damals gewählten Satz trifft.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`kasseIk`*	string · im Pfad

Antwort

200 Gespeichert

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/u1-wahl/<kasseIk>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/uv-traeger Verfügbar UV-Träger des Mandanten (mehrere möglich, mit Gültigkeitszeiträumen) mandant:stammdaten

Ein Unternehmen kann bei mehreren Unfallversicherungsträgern Mitglied sein und bei einem Träger mehrere Unternehmensnummern führen — parallel wie zeitlich anschließend (Pflichtenheft Unfallversicherung 0115, S. 380). Die PIN wird nie ausgeliefert.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`jahr`	integer · Query	nur die in diesem Meldejahr gültigen

Antwort

200 Liste

uv_traeger array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv-traeger" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/uv-traeger Verfügbar UV-Träger anlegen oder ändern mandant:stammdaten

Die Unternehmensnummer wird über die Prüfziffer an Stelle 12 (Faktoren 4,9,4,9,… modulo 10) und den Suffix (Stellen 13–15, nicht „000") geprüft; die PIN muss fünfstellig numerisch sein. Überschneidende Zeiträume derselben Nummer beim selben Träger werden abgewiesen.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`id`	integer	zum Ändern eines bestehenden Satzes
`bbnr_uv`*	string	BBNRUV
`unternehmensnummer`*	string	UNR.S
`pin`	string	5-stellig numerisch; wird nie zurückgegeben
`gueltig_ab`*	string
`gueltig_bis`	string
`notiz`	string

Antwort

200 gespeichert

422 Validierung fehlgeschlagen

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv-traeger" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/mitarbeiter/{mitarbeiterId}/gefahrtarifstellen Verfügbar Gefahrtarifstellen einer Person (mit Anteilen) mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`mitarbeiterId`*	integer · im Pfad

Antwort

200 Liste

gefahrtarifstellen array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<mitarbeiterId>/gefahrtarifstellen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/mitarbeiter/{mitarbeiterId}/gefahrtarifstellen Verfügbar Gefahrtarifstellen einer Person setzen (ganze Aufteilung) mandant:stammdaten

Trifft für eine Person mehr als eine Gefahrtarifstelle zu, ist das Entgelt aufzuteilen — auch träger-übergreifend (Pflichtenheft S. 385). Die Anteile müssen zusammen 100 % ergeben; bei mehreren Stellen wird der Anteil nicht geraten. Die Aufteilung wird immer als Ganzes gesetzt, damit nie ein Zwischenstand mit unter 100 % gelesen werden kann.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`mitarbeiterId`*	integer · im Pfad

Anfrage application/json · Pflicht

`gueltig_ab`*	string
`gueltig_bis`	string
`stellen`*	array<object>

Antwort

200 gespeichert

404 Mitarbeiter nicht gefunden

422 Validierung fehlgeschlagen

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<mitarbeiterId>/gefahrtarifstellen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/uv-stammdaten Verfügbar UV-Stammdaten je Meldejahr mandant:stammdaten

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Liste

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv-stammdaten" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/uv-stammdaten/{meldejahr} Verfügbar Gefahrtarifstellen pflegen mandant:stammdaten

Neukunden-Blocker: ohne Gefahrtarifstelle kein Lohnnachweis. Sie steht nicht im Zugangsdaten-Anschreiben der Berufsgenossenschaft, sondern im Veranlagungsbescheid nach § 159 Abs. 1 SGB VII — sie wird deshalb gepflegt, nicht geraten.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldejahr`*	integer · im Pfad

Antwort

200 Gespeichert

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv-stammdaten/<meldejahr>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/betriebsdaten/aktueller-stand Verfügbar DSBD „Aktueller Stand Betriebsdaten" (Grund 05) anstoßen mandant:stammdaten

Pflichtenheft S. 142: Grund 05 darf nur aktiv vom Anwender im Einzelfall ausgelöst werden — die Betriebsautomatik erzeugt ihn nie. Der Satz trägt alle aktuellen Betriebsdaten ohne Änderungs-Kennzeichen. Das Ereignisdatum ist nicht vorbelegt (S. 145) und muss mitgegeben werden.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

datum_ereignis* string Tag

Antwort

201 DSBD-Entwurf angelegt (gesendet wird nie automatisch)

`id`	integer
`grund`	string
`status`	string
`hinweise`	array<string>

422 Hürde oder fehlende Eingabe (z. B. Ereignisdatum nicht eingegeben)

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsdaten/aktueller-stand" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/betriebsdaten/neuer-dienstleister Verfügbar DSBD „Neuer Dienstleister / Neue Abrechnungssoftware" (Grund 06) mandant:stammdaten

Pflichtenheft S. 142: bei der erstmaligen Erfassung der Betriebsnummer kennzeichnet der Anwender, ob ein Systemwechsel oder Dienstleisterwechsel vorliegt. Bejaht er das, entsteht der DSBD mit Grund 06. Ohne systemwechsel: true entsteht nichts.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`datum_ereignis`*	string	Tag der Übernahme (Anwendereingabe)
`systemwechsel`*	boolean	Der Anwender bejaht Systemwechsel/Dienstleisterwechsel

Antwort

201 DSBD-Entwurf angelegt (gesendet wird nie automatisch)

`id`	integer
`grund`	string
`status`	string
`hinweise`	array<string>

422 Hürde oder fehlende Eingabe (z. B. Ereignisdatum nicht eingegeben)

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsdaten/neuer-dienstleister" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/betriebsdaten/berichtigen Verfügbar Bereits übermittelten DSBD berichtigen mandant:stammdaten

Pflichtenheft S. 146: sind übermittelte Angaben zu korrigieren, entsteht ein weiterer DSBD mit den korrekten (aktuellen) Angaben; DATUM-EREIGNIS ist gleich dem Wert des zu korrigierenden DSBD. Kein Storno.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

meldung_id* integer ID des zu korrigierenden DSBD in lohn_meldungen

Antwort

201 DSBD-Entwurf angelegt (gesendet wird nie automatisch)

`id`	integer
`grund`	string
`status`	string
`hinweise`	array<string>

422 Hürde oder fehlende Eingabe (z. B. Ereignisdatum nicht eingegeben)

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsdaten/berichtigen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/uv-stammdaten/rueckmeldung Verfügbar DSSD der DGUV übernehmen (UV-Stammdatendienst) mandant:stammdaten

Body: satz (der rohe DSSD, mindestens 570 Zeichen), optional pin.

Die DGUV schickt den DSSD auf zwei Wegen: als Antwort auf einen DSAS und proaktiv, wenn sich Gefahrtarifstellen ändern oder die Meldepflicht endet. Beide Wege laufen hier durch — ein proaktiver Satz ohne vorherigen Abruf wird ebenfalls übernommen.

⚠️ Die Antwort ist keine Anzeige, sondern eine Anweisung. Das Pflichtenheft verlangt an einem guten Dutzend Stellen die maschinelle Übernahme: laufende Nummer, Gültigkeit der Unternehmensnummer, Beitragsmaßstab, Gefahrtarifstellen. Sie werden unverändert gespeichert — auch Fremd-Gefahrtarifstellen, ohne Abgleich gegen die eigene UV-Datei.

⚠️ Der Beitragsmaßstab ist die folgenreichste Angabe: er entscheidet, ob überhaupt ein Lohnnachweis erwartet wird (4–6: keiner, und in den Folgejahren auch keine Abfrage mehr) und worauf er sich stützt (2 = Arbeitsstunden, 3 = Anzahl der Versicherten).

Meldet der Satz das Ende der Zuständigkeit und wurde bereits ein Lohnnachweis übermittelt, ist dieser zu stornieren — der Hinweis dazu landet im Posteingang. Gesendet wird nie automatisch.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Übernommen — folgen nennt, was daraus zu tun ist.

422 Kein verwertbarer DSSD

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv-stammdaten/rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/unterbrechung Verfügbar Beschäftigung unterbrechen (Austritt mit späterem Wiedereintritt) mandant:stammdaten

Erfasst eine Unterbrechung des Beschäftigungsverhältnisses beim selben Arbeitgeber: die Person tritt zum austritt aus und zum wiedereintritt wieder ein.

⚠️ Das ist nicht der Austritt der Person. PATCH /mitarbeiter mit austritt beendet das Arbeitsverhältnis endgültig. Hier bleibt es bestehen und bekommt eine Lücke: Eintritt und Austritt der Person spannen weiter den äußeren Rahmen, die Monate innerhalb der Unterbrechung haben keine Beitragstage und kein anteiliges Entgelt.

Zwei Meldungen entstehen als Entwurf, in dieser Reihenfolge:

1. die Abmeldung zum austritt (Abgabegrund 30 — oder 40/49, je nach Sachverhalt), 2. die Wiederanmeldung zum wiedereintritt (Abgabegrund 10; Pflichtenheft EA V2026.2 S. 138).

Ohne wiedereintritt läuft die Unterbrechung offen — die Person gilt ab dem Folgetag des Austritts als nicht beschäftigt, und es entsteht nur die Abmeldung.

⚠️ Für die Angabe „Beschäftigt seit" (Arbeitsbescheinigung, AAG-Erstattungsantrag) zählt danach das Wiedereintrittsdatum, nicht der erste Eintritt (S. 321).

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

`austritt`*	string	letzter Tag der vorangehenden Beschäftigung
`wiedereintritt`	string	erster Tag der nächsten Beschäftigung; fehlt sie, läuft die Unterbrechung offen
`grund`	string	Austrittsgrund der vorangehenden Beschäftigung
`bemerkung`	string

Antwort

201 Unterbrechung erfasst, Melde-Entwürfe angelegt

`unterbrechung`	object
`abmeldung`	object
`anmeldung`	object

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Die Angaben ergeben keine Unterbrechung — etwa weil der Wiedereintritt nicht nach dem Austritt liegt, der Austritt vor dem Eintritt der Person liegt, das Arbeitsverhältnis bereits endgültig beendet ist, oder weil am genannten Tag nach den bereits erfassten Unterbrechungen gar keine Beschäftigung besteht.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/unterbrechung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/mitarbeiter/{id}/unterbrechungen Verfügbar Erfasste Unterbrechungen der Beschäftigung mandant:stammdaten

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Liste, aufsteigend nach Austritt

unterbrechungen array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/unterbrechungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/personalnummer-wechsel Verfügbar Personalnummer wechseln und mit der alten verknüpfen mandant:stammdaten

Vergibt eine neue Personalnummer und verknüpft sie mit der bisherigen.

🔴 Ein Wechsel ist kein Umbenennen. Drei Dinge passieren zusammen, und wer eines auslässt, erzeugt einen Schaden, der erst Monate später auffällt:

1. Die Verknüpfung wird festgehalten — in beide Richtungen auflösbar (/personalnummern/{nummer}/kette). 2. Die alte Nummer wird gesperrt, nicht freigegeben. Sie wird erst nach einem vollen Kalenderjahr wieder vergeben — Meldungen und Rückmeldungen laufen noch lange nach dem Wechsel, und eine zu früh neu vergebene Nummer ordnet sie der falschen Person zu. 3. Die Vortragswerte gehen mit. Ohne sie verliert die Beitragsberechnung die bisherigen Einmalzahlungen des Jahres, und die nächste wird nicht mehr korrekt gegen die Jahres-Beitragsbemessungsgrenze geprüft — zu wenig Beitrag, unbemerkt.

⚠️ Abgewiesen wird der Wechsel, wenn die neue Nummer bereits jemandem gehört oder noch gesperrt ist. Die Antwort nennt den Grund, statt still nichts zu tun.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

`neu`*	string	übernehmende Personalnummer
`gewechselt_am`	string
`grund`	string	steht in den Lohnunterlagen

Antwort

201 gewechselt

404 Mitarbeiter unbekannt

422 Nummer belegt oder gesperrt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/personalnummer-wechsel" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/personalnummern/{nummer}/kette Verfügbar Kette einer Personalnummer — vorwärts und rückwärts mandant:stammdaten

Liefert zu einer Personalnummer die Vorgänger und Nachfolger.

⚠️ Das Pflichtenheft verlangt ausdrücklich beide Richtungen: „bei den Auswertungen zur alten Personalnummer wird die neue (übernehmende) angezeigt und bei der neuen Personalnummer ist die alte Referenzpersonalnummer erkennbar". Wer nur eine Richtung baut, hat die Hälfte — und zwar die, die er selbst gerade brauchte.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`nummer`*	string · im Pfad

Antwort

200 Kette

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/personalnummern/<nummer>/kette" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/personalnummern/mehrfachvergaben Verfügbar Dieselbe Versicherungsnummer unter mehreren Personalnummern mandant:stammdaten

Der vom Pflichtenheft empfohlene Abgleich: erkennt Personen, die unter mehreren Personalnummern geführt werden.

⚠️ Es ist ein Hinweis, keine Abweisung. Dieselbe Person kann legitim zwei Nummern haben — zwei Beschäftigungen im selben Betrieb, oder ein noch nicht vollzogener Wechsel. Wer daraus einen Fehler macht, blockiert gültige Fälle.

Bereits verknüpfte Nummernpaare erscheinen nicht mehr: der Anwender hat gehandelt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Treffer

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/personalnummern/mehrfachvergaben" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/stammdaten/rechtsformen Verfügbar Rechtsform-Codeliste der Bundesagentur für den DSBD

Die amtliche „Codeliste DSBD" (71 Einträge, dreistelliger Schlüssel) aus den Anlagen zur Verfahrensanforderung DSBD V2.32. plausibilisierbar ist Spalte „A" — kann das Programm Name ↔ Rechtsform maschinell prüfen? ⚠️ Nicht zu verwechseln mit /kataloge/dxbd-rechtsformen: das Dialogverfahren der Bundesagentur führt eine eigene, fünfstellige Codeliste. Ohne Mandantenbezug: ein öffentlicher Katalog, keine Personendaten.

Antwort

200 rechtsformen[] mit schluessel, auswahl_lang, plausibilisierbar

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/stammdaten/rechtsformen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/kataloge/dxbd-rechtsformen Verfügbar Rechtsform-Codeliste der Bundesagentur (Dialogverfahren Betriebsdatenpflege)

Die amtliche Codeliste der BA für den Rechtsformschlüssel des DXBD (73 Einträge, fünfstellig). Sie stammt aus der Verfahrensanforderung DXBD/DXBE V1.3 und liegt versioniert im Repo; plausibilisierbar ist Spalte „A" — kann das Programm Name ↔ Rechtsform maschinell prüfen? ⚠️ Nicht zu verwechseln mit dem dreistelligen Rechtsformschlüssel des DSBD-Verfahrens. Ohne Mandantenbezug: ein öffentlicher Katalog, keine Personendaten.

Antwort

200 rechtsformen[] mit schluessel, auswahl_lang, plausibilisierbar

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/kataloge/dxbd-rechtsformen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Bewegungsdaten & Lohnlauf

Monatswerte melden, probeweise rechnen, festschreiben, korrigieren.

PUT /v1/mandanten/{mandantId}/bewegungen/{monat} Verfügbar Bewegungsdaten des Monats setzen mandant:lohnlauf

Ersetzt den Monat vollständig — der Aufruf ist damit von sich aus wiederholbar: alle bisherigen Zeilen des Monats werden gelöscht und durch die übergebenen ersetzt. Ist der Monat bereits festgeschrieben, wird abgewiesen; dann führt nur noch der Korrekturlauf weiter.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad
`Idempotency-Key`	string · Query	Frei gewählter Schlüssel (max. 80 Zeichen). Ein zweiter Aufruf mit demselben Schlüssel, derselben Methode und demselben Pfad liefert innerhalb von 24 Stunden die gespeicherte Antwort zurück, statt die Aktion erneut auszuführen.

Anfrage application/json · Pflicht

mitarbeiter* array<object>

{
  "mitarbeiter": [
    {
      "mitarbeiter_id": 17,
      "zeilen": [
        {
          "art": "stunden",
          "menge": 162.5
        },
        {
          "art": "zuschlag_nacht",
          "menge": 12,
          "prozent": 25
        },
        {
          "art": "einmalzahlung",
          "betrag_cent": 50000,
          "quelle_ref": "Praemie Q2"
        }
      ]
    }
  ]
}

Antwort

200 Gesetzt.

`monat`	string
`zeilen`	integer	Zahl der geschriebenen Zeilen.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 LAUF_STATUS — der Monat ist bereits festgeschrieben.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 monat ist nicht YYYY-MM, oder mitarbeiter ist kein Array.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/bewegungen/<monat>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "mitarbeiter": [
         {
           "mitarbeiter_id": 17,
           "zeilen": [
             {
               "art": "stunden",
               "menge": 162.5
             },
             {
               "art": "zuschlag_nacht",
               "menge": 12,
               "prozent": 25
             },
             {
               "art": "einmalzahlung",
               "betrag_cent": 50000,
               "quelle_ref": "Praemie Q2"
             }
           ]
         }
       ]
     }'

GET /v1/mandanten/{mandantId}/bewegungen/{monat} Verfügbar Bewegungsdaten des Monats lesen mandant:lohnlauf

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad

Antwort

200 Zeilen des Monats.

`monat`	string
`zeilen`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/bewegungen/<monat>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/lohnlauf/{monat}/probelauf Verfügbar Probeabrechnung rechnen mandant:lohnlauf

Rechnet den Monat durch, ohne festzuschreiben. Beliebig oft wiederholbar. Löst den Webhook lohnlauf.probe_fertig aus.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad
`Idempotency-Key`	string · Query	Frei gewählter Schlüssel (max. 80 Zeichen). Ein zweiter Aufruf mit demselben Schlüssel, derselben Methode und demselben Pfad liefert innerhalb von 24 Stunden die gespeicherte Antwort zurück, statt die Aktion erneut auszuführen.

Antwort

200 Ergebnis mit Summen und Warnungen.

`lauf_id`	integer
`monat`	string
`status`	string
`summen`	object	Betriebssummen des Laufs, alle Beträge in Cent.
`warnungen`	array<string>	Auffälligkeiten, die den Lauf nicht verhindern (fehlende Stammdaten, unplausible Werte).

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 LAUF_STATUS — der Monat lässt sich in seinem Zustand nicht (mehr) probeweise rechnen.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Fachlicher Fehler beim Rechnen (fehlende Stammdaten o. Ä.).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnlauf/<monat>/probelauf" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/lohnlauf/{monat}/korrektur Verfügbar Korrekturlauf (Rückrechnung / Aufrollung) mandant:lohnlauf

Rechnet einen festgeschriebenen Monat periodengerecht neu und liefert das Delta sowie die daraus fälligen Korrektur-Meldungen. Legt einen eigenen Korrektur-Lauf ab; der ursprüngliche Lauf bleibt unangetastet.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad

Anfrage application/json

folgemonat string Monat, in dem das Delta ausgezahlt bzw. verrechnet wird. Ohne Angabe bleibt es beim Korrekturmonat.

Antwort

200 Delta und erzeugte Korrektur-Meldungen.

`lauf_id`	integer
`monat`	string
`status`	string
`summen`	object	Betriebssummen des Laufs, alle Beträge in Cent.
`warnungen`	array<string>	Auffälligkeiten, die den Lauf nicht verhindern (fehlende Stammdaten, unplausible Werte).

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 LAUF_STATUS — der Monat ist nicht festgeschrieben, es gibt also nichts aufzurollen.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Fachlicher Fehler beim Rechnen.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnlauf/<monat>/korrektur" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/lohnlauf/{monat}/festschreiben Verfügbar Lauf festschreiben und Dokumente erzeugen mandant:lohnlauf

Schreibt den Monat fest — ab dann sind Bewegungsdaten gesperrt und Änderungen laufen über den Korrekturlauf. Im selben Zug entstehen Lohnabrechnungen, DATEV-Buchungsstapel, SEPA-Datei und ggf. weitere Dokumente.

Löst die Webhooks lohnlauf.festgeschrieben und dokumente.bereit aus. Ein wiederholter Aufruf mit demselben Idempotency-Key liefert die gespeicherte Antwort und setzt bereits: true, statt ein zweites Mal zu schreiben.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad
`Idempotency-Key`	string · Query	Frei gewählter Schlüssel (max. 80 Zeichen). Ein zweiter Aufruf mit demselben Schlüssel, derselben Methode und demselben Pfad liefert innerhalb von 24 Stunden die gespeicherte Antwort zurück, statt die Aktion erneut auszuführen.

Antwort

200 Festgeschrieben, mit erzeugten Dokumenten.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 Drei Fälle: - LAUF_BEFUNDE — die Prüfkette hat Fehler gefunden. Aus einem festgeschriebenen Lauf entstehen Meldungen; mit diesen Angaben dürfte keine entstehen. Die Antwort trägt zusätzlich befunde mit der Liste dessen, was es verhindert — sonst könnte der Aufrufer nur „irgendwo ist ein Fehler" sagen, ohne zu benennen wo. Warnungen halten nicht auf. - LAUF_STATUS — es gibt keinen Probelauf, oder der Lauf ist in einem anderen Stand. - IDEMPOTENZ_KONFLIKT — derselbe Key wurde mit anderem Inhalt verwendet.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnlauf/<monat>/festschreiben" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/lohnlauf/{monat} Verfügbar Lauf-Status und Summen je Mitarbeiter mandant:lohnlauf

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad

Antwort

200 Der jüngste Lauf des Monats.

`lauf_id`	integer?	`null`, solange nicht gerechnet wurde.
`status`	string?	`null` heißt: für diesen Monat wurde noch kein Probelauf gerechnet. Das ist ein Zustand, kein Fehler — die Antwort ist trotzdem 200 mit leerer Liste und den Befunden, damit sich Beanstandungen vor dem Rechnen beheben lassen.
`monat`	string
`festgeschrieben_am`	string?
`festgeschrieben_von`	string?
`befunde`	array<object>	Wird bei jedem Abruf frisch ermittelt, nicht beim Probelauf eingefroren: zwischen Rechnen und Festschreiben kann sich ein Stammdatum ändern.
`warnungen`	array<string>	Hinweise der letzten Berechnung dieses Laufs — anders als `befunde` ein eingefrorener Stand, denn sie beschreiben, was beim Rechnen geschah. ⚠️ Hier steht auch, wer NICHT abgerechnet wurde. Ein Beschäftigter ohne hinterlegten Stundenlohn oder ohne erfasste Stunden fällt aus dem Lauf; die übrigen Abrechnungen sind korrekt, der Beitragsnachweis meldet dann aber zu wenig. Wer diese Liste ignoriert, merkt es erst bei der Krankenkasse. Bis zum 13.08.2026 standen die Hinweise nur in der Antwort des Probelaufs und waren danach nicht mehr abrufbar.
`je_mitarbeiter`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 monat ist kein YYYY-MM.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnlauf/<monat>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/bewegungen/{monat}/mitarbeiter/{maId} Verfügbar Bewegungen eines Mitarbeiters für einen Monat ersetzen mandant:lohnlauf

Ersetzt nur die Zeilen dieser Person in diesem Monat.

⚠️ Der Unterschied zu PUT /bewegungen/{monat} ist wesentlich: der ersetzt den ganzen Monat (löscht erst alle Zeilen des Mandanten). Für den maschinellen Push ist das richtig, für eine Oberfläche eine Falle — wer die Stunden *einer* Person nachträgt und nur diese schickt, löscht die Bewegungen aller anderen. Ohne Fehlermeldung.

Antwortet mit 409 LAUF_STATUS, sobald der Monat festgeschrieben, gemeldet oder abgeschlossen ist. hinweise benennt Zeilen mit Bewegungsarten ohne Wirkung (fehlzeit_krank, urlaub) — sie werden gespeichert, ändern aber nichts an der Abrechnung.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad
`maId`*	integer · im Pfad

Anfrage application/json · Pflicht

zeilen* array<object>

Antwort

200 Ersetzt.

`monat`	string
`mitarbeiter_id`	integer
`zeilen`	integer
`hinweise`	array<string>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 LAUF_STATUS — der Monat ist bereits abgerechnet.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Unbekannte Bewegungsart oder unplausibler Wert; fehler.feld nennt es.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/bewegungen/<monat>/mitarbeiter/<maId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/produktivreife Verfügbar Kann dieser Mandant produktiv abgerechnet werden? (Blocker / Meldung / Hinweis) mandant:stammdaten

Dasselbe Urteil wie npm run produktivreife — vor dem Lauf: BLOCKER (die Person fiele still aus dem Lauf), MELDUNG (rechnet, aber eine Pflichtmeldung wäre unvollständig), HINWEIS. Die Fachbefunde kommen aus der Prüfkette, dem einen Pfad, den auch der Lohnlauf nimmt. ?monat=JJJJ-MM (Vorgabe: laufender Monat). Grundlage der Startseite „Heute" im Portal.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`	string · Query

Antwort

200 Urteil

`monat`	string
`produktivreif`	boolean
`aktiv`	integer
`rechenbar`	integer?
`funde`	object
`funde.BLOCKER`	array<object>
`funde.MELDUNG`	array<object>
`funde.HINWEIS`	array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/produktivreife" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Dokumente

Lohnabrechnung (§ 108 GewO), DATEV-Buchungsstapel, SEPA (pain.001), Digitale LohnSchnittstelle.

GET /v1/mandanten/{mandantId}/lohnlauf/{monat}/dokumente Verfügbar Dokumente eines Laufs auflisten mandant:dokumente:lesen

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad

Antwort

200 Liste der Dateien; heruntergeladen wird über GET /dokumente/{dokId}.

dokumente array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnlauf/<monat>/dokumente" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/dokumente/{dokId} Verfügbar Dokument herunterladen mandant:dokumente:lesen

Liefert die Datei als Download. Der Content-Type richtet sich nach dem Typ: payslip → PDF, buchungsstapel → CSV, sepa → XML, dls → ZIP.

Parameter

dokId* integer · im Pfad

Antwort

200 Die Datei.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 Das Dokument gehört zu einem fremden Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

410 Der Datensatz existiert, die Datei aber nicht mehr.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/dokumente/<dokId>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/dokumente Verfügbar Alle Dokumente eines Mandanten mandant:dokumente:lesen

Bislang gab es Dokumente nur je Lauf. Wer die Entgeltabrechnungen einer Person über das Jahr sucht oder das Lohnkonto von 2025, musste jeden Monat einzeln abfragen.

Der Monat stammt aus dem Lauf; Jahresdokumente (Lohnkonto, DLS) haben keinen Lauf und tragen ihr Jahr im Dateinamen.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`typ`	string · Query
`jahr`	string · Query
`mitarbeiter_id`	integer · Query
`limit`	integer · Query

Antwort

200 Liste.

dokumente array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 jahr ist kein JJJJ.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dokumente" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/meldebescheinigungen/fehlend Verfügbar Übermittelte DEÜV-Meldungen ohne Bescheinigung nach § 28a Abs. 5 SGB IV mandant:dokumente:lesen

Vollzähligkeitsprüfung (Pflichtenheft S. 199): zu jeder übermittelten Meldung gehört eine Bescheinigung an den Beschäftigten. Die Betriebsautomatik erzeugt sie stündlich; diese Liste zeigt, was noch fehlt. ?auch_entwuerfe=1 zählt auch nicht übermittelte Meldungen.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`auch_entwuerfe`	string · Query

Antwort

200 Liste der Meldungen ohne Bescheinigung

fehlend array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldebescheinigungen/fehlend" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldebescheinigungen Verfügbar Bescheinigungen nach § 28a Abs. 5 SGB IV erzeugen mandant:dokumente:lesen

Erzeugt je übermittelter DEÜV-Meldung ein PDF mit allen gemeldeten Daten (gelesen aus dem übermittelten Datensatz, nicht aus den Parametern) und legt es wie eine Lohnunterlage ab (lohn_dokumente, Typ meldebestaetigung, sha256, Audit). Download über GET /dokumente/{dokId}.

Ohne meldung_ids werden alle fehlenden erzeugt. Eine Bescheinigung zu einer noch nicht übermittelten Meldung entsteht nur mit auch_entwuerfe: true und ist als Entwurf gekennzeichnet (Wasserzeichen, Dateiname ENTWURF_…); in der Sandbox zusätzlich SANDBOX_…. Idempotent: eine vorhandene Bescheinigung wird nicht ersetzt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json

`meldung_ids`	array<integer>	Nur diese Meldungen (sonst alle fehlenden)
`auch_entwuerfe`	boolean	Auch nicht übermittelte Meldungen bescheinigen — als Entwurf gekennzeichnet

Antwort

201 Erzeugt

`erzeugt`	array<object>
`uebersprungen`	array<object>

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldebescheinigungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/fehlerprotokoll/{monat} Verfügbar Fehlerprotokoll eines Monats erzeugen (PDF) mandant:dokumente:lesen

Pflichtenheft S. 173: nicht plausible Daten und Tatbestände in EINEM Protokoll — Prüfketten- und Lauf-Befunde, amtliche Kernprüfung der gespeicherten Meldungen (Fehlertexte), Fehler-Rückmeldungen und offene Fristen des Posteingangs. Ersetzt eine ältere Fassung desselben Monats; Download über GET /mandanten/{id}/dokumente/{id}.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`monat`*	string · im Pfad

Antwort

201 Dokument abgelegt (dokument_id, eintraege, fehler).

422 monat ungültig.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/fehlerprotokoll/<monat>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/lohnkonto/{jahr} Verfügbar Jahres-Lohnkonten erzeugen mandant:dokumente:lesen

§ 41 Abs. 1 EStG i.V.m. § 4 LStDV: für jeden Arbeitnehmer und jedes Kalenderjahr ist ein Lohnkonto zu führen. Erzeugt wird je Arbeitnehmer ein PDF; der Download läuft über GET /dokumente/{dokId}.

⚠️ Gerechnet wird ausschließlich aus festgeschriebenen Läufen — ein Probelauf ist folgenlos und darf nicht in ein Dokument wandern, das als Nachweis dient.

Idempotent: eine erneute Anforderung ersetzt die vorherige Fassung desselben Jahres.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`jahr`*	string · im Pfad

Antwort

201 Erzeugt.

`jahr`	integer
`erzeugt`	integer
`uebersprungen`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 KEINE_DATEN — für das Jahr ist kein Monat festgeschrieben.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 jahr ist kein JJJJ.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lohnkonto/<jahr>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dls/{jahr} Verfügbar Digitale LohnSchnittstelle exportieren mandant:dokumente:lesen

Erzeugt den DLS-Export nach § 4 Abs. 2a LStDV für ein Kalenderjahr (Format des amtlichen BZSt-Pakets). Heruntergeladen wird er über GET /dokumente/{dokId}.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`jahr`*	string · im Pfad

Antwort

201 Export erzeugt.

`dokument_id`	integer
`dateiname`	string
`kennzahlen`	object	Zusammenfassung des Exports (Zahl der Mitarbeiter, Zeiträume).

400 jahr ist nicht vierstellig.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 DLS — der Export ist fachlich nicht möglich (keine Läufe im Jahr o. Ä.).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dls/<jahr>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

SV-Meldeverfahren

DEÜV, Beitragsnachweis, AAG, EEL, eAU, A1, DSVV — Datensätze erzeugen und verwalten.

POST /v1/mandanten/{mandantId}/meldungen Verfügbar SV-Meldung erzeugen mandant:meldungen

Baut aus Stammdaten und Anlass den amtlichen Datensatz und legt ihn als Entwurf ab. Der Datensatz läuft dabei durch die amtliche GKV-Kernprüfung.

Die Annahmestelle (Empfänger) kann explizit übergeben werden; sonst wird sie aus dem Routing-Verzeichnis anhand von Verfahren und Kasse aufgelöst.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`verfahren`*	string	Werte: `deuevbeitragsnachweisaagdsvveeleaua1`
`mitarbeiter_id`	integer	Pflicht bei allen Verfahren außer `beitragsnachweis` (der ist betriebsbezogen).
`anlass`	object	Verfahrensabhängige Anlass-Daten (Grund, Zeitraum, Entgelt …).
`annahmestelle_bbnr`	string	Betriebsnummer der Annahmestelle. Ohne Angabe wird sie aufgelöst.
`kasse_bbnr`	string
`kasse_ik`	string
`lauf_id`	integer
`erstellt`	string

Antwort

201 Entwurf angelegt.

`id`	integer
`verfahren`	string
`kennung`	string	Amtliche Datensatz-Kennung, z. B. `DSME`.
`datensatz_format`	string
`status`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 Mitarbeiter unbekannt.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 verfahren unbekannt, mitarbeiter_id fehlt, oder ANNAHMESTELLE nicht auflösbar.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/meldungen Verfügbar Meldungen auflisten mandant:meldungen

Die 200 jüngsten Meldungen, ohne Datensatz-Inhalt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Liste.

meldungen array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/meldungen/{id} Verfügbar Meldung inklusive Datensatz lesen mandant:meldungen

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Meldung mit datensatz und dem Ergebnis der Kernprüfung.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/meldungen/{id} Verfügbar Meldung freigeben oder Freigabe zurückziehen mandant:meldungen

Setzt geprueft (Freigabe) oder zurück auf entwurf (Zurückziehen).

⚠️ Die Freigabe ist der Punkt, an dem personenbezogene Daten an eine Einzugsstelle gehen — eine bewusste Handlung, kein Formalakt. meldungen/transport/versand.js greift ausschließlich freigegebene Meldungen auf; er läuft nicht von selbst.

Eine Meldung, die die Kernprüfung nicht bestanden hat, lässt sich nicht freigeben: sie würde von der Annahmestelle zurückgewiesen, und bis dahin hielte der Betrieb sie für erledigt, während die Frist läuft.

Zurückziehen geht nur vor dem Versand. Danach ist es keine Rücknahme mehr, sondern eine Storno-Meldung — ein eigener Vorgang.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

status* string Werte: geprueftentwurf

Antwort

200 Freigegeben bzw. zurückgezogen.

`id`	integer
`status`	string
`hinweis`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 MELDUNG_STATUS — der Übergang passt nicht zum aktuellen Stand. KERNPRUEFUNG — die Meldung hat die Kernprüfung nicht bestanden.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Ein anderer Zielstatus als geprueft/entwurf.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldeanlaesse Verfügbar Lebensereignis → alle fälligen Meldungen mandant:meldungen

Der bequeme Weg: ein Ereignis melden (Eintritt, Austritt, Krankheit, Elternzeit …) und alle daraus folgenden Meldungen entstehen zusammen. Läuft in einer Transaktion — scheitert eine, entsteht keine.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`typ`*	string	Ereignistyp. Bei unbekanntem Typ nennt `fehler.detail` die erlaubten Werte.
`mitarbeiter_id`	integer
`datum`	string
`annahmestelle_bbnr`	string
`kasse_ik`	string
`lauf_id`	integer

Antwort

201 Erzeugte Meldungen.

`anlass`	string
`erzeugt`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 Mitarbeiter unbekannt.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Unbekannter Meldeanlass, fehlende mitarbeiter_id, oder ANNAHMESTELLE nicht auflösbar.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldeanlaesse" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/uv/stammdatenabruf Verfügbar UV-Stammdatenabruf (DSAS) beim DGUV-Stammdatendienst anstoßen mandant:meldungen

Vorverfahren zum Lohnnachweis: vor der Abgabe des elektronischen Lohnnachweises ist ein Stammdatenabgleich mit dem Stammdatendienst durchzuführen — gemeldet werden dürfen nur die vom Dienst zurückgemeldeten Gefahrtarifstellen. Es entsteht ein DSAS-Entwurf in lohn_meldungen; gesendet wird er wie jede andere Meldung erst nach Freigabe.

Body: meldejahr (JJJJ), optional storno: true.

⚠️ Zeitfenster: frühestens ab dem 1. November des Vorjahres; spätestens im Dezember des Meldejahres (die Betriebsautomatik erinnert an beides). ⚠️ Erst- oder Folgeabfrage entscheidet das System selbst an BBNRUV/BBNRLB/BBNRAS — nicht an der PIN und nicht an der Unternehmensnummer; die von der DGUV zugeteilte laufende Nummer geht ab dem zweiten Jahr zwingend mit. ⚠️ Storno trägt die laufende Nummer, mit der die Ursprungsmeldung ABGESCHICKT wurde — bei einer Initialabfrage also 000, auch wenn die DGUV inzwischen eine laufende Nummer vergeben hat. Zulässig nur, solange im betroffenen Zeitraum noch kein Lohnnachweis erstellt wurde.

Gesperrt (409): Beitragsmaßstab 4/5/6 (kein Lohnnachweis), landwirtschaftliche BG (Anlage 19a), UV-Träger der öffentlichen Hand (Anlage 19b), Arbeitgeber ist selbst Unternehmen eines UV-Trägers (Anlage 19c, Stammdatum uv_arbeitgeber_ist_traeger), Träger-Betriebsnummer als meldende Stelle (Anlagen 7/8), Träger nimmt am Verfahren nicht teil.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`meldejahr`*	integer
`storno`	boolean

Antwort

201 DSAS-Entwurf angelegt (meldung_id, vorgangs_id, lfd_nr, erstabfrage)

404 Storno ohne vorhandenen Abruf

409 Gesperrt (UV_ABRUF_GESPERRT), Storno unzulässig (UV_STORNO_GESPERRT) oder für das Meldejahr ist bereits ein Abruf übermittelt (UV_ABRUF_VORHANDEN — erst stornieren)

422 Zugangsdaten unvollständig, Zeitfenster verfehlt oder Datensatz nicht erzeugbar

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv/stammdatenabruf" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/uv/lohnnachweis/korrektur Verfügbar Übermittelten Lohnnachweis korrigieren (Storno + Neumeldung) mandant:meldungen

Bei nachträglichen Änderungen der stornorelevanten Inhalte eines bereits übermittelten Lohnnachweises entstehen zwei Entwürfe: die Stornierung und die Neumeldung. Gesendet wird nichts; in der Übermittlungsdatei steht der Storno vor der Neumeldung.

⚠️ Eine ausschließliche Änderung der UV-Stunden führt NICHT zur Stornierung — die Route antwortet dann mit 200 und dem Grund, ohne etwas anzulegen.

⚠️ Der Storno entsteht nur zusammen mit einem inhaltlich fehlerfreien Korrektur-DSLN. Wäre der Korrektursatz fehlerhaft, bleibt alles wie es war (200 mit huerden) — eine Stornierung ohne Ersatz ließe den Betrieb für das Jahr ohne Nachweis dastehen.

Ausnahme ohne_neumeldung: true — nur bei rückwirkender Beendigung der meldenden Stelle und beim Storno eines UV07-Nachweises nach erneutem Eintritt im selben Kalenderjahr.

Die Beitragsabrechnung-UV wird neu erzeugt und zusätzlich archiviert; die bisherigen Fassungen bleiben unverändert erhalten.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`meldejahr`*	integer
`ohne_neumeldung`	boolean
`anlass`	string	Klartext für die Ablage.

Antwort

200 Nichts zu tun — grund nennt warum (keine stornorelevante Änderung, nur Stunden, kein übermittelter Nachweis) oder huerden warum es nicht ging

201 Storno (und ggf. Neumeldung) als Entwurf angelegt

422 Meldejahr fehlt oder der Vorgang ist nicht durchführbar

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/uv/lohnnachweis/korrektur" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/betriebsdaten/vorschau Verfügbar DSBD-Vorschau — was aus diesen Betriebsdaten gemeldet würde (speichert nichts) mandant:stammdaten

Pflichtenheft S. 142: vor der Generierung des DSBD kann der Anwender die Inhalte kontrollieren (a5b0d83f); ergibt eine Änderung der Betriebsdaten einen Plausibilitätshinweis, speichert PATCH /mandanten/{id} erst nach Bejahen (betriebsdaten_bestaetigt: true) — sonst 409 PLAUSIBILISIERUNG mit hinweise und vorschau (c12fc154). Body: aenderungen (Mandantenfelder, optional), grund (05|06, optional — sonst aus der Änderung abgeleitet), datum_ereignis.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json

`aenderungen`	object
`grund`	string	Werte: `0506`
`datum_ereignis`	string

Antwort

200 Vorschau: grund, meldepflichtig, betriebsdaten, aenderungen, hinweise, huerden, annahmestelle_bbnr.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/betriebsdaten/vorschau" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/versicherungsnummer/rueckmeldung Verfügbar Rückmeldung der DSRV zur Versicherungsnummer übernehmen mandant:meldungen

Die Gegenrichtung zur Versicherungsnummernabfrage (POST /meldungen mit verfahren: dsvv). Body: sv_nummer, oder mehrdeutig: true, oder gefunden: false.

⚠️ Eine vorhandene Nummer wird nie überschrieben. Meldet die Rentenversicherung eine andere als die hinterlegte, bleibt die hinterlegte stehen und der Widerspruch landet sichtbar im Posteingang — ein stiller Wechsel änderte die Identität der Person in allen künftigen Meldungen.

⚠️ Die zurückgemeldete Nummer wird geprüft (Prüfziffer, Geburtsdatum), bevor sie in den Stammsatz geht. Besteht sie die Prüfung nicht, wird sie nicht übernommen.

mehrdeutig und „nicht gefunden" sind Zustände, keine Fehler: beide werden abgelegt, damit jemand die Abfrage mit genaueren Angaben wiederholt.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Verarbeitet — uebernommen sagt, ob der Stammsatz sich geändert hat.

422 Die Rückmeldung trifft keine Aussage

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/versicherungsnummer/rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/eubp/rueckmeldung Verfügbar Rückmeldung des Rentenversicherungsträgers zur euBP übernehmen mandant:meldungen

Body: art (dssm | dsum | dsgm | pruefergebnis | protokoll), optional meldung_id, status (bei DSSM) und pdf_base64 (beim Prüfbescheid).

⚠️ DSUM und DSGM sind MELDEVORSCHLÄGE, keine fertigen Meldungen. Der Prüfer schlägt eine Korrektur vor; abgeben darf sie nur der Arbeitgeber. Sie landen als Vorschlag im Posteingang und werden nie automatisch gesendet — wer das täte, meldete der Einzugsstelle die Rechtsauffassung eines Dritten unter eigenem Namen.

⚠️ Die Statusmeldung E90 friert die Prüfung ein: danach ist zu diesem Termin nichts mehr zu liefern. Der Status wird auf der Lieferung vermerkt, und POST /eubp liest ihn dort wieder.

Der Prüfbescheid kommt als PDF und wird separat speicherbar abgelegt — er ist ein Dokument für den Arbeitgeber, kein Datenfeld, aus dem etwas zu rechnen wäre.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Verarbeitet — handlungsbedarf sagt, ob jemand hinsehen muss.

422 Unbekannte Art

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/eubp/rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldungen/{meldungId}/verarbeitungsprotokoll Verfügbar Verarbeitungsprotokoll der Annahmestelle übernehmen (Block 4, Rückrichtung) mandant:meldungen

Body: roh — der zurückgesendete Datensatz als Text.

Nach dem Senden liefert die Annahmestelle unseren eigenen Datensatz mit gesetztem Fehlerkennzeichen zurück: FEKZ an Position 61, FEAN (Anzahl der Fehlerbausteine) an 62, danach bis zu neun DBFE-Bausteine à 87 Zeichen. Die Feldlagen sind aus dem amtlichen DEÜV-Kernprüfprogramm belegt.

| FEKZ | Bedeutung | Status | |---|---|---| | 0 | fehlerfrei | bestaetigt | | 1 | Fehler | fehler | | 3 | nur Hinweise | bestaetigt |

⚠️ 3 ist ein Hinweis, keine Ablehnung. Wer ihn als Fehler behandelt, sendet eine bereits angenommene Meldung ein zweites Mal.

⚠️ Zugeordnet wird über die Meldung, nicht über den Inhalt. Welcher Datensatz zurückkam, weiß nur der Aufrufer — aus dem Satz zu raten hieße, eine fremde Rückmeldung der falschen Meldung zuzuordnen und deren Status still zu fälschen.

Der Fehlertext geht im Klartext in den Posteingang: „DSME010" allein sagt niemandem etwas.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldungId`*	integer · im Pfad

Antwort

200 Verbucht — status und fehler sagen, was die Annahmestelle meldet.

404 Meldung nicht bei diesem Mandanten

422 roh fehlt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<meldungId>/verarbeitungsprotokoll" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/transport/dateinummern Verfügbar Dateifolgenummern des Vorlaufsatzes anzeigen mandant:meldungen

Jede Übertragungsdatei trägt im Vorlaufsatz eine sechsstellige laufende Nummer. Sie wird automatisch verwaltet — je Absender, Empfänger und Verfahren, denn dieselbe Betriebsnummer kann an mehrere Annahmestellen senden, und jede führt ihre eigene Folge.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Zählerstände

dateinummern array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/transport/dateinummern" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/mandanten/{mandantId}/transport/dateinummern Verfügbar Dateifolgenummer setzen (nach einer Störung) mandant:meldungen

„Die Dateinummer wird automatisch verwaltet, kann jedoch durch den Anwender editiert werden" (Pflichtenheft S. 119). Nach einer Störung erwartet die Annahmestelle eine bestimmte Nummer — dann setzt der Anwender sie hier.

⚠️ Gesetzt wird der Stand, also die zuletzt verbrauchte Nummer: die nächste Datei trägt stand + 1. Die Antwort nennt sie ausdrücklich.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`verfahren`*	string
`empfaenger_bbnr`*	string
`stand`*	integer

Antwort

200 gesetzt

`ok`	boolean
`stand`	integer
`naechste_datei`	integer
`hinweis`	string

422

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/mandanten/<mandantId>/transport/dateinummern" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldungen/versand In Zertifizierung 🔒 Geprüfte und freigegebene SV-Meldungen an die Datenannahmestellen senden mandant:lohnlauf

Der Aufrufer des Versands (Schlachtplan N5). Es gibt vier Tore, und dieser Endpunkt öffnet keines davon:

1. Betriebs-Riegel VERSAND_FREIGEGEBEN=1 in der Umgebung des Servers — standardmäßig ZU, nur die Geschäftsführung setzt ihn. 2. Kein Sandbox-Mandant. 3. Transport konfiguriert (SV_KOMSERVER_URL, SV_P12_PFAD/SV_P12_PIN, SV_EMPFAENGER_ZERT_PFAD) — Zertifikat und Zugang kommen mit der ITSG-Zulassung. 4. Jede Meldung hat Status geprueft und ist durch einen Menschen freigegeben (POST …/meldungen/{meldungId}/freigabe).

Ein geschlossenes Tor antwortet 423 mit dem Grund (VERSAND_GESPERRT, SANDBOX_KEIN_VERSAND, TRANSPORT_NICHT_KONFIGURIERT) und sendet nichts. nur_zeigen: true zeigt Tore und Stand, ohne zu senden. Nach erfolgreichem Versand entstehen zu den gesendeten DEÜV-Meldungen die Bescheinigungen nach § 28a Abs. 5 SGB IV. Runbook: docs/sv_versand_runbook.md.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json

`akteur`	string	Name des Menschen
`nur_zeigen`	boolean	Nur Tore und Stand zeigen

Antwort

200 Nur gezeigt (nur_zeigen)

201 Gesendet

`versandt`	integer
`ids`	array<integer>
`pakete`	integer
`bescheinigungen`	object?

409 Versand abgebrochen (keine Freigabe, kein Zertifikat, kein Endpunkt, Annahmestelle …)

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

423 Ein Tor ist geschlossen — nichts gesendet

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/versand" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldungen/{meldungId}/freigabe Verfügbar 🔒 Eine Meldung zur Übermittlung freigeben mandant:lohnlauf

Body: akteur (Pflicht — der Name des Menschen, der freigibt) und bestaetigung, die das Verfahren der Meldung wiederholen muss.

🔒 Aus Lohnfluss geht nichts an eine Behörde oder Kasse hinaus, bevor es ausdrücklich freigegeben wurde. Es gibt zwei unabhängige Tore, und eines allein genügt nie:

1. Der Betriebs-Riegel VERSAND_FREIGEGEBEN=1 in der Umgebung — standardmäßig ZU. 2. Die Freigabe je Meldung über diesen Weg.

⚠️ Auch eine Testübermittlung ist gesperrt. Der Testmerker macht sie *fachlich* zum Test; *technisch* ist es eine echte Verbindung zu einem Behördenserver, mit echten Personen- und Entgeltdaten im Umschlag.

⚠️ Es gibt kein „alles freigeben". Eine Sammel-Freigabe wäre praktisch dasselbe wie kein Tor. Und eine Freigabe ohne Namen wird abgewiesen: in der Betriebsprüfung ist „wer hat das abgegeben?" die erste Frage.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldungId`*	integer · im Pfad

Antwort

200 Freigegeben

404 Meldung nicht bei diesem Mandanten

422 Akteur fehlt oder die Bestätigung passt nicht zum Verfahren

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<meldungId>/freigabe" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

DELETE /v1/mandanten/{mandantId}/meldungen/{meldungId}/freigabe Verfügbar 🔒 Eine Freigabe zurücknehmen mandant:lohnlauf

Möglich, solange nichts gesendet wurde.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldungId`*	integer · im Pfad

Antwort

200 Zurückgenommen

409 Keine offene Freigabe — oder bereits gesendet

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X DELETE "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<meldungId>/freigabe" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/traeger-anforderungen Verfügbar Eingehende Anforderung eines Trägers annehmen (vier Anlässe) mandant:meldungen

Body: typ (arbeitgeberkonto | fehlende_jahresmeldung | gesonderte_meldung | mitgliedsbestaetigung), dazu sv_nummer, kasse_ik, zeitraum je nach Anlass.

⚠️ Nicht zu verwechseln mit POST /anforderungen — jener Weg nimmt rvBEA-FORMS und GML57 an, die eine *Bescheinigung* verlangen. Hier hat jeder Anlass eine eigene Handlung.

⚠️ Die Gesonderte Meldung ist NACHRANGIG — die Regel, die man ohne den Text umgekehrt baut: „Entgeltmeldungen aufgrund anderer meldepflichtiger Tatbestände gehen einer Gesonderten Meldung grundsätzlich vor. Einzige Ausnahme stellt die Jahresmeldung dar." Deckt eine andere Meldung den Zeitraum ab, unterbleibt sie — und der Fall bekommt trotzdem ein Fehler-Kennzeichen, denn der Träger erwartet eine Antwort.

⚠️ Der Abgabezeitpunkt hängt daran, ob der Zeitraum schon abgerechnet ist: mit der Abrechnung des letzten Monats des angeforderten Zeitraums, sonst mit der nächsten. Wer immer sofort meldet, meldet ein Entgelt, das noch nicht feststeht.

Zugeordnet wird über die Versicherungsnummer, nie über den Namen: eine falsch zugeordnete Anforderung erzeugte eine Meldung über die falsche Person.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

201 Angenommen — mit Aktion, Zuordnung und Posteingangs-Eintrag.

422 Unbekannter Anforderungstyp

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/traeger-anforderungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/kassenabruf Verfügbar Zuständige Krankenkasse beim GKV-Spitzenverband abrufen mandant:meldungen

Body: anlass (keine_angabe | zmv_unzustaendig | mitgliedsbestaetigung | eau_unzustaendig), bei keine_angabe zusätzlich beschaeftigter_aufgefordert.

⚠️ Der Abruf ist an eine Voraussetzung gebunden, nicht frei. Zulässig nur, sofern eine Meldung nach § 28a SGB IV ansteht und trotz vorheriger Aufforderung des Beschäftigten keine oder unvollständige Angaben vorliegen. Ein Abruf auf Verdacht wäre eine Abfrage von Sozialdaten ohne Grundlage — er wird mit 422 abgewiesen.

⚠️ angaben_vollstaendig wird gemessen, nicht übernommen: liegt an der Zeitscheibe eine Kasse, ist der Abruf beim Anlass „keine Angabe" unzulässig. Meldet sich dagegen eine Kasse selbst als unzuständig, ist die hinterlegte ja gerade die falsche — dann entfällt auch das Nachfragen beim Beschäftigten.

⚠️ Die Anfrage geht an den Spitzenverband (BBNR 93121302), nicht an eine Krankenkasse: er sucht über alle hinweg.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

201 Abruf als Entwurf angelegt

422 Der Abruf ist nicht zulässig — siehe huerden.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/kassenabruf" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/kassenabruf/rueckmeldung Verfügbar Rückmeldung des GKV-Spitzenverbandes übernehmen mandant:meldungen

Body: ergebnis (1 = Mitgliedschaft ermittelt, 2 = keine), bei 1 zusätzlich bbnr_kk.

Bei 1 wandert die Kasse direkt in die Stammdaten — genau dafür wurde gefragt; ein Zwischenschritt „bitte abtippen" wäre die Fehlerquelle, die das Verfahren beseitigen soll.

⚠️ Bei 2 endet das Verfahren, es beginnt nicht neu. Der Arbeitgeber ist zu weiteren Ermittlungen beim Beschäftigten verpflichtet; ein zweiter Abruf brächte dasselbe Ergebnis. Der Fall landet mit Handlungsbedarf im Posteingang.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Verarbeitet — uebernommen sagt, ob der Stammsatz sich geändert hat.

422 ergebnis ist weder 1 noch 2

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/kassenabruf/rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/unbedenklichkeit Verfügbar Unbedenklichkeitsbescheinigung beantragen (je Einzugsstelle) mandant:meldungen

Body: einzugsstellen (Liste aus {kasse_bbnr, bezug}; Bezug einmalig | monatlich | vierteljaehrlich | halbjaehrlich), optional durch_bevollmaechtigten, vollmacht_pdf, auch_englisch.

Die Bescheinigung bestätigt, dass Beiträge ordnungsgemäß abgeführt wurden. Gebraucht wird sie für Dritte: Auftraggeber bei Vergaben, Generalunternehmer bei Nachunternehmern, Banken bei Krediten.

⚠️ Der Bezug wird JE EINZUGSSTELLE gewählt. Ein Arbeitgeber mit Beschäftigten bei fünf Kassen kann bei der einen monatlich abonnieren und bei der anderen einmalig beantragen.

⚠️ Ohne hinterlegte Vollmacht darf ein Bevollmächtigter nicht abrufen — die Kasse gäbe sonst Beitragsdaten an einen Dritten. Das Kennzeichen allein reicht nicht.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

201 Anträge als Entwürfe angelegt

422 Unbekannte Bezugsart oder fehlende Vollmacht — siehe huerden.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/unbedenklichkeit" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

DELETE /v1/mandanten/{mandantId}/unbedenklichkeit/{kasseBbnr} Verfügbar Abonnement bei EINER Einzugsstelle widerrufen mandant:meldungen

⚠️ Der Widerruf gilt je Einzugsstelle, wie das Abonnement selbst. Ein „alles abbestellen" gibt es im Verfahren nicht — ein selbstgebautes beendete stillschweigend Abos, die der Anwender behalten wollte.

Ein widerrufenes Abonnement fällt auf „kein Abo" zurück; die einmalige Anforderung bleibt jederzeit möglich.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`kasseBbnr`*	string · im Pfad

Antwort

200 Widerrufen

404 Kein Abonnement bei dieser Einzugsstelle

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X DELETE "https://api.lohnfluss.de/v1/mandanten/<mandantId>/unbedenklichkeit/<kasseBbnr>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/unbedenklichkeit/rueckmeldung Verfügbar Rückmeldung der Einzugsstelle übernehmen mandant:meldungen

Body: kasse_bbnr (Pflicht), pdf_base64 oder ablehnungsgrund, optional monat (jjjj-mm).

⚠️ Die Bescheinigung kommt als eingebettetes PDF, nicht als Datenfeld. Sie wird abgelegt und bereitgestellt — anzeigbar und druckbar. Werte daraus zu extrahieren wäre am Zweck vorbei.

Läuft ein Abonnement, wird daraus der nächste Termin bestimmt und geführt. Eine Ablehnung landet mit Handlungsbedarf im Posteingang: sie heißt, dass die Kasse Rückstände sieht.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Verarbeitet — mit dokument_id und naechster_termin.

422 kasse_bbnr fehlt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/unbedenklichkeit/rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dxbd Verfügbar Dialogverfahren Betriebsdatenpflege — DXBD anlegen mandant:meldungen

Body: erstmalig | beendigung | manuell | vorher (Stand vor der Änderung), optional bbnr, bestaetigt (beantwortete Rückfragen), negativliste, signalwoerter, rechtsform_plausibilisierbar / rechtsform_passt.

⚠️ Nicht der DSBD. Der geht als Byte-Satz an die Betriebsnummern-Datei der Rentenversicherung — eine Einbahnstraße. Dies hier ist ein Dialog mit der Bundesagentur: auf jeden DXBD antwortet ein DXBE, und die Antwort kann eine Prüfaufforderung sein.

⚠️ Ein offener Vorgang blockiert. Ein neuer A01/A02 darf erst entstehen, wenn der vorige durch B01/B02/B06 abgeschlossen ist. Wer das nicht führt, schickt der BA zwei konkurrierende Änderungen desselben Betriebs, und welche gewinnt, entscheidet die Reihenfolge des Eingangs dort.

⚠️ Rückfragen sind Pflicht, keine Empfehlung. Bleiben sie offen, entsteht keine Meldung — die BA weist unplausible Stammdaten zurück, und jede Zurückweisung ist ein weiterer Dialogschritt. negativliste und signalwoerter kommen von der BA und werden durchgereicht, nicht erfunden.

Antwortet mit 200 und ok: false, wenn kein Anlass besteht oder Rückfragen offen sind — beides sind Zustände, keine Fehleingaben.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Kein Anlass oder offene Rückfragen — siehe rueckfragen/huerden.

201 Entwurf angelegt, Vorgang eröffnet.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dxbd" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dxbd/wukl-abfrage Verfügbar Wirtschaftsunterklasse abfragen (DXBD A05) mandant:meldungen

Fragt die Wirtschaftsunterklasse (WUKL) aus dem Dateisystem der Beschäftigungsbetriebe ab. Body: optional bbnr (sonst die Betriebsnummer des Mandanten).

⚠️ A05 trägt AUSSCHLIESSLICH Mussfelder — keine Betriebsdaten, kein Ereignisdatum: „auch bedingte Mussfelder (m) dürfen nicht übertragen werden, unabhängig davon, ob die entsprechende Information vorliegt".

⚠️ Die Abfrage eröffnet KEINEN Vorgang. Die Antwort darauf ist ein B05 „Hinweis", und der schließt keinen Vorgang — ein Vorgang bliebe für immer offen und sperrte jede künftige Bestands- oder Änderungsmeldung dieses Betriebs.

⚠️ Die zurückgemeldete WUKL wird nicht selbsttätig in die Stammdaten übernommen: sie ist ein gemeldetes Stammdatum, und ein Wert, der ohne Zutun des Anwenders in den Stamm wandert, löste beim nächsten Änderungsvergleich ein A02 aus, das niemand veranlasst hat.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Nicht erzeugt — siehe huerden (gesperrter Nummernkreis, Beendigung übermittelt).

201 Entwurf A05 angelegt.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dxbd/wukl-abfrage" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dxbd/antwort Verfügbar Antwort der Bundesagentur (DXBE) übernehmen mandant:meldungen

Body: abgabegrund (B01–B06), optional datensatz_id, fehler (Liste aus {nummer, hinweis}), bbnr.

⚠️ B03/B04 schließen den Vorgang NICHT. Sie sind Prüfaufforderungen und verlangen ein A06 „Prüfergebnis". Wer sie als Abschluss behandelt, hält den Betrieb für gemeldet, während die BA noch wartet.

⚠️ Dem Anwender wird der BA_Fehlerhinweis angezeigt, nicht die Fehlernummer — „F0001" sagt niemandem etwas.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Verarbeitet — folgemeldung nennt ein fälliges A06.

422 abgabegrund ist kein B01–B06

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dxbd/antwort" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dxbd/{vorgangId}/pruefergebnis Verfügbar Prüfergebnis (A06) zu einer Prüfaufforderung abgeben mandant:meldungen

Body: entscheidungen — je gemeldeter Fehlernummer korrigiert oder bestaetigt; dazu ereignisdatum (jjjjmmtt, Pflicht, nie vorbelegt — Eingabe des Anwenders).

⚠️ Zu JEDER gemeldeten Fehlernummer gehört eine Prüfbestätigung — auch dort, wo der Anwender nichts geändert, sondern die Richtigkeit bestätigt hat. Eine Lücke wird mit 422 abgewiesen und nennt die fehlende Nummer: ein A06 mit Lücke ließe den Vorgang offen und blockierte jede weitere Änderungsmeldung dieses Betriebs, ohne dass etwas rot würde.

Das A06 trägt den korrigierten/bestätigten Stand der betrieblichen Stammdaten und die Referenz_Id des DXBE; es beantwortet die Prüfaufforderung und schließt den Vorgang. Das XML-Wire-Format steht noch aus (docs/dxbd_xml_offen.md) — gespeichert werden die Nutzdaten nach dem Mussfeld-Schnitt.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`vorgangId`*	integer · im Pfad

Antwort

201 Prüfergebnis angelegt

422 Lücke im Prüfergebnis, Ereignisdatum fehlt oder keine Prüfaufforderung vorhanden

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dxbd/<vorgangId>/pruefergebnis" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dxbd/{vorgangId}/unzustaendigkeit Verfügbar Unzuständigkeitserklärung (A04) zu einer Prüfaufforderung abgeben mandant:meldungen

Body optional: begruendung (wird vermerkt, nicht übertragen).

Antwort auf einen DXBE (B03/B04), für dessen Betrieb dieser Mandant nicht zuständig ist. Das A04 trägt die Datensatz_Id des DXBE als Referenz_Id und keine betrieblichen Stammdaten; es schließt den Vorgang. Ohne Referenz-ID (kein DXBE zum Vorgang) 422.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`vorgangId`*	integer · im Pfad

Antwort

201 A04 angelegt

404 Vorgang nicht bei diesem Mandanten

422 keine Referenz-ID oder Vorgang nicht offen

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dxbd/<vorgangId>/unzustaendigkeit" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dxbd/beendigung Verfügbar Vollständige Beendigung der Betriebstätigkeit melden (A03) mandant:meldungen

Body: beendet_am (jjjj-mm-tt — der Tag der vollständigen Einstellung, Eingabe des Anwenders, nie vorbelegt), optional bestaetigt (beantwortete Rückfragen).

⚠️ Vorher stehen die Rückfragen — Mechanismus B des Pflichtenhefts: sind auf der Betriebsnummer noch nicht beendete Beschäftigungsverhältnisse, kommt der Hinweis, die Personen zuerst umzuhängen oder abzumelden. Bleiben Rückfragen offen, wird nichts geschrieben (200, ok: false). Entsteht der A03, wandert das Datum als betrieb_beendet_am in den Mandantenstamm (Migration 086) — danach ist zu dieser Betriebsnummer kein weiterer DXBD möglich.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Rückfragen offen oder Datum fehlt — siehe rueckfragen/huerden.

201 A03 als Entwurf angelegt, Beendigungsdatum gespeichert.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dxbd/beendigung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/anforderungen Verfügbar Anforderung eines Trägers annehmen (rvBEA-FORMS · GML57) mandant:meldungen

Body: anforderung (der Datensatz), eingang (Tag der Quittierung, jjjjmmtt), optional feiertage (Liste jjjjmmtt).

Der Rentenversicherungsträger fordert eine Bescheinigung an und kennzeichnet darin die Felder und Zeiträume, die er braucht. Dieser Weg ordnet die Anforderung automatisiert einer Person zu (über AZ-VU, sonst über die Versicherungsnummer), bestimmt die Frist und legt sie im Posteingang ab.

⚠️ Die Frist ist die kürzeste im ganzen Meldewesen — im Regelfall ein Arbeitstag nach der Quittierung. Sie steht in der eigenen Spalte faellig_am, damit der Posteingang danach sortiert und Überfälliges oben zeigt.

⚠️ Eine nicht zuordenbare Anforderung landet erst recht im Posteingang, zusätzlich mit Fehler-Kennzeichen: sonst wartet der Träger auf eine Antwort, die niemand erstellt, weil niemand von der Anforderung weiß.

⚠️ Die Kandidatenliste für die Zuordnung kommt aus der Datenbank, nicht aus dem Body — sonst entschiede der Absender, gegen wen zugeordnet wird.

Es wird nichts gesendet: erzeugt wird ein Vorgang, der Versand ist ein eigener Schritt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

201 Angenommen — mit Zuordnung, Frist und Posteingangs-Eintrag.

422 anforderung oder eingang fehlt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/anforderungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/anforderungen/{posteingangId}/antwort Verfügbar Antwort auf eine rvBEA-Anforderung erzeugen (DXEB) mandant:meldungen

Erzeugt den Antwortdatensatz zu einer eingegangenen Anforderung des Rentenversicherungsträgers — mit den in der Anforderung gekennzeichneten Feldern und Zeiträumen.

Bescheinigt werden die Werte der jeweiligen Monate, wie sie abgerechnet wurden — nicht ein neu gerechneter Stand (Pflichtenheft S. 329: „die zum Zeitpunkt der Erstellung des Antwortdatensatzes geltenden Werte"). Je Monat gilt der zuletzt festgeschriebene Lauf.

Ein Monat ohne Abrechnung bekommt einen Hinderungsgrund; geschätzt wird nichts. Kann kein einziger Zeitraum bescheinigt werden, trägt die Antwort einen Grund für das Ganze.

⚠️ Der Entwurf geht nicht hinaus — der Versand ist ein eigener, freigegebener Schritt. Die Antwortfrist („innerhalb eines Arbeitstages nach Eingang") steht am Posteingangs-Eintrag und wird vom Fristen-Wächter überwacht.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`posteingangId`*	integer · im Pfad	Der Posteingangs-Eintrag mit der Anforderung (DXAR).

Antwort

201 Antwortdatensatz als Entwurf angelegt.

`ok`	boolean
`meldung`	object
`vollstaendig`	boolean	Falsch, wenn ein Zeitraum nicht bescheinigt werden konnte.
`monate`	integer
`ohne_werte`	integer
`huerden`	array<string>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 Nichts zu bescheinigen — etwa ohne Personenzuordnung oder ohne angeforderte Felder.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/anforderungen/<posteingangId>/antwort" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/anforderungen/werteliste Verfügbar Maschinelle Rückmeldung `Werteliste_AG` des RV-Trägers annehmen mandant:meldungen

Body: meta (Pflicht) und fach_daten. Der Träger meldet zurück, wer zuständig ist.

⚠️ Zugeordnet wird ausschließlich über die mitgelieferten Meta-Daten — keine Heuristik über Namen oder Zeitpunkte. Eine falsch zugeordnete Rückmeldung hängt an der falschen Anforderung und fällt niemandem auf.

⚠️ Der Träger wird im Klartext angezeigt, und zwar mit der Bezeichnung aus der Rückmeldung. Kommt nur ein Schlüssel ohne Bezeichnung, wird er unverändert durchgereicht und das benannt — ein eigener Trägerkatalog sähe amtlich aus und wäre es nicht.

⚠️ Die Werteliste ist eine Auskunft, keine Meldung: kein Entwurf, kein Versand und keine Frist. Ein Fälligkeitsdatum würde eine Handlungspflicht vortäuschen, die es nicht gibt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Angenommen — zugeordnet sagt, ob die Referenz gefunden wurde.

422 meta fehlt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/anforderungen/werteliste" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/dabpv/abonnements Verfügbar DaBPV-Abonnements auf Stand bringen (§ 55a SGB XI) mandant:meldungen

Seit dem 01.07.2023 hängt der PV-Beitrag an der Zahl der Kinder. Der Arbeitgeber darf sie nicht raten — er fragt sie beim Bundeszentralamt für Steuern ab. Ein Abonnement ist eine stehende Anfrage: ändert sich die Kinderzahl, kommt die Antwort von selbst.

Dieser Weg vergleicht je Beschäftigtem Soll und Ist und legt die nötigen An-/Abmeldungen als Entwürfe an. Gesendet wird nie automatisch.

⚠️ „Dem Grunde nach" ist die Falle des Verfahrens. Eine Unterbrechung wegen Krankengeld oder Elternzeit beendet das Abonnement NICHT — die Beitragspflicht besteht fort. Nur Beitragsgruppe PV „0" oder das Ende der Beschäftigung beenden es. Wer bei jeder Unterbrechung abmeldet, erzeugt ein Ab-/Anmelde-Paar je Krankengeld-Phase.

⚠️ Ändert sich das Zuordnungsmerkmal (ABSN-BBNRAS-HABBNR), bricht das Abonnement: es geht eine Abmeldung UND eine Anmeldung hinaus, die Abmeldung zuerst und an einem anderen Tag — sonst kann das BZSt die Reihenfolge nicht erkennen.

Ohne steuerliche Identifikationsnummer entsteht keine Anfrage; der Fall steht in huerden.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Aktionen je Person, erzeugte Entwürfe, Hürden und Hinweise.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dabpv/abonnements" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/dabpv/offen Verfügbar Für wen fehlt die Auskunft zur Kinderzahl noch? mandant:stammdaten

Die Frage, die vor der Abrechnung zu stellen ist.

⚠️ Ohne Rückmeldung und ohne manuelle Angabe wird nicht „kinderlos" unterstellt — das wäre der teurere Beitrag, zulasten des Beschäftigten. Deshalb liefert dieser Weg eine Liste und keine Vermutung.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Liste der Personen ohne Auskunft, je mit Grund.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/dabpv/offen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/dabpv/rueckmeldung Verfügbar Rückmeldung des BZSt zur Kinderzahl übernehmen mandant:meldungen

Body: elterneigenschaft (boolean) und/oder kinder (Liste aus {ab, anzahl}), optional stichtag. Der Weg nimmt sowohl die Antwort auf eine Anfrage als auch die proaktive Rückmeldung entgegen, die ein laufendes Abonnement bei jeder Änderung auslöst.

Die Rückmeldung ist die autoritative Quelle für den PV-Beitrag: pv_kinder wird nachgezogen — aber nur, wenn sich der Wert wirklich ändert, und mit einem Posteingang, damit die Änderung nicht unbemerkt in die nächste Abrechnung läuft. Betroffene Monate sind gegebenenfalls aufzurollen.

Fehlersatz: statt elterneigenschaft/kinder kann fehler ({nummer, text}) übergeben werden — ein vom BZSt ZURÜCKGEWIESENER Satz. Er fasst pv_kinder nicht an und bestätigt kein Abonnement, sondern erzeugt einen Posteingang mit Fehlerkennzeichen: die Angaben sind zu berichtigen und die Anfrage zu wiederholen.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Verarbeitet — uebernommen sagt, ob der Stammsatz sich geändert hat.

422 Die Rückmeldung trifft keine Aussage

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/dabpv/rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/dabpv/historienanfrage Verfügbar Historienanfrage zur Kinderzahl (mit Bis-Datum) mandant:meldungen

Body: ab_datum und bis_datum (jjjj-mm-tt oder jjjjmmtt) — beide Pflicht, beide ohne Vorbelegung. Die Historienanfrage erfragt einen ZURÜCKLIEGENDEN Zeitraum; sie legt kein Abonnement an und beendet keines.

Amtliche Grenzen (Pflichtenheft S. 112): das Bis-Datum muss in der Vergangenheit liegen und darf nicht vor dem Ab-Datum liegen; das Ab-Datum darf höchstens vier Kalenderjahre zurückreichen, frühestens jedoch der 01.07.2023.

Entsteht ein Entwurf, wird er wie jede Meldung erst nach Freigabe übermittelt.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Entwurf angelegt — anfrage zeigt den erzeugten Satz.

422 Nicht erstellt — huerden nennt den Grund (fehlendes Datum, Zeitraum unzulässig).

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/dabpv/historienanfrage" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/eau Verfügbar Elektronische AU-Bescheinigung bei der Krankenkasse anfordern (§ 109 SGB IV) mandant:meldungen

Body: au_beginn (jjjj-mm-tt, Pflicht), optional annahmestelle_bbnr.

⚠️ Die Sperrfristen sind der eigentliche Inhalt des Verfahrens — die Kasse hat die Daten anfangs schlicht noch nicht. Angefordert wird frühestens ab dem 2. Kalendertag der Arbeitsunfähigkeit; nach einer Zwischennachricht gelten 14 bzw. 28 Tage Wartezeit. Wird eine Sperre verletzt, antwortet der Weg mit 422 und nennt in huerden, woran es liegt, sowie in frei_ab den frühesten Tag.

⚠️ Nur für gesetzlich Versicherte, und nur solange am Tag der Abwesenheit ein Beschäftigungsverhältnis bestand.

🔴 Jede Anforderung erhält eine eigene Datensatz-ID und prüft sie gegen alle bereits übermittelten. Die Kasse ordnet ihre Rückmeldungen über dieses Feld zu; zwei Vorgänge mit derselben ID sind für sie ununterscheidbar.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

201 Anforderung als Entwurf angelegt (id, dsid).

422 Eine Sperre greift — siehe huerden und frei_ab.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/eau" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldungen/{meldungId}/eau-rueckmeldung Verfügbar Antwort der Krankenkasse auf eine eAU-Anfrage übernehmen mandant:meldungen

Body: gefunden, au_von, au_bis, festgestellt_am, art, krankenhaus — oder kennzeichen für eine Zwischennachricht, oder storniert: true.

⚠️ Die Kennzeichen 4, 7 und 9 sind keine Antwort, sondern Zwischennachrichten (Nachweis liegt nicht vor / in Prüfung / Weiterleitungsverfahren). Sie erzeugen keine Fehlzeit, sondern einen Posteingang mit dem Tag, ab dem erneut angefragt werden darf.

⚠️ Eine bestätigte AU wird zur Fehlzeit — aber sie überschreibt nie stillschweigend eine vorhandene Fehlzeit und rührt keinen festgeschriebenen Monat an. In beiden Fällen entsteht stattdessen ein Posteingang mit dem Widerspruch; entschieden wird er von einem Menschen.

Zieht die Kasse ihre Rückmeldung zurück (storniert: true), wird die daraus entstandene Fehlzeit gelöscht — AU-Daten sind Gesundheitsdaten. Nur wenn der Zeitraum bereits abgerechnet ist, wird sie stattdessen als ungültig gekennzeichnet.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldungId`*	integer · im Pfad

Antwort

200 Verarbeitet — art sagt was geschah (uebernommen | zwischennachricht | konflikt | nicht_gefunden | storniert).

422 Die Rückmeldung trifft keine Aussage

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<meldungId>/eau-rueckmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/meldungen/{meldungId}/eau-storno Verfügbar Eine eAU-Anfrage zurücknehmen mandant:meldungen

⚠️ Zulässig nur, solange keine fachliche Rückmeldung vorliegt. Die Zwischennachrichten 4, 7 und 9 stehen einer Stornierung nicht entgegen — wer sie als Antwort behandelt, sperrt den Storno zu früh.

Ein Entwurf, der nie hinausging, wird schlicht verworfen. Was gesendet wurde, bekommt einen Storno-Auftrag im Posteingang mit der Datensatz-ID der Ursprungsmeldung (DSID_UR); ohne sie weiß die Kasse nicht, welche Anfrage zurückgenommen wird.

frei_ab nennt den Tag, ab dem erneut angefragt werden darf — die Frist läuft ab dem Erhalt der Zwischennachricht, nicht ab dem Storno.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldungId`*	integer · im Pfad

Antwort

200 Zurückgenommen

409 Nicht mehr möglich — eine fachliche Rückmeldung liegt vor.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/meldungen/<meldungId>/eau-storno" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/deuev/bestandsanmeldung Verfügbar Bestandsanmeldung zum DEÜV-Systembeginn (GD 13) erzeugen mandant:meldungen

Systemwechsel (Pflichtenheft 0104 S. 127): alle Beschäftigten mit Eintritt vor dem DEÜV-Systembeginn des Mandanten (deuev_systembeginn), die noch keinen gemeldeten Stand haben, werden zum Systembeginn mit Grund 13 angemeldet — als Entwürfe. Das Altsystem meldet dieselben Personen mit Grund 36 ab. Idempotent; ohne gesetzten Systembeginn 422. Eintritte am oder nach dem Systembeginn bekommen die gewöhnliche Anmeldung 10 beim Anlegen der Person.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Nichts Neues — alle übersprungen (uebersprungen) oder Hürden (huerden).

201 Entwürfe angelegt (erzeugt: Person, Meldung, Grund, Beginn).

422 Kein DEÜV-Systembeginn gesetzt.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/deuev/bestandsanmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/minijob-befreiung Verfügbar Befreiungsantrag RV anzeigen (Minijob-Altfall, Gründe 33/13) mandant:meldungen

Anzeige des Antrags auf Befreiung von der Rentenversicherungspflicht (§ 6 Abs. 1b SGB VI) gegenüber der Minijob-Zentrale. Body: erhoehung_ab (JJJJ-MM-TT, Tag ab dem das erhöhte Entgelt gilt).

Pflichtenheft S. 186 · Kriterium 976a3f20. Der Altfall: geringfügig Beschäftigte (PGS 109), deren Beschäftigung vor dem 01.01.2013 begann, mit einer Entgelterhöhung danach über 400 € und einem Antrag im ersten Monat der Erhöhung.

⚠️ Gründe 33/13, nicht 32/12. Die Beitragsgruppe wechselt, der Sachverhalt ist trotzdem ein „sonstiger Grund" — beide wären formal zulässig, keine Kernprüfung sieht den Unterschied.

⚠️ Entsteht nie automatisch — der Antrag ist ein Papier des Beschäftigten. Der Tag seines Eingangs steht als rv_befreiung_antrag_am an der Zeitscheibe.

⚠️ Die Befreiung wirkt ab dem Monat des Eingangs nur, wenn die Meldung die Minijob-Zentrale binnen sechs Wochen erreicht (§ 6 Abs. 1b S. 3 SGB VI) — sonst erst ab dem Folgemonat der Meldung. Der Hinweis steht in der Antwort.

Antwort

201 Meldepaar 33/13 als Entwürfe angelegt.

404 Mitarbeiter unbekannt

422 Die Voraussetzungen des Altfalls sind nicht erfüllt — fehler.meldung nennt ALLE fehlenden.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/minijob-befreiung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/deuev/systemwechsel Verfügbar Abmeldungen bei Wechsel des Entgeltabrechnungssystems (Grund 36) mandant:meldungen

Das Gegenstück zur Bestandsanmeldung: verlässt der Mandant dieses System, wird für jeden Beschäftigten der bis dahin gemeldete Zeitraum mit Abgabegrund 36 abgeschlossen. Das neue System meldet die Menschen mit Grund 13 wieder an.

Pflichtenheft S. 127 · Kriterium 3b975d05 (F1). ⚠️ Ohne diese Meldung bleibt der Bestand bei den Einzugsstellen offen — zwei Systeme melden dieselbe Beschäftigung.

⚠️ Keine Abmeldung der Beschäftigung: kein Austrittsdatum, keine Wirkung auf Lohnkonto oder Beitragsnachweis. Der DEÜV-Stand wird geschlossen, damit hier nichts mehr entsteht.

⚠️ Entsteht nie automatisch — das Datum kennt nur der Anwender. Erzeugt werden Entwürfe; gesendet wird nur nach Freigabe.

Anfrage application/json · Pflicht

systemende* string Letzter Tag, für den dieses System meldet.

Antwort

200 Nichts zu melden (kein gemeldeter Stand offen).

201 Entwürfe angelegt.

422 systemende fehlt, ist kein Datum oder liegt vor dem DEÜV-Systembeginn.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/deuev/systemwechsel" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/eel/ende-anfordern Verfügbar EEL — Ende der Entgeltersatzleistung anfordern (Grund 42, DBEE) mandant:meldungen

Ausschließlich auf Anwendervorgabe (Pflichtenheft S. 217): die Kasse meldet das Ende der Leistung in der Regel proaktiv (Grund 62); die Anforderung ist für Fälle ohne zeitnahe Rückmeldung gedacht. Body: eel_ab (Beginn der Entgeltersatzleistung, JJJJ-MM-TT), optional fehlzeit_id. Entwurf, Freigabe erforderlich. Die Antwort der Kasse (62) wird im Posteingang abgelegt und der Anforderung zugeordnet (beantwortet_durch); ENDEGRUND 01 erzeugt den Hinweis „Fehlzeit korrigieren/stornieren".

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

`eel_ab`*	string
`fehlzeit_id`	integer

Antwort

201 Entwurf angelegt (meldung_id, Grund 42)

422 Hürde (z. B. keine Annahmestelle, kein Ansprechpartner) oder eel_ab fehlt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/eel/ende-anfordern" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/fehlzeiten/{id}/vorerkrankungsanfrage Verfügbar EEL — Vorerkrankungsanfrage (Grund 41, DBVO) zu einer Krankheits-Fehlzeit anstoßen mandant:meldungen

Dieselbe Regel wie der automatische Auslöser (Fehlzeit-POST, Betriebsautomatik): nur gesetzlich Versicherte (nicht PGR 109/110/190), aktuelle AU attestiert UND mindestens eine frühere attestierte AU, zwischen Beginn der aktuellen und Ende der letzten AU höchstens 6 Monate, die 6-Monats-Kette zusammen mit der aktuellen AU ≥ 30 Tage (offenes Ende = heute + 7). Nur attestierte Zeiten gehen in den DBVO (Pflichtenheft S. 226/227, VB EEL 3.12). Entwurf.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Anfrage existiert schon (vorhanden)

201 Entwurf angelegt (meldung_id, pruefung)

422 Nicht zulässig (Grund im detail) oder Hürde

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/fehlzeiten/<id>/vorerkrankungsanfrage" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/eel/faelle Verfügbar EEL-Fälle mit Zustand (laufend/beendet, offene Anforderungen, Rückmeldungen) mandant:meldungen

Ein Fall = auslösende Fehlzeit + unsere Meldungen (Bescheinigung, 41/42, 51, 99) + die Rückmeldungen der Kasse (61/62/71). laufend steuert den Wechsel der meldenden Stelle: Grund 99 entsteht nur in laufenden Fällen (Pflichtenheft S. 206), unbeantwortete 41/42 werden erneut abgesetzt (S. 205) — beides als Entwürfe, ausgelöst durch PATCH /mandanten/{id} mit geänderter Betriebsnummer (eel_wechsel_meldende_stelle in der Antwort).

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 faelle[]

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/eel/faelle" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/aag/rueckmeldungen Verfügbar AAG — Rückmeldungen der Umlagekassen (DSRA/DBRA) auf Erstattungsanträge mandant:meldungen

Was die Umlagekasse zu einem U1-/U2-Erstattungsantrag zurückgemeldet hat: beantragt_cent und festgestellt_cent nebeneinander, dazu abweichung_cent, kennzeichen_feststellung (1 vollständig · 2 teilweise · 3 nicht entsprochen) und grund_abweichung (00–32). Zugeordnet wird über die Datensatz-ID unseres DSER. Eingang: POST /eingang. ⚠️ Es wird nichts umgebucht — eine Kürzung ist eine Entscheidung der Kasse.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 rueckmeldungen[]

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/aag/rueckmeldungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/eel/rueckmeldungen Verfügbar EEL — Rückmeldungen der Kasse (61/62/71 …), strukturiert gelesen mandant:meldungen

Was der Posteingangs-Verteiler aus dem DSLW der Kasse gelesen hat (DBHE Höhe der Leistung, DBEE Ende/Verlängerung, DBVO anrechenbare Vorerkrankungen, DBID) und was daraus folgte (verarbeitet: Hinweise, DBBE-Entwurf nach § 23c). Eingang: POST /eingang bzw. der Abruf vom Kommunikationsserver.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 rueckmeldungen[]

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/eel/rueckmeldungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/gesonderte-meldung Verfügbar Gesonderte Meldung (GD 57, § 194 SGB VI) auf Anforderung erzeugen mandant:meldungen

Body: zeitraum_von, zeitraum_bis (JJJJ-MM-TT, ein Kalenderjahr), anlass (rentenantrag | auskunftsersuchen).

⚠️ Nachrangig: eine Entgeltmeldung aus einem anderen Tatbestand (GD 30–49, 51–53, 70–72) geht vor — nur die Jahresmeldung tritt zurück. ⚠️ Fällig mit der Abrechnung des letzten Monats des Zeitraums: ist er noch nicht abgerechnet, wird die Anforderung im Posteingang vorgemerkt und beim Festschreiben erzeugt (vorgemerkt in der Antwort). Die Folgemeldung beginnt am Anschlusstag; eine später entstehende vorrangige Meldung storniert die Gesonderte Meldung und meldet den Rest erneut.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

`zeitraum_von`*	string
`zeitraum_bis`*	string
`anlass`*	string	Werte: `rentenantragauskunftsersuchen`

Antwort

200 Vorgemerkt (vorgemerkt = Posteingangs-ID) oder Hürden (huerden).

201 Entwurf angelegt (meldung_id).

404 Mitarbeiter unbekannt.

422 Zeitraum oder Anlass unzulässig.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/gesonderte-meldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/arbeitsbescheinigung Verfügbar Arbeitsbescheinigung erzeugen (§§ 312 f. SGB III, BEA) mandant:meldungen

Erzeugt die elektronische Arbeitsbescheinigung als Entwurf.

🔴 Auf Verlangen, nicht beim Austritt. verlangt_von (bundesagentur | beschaeftigter) ist Pflicht — es gibt bewusst keinen automatischen Auslöser. Wer die Bescheinigung an den Austritt hängt, meldet der Bundesagentur Daten zu Menschen, die nie Arbeitslosengeld beantragen.

⚠️ Der Rückblick ist nicht pauschal zwölf Monate. Liegen in zwölf Monaten weniger als 150 Kalendertage mit Entgeltzahlung, sind 24 Monate zu bescheinigen — die Antwort nennt den ermittelten Umfang samt Begründung unter umfang.

⚠️ Testamentsprinzip: es wird nicht storniert. Eine spätere Bescheinigung ersetzt die frühere; es gilt die mit dem jüngsten Erstellungsdatum.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Entwurf erzeugt — oder Hürden benannt (meldung_id: null).

422 verlangt_von fehlt oder ist unzulässig

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/arbeitsbescheinigung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/nebeneinkommensbescheinigung Verfügbar Nebeneinkommensbescheinigung erzeugen (§ 313 SGB III, BEA · DSNE) mandant:meldungen

Erzeugt die Nebeneinkommensbescheinigung für einen Kalendermonat (monat, YYYY-MM) als Entwurf — wer Arbeitslosengeld bezieht und nebenher arbeitet.

🔴 konstant ist eine Pflichtangabe ohne Vorbelegung (true/false): bleiben Entgelt und wöchentliche Arbeitszeit künftig gleich? Die Bundesagentur rechnet mit dem gemeldeten Wert weiter, bis eine neue Meldung eingeht — eine geratene Antwort erzeugt Rückforderungen. Fehlt sie, entsteht kein Datensatz, sondern eine Hürde.

⚠️ verlangt_von (bundesagentur | beschaeftigter) ist Pflicht — auf Verlangen, nie automatisch. ⚠️ Bei Personengruppe 109 wird kein SV-Brutto übermittelt (Grundstellung). ⚠️ Eine Einmalzahlung braucht einmalzahlung_netto_cent und den Zeitraum einmalzahlung_von/einmalzahlung_bis — das Prüfprogramm verlangt ihn zu jeder Einmalzahlung.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Entwurf (DSNE) erzeugt — oder Hürden benannt (meldung_id: null).

422 verlangt_von oder monat fehlt oder ist unzulässig

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/nebeneinkommensbescheinigung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{id}/arbeitsbescheinigung-eu Verfügbar EU-Arbeitsbescheinigung erzeugen (§ 312a SGB III, BEA · DSEU) mandant:meldungen

Erzeugt die Arbeitsbescheinigung für Zwecke des zwischen- und überstaatlichen Rechts (Grundlage des PD U1) als Entwurf.

⚠️ Der Bescheinigungszeitraum steht im Anschreiben der Bundesagentur — jedes Land braucht andere Zeiträume. bescheinigung_von (YYYY-MM) übernimmt ihn; ohne Angabe gelten die 24 Monate des Pflichtenhefts. Lücken im Rückblick sind eine Hürde, kein stilles Kürzen (luecken_akzeptiert: true macht sie zum Hinweis).

⚠️ Arbeitszeitänderungen brauchen den Grund (arbeitszeitaenderungen: [{ab, grund 01–12, wochenstunden}]); bei 01/02/05/06 sind 60 statt 24 Monate zu bescheinigen. Fehlzeiten, die sich nicht eindeutig auf die BA-Schlüssel der Anlage 5 abbilden lassen, nennt die Antwort als Hürde — fehlzeiten_ba: {fehlzeitId: art} legt sie fest. Eine Kündigung braucht beendigung.kuendigung_am und kuendigungsfrist_wochen; nur ein befristetes Arbeitsverhältnis mit Fristablauf kommt ohne Datum aus.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Entwurf (DSEU) erzeugt — oder Hürden benannt (meldung_id: null).

422 verlangt_von fehlt oder ist unzulässig

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<id>/arbeitsbescheinigung-eu" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/eubp Verfügbar euBP-Gesamtlieferung vorbereiten (§ 28p Abs. 6a SGB IV) mandant:meldungen

Erzeugt die Gesamtlieferung für einen Prüftermin der elektronisch unterstützten Betriebsprüfung — die amtlichen Datensätze nach Anlage 1 der Grundsätze euBP (V3.5.0: VOSZ · DSKO · DSST · DSZE · DSFB · DSAG · DSBN · DSAN/DSLA · NCSZ, mit den Bausteinen DBFZ/DBKG/DBSC/DBRB) — als Entwurf. Übermittelt wird nichts. Geprüft wird mit der Satzprüfung aus dem euBP-Datentool der DRV (npm run kernpruefung:eubp).

Body: entweder pruefzeitraum_von/pruefzeitraum_bis (YYYY-MM) aus der Prüfanmeldung — oder nur prueftermin (YYYY-MM-DD); dann wird der Übermittlungszeitraum mit fünf Kalenderjahren vor dem Prüftermin vorbelegt. Optional liefertermin (spätester Liefertermin), uebermittlung_von/uebermittlung_bis (der Anwender ändert den Zeitraum), vorgang_id (Neulieferung zu einem bestehenden Prüfvorgang) und anwenderangaben: pruefbescheid_elektronisch (Pflicht, ohne Vorbelegung), gddue (1 Prüftermin · 2 Programmwechsel · 3 Dienstleisterwechsel — Pflicht, ohne Vorbelegung), anrede_ap (M|W für den Kommunikationssatz), zugangseroeffnung.email_ep (DSZE, Pflicht bei elektronischem Prüfbescheid), fragebogen (DSFB, optional: kennzlstap, kennzwg, kennzfm), personen_angaben (je Mitarbeiter-ID z. B. { rentenbezieher: true }). Die Angaben werden im Prüfvorgang gespeichert (vorgang_id in der Antwort).

⚠️ Der Übermittlungszeitraum ist größer als der Prüfzeitraum. Dazu gehören das Abrechnungsjahr vor dem Prüfzeitraum und das laufende Jahr bis zum letzten abgerechneten Monat. Die Antwort nennt ihn unter uebermittlungszeitraum.

⚠️ Ein Neuversand setzt eine Stornierung voraus — eine eigene Sendung über POST /eubp/{meldungId}/storno; sonst lägen zwei Lieferungen zum selben Prüftermin vor. Nach der Statusmeldung E90 ist die Prüfung abgeschlossen und keine Lieferung mehr möglich.

⚠️ Kein Mussfeld bekommt einen Ersatzwert: fehlt z. B. der Rentenbezug einer Person (DSAN KENNZRBZ), entsteht keine Lieferung, sondern eine Hürde, die die Person und den Weg nennt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Entwurf erzeugt — oder Hürden benannt (dann meldung_id: null); immer mit vorgang_id.

422 Prüfzeitraum/Prüftermin unplausibel

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/eubp" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/eubp/vorbelegung Verfügbar Vorbelegung des euBP-Übermittlungszeitraums ansehen mandant:meldungen

Query: prueftermin (YYYY-MM-DD) oder pruefzeitraum_von/pruefzeitraum_bis (YYYY-MM). Liefert den Zeitraum, der bei POST /eubp gelten würde — fünf Kalenderjahre vor dem Prüftermin bzw. Prüfzeitraum + Jahr davor + laufendes Jahr bis zum letzten abgerechneten Monat —, dazu den ersten abgerechneten Monat (davor liegt nichts in Lohnfluss) und die Hinweise. Der Anwender darf den Zeitraum ändern (aenderbar: true).

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Zeitraum mit Begründung — oder zeitraum: null, wenn nichts abgerechnet ist.

422 weder Prüftermin noch Prüfzeitraum

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/eubp/vorbelegung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/eubp/{meldungId}/storno Verfügbar euBP-Gesamtlieferung stornieren (eigene Sendung) mandant:meldungen

Erzeugt die Stornosendung zu einer Gesamtlieferung — genau VOSZ · DSKO · DSST mit KENNZST = J · NCSZ, mit BBNRAS/BBNRMS/ZRVON/ZRBIS/GDDUE der stornierten Sendung (Grundsätze euBP 6.6, Anlage 5). Sie trägt keine Daten; erst danach ist zu diesem Prüftermin eine Neulieferung möglich (POST /eubp mit derselben vorgang_id).

⚠️ Nach der Statusmeldung E90 ist keine Stornierung mehr möglich; eine bereits stornierte Lieferung wird nicht ein zweites Mal storniert (422).

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`meldungId`*	integer · im Pfad

Antwort

201 Stornosendung als Entwurf angelegt (meldung_id, storno_von).

404 Lieferung nicht bei diesem Mandanten

422 bereits storniert, Prüfung abgeschlossen (E90) oder kein Lieferungssatz

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/eubp/<meldungId>/storno" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Lohnsteuer (ELSTER)

Lohnsteuer-Anmeldung, Lohnsteuerbescheinigung, ELStAM.

POST /v1/mandanten/{mandantId}/lsta/{zeitraum} Verfügbar Lohnsteuer-Anmeldung vorbereiten mandant:lohnlauf

Berechnet die BMF-Kennzahlen aus den Läufen des Zeitraums und legt den Entwurf ab. Übermittelt wird getrennt.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`zeitraum`*	string · im Pfad	Anmeldezeitraum — Monat `YYYY-MM`, Quartal `YYYY-Qn` oder Jahr `YYYY`.

Antwort

201 Entwurf mit Kennzahlen und Hinweisen.

`id`	integer
`zeitraum`	string
`kennzahlen`	object
`hinweise`	array<string>	Fehlende oder unplausible Stammdaten — blockieren den Entwurf nicht, wohl aber die Übermittlung.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 LSTA — der Entwurf ist fachlich nicht möglich.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lsta/<zeitraum>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/lsta/{zeitraum} Verfügbar LStA-Entwürfe des Zeitraums lesen mandant:lohnlauf

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`zeitraum`*	string · im Pfad	Anmeldezeitraum — Monat `YYYY-MM`, Quartal `YYYY-Qn` oder Jahr `YYYY`.

Antwort

200 Entwürfe, jüngster zuerst.

meldungen array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lsta/<zeitraum>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/lsta/{zeitraum}/uebermitteln In Zertifizierung Lohnsteuer-Anmeldung an ELSTER übermitteln mandant:lohnlauf

Übermittelt den jüngsten Entwurf des Zeitraums über ERiC. Ohne verfügbare ERiC-Bibliothek antwortet der Endpunkt mit 501 ERIC_FEHLT.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`zeitraum`*	string · im Pfad

Antwort

200 Übermittelt — mit Transferticket.

`transferticket`	string?
`returncode`	integer

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 Kein Entwurf für den Zeitraum.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 LSTA — ERiC hat den Datensatz abgewiesen.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

423 KEINE_FREIGABE / SANDBOX_KEIN_VERSAND — Betriebs-Riegel oder Freigabe geschlossen bzw. Sandbox-Mandant; es wurde nichts gesendet.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

501 ERIC_FEHLT — auf dieser Instanz ist ERiC nicht eingerichtet.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lsta/<zeitraum>/uebermitteln" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/lstb/{vz} Verfügbar Lohnsteuerbescheinigungen des Jahres erzeugen mandant:lohnlauf

Bildet je Mitarbeiter die Jahreswerte aus den Läufen des VZ und legt die Bescheinigung als Entwurf ab. Ohne mitarbeiter_id für alle.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`vz`*	string · im Pfad	Veranlagungszeitraum (Kalenderjahr).

Anfrage application/json

mitarbeiter_id integer Nur für diesen Mitarbeiter.

Antwort

201 Entwürfe angelegt.

ergebnisse array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 LSTB — z. B. keine Läufe im Veranlagungszeitraum.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lstb/<vz>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/lstb/{vz} Verfügbar LStB-Entwürfe des Jahres lesen mandant:lohnlauf

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`vz`*	string · im Pfad	Veranlagungszeitraum (Kalenderjahr).

Antwort

200 Entwürfe je Mitarbeiter.

meldungen array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/lstb/<vz>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{mitarbeiterId}/elstam/{anlass} Verfügbar ELStAM-Entwurf je Mitarbeiter mandant:lohnlauf

Legt An-, Ab- oder Ummeldung beim Finanzamt als Entwurf ab. Die Daten kommen aus Ein-/Austritt des Mitarbeiters, lassen sich aber überschreiben.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`mitarbeiterId`*	integer · im Pfad
`anlass`*	string · im Pfad

Anfrage application/json

`referenzdatum`	string
`beschaeftigungsbeginn`	string
`abmeldedatum`	string
`hauptarbeitgeber`	boolean

Antwort

201 Entwurf angelegt.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 ELSTAM — z. B. fehlende Steuer-IdNr.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<mitarbeiterId>/elstam/<anlass>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/mitarbeiter/{mitarbeiterId}/elstam/{anlass}/uebermitteln In Zertifizierung ELStAM-Meldung übermitteln mandant:lohnlauf

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`mitarbeiterId`*	integer · im Pfad
`anlass`*	string · im Pfad

Antwort

200 Übermittelt.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 Kein Entwurf für Mitarbeiter und Anlass.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 ELSTAM — ERiC hat abgewiesen.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

423 KEINE_FREIGABE / SANDBOX_KEIN_VERSAND — Betriebs-Riegel oder Freigabe geschlossen bzw. Sandbox-Mandant; es wurde nichts gesendet.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

501 ERIC_FEHLT — ERiC ist auf dieser Instanz nicht eingerichtet.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/mitarbeiter/<mitarbeiterId>/elstam/<anlass>/uebermitteln" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/elstam/anmeldung Verfügbar ELStAM-Meldung auf Mandantenebene mandant:meldungen

Wie der mitarbeiterbezogene Entwurf, aber mit mitarbeiter_id im Body — praktisch für Massenanlage.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`mitarbeiter_id`*	integer
`anlass`	string	Werte: `anmeldungabmeldungummeldung`
`referenzdatum`	string
`hauptarbeitgeber`	boolean

Antwort

201 Entwurf angelegt, inklusive Datensatz.

`id`	integer
`verfahren`	string
`anlass`	string
`status`	string
`datensatz`	object

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 Mitarbeiter unbekannt.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 mitarbeiter_id fehlt oder der Datensatz ist unvollständig.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/elstam/anmeldung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/elstam/aenderungen Verfügbar Eingehende ELStAM-Änderungsliste verarbeiten mandant:meldungen

Das „Abo": geänderte Steuerabzugsmerkmale vom Finanzamt einspielen. Je Änderung entsteht eine neue Mitarbeiter-Zeitscheibe und ein Posteingang-Eintrag.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

aenderungen* array<object>

Antwort

200 Ergebnis je Änderung.

`verarbeitet`	integer
`ergebnis`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 aenderungen[] fehlt oder ist leer.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/elstam/aenderungen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Posteingang

Eingehende Rückläufe und Anforderungen an einem Ort. Ablage und Endpunkte sind gebaut und testbar; echte Post kommt mit dem freigeschalteten Empfangskanal.

POST /v1/eingang Verfügbar Eingegangene Meldedatei einspeisen partner:mandanten

Nimmt den Inhalt einer von einer Datenannahmestelle eingegangenen Meldedatei entgegen, erkennt die enthaltenen Datensätze, ordnet sie über die Betriebsnummer des Beschäftigungsbetriebes (BBNR-AG) einem Mandanten zu und legt sie im Posteingang ab. Wo ein Verfahren eine maschinelle Folge kennt (z. B. DSKK Meldegrund 06 → DSAK-Antwort), entsteht dabei ein Entwurf — gesendet wird nie automatisch.

Derselbe Satz wird nicht zweimal verarbeitet (Sperre über einen Hash des Rohsatzes). Nicht zuordenbare, unbekannte und fehlerhafte Sätze werden nicht verworfen, sondern in der Antwort benannt; der Aufrufer darf die Datei dann nicht löschen.

Sicherheitsgrenze: als Ziel kommen ausschließlich Mandanten des eigenen Partners in Frage.

Anfrage application/json · Pflicht

`roh`*	string	Inhalt der Meldedatei (ISO-8859-1
`quelle`	string	Woher die Datei kam

Antwort

200 Verarbeitet. Die Listen benennen, was NICHT durchlief.

`ok`	boolean
`gelesen`	integer	Nutzdatensätze ohne Umschlag (VOSZ/NCSZ/DSKO)
`doppelt`	integer	bereits früher verarbeitete Sätze
`verarbeitet`	array<object>
`nicht_zuordenbar`	array<object>
`unbekannt`	array<object>
`fehler`	array<object>

422 Validierung fehlgeschlagen

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/eingang" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/posteingang Verfügbar Posteingang auflisten mandant:meldungen

Eingehende Rückmeldungen, Anforderungen und ELStAM-Mitteilungen — die Datenbasis für eine Inbox. offen eignet sich als Badge-Zähler.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`status`	string · Query
`kategorie`	string · Query
`limit`	integer · Query

Antwort

200 Einträge und Zahl der offenen.

`offen`	integer
`eintraege`	array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/posteingang" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/posteingang/{id} Verfügbar Posteingang-Eintrag lesen mandant:meldungen

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Eintrag.

`id`	integer
`kategorie`	string
`status`	string
`betreff`	string
`eingang_am`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/posteingang/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/posteingang/{id} Verfügbar Status setzen mandant:meldungen

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Anfrage application/json · Pflicht

status* string Werte: neugelesenerledigt

Antwort

200 Gesetzt.

`id`	integer
`status`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Status ungültig — fehler.detail nennt die erlaubten Werte.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/posteingang/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Verwaltung

Benutzer und Rollen, Protokoll-Einsicht und API-Schlüssel. Schlüssel werden hier erzeugt und abgeschaltet — der Geheimwert ist nur im Moment der Erzeugung sichtbar.

GET /v1/mandanten/{mandantId}/protokoll Verfügbar Protokoll (Audit-Log) des Mandanten mandant:verwaltung

Wer hat wann was geändert. Für die ITSG-Systemuntersuchung ist die Nachvollziehbarkeit ein eigener Prüfpunkt; die Daten lagen seit jeher in lohn_audit_log, einsehen konnte sie niemand außer über die Datenbank.

⚠️ Die Einträge enthalten personenbezogene Daten — das ist ihr Zweck. Sie bleiben deshalb hinter mandant:verwaltung und liefern nur den eigenen Mandanten.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`tabelle`	string · Query	z. B. `lohn_mitarbeiter`
`zeilen_id`	integer · Query
`aktion`	string · Query
`von`	string · Query
`bis`	string · Query
`limit`	integer · Query

Antwort

200 Einträge, neueste zuerst.

eintraege array<object>

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/protokoll" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/protokoll.csv Verfügbar Protokoll als CSV (für die Betriebsprüfung) mandant:verwaltung

Ein Prüfer bekommt keinen Datenbankzugang und liest kein JSON am Bildschirm. Er will eine Datei, die er ablegen und in seiner eigenen Software öffnen kann.

Trennzeichen Semikolon, Kodierung UTF-8 mit BOM — so öffnet Excel in einer deutschen Windows-Umgebung ohne Import-Dialog und ohne zerschossene Umlaute.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`tabelle`	string · Query
`von`	string · Query
`bis`	string · Query

Antwort

200 CSV-Datei.

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/protokoll.csv" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/benutzer/{id}/einladung Verfügbar Einladung erzeugen (Passwort setzen lassen) mandant:verwaltung

Der Weg, auf dem ein neuer Benutzer zu seinem Passwort kommt.

⚠️ POST /benutzer legt einen Benutzer mit leerem Passwort-Hash an und verwies auf einen „Zurücksetzen-Weg", den es nicht gab — ein so angelegter Benutzer konnte sich nie anmelden.

Das Klartext-Token wird genau einmal zurückgegeben; in der Datenbank steht nur sein Hash. Der Administrator gibt es auf einem anderen Weg weiter — eine Mail-Strecke gibt es noch nicht. Eingelöst wird es über POST /portal/passwort-setzen (ohne Anmeldung).

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

201 Einladung erzeugt.

`benutzer_id`	integer
`email`	string
`token`	string	Nur EINMAL sichtbar.
`gueltig_bis_minuten`	integer
`hinweis`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 Das Konto ist deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/benutzer/<id>/einladung" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/api-schluessel Verfügbar API-Schlüssel des Mandanten auflisten mandant:verwaltung

Listet die Schlüssel ohne ihren Geheimwert — der ist nur im Moment der Erzeugung sichtbar. Zurück kommt, was man zum Wiedererkennen und Abschalten braucht: Bezeichnung, Berechtigungen, ob er aktiv ist und wann er zuletzt benutzt wurde.

Die Antwort führt zusätzlich den Katalog der vergebbaren Berechtigungen mit (verfuegbare_scopes). Eine Oberfläche müsste ihn sonst selbst pflegen — und wäre die nächste Liste, die von den Routen abweicht.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Schlüssel und vergebbare Berechtigungen.

`schluessel`	array<object>
`verfuegbare_scopes`	array<object>

{
  "schluessel": [
    {
      "id": 7,
      "label": "Zeiterfassung Produktiv",
      "scopes": [
        "mandant:stammdaten",
        "mandant:lohnlauf"
      ],
      "aktiv": 1,
      "created_at": "2026-08-09T10:12:00Z",
      "zuletzt_benutzt_am": "2026-08-09T11:40:00Z"
    }
  ],
  "verfuegbare_scopes": [
    {
      "scope": "mandant:lohnlauf",
      "titel": "Abrechnung",
      "zweck": "Bewegungsdaten schreiben, Probelauf rechnen, festschreiben, Korrekturlauf anstoßen."
    }
  ]
}

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/api-schluessel" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/api-schluessel Verfügbar API-Schlüssel erzeugen mandant:verwaltung

⚠️ Der Schlüssel wird genau einmal zurückgegeben. Gespeichert wird nur sein SHA-256-Hash; wir können ihn nicht erneut anzeigen, nur ersetzen. Dieselbe Regel wie bei der Benutzer-Einladung — wer die Datenbank liest, soll keine fremde Anbindung übernehmen können.

Ein Mandant kann sich keinen Partner-Scope geben. partner:mandanten sieht alle Mandanten eines Partners; selbst ausgestellt wäre er ein Weg an fremde Gehaltsdaten. Der Scope existiert, ist hier aber verboten — die Antwort sagt das mit 403, nicht mit „unbekannt".

Gehört der Mandant zur Sandbox, trägt der Schlüssel zwingend das Präfix lk_test_ — die Umgebung folgt dem Mandanten, sie ist keine Eingabe des Aufrufers. Die Kennzeichnung folgt dem Mandanten, nicht dem Wunsch des Aufrufers.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Anfrage application/json · Pflicht

`label`*	string	Wofür der Schlüssel da ist — er taucht im Protokoll als Akteur auf.
`scopes`*	array<string>	Mindestens einer. Nur `mandant:*` ist selbst vergebbar.
`test`	boolean	Erzwingt einen Test-Schlüssel. Bei einem Testmandanten ohnehin gesetzt.

{
  "label": "Zeiterfassung Produktiv",
  "scopes": [
    "mandant:stammdaten",
    "mandant:lohnlauf"
  ]
}

Antwort

201 Angelegt — mit dem einmalig sichtbaren Schlüssel.

`id`	integer
`label`	string
`scopes`	array<string>
`test`	boolean
`schluessel`	string	⚠️ Nur EINMAL sichtbar.
`hinweis`	string

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 Scope fehlt — oder ein Partner-Scope wurde selbst angefordert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

422 Label fehlt, keine Scopes, oder ein Scope ist unbekannt.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/api-schluessel" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "label": "Zeiterfassung Produktiv",
       "scopes": [
         "mandant:stammdaten",
         "mandant:lohnlauf"
       ]
     }'

DELETE /v1/mandanten/{mandantId}/api-schluessel/{id} Verfügbar API-Schlüssel abschalten mandant:verwaltung

Setzt den Schlüssel auf inaktiv; die Zeile bleibt bestehen. Bewusst kein echtes Löschen — Protokoll und zuletzt_benutzt_am sollen nachvollziehbar bleiben, gerade wenn ein Schlüssel wegen eines Verdachts abgeschaltet wird.

⚠️ Ein Schlüssel kann sich nicht selbst abschalten (409). Sonst nimmt sich ein Integrator mit einem Aufruf den Zugang, mit dem er ihn zurückholen könnte — dieselbe Falle wie beim letzten Administrator.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Abgeschaltet (oder war es schon).

`id`	integer
`aktiv`	boolean
`unveraendert`	boolean

401 AUTH — Key fehlt, ist unbekannt oder deaktiviert.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

403 AUTH — Scope fehlt, oder der Key gehört zu einem anderen Mandanten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

404 NICHT_GEFUNDEN — die Ressource gibt es nicht (oder nicht für diesen Mandanten).

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

409 Der eigene Schlüssel kann sich nicht selbst abschalten.

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Aufruf

curl -X DELETE "https://api.lohnfluss.de/v1/mandanten/<mandantId>/api-schluessel/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/uv/hoechst-jav Verfügbar Höchstjahresarbeitsverdienst je UV-Träger und Jahr (Liste) partner:mandanten

Partnerweiter Stammdatensatz (lohn_uv_hoechst_jav). Ohne Wert deckelt der elektronische Lohnnachweis das UV-Entgelt nicht und nennt das im Hinweis.

Parameter

jahr integer · Query

Antwort

200 Werte

werte array<object>

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/uv/hoechst-jav" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PUT /v1/uv/hoechst-jav Verfügbar Höchstjahresarbeitsverdienst je UV-Träger und Jahr setzen partner:mandanten

Die Schreibstelle für den Höchst-JAV (bis 22.08.2026 gab es keine — die Tabelle wurde gelesen, nie gefüllt). Wert aus der Satzung des Trägers oder dem Stammdatendienst; quelle ist Pflicht, geschätzt wird nicht. Je Träger und Jahr genau ein Wert (erneutes Setzen ersetzt).

Anfrage application/json · Pflicht

`bbnr_uv`*	string	achtstellige Betriebsnummer des UV-Trägers
`jahr`*	integer
`betrag_cent`*	integer
`quelle`*	string	Werte: `stammdatendienstsatzung_manuell`

Antwort

200 Gesetzt

422 Ungültige Eingabe

`fehler`	object
`fehler.code`	string	Maschinenlesbare Kategorie.
`fehler.titel`	string	Kurzer Klartext.
`fehler.detail`	string?	Ergänzung — oft das betroffene Feld oder die erlaubten Werte.

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PUT "https://api.lohnfluss.de/v1/uv/hoechst-jav" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/zuruecksetzen Verfügbar Sandbox-Mandanten auf Anfang stellen mandant:verwaltung

Nur in der Sandbox. Auf einem produktiven Mandanten antwortet der Endpunkt 403 NUR_SANDBOX — ein Zurücksetzen würde dort festgeschriebene Entgeltabrechnungen löschen, für die eine Aufbewahrungspflicht besteht.

Gelöscht werden die beweglichen Daten: Läufe, Abrechnungen, Meldungen, Dokumente, Bewegungsdaten, Posteingang, Webhook-Zustellungen. Es bleiben die Stammdaten — Mandant, Mitarbeiter, Zeitscheiben, Bankverbindung, Fehlzeiten, Schlüssel. Ein Vollabriss würde nach jedem Versuch ein neues Seeding erzwingen; das wäre keine Erleichterung, sondern eine zweite Hürde.

Die Antwort nennt je Tabelle die Anzahl gelöschter Zeilen und unter dateien, wie viele abgelegte Dokumente mitgelöscht wurden. Erscheint unbekannte_tabellen, ist eine Fachtabelle hinzugekommen, die der Reset noch nicht kennt — dann ist der Mandant nicht vollständig zurückgesetzt.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Zurückgesetzt

403 Kein Sandbox-Mandant (NUR_SANDBOX)

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/zuruecksetzen" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

GET /v1/mandanten/{mandantId}/benutzer Verfügbar Benutzer des Mandanten mandant:verwaltung

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

200 Liste

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/mandanten/<mandantId>/benutzer" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

POST /v1/mandanten/{mandantId}/benutzer Verfügbar Benutzer anlegen mandant:verwaltung

Kein Passwort über die API. Es wird weder entgegengenommen noch zurückgegeben — der Benutzer setzt es selbst über den Zurücksetzen-Weg des Portals. Ein API-Feld dafür wäre ein Passwort im Anfrage-Protokoll.

Parameter

mandantId* integer · im Pfad Id des Arbeitgebers.

Antwort

201 Angelegt

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X POST "https://api.lohnfluss.de/v1/mandanten/<mandantId>/benutzer" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

PATCH /v1/mandanten/{mandantId}/benutzer/{id} Verfügbar Benutzer ändern (Name, Rolle, aktiv) mandant:verwaltung

Der letzte aktive Administrator kann weder herabgestuft noch deaktiviert werden (409). Ohne diesen Riegel kann ein Mandant sich die Verwaltung seines eigenen Zugangs nehmen — und niemand außer uns kommt wieder hinein.

Parameter

`mandantId`*	integer · im Pfad	Id des Arbeitgebers.
`id`*	integer · im Pfad

Antwort

200 Geändert

Die Form dieser Antwort ist in der Spec noch nicht ausgeschrieben — sie kommt mit dem nächsten Durchgang. Bis dahin gilt der Endpunkt als vorhanden, aber nicht als beschrieben.

Aufruf

curl -X PATCH "https://api.lohnfluss.de/v1/mandanten/<mandantId>/benutzer/<id>" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Service

Programmstand, Verfahrensversionen und Testkennung — was in jeder Meldung mitgeht.

GET /v1/programmstand Verfügbar Programmstand, Identifier und Verfahrensversionen

Für die ITSG-Systemuntersuchung und für jeden, der wissen will, womit gerechnet wurde.

⚠️ Die Prod-/Mod-ID steht in jeder Meldung. Solange die ITSG keine vergeben hat, geht eine erkennbare Platzhalter-Kennung hinaus (vergeben: false) — echte Übermittlungen sind damit nicht zulässig.

elster_echtbetrieb: false heißt: alles geht mit Testkennung hinaus. Das ist der Normalzustand bis zur Zulassung. Zugangsdaten oder Umgebungswerte stehen hier nicht.

Antwort

200 Der Stand.

`programm`	object
`programm.name`	string
`programm.version`	string
`programm.hersteller`	string
`identifier`	object
`identifier.prod_id`	string
`identifier.mod_id`	string
`identifier.vergeben`	boolean
`identifier.hinweis`	string?
`elster_echtbetrieb`	boolean
`verfahrensversionen`	array<object>
`gilt_jetzt`	object?

Aufruf

curl -X GET "https://api.lohnfluss.de/v1/programmstand" \
  -H "Authorization: Bearer $LOHNFLUSS_KEY"

Zeilen mit In Zertifizierung zeigen die geplante Form — sie sind gebaut, aber noch nicht scharf. Alles mit Verfügbar läuft heute in der Sandbox.

Webhooks

Auch sie stehen in der Spec, nicht in einer gepflegten Liste. HMAC-signiert, mit Wiederholung bei Zustellfehlern.

EVENT lohnlauf.probe_fertig Probelauf gerechnet

EVENT lohnlauf.festgeschrieben Lauf festgeschrieben

EVENT dokumente.bereit Dokumente eines Laufs erzeugt

Ereignisse zu Rückmeldungen der Sozialversicherung kommen mit dem freigeschalteten Empfangskanal dazu. Wie man anfängt — Auth, Idempotenz, ein Monat in fünf Aufrufen →

Sandbox-Zugang & vollständige Docs

Partner der Warteliste testen zuerst gegen die verfügbaren Endpunkte — und bekommen Versand und Rückmeldungen, sobald die Zertifizierung steht.

Zugang anfragen