Zeitflex an andere Systeme anbinden: API-Schlüssel und Webhooks

Ein Kassensystem, das die Besetzung der Woche kennen will. Ein Lohnbüro, das erfahren soll, wenn der Monat abgeschlossen ist. Eine eigene Auswertung, die auf jede Stempelung reagiert. Dafür gibt es unter Einstellungen → API & Webhooks zwei Werkzeuge. Diese Seite sagt ehrlich, was jedes davon heute leistet — und wo die Schnittstelle bewusst aufhört.

Wer die Seite sieht und was sie kostet

API-Schlüssel und Webhooks gehören zum Plan Pro. Im Plan Kostenlos und im Plan Starter zeigt der Reiter statt der Einrichtung einen Hinweis auf das Abo. Während der Testphase gilt Pro, also auch diese Funktion. Bedienen dürfen sie nur Inhaber und Manager; Mitarbeitende sehen den Reiter nicht. Was die Pläne sonst unterscheidet, steht unter Pläne und Preise.

Webhooks: Zeitflex ruft Ihr System auf

Ein Webhook ist eine HTTPS-Adresse in Ihrem System, die Zeitflex aufruft, sobald etwas passiert ist. So richten Sie einen ein:

1. Öffnen Sie Einstellungen → API & Webhooks.
2. Tragen Sie unter Neue Webhook-URL (nur HTTPS) die Adresse Ihres Systems ein. Adressen ohne HTTPS nimmt Zeitflex nicht an.
3. Wählen Sie mindestens ein Ereignis und legen Sie den Endpoint an.
4. Kopieren Sie das Signatur-Secret (beginnt mit whsec_) sofort. Es wird genau einmal angezeigt und ist danach nicht mehr abrufbar. Ist es verloren, legen Sie den Endpoint neu an.

Später ändern Sie Adresse und Ereignisse, schalten den Endpoint vorübergehend aus oder löschen ihn. Jeder dieser Schritte steht im Protokoll des Betriebs.

Die fünf Ereignisse

Jede Zustellung ist ein JSON-Dokument mit id, type, createdAt, organizationId und dem Block data. Was nie darin steht: Namen, Löhne, Zuschläge, GPS-Koordinaten, der Begründungstext einer Rücknahme (er kann bei einer Krankmeldung Gesundheitsdaten enthalten) und Dateien. Die Arten „Krankheit“ und „Kind krank“ sind Gesundheitsdaten und kommen deshalb nur als ABWESENHEIT; Urlaub, Freizeitausgleich und die übrigen Arten stehen wie gewohnt da. Ihr System bekommt IDs und arbeitet mit dem, was es ohnehin über die Person weiß.

Wie Sie die Echtheit prüfen

Jede Zustellung trägt den Kopfzeilen-Eintrag Stempo-Signature: t=<Unix-Sekunden>,v1=<Hex>. Der Wert v1 ist ein HMAC-SHA256 über die Zeichenkette <t>.<roher JSON-Text> mit Ihrem Signatur-Secret als Schlüssel. Rechnen Sie ihn auf Ihrer Seite nach und verwerfen Sie alles, was nicht übereinstimmt. Der Name der Kopfzeile stammt aus der Zeit, als das Produkt Stempo hieß, und bleibt absichtlich so — eine Umbenennung würde jede bestehende Anbindung still brechen. Der User-Agent lautet entsprechend Stempo-Webhooks/1.0.

Was passiert, wenn Ihr System nicht antwortet

Zeitflex versucht die Zustellung dreimal: sofort, nach 0,5 Sekunden und nach 2 Sekunden. Jeder Versuch bricht nach 5 Sekunden ab. Antwortet Ihr System mit einem Fehler der Klasse 4xx (außer 408 und 429), gibt es keinen weiteren Versuch — die Anfrage gilt als dauerhaft abgewiesen. Danach hält Zeitflex den Fehlversuch im Protokoll fest, und das war es.

Ein nicht erreichbarer Endpoint verändert nichts an den Daten: Stempelung, Genehmigung oder Monatsabschluss sind gespeichert, bevor der erste Zustellversuch beginnt. Die Rückmeldung an die Person, die gerade stempelt oder genehmigt, kann sich allerdings um die Dauer der Zustellversuche verzögern — Zeitflex wartet die drei Versuche ab, bevor es antwortet.

API-Schlüssel: Zeiten eines Monats abholen

Unter Neuer API-Schlüssel vergeben Sie einen Namen (2 bis 60 Zeichen) und wählen Lesen, Schreiben oder beides. Der Schlüssel beginnt mit stpo_, wird einmal angezeigt und danach nie wieder — Zeitflex speichert nur einen SHA-256-Hash und zur Wiedererkennung das Präfix stpo_ samt den ersten acht Zeichen danach. Ein Schlüssel lässt sich jederzeit widerrufen; Erstellung und Widerruf stehen im Protokoll.

Ein Schlüssel mit dem Recht Lesen öffnet genau eine Adresse: die Zeiten Ihres Betriebs für einen Monat. Ihr Programm schickt den Schlüssel im Kopf Authorization mit, zum Beispiel so:

curl -H "Authorization: Bearer stpo_IhrSchluessel" \
  "https://app.zeitflex.de/api/v1/zeiten?monat=2026-09"

Die Antwort ist JSON. Je Person stehen darin die Kennung, der Name und die Personalnummer, darunter die Arbeitstage des Monats mit Brutto-, Pausen- und Nettominuten und die Einträge jedes Tages (Beginn, Ende, Arbeit oder Pause, Freigabestand, Erfassungsweg). Die Minuten rechnet dieselbe Stelle wie Stundenzettel und Monatsabschluss — gesetzliche Pause und Rundung Ihres Betriebs je Arbeitstag. Die Feldnamen sind deutsch. So sieht eine Antwort aus (gekürzt, eine Person mit einem Arbeitstag von 8 bis 16:30 Uhr ohne gestempelte Pause):

{
  "monat": "2026-09",
  "zeitzone": "Europe/Berlin",
  "rundung": "NONE",
  "personen": [
    {
      "kennung": "cmg1u4n8r0002qv8hx5y6z7w8",
      "name": "Anna Abel",
      "personalnummer": "17",
      "summe": { "bruttoMinuten": 510, "gestempeltePausenMinuten": 0,
                 "autoPausenAbzugMinuten": 30, "nettoMinuten": 480 },
      "tage": [
        {
          "datum": "2026-09-01",
          "bruttoMinuten": 510,
          "gestempeltePausenMinuten": 0,
          "autoPausenAbzugMinuten": 30,
          "nettoMinuten": 480,
          "eintraege": [
            { "kennung": "cmg2x7k1p0004qv8h1a2b3c4d", "typ": "ARBEIT",
              "beginn": "2026-09-01T06:00:00.000Z", "ende": "2026-09-01T14:30:00.000Z",
              "status": "GENEHMIGT", "quelle": "STEMPELUHR" }
          ]
        }
      ]
    }
  ]
}

Beginn und Ende stehen in UTC (das Z am Ende); datum ist der Tag in deutscher Zeit. Ein paar Regeln:

• Der Monat gilt in deutscher Zeit. Eine Schicht zählt zu dem Tag und Monat, an dem sie begann: Die Nachtschicht vom 30. auf den 1. steht im alten Monat.
• Geliefert werden abgeschlossene Zeiten in ihrer aktuellen Fassung. Eine laufende Stempelung erscheint, sobald ausgestempelt ist; eine korrigierte Zeit nur in der neuen Fassung; eine nicht anerkannte Zeit gar nicht.
• Ob eine Zeit abgerechnet wird, entscheidet weiterhin der Monatsabschluss. Den Freigabestand sehen Sie je Eintrag im Feld status: OFFEN, EINGEREICHT oder GENEHMIGT.
• Das Feld quelle nennt den Erfassungsweg: STEMPELUHR (Wand-Terminal), WEB (in der Web-App gestempelt), API (aus der Handy-App übermittelt oder im Browser ohne Netz gestempelt und nachgeliefert — nie über diese Schnittstelle), MANUELL (von Hand nachgetragen oder korrigiert) oder IMPORT (über den Import). Ihr Programm sollte auch Werte annehmen, die es noch nicht kennt — die Liste kann wachsen.
• Keine Lohnwerte: keine Stundensätze, kein Brutto in Euro, keine Zuschläge — und keine Standortdaten, Notizen oder Abwesenheiten.
• Höchstens 60 Abrufe je Stunde und Schlüssel, und höchstens 120 Abrufe in 10 Minuten von derselben IP-Adresse — zusammen für alle Schlüssel, die hinter dieser Adresse abrufen. Darüber antwortet Zeitflex mit 429 und nennt im Kopf Retry-After die Sekunden bis zum nächsten erlaubten Abruf.
• Abrufe stehen im Änderungsprotokoll, zusammengefasst: eine Zeile je Schlüssel, IP-Adresse und Monat in 24 Stunden. Ruft derselbe Schlüssel von einer anderen Adresse oder einen anderen Monat ab, steht das als eigene Zeile da. Unter Einstellungen → API & Webhooks sehen Sie beim Schlüssel, wann er zuletzt genutzt wurde — dieser Zeitpunkt gilt für jeden einzelnen Abruf.

Fehler kommen ebenfalls als JSON, mit einem Satz (fehler) und einer festen Kennung (code), nach der Ihr Programm sich richten kann. Der Satz ist deutsch; mit dem Kopf x-zeitflex-sprache: en kommt er englisch. Verzweigen Sie trotzdem nach code, nicht nach dem Satz — der Wortlaut kann sich ändern, die Kennung nicht:

Wer Daten in Zeitflex hineinbringen will, nutzt den Import unter Import (siehe Daten aus Excel oder einem anderen Programm importieren). Wer Daten herausholen will, nutzt den CSV-Export ab Plan Starter oder den DATEV-Export im Plan Pro (siehe DATEV-Export einrichten).

Was die Schnittstelle bewusst nicht tut

• Sie liefert keine Standortdaten. Ob Koordinaten beim Stempeln überhaupt gespeichert werden, entscheidet der Schalter unter Einstellungen → GPS & Datenschutz; ohne ihn werden keine Koordinaten abgelegt, gleich über welchen Weg gestempelt wird. Mehr unter Standort beim Stempeln.
• Sie sendet keine Atteste und keine Begründungstexte einer Rücknahme. Krankheit und Kind krank erscheinen nur als neutrale Art ABWESENHEIT — weil die übrigen Arten erkennbar bleiben, kann ein Empfänger daraus aber schließen, dass es keine von ihnen war.
• Sie sendet keine Lohn- oder Entgeltdaten. Die Lohnabrechnung selbst bereitet Zeitflex nur vor; sie läuft bei Ihrem Lohnbüro oder Ihrer Steuerkanzlei.
• Sie bietet keine Anbindung an Google- oder Outlook-Kalender per OAuth. Für den Dienstplan im Kalender gibt es das Abo je Person unter Einstellungen → Kalender.

Kommen Sie nicht weiter?

Fragen Sie den Support — oder lesen Sie weiter unter Pläne und Preise und Standort beim Stempeln.