Stempeluhr API

Zeiterfassung per Stempeluhr API

URL

https://timesaver.ch/app/rest/mandators/<mandator id>/worktime

Stempeluhr bedienen per API

Die Stempelungen können als JSON gesendet werden und können entweder in Echtzeit oder als Zusammenfassung abgearbeitet werden.

Um die Stempelungen für den korrekten Mitarbeiter verbuchen zu können muss entweder die E-Mail Adresse oder die NFC Tag Id übermittelt werden. Erste (und alle weiteren ungeraden) Stempelung pro Mitarbeiter wird als Anfang der Arbeitszeit verbucht. Die zweite (und alle weiteren geraden) Stempelung wird als Ende dieser Arbeitszeit verbucht.

Weitere optionale Felder sind die NFC Geräte ID, falls die Stempelung auf ein einzelnes Gerät beschränkt ist, und die An-/Abwesenheitsart.

Es bestehen also folgende Felder:

Feld	Optional	Beschreibung
id	ja	ID um Fehlermeldungen bei einer fehlerhaften Stempelung zu identifizieren.
timestamp	nein	Stempelung mit Datum und Uhrzeit im Format 'yyyy-mm-dd hh:mm:ss'.
email	ja*	Email für die Identifizierung der Stempelung. Entweder Email oder NFC Tag muss gesetzt sein. Falls Email nicht gesetzt ist, wird NFC Tag verwendet.
nfc_id	ja*	NFC Tag für die Identifizierung der Stempelung. Entweder Email oder NFC Tag muss gesetzt sein. Falls NFC Tag nicht gesetzt ist, wird Email verwendet.
nfc_device_id	ja	Kann übertragen werden, falls die Stempelung auf ein im vornherein definiertes Gerät beschränkt ist, oder als Kennung um zu identifizieren von welchem Gerät aus gestempelt wurde.
pat_id	ja	ID für An-/Abwesenheitsart, welche bei der Stempelung verwendet wird. Falls nicht gesetzt, wird default Anwesenheitsart verwendet.

Request

Headers

POST https://timesaver.ch/app/rest/mandators/59/worktime
Authorization: APIKey NjMyMDE3ZGQtZTgyYi00ZDE4LTkxYzItMmUzNTU4MWI1MmMzOjE5Ny==
Content-Type: application/json;charset=UTF-8
Accept: application/json

Body

[
  {
    "id": 1,
    "email": "mail@test.ch",
    "timestamp": "2020-01-23 09:05:08"
  },
  {
    "id": 2,
    "nfc_id": "abc123456789",
    "timestamp": "2020-01-23 13:16:19"
  },
  {
    "email": "mail@test.ch",
    "timestamp": "2020-01-23 15:43:01"
  }
]

Response

Headers

ETag: MTUyNjQ2ODI3MDk4MToy
Cache-Control: private, max-age=120
Content-Type: application/json;charset=UTF-8

Body

[
  {
    "id": 1,
    "timestamp": "2020-01-23 09:05:08",
    "email": "mail@test.ch",
    "user": "Hans Muster"
  },
  {
    "id": 2,
    "timestamp": "2020-01-23 13:16:19",
    "nfc_id": "abc123456789",
    "user": "Nfc Muster"
  },
  {
    "timestamp": "2020-01-23 15:43:01",
    "email": "mail@test.ch",
    "user": "Hans Muster"
  }
]

Fehlermeldungen

Es gibt folgende Fehlermeldungen für diese API

HTTP-Code	Fehler	Grund
201 - Created		Der Datensatz konnte vollständig bearbeitet und gespeichert werden.
400 - Bad Request	JSON could not be parsed. Please check your syntax!	Der Datensatz ist nicht als JSON-Array übermittelt worden oder hat fehlerhafte Syntax
401 - Unauthorized		Es wurde keine oder eine fehlerhafte Authentifizierung übermittelt.
403 - Forbidden		Es wurde eine gültige Authentifizierung übermittelt, die jedoch nicht mit dem Mandant übereinstimmt.
422 - Unprocessable Entity	Entweder E-Mail oder NFC Tag ID muss gesetzt sein.	Es muss mindesten eines der beiden Felder email oder nfc_id gesetzt sein um den zugehörigen Benutzer zu identifizieren.
422 - Unprocessable Entity	Kein Benutzer gefunden.	Entweder ist der Benutzer noch nicht erstellt oder es hat ein Schreibfehler in der E-Mail Adresse oder der NFC Tag ID.
422 - Unprocessable Entity	Datum falsch formatiert oder nicht vorhanden.	Das Datum konnte nicht verarbeitet werden, entweder weil gar keines übermittelt wurde oder weil es nicht im Format `YYYY-MM-DD hh:mm:ss` ist
422 - Unprocessable Entity	Benutzer nicht Mitarbeiter im Mandant.	Der Benutzer wurde zwar gefunden, wurde aber nicht zu diesem Mandanten hinzugefügt.
422 - Unprocessable Entity	Benutzer für E-Mail und für NFC Tag ID stimmen nicht überein.	Es wurde eine E-Mail Adresse und eine NFC Tag ID übermittelt, diese weisen jedoch auf zwei verschiedene Benutzer.
422 - Unprocessable Entity	Keine Berechtigung für diesen Benutzer.	Der authentifizierte Benutzer versucht Daten für einen anderen Benutzer zu übermitteln, obwohl er keine Vorgesetztenrolle hat und nicht Mandantenverantwortlicher ist.
422 - Unprocessable Entity	Die ID muss eine Zahl sein.	Die übermittelte ID ist keine Zahl.
422 - Unprocessable Entity	Die Ab-/Anwesenheitsart ID muss eine Zahl sein.	Die übermittelte ID für die Ab-/Anwesenheitsart ist keine Zahl.
422 - Unprocessable Entity	Ab-/Anwesenheitsart ungültig.	Die übermittelte ID für die Ab-/Anwesenheitsart ist im Mandant nicht auffindbar.
422 - Unprocessable Entity	Dauer des Zeiteintrags zu klein.	Die Dauer zwischen Ein- und Ausstempeln ist zu kurz. Wahrscheinlich eine Folge von einer Doppelstempelung.
422 - Unprocessable Entity	GPS ist zwingend nötig für die Zeiterfassung.	In den Mandanteneinstellungen ist für diesen Benutzer die GPS Position zwingend notwendig für die Zeiterfassung. Dieser Benutzer kann nur über die mobile App oder über das Touchterminal die Zeit erfassen.
422 - Unprocessable Entity	Es wurde keine oder eine falsche NFC Device ID übertragen, obwohl eine verlangt wird.	Für die übertragene NFC Tag ID ist ein Gerät hinterlegt, was bedeutet, dass nur über dieses Gerät gestempelt werden darf. Das übertragene NFC Geräte Tag stimmt nicht mit dem hinterlegten Gerät überein, oder es wurde kein NFC Geräte Tag übermittelt, obwohl eines verlangt wird.
422 - Unprocessable Entity	Fehlerhafter Eintrag. Konnte nicht gespeichert werden.	Die übermittelten Daten sind eigentlich korrekt, aber konnten nicht gespeichert werden. Wahrscheinlich gibt es während der übermittelten Zeit bereits einen anderen Eintrag mit Überschneidungen.
500 - Internal Server Error		Der Server hat ein Problem festgestellt und kann die übermittelten Daten nicht bearbeiten.