Entwickler-API
Holen Sie Ihre Daten dort ab, wo Sie sie brauchen. Statt auf eine Schnittstelle für jedes Zielsystem zu warten, liest Ihr Systemhaus oder Ihr Automatisierungsdienst direkt aus FourTimes.
Mit der Berechtigung zur API-Schlüsselverwaltung erstellen Sie Schlüssel in den Organisation-Einstellungen unter „Verbindungen & API“. Sie wählen die erlaubten Bereiche und können Schlüssel dort widerrufen. Der vollständige Schlüssel wird nur bei der Erstellung angezeigt.
Die API ruft Zeiterfassungs- und Stammdaten ab. Sie kann diese Daten nicht anlegen oder ändern. Gehälter und Mitarbeiter-Stundensätze sind nicht enthalten.
Alle Endpunkte liefern JSON. Zeitstempel werden als ISO-8601-Zeichenketten in UTC ausgegeben. Optionale Angaben können null sein.
Authentifizierung
Jede Anfrage trägt den Schlüssel als Bearer-Token im Authorization-Header. Ein fehlender, ungültiger oder widerrufener Schlüssel führt zu 401. Fehlt dem Schlüssel der passende Bereich, antwortet die API mit 403.
curl -H "Authorization: Bearer ft_…" \
"https://<deployment>.convex.site/api/v1/time-entries?from=2026-05-01&to=2026-06-01"Ersetzen Sie die Beispieladresse durch die API-Basisadresse Ihrer FourTimes-Instanz und ft_… durch Ihren Schlüssel. Die API läuft auf der HTTP-Adresse des Backends, nicht auf der Web-App-Adresse. Die passende Basisadresse erhalten Sie beim Support.
Ein Aufruf von /api/v1 liefert die Bereiche des Schlüssels und die Endpunktliste zurück. Die Liste enthält alle Endpunkte, der Zugriff richtet sich nach den freigegebenen Bereichen.
Endpunkte
Alle Endpunkte verwenden GET. limit ist optional und beträgt standardmäßig 100, maximal 500. Schichtpläne sind in Version 1 nicht abrufbar.
| Endpunkt | Bereich | Parameter | Inhalt |
|---|---|---|---|
GET /api/v1/time-entries | time-entries | from, to, cursor, limit | Erfasste Zeiten mit Kunde, Projekt, Leistung und Abrechnungsstatus. |
GET /api/v1/attendance | attendance | from, to, limit | Anwesenheitssitzungen mit Stunden aus abgeschlossenen Zeitsegmenten. |
GET /api/v1/absences | absences | from, to, cursor, limit | Urlaub, Krankheit und weitere Abwesenheiten samt Status. |
GET /api/v1/customers | customers | cursor, limit | Kundenstammdaten inklusive Kundennummer. |
GET /api/v1/services | services | cursor, limit | Dienstleistungen mit Preis, Abrechnungsart und Steuersatz. |
GET /api/v1/projects | projects | cursor, limit | Projekte mit Kundenbezug und Stundenbudget. |
GET /api/v1/employees | employees | cursor, limit | Mitglieder mit Kontaktdaten, Rolle, Personalnummer und Wochenstunden. Keine Gehaltsdaten. |
Bei Listen mit cursor enthält die Antwort data, nextCursor und isDone. Übergeben Sie den nächsten Cursor bei unveränderten Filtern, bis isDone den Wert true hat. Bei gefilterten Abwesenheiten kann auch eine leere Seite einen weiteren Cursor haben.
Anwesenheiten liefern stattdessen data und truncated. Bei truncated: true ist die Antwort möglicherweise unvollständig. Erhöhen Sie das Limit bis maximal 500 oder fragen Sie kleinere Zeiträume ab. Einen Cursor gibt es für diesen Endpunkt derzeit nicht.
Für Zeiteinträge und Anwesenheiten sind from und to Pflicht. Ausgewählt werden Einträge, deren Beginn im Zeitraum liegt, einschließlich from und vor to. Bei Abwesenheiten sind beide Filter optional und erfassen zeitliche Überschneidungen. Verwenden Sie ISO-Daten, ISO-Zeitstempel mit Zeitzone oder Unix-Zeit in Millisekunden. Ein reines Datum wie 2026-05-01 steht für 00:00 Uhr UTC.