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
}