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. 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: was heute geht und was nicht

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.

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 Gesundheitsdaten: Atteste und der Begründungstext einer Rücknahme bleiben im Betrieb.
• 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.