Die clocko:do API:
Anbindung von clocko:do an andere Systeme

clocko:do REST-API

Unsere API öffnet clocko:do für andere Systeme. Rechnungs- und Projektmanagement-Anwendungen oder eigene Shell-Skripte etwa sind nützliche Mash-ups mit clocko:do. Als REST-API ermöglicht die Schnittstelle, clocko:do-Daten über HTTP im JSON-Format abzufragen, zu verändern und die Stoppuhr zu steuern.

Adresse der clocko:do-API

Zugriff auf die Schnittstelle erhalten Sie über folgende Adresse:

https://my.clockodo.com/api/[Ressourcen-Typ]

Hierbei stellt der Ressourcen-Typ eine Klasse Ihrer Daten dar. Im Menü finden Sie zu jedem Ressourcen-Typ genauere Beschreibungen. So finden Sie beispielsweise unter "/api/entries" detaillierte Informationen dazu, wie Sie den Ressourcentyp "entry" verwalten können, wobei "entries" Zeiteinträge in Ihrer clocko:do-Umgebung sind.

Sobald Sie eine bestimmte Ressource anfragen, also z.B. Informationen zu genau einem Zeiteintrag abfragen, verändert sich die URL wie folgt:

https://my.clockodo.com/api/[Ressourcen-Typ]/[Ressourcen-ID]

HTTP-Verben

Um der API mitzuteilen welche Operationen Sie auf den Ressourcen ausführen möchten, werden die sogenannten Verben des HTTP-Protokolls genutzt. Folgende Operationen sind üblicherweise möglich:

GET Liste aller Ressourcen des gewählten Ressourcen-Typs abfragen
GET, mit Übergabe einer Ressourcen-ID in der URL Genau eine Ressource abfragen
POST Eine neue Ressource einfügen
PUT, mit Übergabe einer Ressourcen-ID in der URL Eine Ressource aktualisieren/bearbeiten
DELETE Eine Ressource löschen (bei den meisten Ressourcen erlaubt die clocko:do-API jedoch kein endgültiges Löschen, sondern deaktiviert die Ressource)

Authentifizierung

Um über die API Zugriff auf Ihre Daten zu erhalten, müssen Sie sich bei der API mit dem sogenannenten API-Key authentifizieren. Dafür gibt es zwei verschiedene Arten:

Über folgende HTTP-Header:

X-ClockodoApiUser: [E-Mail-Adresse]
X-ClockodoApiKey: [API-Key]

Oder mittels der Basis-Authentifizierung des HTTP-Protokolls:

User: [E-Mail-Adresse]
Passwort: [API-Key]

Für jeden Mitarbeiter steht ein eigener API-Zugang bereit, der die jeweiligen Zugriffsrechte des Benutzers berücksichtigt.

Jeder Mitarbeiter findet seinen API-Key im Menüpunkt "Meine Daten" in seiner clocko:do-Umgebung.

Client-Identification

Jede Anfrage an unsere API muss eine Identifikation der aufrufenden Anwendung, samt der E-Mail-Adresse eines technischen Ansprechpartners enthalten. Hierfür muss der folgende HTTP-Header genutzt werden:

X-Clockodo-External-Application: [Name der Anwendung oder Ihres Unternehmens];[E-Mail-Adresse]

Beispiel:

X-Clockodo-External-Application: Clickbits;admin@clickbits.de

Lokalisierung: Übersetzungen & Formate

Einige Rückgaben der API erfolgen lokalisiert. So z.B. das Texte die ein Datum beschreiben, Fehlermeldungen und ähnliches. Um zwischen den verfügbaren Sprachen umzuschalten (de/en/fr), nutzen Sie bitten den Accept-Language-Header des HTTP-Protokolls.

Accept-Language: de

Response-Codes

Die API antwortet auf Anfragen mit den Status-Codes des HTTP-Protokolls. Bei Fehlern finden Sie außerdem zusätzliche Fehlerinformationen in der Antwort.

200 - OK Die Anfrage war erfolgreich
400 - Bad Request Die Anfrage war fehlerhaft (z.B. fehlende Parameter)
401 - Unauthorized Authentifizierung nicht erfolgreich
403 - Forbidden Unzureichende Zugriffsrechte für die angefragte Ressource
404 - Not found Die angefragte Ressource konnte nicht gefunden werden
405 - Method Not Allowed Der angefragte Endpunkt kann nicht verwendet werden
409 - Conflict Eine Ressource mit den Daten existiert bereits
429 - Too many requests Zu viele Anfragen an einen Endpunkt innerhalb eines bestimmten Zeitraums
500 - Internal Server Error Es ist ein unbekannter Fehler aufgetreten

Seitenweise Ausgabe

Bestimmte Ressourcen liefern im Zweifel sehr viel Daten zurück. Daher ist für diese Ressourcen eine seitenweise Ausgabe aktiv, sodass die Anzahl der pro Aufruf zurückgegebenen Elemente begrenzt ist. Über den zusätzlichen Anfrage-Parameter "page" können Sie dann auf weitere Elemente zugreifen.

Zusätzlicher-Anfrage-Parameter
page (integer)
Zusätzlicher Inhalt der Antwort
'paging': {
  'items_per_page': [integer],
  'current_page': [integer],
  'count_pages': [integer],
  'count_items': [integer]
}

Hinweis: Derzeit ist die seitenweise Ausgabe nur für die Ressourcen "entries", "entriesTexts", "customers" und "projects" aktiv.

Beispiel-Aufrufe

Beispiel für den Abruf aller Leistungen mit cURL unter Nutzung der Basis-Authentifizierung
curl -v 
  -X GET \ 
  -u [E-Mail-Adresse]:[API-Key] \ 
  -H 'X-Clockodo-External-Application: [Name der Anwendung];[E-Mail-Adresse]' \ 
  'https://my.clockodo.com/api/services'
Beispiel für den Abruf aller Leistungen mit cURL mit Authentifizierung über den HTTP-Header
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/services'
Beispiel für das Anlegen einer Leistung
curl -v 
  -X POST \ 
  -H 'X-ClockodoApiUser: [E-Mail-Adresse]' \ 
  -H 'X-ClockodoApiKey: [API-Key]' \ 
  -H 'X-Clockodo-External-Application: [Name der Anwendung];[E-Mail-Adresse]' \ 
  --data "name=Testleistung" \
  'https://my.clockodo.com/api/services'
stripes illustration
Kontaktieren Sie uns!

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

Jetzt kontaktieren!

Alle Funktionen 14 Tage kostenlos testen

Mit dem Absenden des Formulars akzeptieren Sie unsere AGB und unsere Datenschutz­erklärung und bestätigen, dass Sie clockodo als Unternehmer nutzen.

Nutzen Sie die Erfahrungen von 6.000 weiteren Unternehmen:

Bechtle Mannheim LogoBechtlePeerigon LogoPeerigon GmbH
Phoenix Logistik LogoPhoenix LogistikFieda LogoFidea