Clockodo API: Verwaltung und Gruppierung von Zeiteinträgen

Endpunkt api/v2/entrygroups

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

Alles zum Endpunkt api/v2/entrygroups

Objekttyp „entrygroup“
Gruppen von Zeiteinträgen abfragen
Gruppen von Zeiteinträgen bearbeiten
Eine Gruppe von Zeiteinträgen löschen

Objekttyp „entrygroup“

Parameter	Typ	Beschreibung
grouped_by	string	Gruppierungskriterium der aktuellen Gruppierungsebene
group	string	Identifikator der aktuellen Gruppe
name	string	Textliche Beschreibung der aktuellen Gruppe
number	string\|null	Datennummer der Gruppe (Kundennummer, Personalnummer, ...) Nur falls das aktuelle Gruppierungskriterium customers_id, projects_id, services_id oder users_id ist
note	string\|null	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 grouped_by 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\|null	Durchschnittlicher Stundensatz der Gruppe Nur bei notwendigen Mitarbeiterrechten für die Gruppe
[hourly_rate_is_equal_and_has_no_lump_sums]	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/v2/entrygroups

Notwendige Parameter	time_since	string	Filter Startzeitpunkt im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
	time_until	string	Filter Endzeitpunkt im Format ISO 8601 UTC, z.B. „2021-06-30T12:34:56Z“
	grouping	array	Gruppierung von Einträge; Gruppen werden verschachtelt ausgegeben Ausgewählte Kriterien aus folgender Liste: [customers_id, projects_id, services_id, users_id, texts_id, lumpsum_services_id, billable, is_lumpsum, year, week, month, day] Beispiel in HTTP-GET-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[lumpsum_services_id]	integer	Filter nach Pauschale
	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
	filter[budget_type]	string	Filter nach Budget-Typ strict, strict-completed, strict-incomplete, soft, soft-completed, soft-incomplete, without, without-strict
	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	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)

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/entrygroups?time_since=2024-01-01T00:00:00Z&time_until=2024-02-01T00:00:00Z&grouping[]=projects_id&grouping[]=services_id&filter[users_id]=123&filter[customers_id]=456

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/v2/entrygroups

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

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[lumpsum_services_id]	integer	Filter nach Pauschale
	filter[billable]	integer	Filter nach Abrechenbarkeit
	filter[text] / filter[texts_id]	string / integer	Filter nach Beschreibung
	filter[budget_type]	string	Filter nach Budget-Typ strict, strict-completed, strict-incomplete, soft, soft-completed, soft-incomplete, without, without-strict
	users_id	integer	Neu zu setzende Mitarbeiterzuordnung
	customers_id	integer	Neu zu setzende Kundenzuordnung
	projects_id	integer	Neu zu setzende Projektzuordnung
	services_id	integer	Neu zu setzende Leistungszuordnung
	lumpsum_services_id	integer	Neu zu setzende Pauschalleistungzuordnung
	billable	integer	Neu zu setzender Wert für die Abrechenbarkeit 0, 1 oder 2 billable = 2 entspricht hier "Abrechenbar und bereits abgerechnet"
	text	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.

Beispiel-Aufruf mit allen Parametern als JSON-Body

{
  "time_since": "2024-01-01T00:00:00Z",
  "time_until": "2024-02-01T00:00:00Z",
  "grouping": ["projects_id", "services_id"],
  "filter": {
    "users_id": 123,
    "customers_id": 456
  }
}

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/v2/entrygroups

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

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[lumpsum_services_id]	integer	Filter nach Pauschale
	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
	filter[budget_type]	string	Filter nach Budget-Typ strict, strict-completed, strict-incomplete, soft, soft-completed, soft-incomplete, without, without-strict
	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]
}

API-Dokumentation Grundlagen der Clockodo REST-API
api/absencesAbwesenheiten (Urlaubstage, Krankheitstage, ...) verwalten
api/v2/clockKontrolle der Stoppuhr
api/v2/customersKunden verwalten
api/v2/entriesZeit- und Pauschaleinträge verwalten
api/v2/entriesTextsBeschreibungen von Zeit- und Pauscheleinträgen auslesen
api/v2/entrygroupsGanze Gruppen von Zeiteinträgen auslesen und verwalten (insbesondere zu Auswertungs- und Rechnungszwecken nützlich)
api/holidayscarryUrlaubsüberträge verwalten
api/holidaysquotaUrlaubskontingente verwalten
api/v2/lumpsumservicesPauschalleistungen verwalten
api/nonbusinessdaysFeiertage ausgewertet auslesen
api/nonbusinessgroupsFeiertagsgruppen auslesen
api/overtimecarryÜberstundenüberträge verwalten
api/v2/projectsProjekte verwalten
api/registerClockodo-Accounts anlegen
api/v2/servicesLeistungen verwalten
api/v2/surchargesZuschlagsmodelle verwalten
api/targethoursSollstunden verwalten
api/v2/teamsTeams verwalten
api/userreportsStundenkonten auslesen
api/v2/usersMitarbeiter verwalten
api/v2/users/access/customers-projectsKunden- und Projektrechte auslesen
api/v2/users/access/servicesLeistungsrechte auslesen
api/v2/aggregates/users/meBenutzer- und Firmeneinstellungen auslesen
api/v2/workTimesArbeitszeiten auslesen
api/v2/workTimes/changeRequestsAnträge auf Änderung der Arbeitszeit verwalten

Kontaktieren Sie uns!

Unser Customer-Success-Team steht Ihnen für Fragen zur Verfügung!

Jetzt kontaktieren!