REST-API

Die clockodo-API ermöglicht die Anbindung von clockodo an andere Systeme. Rechnungs- und Projektmanagement-Anwendungen oder eigene Shell-Skripte sind Beispiele für nützliche Mash-Ups mit clockodo.

api/entries: Zeit- und Pauschaleinträge verwalten

Objekttyp „entry“

Parameter	Typ	Beschreibung
id	integer	Die ID des Eintrags
customers_id	integer	Die ID des zugehörigen Kunden
projects_id	integer\|null	Die ID des zugehörigen Projekts
users_id	integer	Die ID des zugehörigen Mitarbeiters
services_id	integer\|null	Die ID der zugehörigen Leistung
lumpSums_id	integer\|null	Die ID der zugehörigen Pauschale
billable	integer	Abrechenbarkeit (1 oder 0)
billed	boolean	Eintrag ist abrechenbar und bereits abgerechnet Um einen Eintrag auf "billed = true" zu setzen, muss beim Bearbeiten-Request "billable = 2" übertragen werden.
texts_id	integer\|null	Die ID der Textbeschreibung
text	string\|null	Textbeschreibung
duration	integer	Dauer des Eintrags in Sekunden
duration_time	string	Dauer des Eintrags in HH:MM:SS Format
offset	integer	Die Korrektur des Eintrags in Sekunden. Ist gesetzt falls die Dauer von dem Zeitraum zwischen Start und Ende abweicht.
offset_time	string	Korrektur des Eintrags in HH:MM:SS Format.Ist gesetzt falls die Dauer von dem Zeitraum zwischen Start und Ende abweicht.
time_since	string	Anfangszeit (Zeitstempel, je nach Anfrage formatiert)
time_until	string\|null	Endzeit, NULL falls Eintrag noch läuft (Zeitstempel, je nach Anfrage formatiert)
time_insert	string	Erstellzeitpunkt (Zeitstempel, je nach Anfrage formatiert)
time_last_change	string	Zeitpunkt der letzten Änderung (Zeitstempel, je nach Anfrage formatiert)
time_last_change_worktime	string	Zeitpunkt der letzten Änderung arbeitszeitrelevanter Details (Zeitstempel, je nach Anfrage formatiert)
clocked	boolean	Eintrag wurde mit der Uhr gestoppt
is_clocking	boolean	Eintrag läuft noch
lumpSum	float\|null	Gibt den Pauschalbetrag zurück, falls der Eintrag ein Pauschaleintrag mit einfachem Betrag ist, der keiner Pauschale zugeordnet ist
lumpSums_amount	float\|null	Gibt die Menge zurück, falls der Eintrag ein Pauschaleintrag mit Zuordnung zu einer Pauschale ist
[hourly_rate]	float	Stundensatz Nur bei notwendigen Mitarbeiterrechten und nur in der Auflistfunktion
[revenue]	float	Umsatz des Zeiteintrags Nur bei notwendigen Mitarbeiterrechten und nur in der Auflistfunktion
[budget]	float	Budget des zugehörigen Projekts Nur bei notwendigen Mitarbeiterrechten und nur in der Auflistfunktion
[budget_is_hours]	boolean	Budget des zugehörigen Projekts ist Zeitbudget statt monetärem Budget Nur bei notwendigen Mitarbeiterrechten und nur in der Auflistfunktion
[budget_is_not_strict]	boolean	Budget des zugehörigen Projekts ist Soll-Zeit statt eines hartem Budgets Nur bei notwendigen Mitarbeiterrechten und nur in der Auflistfunktion
[customers_name]	string	Name des zugehörigen Kunden Nur in der Auflistfunktion
[projects_name]	string\|null	Name des zugehörigen Projekts Nur in der Auflistfunktion
[services_name]	string\|null	Name der zugehörigen Leistung Nur in der Auflistfunktion
[users_name]	string	Name des zugehörigen Mitarbeiters Nur in der Auflistfunktion

Einträge auflisten

Anfrage

GET /api/entries

Notwendige Parameter	time_since	string (z.B. „YYYY-MM-DD HH:MM:SS“; vgl. Abschnitt „Lokalisierung“)
	time_until	string (z.B. „YYYY-MM-DD HH:MM:SS“; vgl. Abschnitt „Lokalisierung“)

Optionale Parameter	filter[users_id]	integer
	filter[customers_id]	integer
	filter[projects_id]	integer
	filter[services_id]	integer
	filter[lumpSums_id]	integer
	filter[billable]	integer 0, 1 oder 2 Bei der Anfrage filter[billable]=2 erhalten sie als Antwort nur Einträge mit billable = 1 und billed = true
	filter[text] / filter[texts_id]	string / integer
	filter[budget_type]	string strict, strict-completed, strict-incomplete, soft, soft-completed, soft-incomplete, without, without-strict

Bitte beachten Sie, dass die Abfrage der Zeiteinträge über die aufgelisteten Parameter zeitlich eingeschränkt werden muss und darüber hinaus über die Filter-Parameter eingeschränkt werden kann.

Da Sie als Rückgabe sehr viele Zeiteinträge erhalten können, ist für diese Abfrage die seitenweise Ausgabe aktiv.

Beachten Sie außerdem, dass GET-Parameter URL-kodiert werden müssen. Im folgendem Beispiel sehen Sie ein Beispiel für cURL. Bibliotheken und Anwendungen (Rest-Clients) kodieren die Parameter normalerweise automatisch.

Beispielhafter Aufruf mit cURL

curl -v 
  -X GET \ 
  -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ 
  -H 'X-ClockodoApiKey: [API-Key]' \ 
  "https://my.clockodo.com/api/entries?time_since=2021-01-01%2000:00:00&time_until=2021-02-01%2000:00:00"

Antwort

{
  "paging": [paging information],
  "filter": [list of respected filters],
  "entries": 
  {
    [object of type entry],
    [object of type entry],
    ...
  }
}

Vgl. Sie hier die Beschreibung zur seitenweise Ausgabe [paging information].

Eintrag abrufen

Anfrage

GET /api/entries/[ID]

Antwort

{
  "entry": [object of type entry]
}

Eintrag anlegen

Anfrage

POST /api/entries

Zeiteintrag

Notwendige Parameter	customers_id, services_id, billable, time_since, time_until

Optionale Parameter	users_id, duration, hourly_rate, projects_id, text

Pauschaleintrag mit Leistung

Notwendige Parameter	customers_id, services_id, lumpSum, billable, time_since

Optionale Parameter	users_id, projects_id, text

Pauschaleintrag mit Pauschalleistung

Notwendige Parameter	customers_id, lumpSums_id, lumpSums_amount, billable, time_since

Optionale Parameter	users_id, projects_id, text

Antwort

{
  "entry": [object of type entry]
}

Eintrag bearbeiten

Anfrage

PUT /api/entries/[ID]

Notwendige Parameter	keine

Optionale Parameter	customers_id, projects_id, services_id, lumpSums_id, users_id, billable, text, duration, lumpSum, lumpSums_amount, hourly_rate, time_since,time_until

Antwort

{
  "entry": [object of type entry]
}

Eintrag löschen

Anfrage

DELETE /api/entries/[ID]

Antwort

{
  "success": true
}