Zum Inhalt springen

Entwickler-Einstieg

Vom Schlüssel zum fertigen Monat

Diese Seite bringt Sie einmal durch den ganzen Ablauf. Welche Endpunkte es gibt und wie weit jeder einzelne ist, steht in der API-Referenz — erzeugt aus derselben Spec, gegen die der Dienst geprüft wird.

Zur ITSG-Systemuntersuchung angemeldet   Sandbox auf Anfrage

Grundlagen

  • Basis-URL: https://api.lohnfluss.de/v1
  • Auth: Authorization: Bearer lk_live_…, Scopes je Zugriff
  • Beträge: immer Cent-Integer (kein Float)
  • Idempotenz: Idempotency-Key je schreibendem Aufruf
  • Fehler: einheitlich { fehler: { code, titel, detail } }
  • Mandantenmodell: ein Partner-Schlüssel, beliebig viele Mandanten

Erster Aufruf

curl https://api.lohnfluss.de/v1/mandanten \
  -H "Authorization: Bearer lk_live_…" \
  -H "Idempotency-Key: 8f3a…"

Antwortet mit den Mandanten Ihres Partner-Schlüssels. Ein Mandanten-Schlüssel sieht nur sich selbst — dieselbe Route, engerer Ausschnitt.

Ein vollständiger Monat — fünf Aufrufe

Mehr braucht eine Abrechnung nicht. Alles dazwischen — Lohnsteuer nach amtlichem Programmablaufplan, Beiträge, Umlagen, Pfändung, betriebliche Altersversorgung — passiert im Dienst.

  1. 1

    Bewegungsdaten melden

    PUT /mandanten/42/bewegungen/2026-07

    Stunden, Zuschläge, Einmalzahlungen des Monats. Ein Aufruf für den ganzen Betrieb — was Sie nicht schicken, bleibt beim Stammdatenwert.

  2. 2

    Probelauf rechnen

    POST /mandanten/42/lohnlauf/2026-07/probelauf

    Rechnet vollständig, schreibt nichts fest. Sie bekommen Brutto, Abzüge, Netto und Arbeitgeberkosten je Mitarbeiter zurück und können beliebig oft wiederholen.

  3. 3

    Festschreiben

    POST /mandanten/42/lohnlauf/2026-07/festschreiben

    Ab hier ist der Monat unveränderlich. Korrekturen laufen danach als eigener Korrekturlauf — so, wie es die Aufbewahrungspflichten verlangen.

  4. 4

    Dokumente abholen

    GET /dokumente/9981

    Entgeltabrechnungen (§ 108 GewO), DATEV-Buchungsstapel, SEPA-Zahldatei und Lohnjournal entstehen beim Festschreiben — Sie laden sie nur noch herunter.

  5. 5

    Meldungen erzeugen

    POST /mandanten/42/meldeanlaesse

    Lohnsteuer-Anmeldung und die SV-Datensätze fallen aus demselben Lauf. Ein Lebensereignis (Eintritt, Krankheit, Austritt) erzeugt alle dazu fälligen Meldungen auf einmal.

Wiederholen ohne Risiko

Ein Timeout heißt nicht, dass nichts passiert ist. Deshalb trägt jeder schreibende Aufruf einen Idempotency-Key: derselbe Schlüssel liefert 24 Stunden lang die ursprüngliche Antwort zurück, statt den Vorgang ein zweites Mal auszuführen. Ein doppelt festgeschriebener Lohnlauf kann so nicht entstehen.

Wenn etwas schiefgeht

{
  "fehler": {
    "code": "bewegungsdaten_unvollstaendig",
    "titel": "Monat kann nicht gerechnet werden",
    "detail": "Mitarbeiter 7: keine Stunden für 2026-07"
  }
}

Und dann?

  • Webhooks melden fertige Läufe und Dokumente zurück, HMAC-signiert: lohnlauf.probe_fertig, lohnlauf.festgeschrieben, dokumente.bereit
  • 146 Endpunkte mit ehrlichem Baustand in der Referenz
  • Die Spec selbst als OpenAPI 3.1 (JSON) — für Postman, Insomnia oder einen generierten Client
  • Das Portal als klickbare Vorschau, wenn Ihre Kunden statt der API eine Oberfläche brauchen

Sandbox-Zugang anfragen

Partner der Warteliste bekommen zuerst einen Test-Schlüssel gegen die verfügbaren Endpunkte.

Zugang anfragen Baustand ansehen