API-Zugriff

mTime bietet eine REST-API für Entwicklerinnen und Entwickler, die das System anbinden oder automatisieren möchten. Diese Seite gibt einen Überblick – die OpenAPI-Spezifikation ist die maßgebliche Referenz für jeden Endpunkt, jedes Anfrage- und Antwortschema und jede erforderliche Berechtigung. Details zu einzelnen Endpunkten werden hier bewusst nicht wiederholt.

Basis-URL

Jede Umgebung hat ihre eigenen Daten und ihre eigenen Schlüssel – ein in der einen ausgestellter Schlüssel funktioniert nie in der anderen. GET /ping antwortet ohne Anmeldedaten – das ist die einfache Verbindungsprüfung.

Authentifizierung

Die API authentifiziert über API-Schlüssel, die einem Dienstbenutzer gehören.

1. Legen Sie unter Administration › Benutzer einen Dienstbenutzer an und geben Sie ihm einen API-Schlüssel. Kopieren Sie den Schlüssel sofort – er wird nur einmal angezeigt.

2. Senden Sie den Schlüssel bei jeder Anfrage als Bearer-Token:

   Authorization: Bearer mtime_ak_...

Um einen Schlüssel zu prüfen, rufen Sie GET /api/version auf: Der Endpunkt akzeptiert jede gültige Anmeldung und erfordert keine Berechtigung, er antwortet also mit 200 für einen funktionierenden Schlüssel und mit 401 für einen ungültigen, ohne dass eine Rolle dazwischenkommt.

OpenAPI-Spezifikation

Der vollständige Vertrag wird als OpenAPI 3.1 veröffentlicht:

• GET /api/openapi.yaml
• GET /api/openapi.json
• /api/docs stellt ihn im Browser dar – Produktion, Staging

In der App befindet sich die Referenz unter Ressourcen › API-Referenz, und für diesen Eintrag ist die Rolle Entwickler erforderlich. Inhaber haben sie bereits – die Rolle Inhaber enthält Entwickler –, und keine andere Rolle zeigt den Eintrag. Weisen Sie die Rolle Entwickler unter Administration › Benutzer der Person zu, die die Integration baut: Sie öffnet die Referenz und sonst nichts, Sie können sie also unbedenklich vergeben.

Sie beschreibt genau die Endpunkte, die ein API-Schlüssel erreichen darf. Ein Endpunkt, der fehlt, steht Integrationen nicht zur Verfügung, und ein Aufruf liefert 404 statt einer Erklärung – betrachten Sie die Spezifikation also als Liste dessen, was existiert.

Erzeugen Sie daraus einen typisierten Client, statt Anfragetypen von Hand zu schreiben. Jede Operation gibt außerdem die erforderliche Berechtigung an (x-required-permission), sodass Sie vorab sehen, welche Rolle Ihr Dienstbenutzer braucht.

API-Bereiche

Die Operationen in der Spezifikation sind nach Tag gruppiert; diese Gruppierung ist maßgeblich. Diese Bereiche deckt die API heute ab – jeder verlinkt in die Referenz:

Mit einem API-Schlüssel sind Importe nur in einem als Testarbeitsbereich gekennzeichneten Arbeitsbereich erlaubt, unabhängig von Modus oder Umfang. Nur die reinen Test-Batch-Jobs – etwa Seed timesheet pattern – dürfen ausgelöst werden. Importieren und Exportieren sind Berechtigungen des Inhabers, und ein Dienstbenutzer kann kein Inhaber sein – geben Sie ihm daher zusätzlich zu seiner anderen Rolle eine benutzerdefinierte Rolle mit den Berechtigungen für Import und Export.

Alles andere, was die App selbst verwendet – die übrige Verwaltung des Arbeitsbereichs, Benutzer und API-Schlüssel, Genehmigungen, Kioske, Abwesenheitsanträge, Ereignisse und Webhooks –, ist heute nicht Teil der API. Diese Endpunkte fehlen in der Spezifikation, und ein Schlüssel, der einen davon aufruft, erhält 404.

Berechtigungen

Jeder Endpunkt ist durch eine Berechtigung geschützt (zum Beispiel settings:create:*), die sich aus der Rolle des Dienstbenutzers ergibt. Liefert ein Aufruf 403, vergleichen Sie die in der Spezifikation angegebene Berechtigung der Operation mit der Rolle des Dienstbenutzers.

Das Domänenmodell

Einige Konzepte liegen dem größten Teil der API zugrunde:

• Anstellungsbedingungen (die „Vereinbarung“) enthalten die vertraglichen Einstellungen einer Anstellung: die Sollarbeitszeit, das Gleitzeitkonto, die Aktivität für Stundenlohn, den Standardgrund und den Genehmigungsmodus für Zeitnachweise. Feiertagskalender, Regelungen (Abwesenheit, Zuschlag, Arbeitszeit und Abrechnung) und Gründe sind nicht an Anstellungsbedingungen gebunden – jedes davon gibt einen Verfügbarkeitsbereich (availability_scope) an, der nach Arbeitsland, Organisationseinheit und Anstellungsbedingungen bestimmt, für welche Anstellungen es gilt.
• Aktivitäten sind die Kategorien, auf die Zeit erfasst wird. Jede hat einen Typ – work, timeoff, non-work oder allowance – und kann verschachtelt sein (eine untergeordnete Aktivität muss den Typ der übergeordneten teilen). Eine Aktivität kann ein Projekt und/oder benutzerdefinierte Dimensionen erfordern.
• Projekte sind Arbeits- bzw. Abrechnungseinheiten, auf die Zeiteinträge erfasst werden können, und können die Genehmigung einer Führungskraft erfordern.
• Dimensionen sind benutzerdefinierte Merkmale (zum Beispiel ein Fahrzeug oder ein Gerät) mit einer festgelegten Menge zulässiger Werte. Aktivitäten können sie erfordern, wodurch geprüft wird, was Benutzer auswählen dürfen.
• Zeitkonten enthalten Salden – Abwesenheiten in Tagen oder Gleitzeit in Stunden.

Zwei Ebenen der Zeit

Zeit wird auf zwei unabhängigen Ebenen erfasst:

• Anwesenheit – Ein-/Ausstempelungen. Ein Anwesenheitsintervall trägt einen Grund (und optional eine Notiz und eine Aktivität). Die Regel-Engine wertet Anwesenheitsintervalle aus.
• Einträge – Zeiteinträge im Raster, die Zeit einer Aktivität, einem Projekt und Dimensionswerten zuordnen.

Standardmäßig sind diese Ebenen unabhängig; eine Arbeitszeit-Einschränkung kann verlangen, dass sie übereinstimmen. Als Faustregel: wann und warum stehen in der Anwesenheit, was und wo in den Einträgen.

Die Regel-Engine

Zuschläge, Überstunden, Rufbereitschaftszuschläge und Gleitzeit werden durch Regelungen aus Plug-ins berechnet:

• Zuschlagsregelungen wandeln gearbeitete Zeit in einen zu vergütenden Betrag um – entweder über einen sollzeitbezogenen Wochenzähler (Mehrarbeit, Überstunden, Minusstunden, gearbeitete Stunden) oder über geordnete Regeln (Filter, die Intervalle auswählen, plus eine Berechnung, die daraus einen Betrag macht), optional durch bestimmte Gründe ausgelöst, und auf eine Zuschlagsaktivität als Ziel erfasst.
• Arbeitszeitregelungen enthalten Einschränkungen der Arbeitszeit und automatische Erfassungen (etwa einen Abzug für die Mittagspause). Das Gleitzeitkonto selbst wird in den Anstellungsbedingungen festgelegt.
• Abrechnungsregeln sind die Verarbeitungskette beim Periodenabschluss, die Zähler einem Zeitkonto gutschreibt und zwischen Auszahlung und Gleitzeit entscheidet.

Filter, Berechnungen, Zähler, Erwerbe, Verfälle, Verbrauchsregeln, Feiertagsgeneratoren und die verschiedenen Arbeitszeit- und Abrechnungsschritte sind alle Plug-ins. Die verfügbaren Plug-ins und das Konfigurationsschema jedes Plug-ins finden Sie unter:

• GET /api/descriptor/plugins/
• GET /api/descriptor/plugins/{registry}/{plugin_id}/schema

Diese Beschreibungsendpunkte antworten ohne Schlüssel, sind aber nicht in der Spezifikation beschrieben – die Regelungen selbst werden in der App konfiguriert.

Reihenfolge der Konfiguration

Nur ein Teil der Konfiguration ist heute über die API beschreibbar – Aktivitäten, Dimensionen, Zeitkonten, Mitarbeitende, Organisationseinheiten und Projekte; Kalender, Gründe, Regelungen und Anstellungsbedingungen werden in der App eingerichtet. Weil Objekte aufeinander verweisen, legen Sie sie von der Grundlage her an: Dimensionen und Zeitkonten → Aktivitäten → Organisationseinheiten → Mitarbeitende → Projekte.

Versionierung mit Gültigkeitsdatum

Konfigurationsobjekte und Personaldatensätze sind versioniert. Eine Änderung gilt ab ihrem Gültigkeitsdatum, und ein neu angelegtes Objekt gilt nicht vor seinem Anlagedatum. Um eine vergangene Periode zu ändern, fügen Sie eine rückwirkende Version hinzu, statt die aktuelle zu bearbeiten.

Wie Ergebnisse entstehen

Gearbeitete Summen, Zuschläge, Gleitzeit und Auszahlung werden nicht live im täglichen Zeitnachweis berechnet – sie entstehen, wenn ein Periodenabschluss erzeugt und anschließend eingereicht und genehmigt wird (Abrechnung). Die Erzeugung der Periodenabschlüsse läuft als geplanter Batch-Job; der Betrag für Auszahlung oder Gleitzeit wird beim Einreichen gewählt. Bauen Sie Integrationen daher so, dass sie abgerechnete Zahlen aus Periodenabschlüssen und Berichten zu Kontobewegungen lesen.

Listen und Umfang

Sammlungen sind seitenweise abrufbar und filterbar (siehe die jeweilige Operation in der Spezifikation). Einige benutzerbezogene Listen liefern standardmäßig die eigenen Daten der aufrufenden Person – zum Beispiel beziehen sich Periodenabschlüsse standardmäßig auf deren Bereich; fordern Sie den arbeitsbereichsweiten Bereich ausdrücklich an, wenn Ihre Integration ihn braucht.

Das limit einer Liste liegt zwischen 1 und 1000; lassen Sie es weg, um den Standardwert zu erhalten. Ein Wert außerhalb dieses Bereichs wird mit 422 abgelehnt. /timesheet/statements liefert höchstens 500 Periodenabschlüsse: Passen mehr, trägt die Antwort den Header MTime-Truncated: true – grenzen Sie dann den Zeitraum oder den Filter ein.

Die Referenzlisten (Konten, Aktivitäten, Dimensionen, Anstellungsbedingungen, Organisationseinheiten und Projekte) tragen ein schwaches ETag. Senden Sie es in If-None-Match zurück, und eine unveränderte Liste antwortet mit 304 Not Modified ohne Inhalt – so müssen Sie sie nicht bei jeder Synchronisierung neu herunterladen.

Ratenbegrenzung

Jeder API-Schlüssel darf 300 Anfragen pro Minute stellen, alle Schlüssel eines Arbeitsbereichs zusammen 600 – mehr Schlüssel anzulegen erhöht das Kontingent also nicht. Jede Antwort enthält RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Eine Anfrage über dem Limit erhält 429 Too Many Requests mit einem Header Retry-After, der die Wartezeit in Sekunden angibt. Warten Sie diese Zeit ab und versuchen Sie es dann erneut.