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/v2/entries: Zeit- und Pauschaleinträge verwalten

Die erste Version dieses Endpunktes (api/entries) ist veraltet und nur noch bis 31.12.2022 verfügbar.

Objekttyp „entry“

Basis-Informationen

in allen Entry-Typen vorhanden

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
billable	integer	Abrechenbarkeit 0: nicht abrechenbar, 1: abrechenbar, 2: bereits abgerechnet
texts_id	integer\|null	Die ID der Textbeschreibung
time_since	string	Anfangszeit im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
time_until	string\|null	Endzeit, NULL falls Eintrag noch läuft im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
time_insert	string	Erstellzeitpunkt im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
time_last_change	string	Zeitpunkt der letzten Änderung im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
[customers_name]	string	Name des zugehörigen Kunden Nur in der Auflistfunktion im Enhanced-List-Modus
[projects_name]	string\|null	Name des zugehörigen Projekts Nur in der Auflistfunktion im Enhanced-List-Modus
[users_name]	string	Name des zugehörigen Mitarbeiters Nur in der Auflistfunktion im Enhanced-List-Modus
[text]	string\|null	Textbeschreibung Nur in der Auflistfunktion im Enhanced-List-Modus
[revenue]	float	Umsatz des Zeiteintrags Nur bei notwendigen Mitarbeiterrechten und nur in der Auflistfunktion im Enhanced-List-Modus
type	integer	Typ des Eintrags 1: Zeiteintrag, 2: Pauschalwert, 3: Eintrag mit Pauschalleistung

Typ 1: Zeiteintrag

weitere Parameter zusätzlich zu den Basis-Informationen:

Parameter	Typ	Beschreibung
services_id	integer	Die ID der zugehörigen Leistung
duration	integer\|null	Dauer des Eintrags in Sekunden NULL falls der Eintrag noch läuft
offset	integer	Korrektur des Eintrags in Sekunden, falls die Dauer von der Differenz zwischen Start und Ende abweicht
clocked	boolean	Eintrag wurde mit der Uhr gestoppt
clocked_offline	boolean	Eintrag wurde mit der Stoppuhr offline erfasst
time_clocked_since	string\|null	Zeitpunkt, zu dem die Uhr gestartet wurde im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
time_last_change_worktime	string	Zeitpunkt der letzten Änderung arbeitszeitrelevanter Details im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
hourly_rate	float	Stundensatz Nur bei notwendigen Mitarbeiterrechten
[services_name]	string	Name der zugehörigen Leistung Nur in der Auflistfunktion im Enhanced-List-Modus

Typ 2: Pauschalwert

weitere Parameter zusätzlich zu den Basis-Informationen:

Parameter	Typ	Beschreibung
services_id	integer	Die ID der zugehörigen Leistung
lumpsum	float	Wert des Pauschalbetrags
[services_name]	string	Name der zugehörigen Leistung Nur in der Auflistfunktion im Enhanced-List-Modus

Typ 3: Eintrag mit Pauschalleistung

weitere Parameter zusätzlich zu den Basis-Informationen:

Parameter	Typ	Beschreibung
lumpsum_services_id	integer	Die ID der zugehörigen Pauschalleistung
lumpsums_amount	float	Menge in der jeweiligen Einheit
[lumpsum_services_price]	float	Preis pro Einheit Nur in der Auflistfunktion im Enhanced-List-Modus

Einträge auflisten

Anfrage

GET /api/v2/entries

Notwendige Parameter	time_since	string im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
	time_until	string im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“

Optionale Parameter	filter[users_id]	integer
	filter[customers_id]	integer
	filter[projects_id]	integer
	filter[services_id]	integer
	filter[lumpsum_services_id]	integer
	filter[billable]	integer 0, 1 oder 2
	filter[text] / filter[texts_id]	string / integer
	filter[budget_type]	string strict, strict-completed, strict-incomplete, soft, soft-completed, soft-incomplete, without, without-strict
	enhanced_list	boolean Ermöglicht die Ausgabe zusätzlicher Informationen
	calc_also_revenues_for_projects_with_hard_budget	boolean Normalerweise werden für Zeiteinträge zu Projekte mit hartem Budget keine Umsätze berechnet. Dies kann hier aktiviert werden. Beachten Sie jedoch dass in diesem Fall die Summe aller Umsätze über dem harten Projektbudget liegen kann. Nur für enhanced_list=1

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]' \ 
  -H 'X-Clockodo-External-Application: [Name der Anwendung];[E-Mail-Adresse]' \ 
  "https://my.clockodo.com/api/v2/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/v2/entries/[ID]

Antwort

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

Eintrag anlegen

Anfrage

POST /api/v2/entries

Typ 1: Zeiteintrag

Notwendige Parameter	customers_id, services_id, billable, time_since, time_until

Optionale Parameter	users_id, duration, hourly_rate, projects_id, text

Typ 2: Pauschalwert

Notwendige Parameter	customers_id, services_id, lumpsum, billable, time_since

Optionale Parameter	users_id, projects_id, text

Typ 3: Eintrag mit Pauschalleistung

Notwendige Parameter	customers_id, lumpsum_services_id, lumpsum_services_amount, billable, time_since

Optionale Parameter	users_id, projects_id, text

Antwort

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

Eintrag bearbeiten

Anfrage

PUT /api/v2/entries/[ID]

Notwendige Parameter	keine

Optionale Parameter	customers_id, projects_id, services_id, lumpsum_services_id, users_id, billable, text, duration, lumpsum, lumpsum_services_amount, hourly_rate, time_since, time_until

Antwort

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

Eintrag löschen

Anfrage

DELETE /api/v2/entries/[ID]

Antwort

{
  "success": true
}