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/entrygroups: Mehrere Zeiteinträge auf einmal verwalten und Zeiteinträge gruppiert abfragen

Die gruppierte Abfrage von Zeiteinträgen eignet sich insbesondere zu Auswertungszwecken oder zur Rechnungsstellung.


Objekttyp „entrygroup“

Parameter Typ Beschreibung
groupedBy string Gruppierungskriterium der aktuellen Gruppierungsebene
group string Identifikator der aktuellen Gruppe
name string Textliche Beschreibung der aktuellen Gruppe
number string Datennummer der Gruppe (Kundennummer, Personalnummer, ...) Nur falls das aktuelle Gruppierungskriterium customers_id, projects_id, services_id oder users_id ist
note string Notiz zu der Gruppe Nur falls das aktuelle Gruppierungskriterium customers_id, projects_id oder services_id ist
restrictions array Einschränkungen die auf die aktuelle Gruppe zutreffen, außer dem jeweils aktuellen groupedBy und Zeiteinschränkungen
duration integer Dauer aller Zeiteinträge der Gruppe
[revenue] float Umsatz aller Zeiteinträge der Gruppe Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[budget_used] boolean Wurde für mindestens einen Zeiteintrag hartes Projektbudget genutzt? Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[has_budget_revenues_ billed] boolean Hat die Gruppe mindestens einen Zeiteintrag der hartes Projektbudget nutzt und bereits abgerechnet wurde? Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[has_budget_revenues_ not_billed] boolean Hat die Gruppe mindestens einen Zeiteintrag der hartes Projektbudget nutzt und noch nicht abgerechnet wurde? Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[has_non_budget_revenues_ billed] boolean Hat die Gruppe mindestens einen Zeiteintrag der kein hartes Projektbudget nutzt und bereits abgerechnet wurde? Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[has_non_budget_revenues_ not_billed] boolean Hat die Gruppe mindestens einen Zeiteintrag der kein hartes Projektbudget nutzt und noch nicht abgerechnet wurde? Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[hourly_rate] float Durchschnittlicher Stundensatz der Gruppe Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[hourly_rate_is_equal_and_ has_no_lumpSums] boolean Ist der Stundensatz für alle abrechenbaren Einträge gleich und hat die Gruppe keine Pauschaleinträge? In diesem Fall lässt sich der Umsatz wie folgt errechnen: revenue = hourly_rate * duration
Dies ist insbesondere für die Erstellung von Rechnungsposten nützlich. Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[duration_without_rounding] integer Dauer ungerundet Nur falls Rundung angefragt wurde
[revenue_without_rounding] float Umsatz ungerundet Nur falls Rundung angefragt wurde und nur bei notwendigen Mitarbeiterrechten für die Gruppe
[rounding_success] boolean War das Runden des Umsatzes erfolgreich oder konnte die Rundung wegen unterschiedlicher Stundensätze nicht durchgeführt werden? Nur auf unterster Gruppierungsebene falls Rundung angefragt wurde und nur bei notwendigen Mitarbeiterrechten.
[sub_groups] array Falls mehrere Gruppierungskriterien übergeben wurden, findet sich hier die nächste Ebene

Gruppen von Zeiteinträgen abfragen

Anfrage
GET /api/entrygroups
Notwendige Parameter time_since string (YYYY-MM-DD HH:MM:SS)
time_until string (YYYY-MM-DD HH:MM:SS)
grouping array Ausgewählte Kriterien aus folgender Liste: [customers_id, projects_id, services_id, users_id, texts_id, billable, is_lumpSum, year, week, month, day]
Beispiel in HTTP-POST-Notation: grouping[]=customers_id&grouping[]=users_id
Optionale Parameter filter[users_id] integer Filter nach Mitarbeiter
filter[customers_id] integer Filter nach Kunden
filter[projects_id] integer Filter nach Projekt
filter[services_id] integer Filter nach Leistung
filter[billable] integer Filter nach Abrechenbarkeit 0, 1 oder 2
billable = 2 entspricht hier "Abrechenbar und bereits abgerechnet"
filter[text] / filter[texts_id] string / integer Filter nach Beschreibung
round_to_minutes integer Rundung der Dauern auf die übergebene Anzahl von Minuten aktivieren (Default 0)
prepend_customer_to_ project_name boolean Kundennamen werden bei Projektnamen vorangestellt (Default true)
calc_also_revenues_for_ projects_with_hard_budget boolean(Default false) 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. (Default false)
Antwort
{
  "groups": 
  {
    [object of type group which may contain subgroups],
    [object of type group which may contain subgroups],
    ...
  }
}

Gruppen von Zeiteinträgen bearbeiten

Anfrage
PUT /api/entrygroups
Notwendige Parameter time_since string Filter Startzeitpunkt (YYYY-MM-DD HH:MM:SS)
time_until string Filter Endzeitpunkt (YYYY-MM-DD HH:MM:SS)
Optionale Parameter filter[users_id] integer Filter nach Mitarbeiter
filter[customers_id] integer Filter nach Kunden
filter[projects_id] integer Filter nach Projekt
filter[services_id] integer Filter nach Leistung
filter[billable] integer Filter nach Abrechenbarkeit
filter[text] / filter[texts_id] string / integer Filter nach Beschreibung
users_id int Neu zu setzende Mitarbeiterzuordnung
customers_id int Neu zu setzende Kundenzuordnung
projects_id int Neu zu setzende Projektzuordnung
services_id int Neu zu setzende Leistungszuordnung
billable int Neu zu setzender Wert für die Abrechenbarkeit 0, 1 oder 2
billable = 2 entspricht hier "Abrechenbar und bereits abgerechnet"
texts_id / text integer / string Neu zu setzende Beschreibung
hourly_rate float Neu zu setzender Stundensatz
confirm_key string Bearbeitungsbestätigung Zur Sicherheit wird unsere API zunächst mit diesem Bestätigungskey antworten bevor die Aktion ausgeführt wird (vgl. Abschnitt "Erste Antwort"). Bitte zeigen Sie in Ihrer Umsetzung auch eine entsprechende Bestätigungs-Anfrage inkl. der Anzahl betroffener Zeiteinträge an.
Erste Antwort (auf Anfrage ohne Confirm-Key):
{
  "confirm_key": [string],
  "affected_entries": [integer, count of entries which will be affected]
}
Finale Antwort (auf Anfrage mit Confirm-Key):
{
  "success": true,
  "edited_entries": [integer]
}

Eine Gruppe von Zeiteinträgen löschen

Anfrage
DELETE /api/entrygroups
Notwendige Parameter time_since string Filter Startzeitpunkt (YYYY-MM-DD HH:MM:SS)
time_until string Filter Endzeitpunkt (YYYY-MM-DD HH:MM:SS)
Optionale Parameter filter[users_id] integer Filter nach Mitarbeiter
filter[customers_id] integer Filter nach Kunden
filter[projects_id] integer Filter nach Projekt
filter[services_id] integer Filter nach Leistung
filter[billable] integer Filter nach Abrechenbarkeit 0, 1 oder 2
billable = 2 entspricht hier "Abrechenbar und bereits abgerechnet"
filter[text] / filter[texts_id] string / integer Filter nach Beschreibung
confirm_key string Bearbeitungsbestätigung Zur Sicherheit wird unsere API zunächst mit diesem Bestätigungskey antworten bevor die Aktion ausgeführt wird (vgl. Abschnitt "Erste Antwort"). Bitte zeigen Sie in Ihrer Umsetzung auch eine entsprechende Bestätigungs-Anfrage inkl. der Anzahl betroffener Zeiteinträge an.
Erste Antwort (auf Anfrage ohne Confirm-Key):
{
  "confirm_key": [string],
  "affected_entries": [integer, count of entries which will be affected]
}
Finale Antwort (auf Anfrage mit Confirm-Key):
{
  "success": true,
  "deleted_entries": [integer]
}