timefusion

Integrations-API

Rechnungs-, Buchhaltungs- oder ERP-Software über API-Schlüssel an timefusion anbinden

Über die Integrations-API tauschen andere Systeme Daten mit timefusion aus, etwa eine Rechnungs-, Buchhaltungs- oder ERP-Software. Ein angebundenes System kann zum Beispiel:

  • Zeitbuchungen, Stammdaten und Rechnungen lesen
  • Kunden, Projekte und Stundensätze anlegen und ändern
  • Zeitbuchungen als abgerechnet markieren

Jedes System erhält einen eigenen API-Schlüssel, der festlegt, worauf es zugreifen darf. Ein Schlüssel gilt für die gesamte Organisation, unabhängig von den Rechten der Person, die ihn erstellt hat.

Die technische Referenz der API ist öffentlich und in englischer Sprache: Entwickler-Dokumentation der Integrations-API. In timefusion findest du den Link Entwickler-Dokumentation oben rechts unter Einstellungen → Integrations-API.

Wer kann die Integrations-API verwenden?

AufgabeBenötigte Berechtigung
Integrations-API ein- und ausschaltenOrganisation verwalten
API-Schlüssel erstellen, ersetzen und widerrufenIntegrations-API-Schlüssel verwalten

Beide Berechtigungen gibt es nur mit der vordefinierten Rolle Administrator. Keine eigene Rolle kann sie enthalten, weil ein Schlüssel unabhängig von den Rechten seines Erstellers auf Daten der gesamten Organisation zugreift.

Integrations-API aktivieren

Gehe zu Einstellungen → Funktionen

Aktiviere den Schalter Integrations-API

Speichere die Einstellungen

Danach erscheint unter Einstellungen der Bereich Integrations-API.

Ausschalten weist sofort alle Anfragen ab, widerruft aber keinen Schlüssel. Nach dem erneuten Einschalten funktionieren alle vorhandenen Schlüssel wieder. Ist ein Schlüssel in falsche Hände geraten, widerrufe ihn.

Angebundene Systeme

Unter Einstellungen → Integrations-API siehst du alle Systeme, die über einen aktiven API-Schlüssel angebunden sind:

  • Name des Schlüssels und seine Berechtigungen
  • Zuletzt aktiv: wann das System die API zuletzt verwendet hat. Ein neuer Schlüssel zeigt zunächst Noch nicht verwendet und nach 7 Tagen ohne Anfrage Nie verwendet.
  • Anfragen der letzten 30 Tage, davon fehlgeschlagene als Fehler
  • Hinweise, wenn ein Schlüssel bald abläuft oder ein Schlüsselwechsel noch nicht abgeschlossen ist

Während ein Schlüssel ersetzt wird, erscheinen alter und neuer Schlüssel als ein Eintrag. Abgelaufene und widerrufene Schlüssel findest du unter API-Schlüssel verwalten.

Angebundene SystemeAngebundene Systeme

API-Schlüssel erstellen

Erstelle für jedes externe System einen eigenen Schlüssel. So lässt sich ein einzelnes System jederzeit trennen, ohne die anderen zu beeinträchtigen. Es sind höchstens 10 aktive Schlüssel möglich.

Gehe zu Einstellungen → Integrations-API und klicke auf API-Schlüssel verwalten

Klicke auf Neuer Schlüssel

Gib einen Name ein, z.B. den Namen des Systems

Der Name erscheint später bei jeder Buchung, die über diesen Schlüssel abgerechnet wurde, z.B. von Rechnungsprogramm (API).

Wähle die Berechtigungen: Alles lesen, Abrechnung oder Eigene Auswahl

Wähle die Gültigkeit: 365 Tage (voreingestellt), 90 Tage oder Kein Ablauf

Klicke auf Schlüssel erstellen

Kopiere den Schlüssel mit Schlüssel kopieren und trage ihn im externen System ein. Dort werden zusätzlich die angezeigte Basis-URL und die Authentifizierung benötigt: Das System schickt den Schlüssel bei jeder Anfrage im Header Authorization: Bearer <Schlüssel> mit.

Bestätige anschließend mit Ich habe den Schlüssel gespeichert.

API-Schlüssel mit eigener Auswahl an Berechtigungen erstellenAPI-Schlüssel mit eigener Auswahl an Berechtigungen erstellen

Der Schlüssel wird nur einmal direkt nach dem Erstellen angezeigt. Bewahre ihn sicher auf und gib ihn nur an das System weiter, für das er bestimmt ist. Geht er verloren, ersetze ihn durch einen neuen.

Mitglieder mit der Berechtigung Organisation verwalten werden per E-Mail über jeden neuen Schlüssel informiert.

Berechtigungen eines API-Schlüssels

Wähle nur, was das System wirklich braucht. Die Berechtigungen eines Schlüssels lassen sich nach dem Erstellen nicht mehr ändern, dafür wird der Schlüssel ersetzt.

VorlageErlaubt
Alles lesenAlle Daten abfragen, nichts verändern. Enthält auch Personen lesen
AbrechnungZeitbuchungen, Stammdaten und Rechnungen lesen und Buchungen als abgerechnet markieren. Ohne Personen lesen
Eigene AuswahlBerechtigungen einzeln wählen

Ist die Funktion Buchhaltung nicht aktiv, enthalten beide Vorlagen kein Beträge & Stundensätze lesen. Unter Rechte einzeln anpassen siehst du, welche Berechtigungen eine Vorlage gewählt hat, und kannst sie einzeln ändern:

BerechtigungErlaubt
Zeitbuchungen lesenZeitbuchungen abfragen, mit Projekt, Aufgabe, Person und Dauer
Stammdaten lesenProjekte, Aufgaben, Kunden und Stundensätze abfragen
Personen lesenPersonen abfragen, mit Name, E-Mail-Adresse, Stundensatz und Status. Das sind personenbezogene Daten aller Mitglieder, auch der deaktivierten
Rechnungen lesenRechnungen abfragen, mit Nummer, Anlagedatum und Summe der verknüpften Zeitbuchungen
Beträge & Stundensätze lesenStundensätze und Euro-Beträge in den Antworten mitliefern. Nur mit aktivierter Funktion Buchhaltung
Zeitbuchungen abrechnenZeitbuchungen als abgerechnet markieren und die Markierung wieder aufheben
Kunden anlegen & ändernKunden anlegen und ändern, mit Name, Stundensatz und Archivierung
Projekte anlegen & ändernProjekte anlegen und ändern, mit Name, Projektnummer, Farbe, Kunde, Stundensatz und Deaktivierung
Stundensätze anlegen & ändernStundensätze anlegen und ändern, mit Name, Betrag, Beschreibung und Archivierung. Nur mit aktivierter Funktion Buchhaltung

Um einen Stundensatz zu setzen oder zu ändern, braucht der Schlüssel zusätzlich Beträge & Stundensätze lesen. Das gilt auch für den Stundensatz von Kunden und Projekten. Passt eine Auswahl nicht zusammen, z.B. Zeitbuchungen abrechnen ohne Zeitbuchungen lesen, weist das Formular darauf hin und bietet an, die fehlende Berechtigung hinzuzufügen.

  • Eine über die API abgerechnete Buchung ist in timefusion wie jede abgerechnete Buchung für Änderungen gesperrt.
  • Mit den Berechtigungen zum Anlegen & Ändern kann der nächste Abgleich Änderungen überschreiben, die in timefusion an Kunden oder Projekten gemacht wurden.
  • Ein geänderter Stundensatz gilt sofort für alle noch nicht abgerechneten Buchungen mit diesem Satz.

API-Schlüssel verwalten

Unter Einstellungen → Integrations-API → API-Schlüssel verwalten werden alle Schlüssel mit Name, Berechtigungen, Zuletzt verwendet (inkl. Anfragen und Fehlern der letzten 30 Tage), Erstellt (mit Ersteller) und Status aufgelistet. Über der Liste steht, wie viele der 10 möglichen Schlüssel aktiv sind, z.B. 3 von 10 aktiv.

StatusBedeutung
AktivDer Schlüssel kann verwendet werden
AbgelaufenDie Gültigkeit ist abgelaufen, Anfragen werden abgewiesen
WiderrufenDer Schlüssel wurde widerrufen, Anfragen werden abgewiesen

Abgelaufene Schlüssel stehen am Ende der Liste. Widerrufene Schlüssel sind ausgeblendet und lassen sich mit Widerrufene Schlüssel anzeigen einblenden. Über das Präfix (z.B. sk_tf_int_live_…) erkennst du einen Schlüssel im angebundenen System wieder.

API-Schlüssel mit den Status Aktiv, Abgelaufen und WiderrufenAPI-Schlüssel mit den Status Aktiv, Abgelaufen und Widerrufen

API-Schlüssel ersetzen

Ein Schlüssel lässt sich nicht verlängern. Läuft er ab, sollen sich die Berechtigungen ändern oder ist der Schlüssel verloren gegangen, ersetze ihn durch einen neuen. Anders als beim Widerrufen und neu Erstellen funktionieren dabei beide Schlüssel eine Zeit lang, sodass das angebundene System ohne Unterbrechung umgestellt werden kann.

Klicke beim Schlüssel auf Schlüssel ersetzen

Prüfe Name und Berechtigungen. Beide werden vom bisherigen Schlüssel übernommen und können hier geändert werden.

Wähle die Gültigkeit des neuen Schlüssels und die Übergangsfrist: 7 Tage, 30 Tage oder Sofort

Während der Übergangsfrist funktionieren beide Schlüssel. Danach läuft der bisherige Schlüssel automatisch ab, du musst ihn nicht widerrufen. Unter der Auswahl steht, an welchem Tag das passiert. Mit Sofort wird er direkt widerrufen.

Klicke auf Schlüssel ersetzen, kopiere den neuen Schlüssel und trage ihn im angebundenen System ein

API-Schlüssel ersetzen mit ÜbergangsfristAPI-Schlüssel ersetzen mit Übergangsfrist

  • Die Übergangsfrist verlängert den bisherigen Schlüssel nicht. Läuft er vorher ab, endet sie an seinem Ablaufdatum.
  • Sind bereits 10 Schlüssel aktiv, ist nur Sofort möglich. Eine Übergangsfrist würde vorübergehend einen elften aktiven Schlüssel benötigen.
  • Wurde der bisherige Schlüssel noch nie verwendet, bringt eine Übergangsfrist nichts. Widerrufe ihn dann besser und erstelle einen neuen.
  • Bis zum Ende der Übergangsfrist zeigt die Übersicht Schlüsselwechsel läuft. Solange der neue Schlüssel noch nicht verwendet wurde, steht dort Schlüsselwechsel offen.

14 und 3 Tage vor dem Ablauf eines Schlüssels erhalten alle Mitglieder mit der Berechtigung Organisation verwalten eine Erinnerung per E-Mail. Wurde schon ein neuer Schlüssel erstellt, sagt die E-Mail, ob er bereits verwendet wird oder noch im angebundenen System eingetragen werden muss.

API-Schlüssel widerrufen

Klicke beim Schlüssel auf Schlüssel widerrufen und bestätige. Der Zugang wird sofort und dauerhaft entzogen, Anfragen mit diesem Schlüssel werden ab sofort abgewiesen. Ein widerrufener Schlüssel lässt sich nicht wiederherstellen.

Bereits abgerechnete Buchungen bleiben unverändert und behalten den Vermerk auf den widerrufenen Schlüssel.

Häufige Fragen

Welche Daten kann ein angebundenes System ändern?

Nur, was die Berechtigungen des Schlüssels erlauben: Kunden, Projekte und Stundensätze anlegen und ändern sowie Zeitbuchungen als abgerechnet markieren. Zeitbuchungen selbst kann ein System weder anlegen noch ändern oder löschen.

Die Anfragen meines Systems werden abgewiesen. Was kann ich tun?

  • Prüfe unter Einstellungen → Funktionen, ob die Integrations-API aktiviert ist
  • Prüfe unter API-Schlüssel verwalten, ob der Schlüssel abgelaufen oder widerrufen ist, und ersetze ihn gegebenenfalls
  • Prüfe, ob der Schlüssel die benötigte Berechtigung hat
  • Prüfe, ob das System den Schlüssel im Header Authorization: Bearer <Schlüssel> mitschickt

Ich habe den Schlüssel nicht gespeichert. Kann ich ihn erneut anzeigen?

Nein, der Schlüssel wird aus Sicherheitsgründen nur einmal angezeigt. Ersetze ihn durch einen neuen.

Was tue ich, wenn ein Schlüssel in falsche Hände geraten ist?

Widerrufe ihn sofort. Soll das System weiterlaufen, ersetze ihn stattdessen mit der Übergangsfrist Sofort.

Zuletzt aktualisiert

Auf dieser Seite