Unsere API öffnet Clockodo für andere Systeme. Rechnungs- und Projektmanagement-Anwendungen oder eigene Shell-Skripte etwa sind nützliche Mash-ups mit Clockodo. Als REST-API ermöglicht die Schnittstelle, Clockodo-Daten über HTTP im JSON-Format abzufragen, zu verändern und die Stoppuhr zu steuern.
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 Clockodo-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]
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 Clockodo-API jedoch kein endgültiges Löschen, sondern deaktiviert die Ressource) |
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 Clockodo-Umgebung.
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]
X-Clockodo-External-Application: Clockodo;admin@clockodo.com
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
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 |
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)
|
|---|
'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.
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'
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'
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'
Unser Customer-Success-Team steht Ihnen für Fragen zur Verfügung!
Bechtle
Peerigon GmbH
Phoenix Logistik
Fidea