TANSS-API: Daten auslesen — und was in der Referenz nicht steht

Inhalt in Kürze

• Die TANSS-API ist groß und gut dokumentiert — ein offener MCP-Server bildet nach eigener Angabe 238 Endpunkte ab. Was die Referenz nicht beantwortet, ist die Frage nach dem richtigen Weg für den jeweiligen Zweck.
• Die Anmeldung ist die erste Hürde: TANSS nutzt einen eigenen Header statt Authorization, und es gibt zwei Token-Arten mit unterschiedlichen Rechten und Laufzeiten.
• Für Auswertungen über Monate ist die Datenbank der bessere Weg, für einzelne Vorgänge und jeden Schreibzugriff die API. Wir nutzen beides — und zwar bewusst getrennt.
• Sechs Eigenheiten kosten jeden, der neu anfängt, ein bis zwei Tage. Sie stehen weiter unten, damit sie niemanden mehr kosten.

TANSS ist im deutschen Mittelstands-Channel weit verbreitet — in den Verbünden, in denen sich inhabergeführte Häuser organisieren, gehört es zum Standardwerkzeug (Marktüberblick: IT-Systemhäuser in Deutschland).

Wer ein Systemhaus mit TANSS betreibt, kommt irgendwann an den Punkt, an dem die Oberfläche nicht mehr reicht: ein Report, den es so nicht gibt, ein Ticket, das automatisch entstehen soll, eine Zahl fürs Monatsgespräch. Dann steht die Frage im Raum, wie man an die eigenen Daten kommt.

Die Antwort lautet nicht „API” und auch nicht „Datenbank”. Sie lautet: beides, aber für verschiedene Aufgaben. Dieser Beitrag beschreibt, welcher Weg wofür taugt — und die Stolperstellen, die wir beim Bauen unserer eigenen Anbindung gefunden haben.

Zwei Wege aus TANSS heraus

TANSS ist ein ITSM-System für IT-Dienstleister — Ticketing, Zeiterfassung, Dokumentation, Assets. Beide Zugänge zu diesen Daten haben ein klares Profil.

Der entscheidende Satz dahinter: Eine API ist für Vorgänge gebaut, eine Datenbank für Mengen. Wer eine Jahresauswertung über die API zusammensetzt, macht aus einer Abfrage zehntausende — und wer ein Ticket per SQL anlegt, umgeht sämtliche Prüfungen, die das System aus gutem Grund hat.

Bei uns läuft es deshalb geteilt: Die Disposition schreibt und liest über die API, die betriebswirtschaftliche Auswertung liest über die Datenbank.

Die Anmeldung: zwei Modi, zwei Header, zwei Rechtestufen

Hier verlieren die meisten den ersten halben Tag. TANSS verwendet nicht den üblichen Authorization-Header, sondern einen eigenen — und welcher es ist, hängt vom Anmeldeweg ab.

Die beiden Modi unterscheiden sich nicht nur im Header, sondern in dem, was sie dürfen:

• API-Token: dauerhaft gültig, kein Ablauf, aber in den Rechten beschnitten. Leistungen (Supports) lassen sich damit nicht anlegen.
• Employee-Login: läuft unter einem echten Mitarbeiterkonto, volle Rechte auf Tickets und Leistungen — dafür begrenzt gültig. Der Token hält rund vier Stunden, der Refresh-Token rund fünf Tage.
• Zweiter Faktor: Ist für das Konto eine Einmalkennung aktiv, verlangt der Login sie auch beim maschinellen Zugriff. Das gehört in die Planung, nicht in die Fehlersuche.

Praktisch heißt das: Wer beide Wege braucht, baut eine kleine Automatik, die je Endpunkt den passenden Token wählt und den Employee-Token erneuert, bevor er abläuft. Vier Stunden klingen lang — bis der erste Nachtlauf um 03:00 Uhr an einem Token scheitert, der um 01:30 Uhr ausgelaufen ist.

Dass dieses Muster kein Einzelfall ist, zeigt der offene TANSS-MCP-Server von pronet systems: Er bildet nach eigener Angabe 238 Endpunkte ab, weist ausdrücklich auf den abweichenden Header hin und arbeitet mit sechs rollenspezifischen Token-Arten — unter anderem für ERP, Telefonie, Fernwartung und Monitoring. Die offizielle Referenz steht unter api-doc.tanss.de.

Sechs Eigenheiten, die einen Tag kosten können

Nichts davon ist ein Fehler im System. Es sind Entwurfsentscheidungen, die man kennen muss, weil sie von dem abweichen, was man erwartet.

1. Die Suche ist ein PUT. PUT /api/v1/search ändert nichts, die Parameter gehen als JSON-Body mit. Wer seine eigene Schutzschicht so baut, dass alle PUT-Aufrufe als schreibend gelten, sperrt sich die Suche selbst aus.
2. Ein PUT, das nur liest. Die Geräteliste wird ebenfalls per PUT abgefragt. Die HTTP-Methode taugt bei dieser API also nicht als Unterscheidung zwischen Lesen und Schreiben — man braucht eine Liste je Endpunkt.
3. Ein POST, das nur nachschlägt. Die Anrufererkennung löst eine Rufnummer zu Firma und Kontakt auf und speichert nichts; die Antwort trägt die Kennung 0. Ohne den Zusatz zum Nachschlagen legt derselbe Bereich aber einen echten Anruf an. Ein Buchstabe Unterschied im Pfad, ein großer Unterschied im Ergebnis.
4. Jede Antwort steckt in einem Umschlag. Zurück kommt ein Objekt mit meta und content. Die Nutzdaten liegen unter content — wer die Antwort direkt weiterverarbeitet, bekommt Metadaten statt Inhalt.
5. Der Ticketstatus heißt nicht so, wie man ihn nennt. Das Feld ist statusId, nicht ticketState. Ein Tippfehler, der in der Oberfläche nie auffällt, weil dort ein Wort steht und keine Kennung.
6. 403 ist beim Ticketschließen meistens kein Rechteproblem. TANSS lehnt das Schließen ab, wenn Checklisten, Termine oder Unter-Tickets offen sind, und liefert dafür sprechende Codes. Das ist eine Geschäftsregel, kein Defekt — wer beides gleich behandelt, versucht es täglich erneut und übersieht im Rauschen die echten Fehler.

Warum wir Auswertungen trotzdem aus der Datenbank lesen

Für die Frage „Wie viele Vorgänge kamen im Mai herein, wie viele gingen hinaus, und wie alt ist der Rückstau?” ist die API der falsche Weg. Nicht weil sie es nicht könnte, sondern weil sie jeden Vorgang einzeln herausgibt und die Rechnerei damit auf der eigenen Seite landet.

Eine Aggregation gehört dorthin, wo die Daten liegen. Ein einziger lesender Zugriff auf die TANSS-Datenbank liefert dieselbe Auswertung in Sekunden — und zwar für alle Monate auf einmal, was für Zeitreihen der eigentliche Punkt ist.

Der Preis dafür ist Verantwortung, und die haben wir doppelt abgesichert:

• Ein eigener Datenbankbenutzer mit reinem Leserecht. Die Beschränkung liegt auf der Datenbank, nicht im Code — ein Programmierfehler kann sie damit nicht aufheben.
• Eine zweite Prüfung im Code: Jede abgesetzte Anweisung muss mit SELECT beginnen, sonst bricht der Aufruf ab, bevor er die Verbindung erreicht.
• Kein Schreibweg, auch kein versehentlicher. Alles, was etwas verändert, läuft ausschließlich über die API und damit durch die Prüfungen von TANSS.
• Feste Verbindungsgrenze, damit eine Auswertung dem Produktivsystem nie Luft nimmt.

Was so eine Automatisierung am Ende wert ist, hängt weniger an der Technik als an der Zeit, die vorher von Hand verging — dazu haben wir die Rechnung in Automatisierung im Mittelstand: was sie kostet und was sie bringt aufgeschrieben.

Der wunde Punkt dieses Wegs ist ehrlich zu benennen: Ein Datenbankschema ist keine zugesagte Schnittstelle. Es kann sich mit einem Update ändern, und dann bricht die Auswertung. Deshalb liegt bei uns alles, was zugesichert funktionieren muss, auf der API — und nur die Auswertung auf der Datenbank, wo ein Bruch auffällt, aber nichts kaputt macht.

Aus der Praxis

Wir haben ein halbes Jahr lang versucht, alles über die API zu lösen, weil das der saubere Weg schien. Am Ende war die Auswertung langsam und der Code kompliziert. Die Trennung — schreiben über die Schnittstelle, auswerten über die Datenbank — hat beides gelöst und war in zwei Tagen gebaut.

Jens HagelInhaber, hagel IT-Services GmbH

Was danach möglich wird

Sobald beide Wege stehen, ändert sich nicht die Technik, sondern das Gespräch. Aus „gefühlt läuft viel” wird eine Zahl, die man neben eine andere legen kann.

Bei uns sind daraus drei Auswertungen geworden, die vorher niemand hatte: Zulauf gegen Durchsatz je Monat, der Rückstau nach Alter statt nach Menge — und, in Verbindung mit dem ERP, der Ertrag je Kunde neben dem Aufwand, den dieser Kunde erzeugt. Wie das zusammenhängt, steht in unserem Beitrag Sieben Systeme, eine Zahl.

Wer das nicht selbst bauen will: Genau diese Verbindung leistet Yupana im Systemhaus-Controlling — angeboten von der frag.hugo Informationssicherheit GmbH, bei uns im eigenen Haus im Einsatz.

Wenn Sie so etwas nicht selbst betreiben wollen

Schnittstellen zu bauen ist das eine, sie über Jahre am Laufen zu halten das andere — Token laufen ab, Systeme werden aktualisiert, und irgendwann ist der Kollege weg, der es gebaut hat. Genau diese Dauerverantwortung übernehmen wir für unsere Kunden im Rahmen der Managed IT-Services aus Hamburg. Unternehmen mit eigener IT-Mannschaft arbeiten mit uns im Co-Managed-Modell, bei dem die Schnittstellenpflege bei uns liegt und die Fachentscheidungen bei Ihnen.

Bevor etwas gebaut wird, steht bei uns immer die IT-Bestandsaufnahme — welche Systeme reden schon miteinander, und wo lohnt sich eine Verbindung überhaupt.

Fazit: Nicht ein Weg, sondern zwei mit klarer Aufgabe

Die TANSS-API ist umfangreich und offen dokumentiert. Ihre Eigenheiten sind kein Mangel, sondern eine Lernkurve — und die lässt sich abkürzen, wenn jemand die sechs Punkte oben vorher nennt.

Für alles, was etwas verändert, ist die API der einzige richtige Weg, weil sie die Regeln des Systems mitbringt. Für Auswertungen über Monate ist ein lesender Datenbankzugriff die ehrlichere Antwort. Wer beides trennt, bekommt eine Anbindung, die schnell ist und trotzdem nichts kaputt machen kann.

Wir betreuen aus der Spaldingstraße in der City Süd mittelständische Unternehmen in Hamburg und Norddeutschland — mehr dazu als IT-Systemhaus Hamburg, über uns und über den Verbund auch als IT-Dienstleister in Bremen.

Häufige Fragen (FAQ)

Wie authentifiziert man sich an der TANSS-API?

Über einen eigenen Header, nicht über den üblichen Authorization-Header. Es gibt zwei Modi: einen dauerhaften API-Token, der als Header apiKey mitgeschickt wird, und einen Employee-Login, dessen Token als apiToken geht. Der Employee-Token ist rund vier Stunden gültig, der zugehörige Refresh-Token rund fünf Tage.

Was ist der Unterschied zwischen API-Token und Employee-Login bei TANSS?

Der API-Token ist dauerhaft, aber in den Rechten beschnitten — Leistungen (Supports) lassen sich damit nicht anlegen. Der Employee-Login läuft unter einem echten Mitarbeiterkonto, hat volle Rechte auf Tickets und Leistungen und muss regelmäßig erneuert werden. Wer beides mischt, braucht eine Automatik, die je Endpunkt den passenden Token wählt.

Warum ist die Suche in der TANSS-API ein PUT-Request?

Weil die Suchparameter als JSON-Body übergeben werden und der Endpunkt so entworfen wurde. Fachlich ändert die Suche nichts. Für die eigene Absicherung heißt das: Eine Whitelist, die einfach alle PUT-Aufrufe als schreibend behandelt, sperrt die Suche mit aus.

Sollte man TANSS-Daten über die API oder direkt aus der Datenbank lesen?

Beides, je nach Zweck. Für einzelne Vorgänge, für Schreibzugriffe und für alles, was TANSS-Geschäftsregeln beachten muss, ist die API der richtige Weg. Für Auswertungen über Monate — Zulauf, Durchsatz, Rückstau, Stunden je Abteilung — ist ein lesender Datenbankzugriff um Größenordnungen effizienter, weil die Aggregation dorthin gehört, wo die Daten liegen.

Ist ein direkter Datenbankzugriff auf TANSS gefährlich?

Schreibend ja, lesend nicht — vorausgesetzt, die Beschränkung liegt auf der Datenbank und nicht nur im eigenen Code. Wir vergeben dafür einen eigenen Benutzer mit reinem Leserecht und prüfen im Code zusätzlich, dass jede abgesetzte Anweisung mit SELECT beginnt. Zwei Schlösser, weil eines irgendwann jemand aufmacht.

Was bedeutet ein HTTP 403 beim Schließen eines TANSS-Tickets?

Meistens kein Rechteproblem, sondern eine Geschäftsregel: offene Checklisten, offene Termine oder offene Unter-Tickets verhindern das Schließen. TANSS liefert dafür sprechende Codes wie OPEN_CHECKLISTS_EXIST. Wer diese Fälle als Systemfehler behandelt, wiederholt sie täglich erfolglos und übersieht die echten Defekte im Protokoll.

Weiterführende Quellen

• TANSS API Reference — die offizielle Endpunkt-Übersicht
• TANSS MCP Server (pronet systems) — 238 Endpunkte, mit Hinweisen zu Header und Token-Rollen
• TANSS Module und Schnittstellen — Herstellerübersicht der offenen Schnittstellen