Tripletex-Schnittstelle und API-Integration
Tripletex ist eine norwegische Cloud-Buchhaltungsplattform, die von Einzelunternehmern bis zu mittelständischen Firmen eingesetzt wird, mit eigener API und eigenem Entwicklerprogramm. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Eine Tripletex-Anbindung in Tagen
Tripletex ist gut dokumentiert, und drei seiner Eigenheiten landen bei Ihren Entwicklern, bevor etwas Nützliches passiert. Hier stehen sie, und hier steht, was Maesn davon abnimmt.
Das Session-Token wird hier verwahrt
Tripletex verbindet zwei Tokens zu einem dritten: ein Consumer-Token, das Ihre Integration ausweist, und ein Employee-Token, das Ihr Kunde in seinem eigenen Tripletex erzeugt. Zusammen ergeben sie ein Session-Token, und das ist es, was jeder spätere Aufruf tatsächlich trägt, und es wird mit einem Ablaufdatum erzeugt und nicht mit einer Laufzeit. Maesn leitet es ab und leitet ein neues ab, wenn es abgelaufen ist.
Die Zeilennummerierung passiert hier
Einen Buchungssatz in Tripletex zu aktualisieren läuft für bestehende Zeilen über die ID, aber eine Zeile, die Sie hinzufügen, hat noch keine ID und muss stattdessen ihre Zeilennummer tragen. Maesn hat kein Zeilenfeld, das es Ihnen geben könnte, und eines zu erfinden würde diese Buchführung in Ihr Schema schieben. Also liest Maesn vor der Aktualisierung den Buchungssatz, nimmt die bereits belegten Zeilen und nummeriert die neue Zeile selbst. Ihr Code sendet einfach die Zeile.
Einmal aufgelöst, beim Verbinden
Jede Anfrage muss sagen, zu welcher Firma sie gehört, und Tripletex entnimmt das dem Benutzernamen, mit dem Sie sich anmelden, und nicht der Anfrage. Ein Mitarbeiter, der null oder gar nichts sendet, erreicht die eigene Firma. Ein Buchhalter sendet die Firmen-ID eines Mandanten und muss wissen, welche Mandanten er erreichen darf. Maesn klärt das beim Anlegen der Verbindung. Ihre Anfragen tragen also einen Account-Key und nie eine Firma.
Auf Ihrer Seite bleibt ein REST-Aufruf gegen ein Datenmodell, das Sie einmal implementieren. Ein norwegischer Kunde ist kein Grund mehr, ein zweites Projekt zu eröffnen.
Der zweite der drei ist der, der Leute überrascht, weil nichts daran nach einem Problem aussieht, bis die erste Aktualisierung fehlschlägt. Eine Zeile zu einem bestehenden Buchungssatz hinzuzufügen wird nicht so adressiert wie der Rest des Objekts: Bestehende Zeilen werden über ihre ID gefunden, aber eine Zeile, die es noch nicht gibt, muss ankündigen, welche Position sie einnehmen wird. Maesn liest den Buchungssatz, sieht, welche Positionen belegt sind, und nummeriert die neue, bevor der Schreibzugriff hinausgeht, diese Logik erreicht Ihren Code also nie. Wenn später doch etwas schiefgeht, bedeutet ein Fehlermodell über den ganzen Katalog einen Status und einen Body zum Auslesen, Tripletex gehört also in Ihr Support-Runbook und nicht in eine Verzweigung in Ihrem Client.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Drei Gründe, die Tripletex-Schnittstelle über Maesn anzubinden
Tripletex direkt anzubinden ist ein Projekt, das ein guter Entwickler abschließen kann. Seinen Austausch zweier Tokens ein Jahr lang zu halten, seine Zeilennummerierung bei jedem Schreibzugriff korrekt zu halten und dann dasselbe für das nächste System noch einmal zu tun, entscheidet über Ihre Roadmap.
Die Tripletex-Arbeit bleibt hier
Der Tausch der zwei Tokens, die Session, die mit einem Ablaufdatum erzeugt wird, der Buchhalter, der eine Firma wählen muss, und die Zeilennummerierung bei jeder Aktualisierung eines Buchungssatzes sind das, was jede Tripletex-Integration lösen muss. Gelöst wird es einmal, hier, für jeden Kunden, den Sie anbinden.
Heute live, Lesen und Schreiben
Konten, Buchungssätze und Steuersätze sind auf der Verbindung lesbar, und Buchungssätze lassen sich darüber anlegen und aktualisieren. Das ist ein funktionierender Buchungsweg und keine reine Lesesicht. Der Rest des Katalogs ist auf Anfrage verfügbar, sagen Sie uns also, was Ihr Anwendungsfall braucht, und wir bestätigen es, bevor Sie bauen.
Das nächste System kostet nichts
Sobald Tripletex läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle, mit demselben Datenmodell dahinter und denselben zwei Headern davor. Ihre zweite Integration ist ein Konfigurationsschritt, und Ihre Entwickler verwenden wieder, was sie hier gelernt haben.
Zwei Tripletex-Tokens, und die eine Session daraus
Tripletex authentifiziert mit einem Token, das Ihr Kunde hält, und einem Token, das Sie halten, zusammengeführt zu einem Session-Token, das jeden späteren Aufruf trägt. Maesn übernimmt das Zusammenführen. Vor dem Entwurf Ihres Onboardings sollten Sie wissen, dass Tripletex eine Einzelfirma und eine Kanzlei unterschiedlich behandelt, und dass dieser Unterschied bis in die Anfrage selbst reicht.
- Zwei Tokens, zu einer Session verbunden
- Headless oder interaktiv
Eine Implementierung, und der Kanzleifall gehört dazu.
- Einzelfirma oder Kanzlei
- Tripletex hat zwei davon, und der Unterschied ist nicht kosmetisch. Ein Mitarbeiter meldet sich an und ist immer in einer Firma. Ein Buchhalter erreicht viele. Eine davon muss also gewählt werden, und Tripletex veröffentlicht einen eigenen Aufruf, der die Firmen auflistet, die eine Anmeldung benutzen darf. Maesn macht diesen Aufruf und klärt die Wahl, während die Verbindung entsteht, der Fall mit mehreren Gesellschaften kostet Sie also eine Entscheidung beim Onboarding und keinen Codepfad.
- Zwei Wege, das Token einzusammeln
- Weil das Employee-Token ein Wert ist, den Ihr Kunde bereits hat, steht Tripletex auf beiden unserer Authentifizierungswege. Sie können ihn auf eine Maesn-Seite schicken, die danach fragt, oder Sie fragen in Ihrem eigenen Produkt danach und geben es direkt an die API, die den Account-Key zurückgibt, ohne eine Seite von uns dazwischen. Der zweite Weg hält Ihr Onboarding vollständig in Ihrer eigenen Oberfläche.
Das Session-Token hinter all dem wird mit einem Ablaufdatum erzeugt. Es ist also von Haus aus endlich und nicht durch Entzug. Maesn leitet ein neues ab, wenn es abläuft, und deshalb ändert sich der Account-Key, den Sie halten, dabei nicht.
- 1
Ihr Kunde gibt sein Employee-Token ein
Er erzeugt es in seinem eigenen Tripletex unter den Benutzereinstellungen und dem API-Zugang und gibt es entweder auf einer Maesn-Seite oder in Ihrem Produkt ein. Es ist ein Wert, und ein Passwort von ihm kommt an keiner Stelle des Austauschs vor.
- 2
Maesn verbindet es mit Ihrem Consumer-Token
Ihr Consumer-Token ist auf Ihrem Mandanten bereits eingerichtet. Die beiden treffen sich also auf unserer Seite und ergeben das Session-Token, das Tripletex erwartet. Ihr Consumer-Token läuft nie durch Ihr Frontend, und Ihr Kunde sieht es nie.
- 3
Sie arbeiten mit einem Account-Key
Maesn speichert die Verbindung und gibt einen Account-Key zurück. Ab da trägt jede Anfrage Ihren API-Schlüssel und diesen Account-Key, dieselben zwei Header, die Sie für jedes andere System im Katalog ohnehin schon senden.
Es lohnt sich, konkret zu benennen, wer was hält, denn die Aufteilung ist ungewöhnlich. Ihr Consumer-Token gehört Ihnen und weist Ihr Produkt bei Tripletex über jeden Kunden hinweg aus, den Sie anbinden. Das Employee-Token gehört dem Kunden, entsteht in dessen eigenem Tripletex und wird nie Ihres. Das Session-Token, das den Verkehr tatsächlich trägt, existiert nur, weil beide vorlagen, und es wird mit einem Ablaufdatum erzeugt und nicht mit einer Laufzeit. Unified Authentication macht daraus eine Einzelheit statt eines Entwurfsproblems: Der Austausch, die Session und der Account-Key verhalten sich hier genauso wie bei einem System mit einfachem Redirect, Ihr Produkt sieht also über jedes System hinweg, das es erreicht, dieselbe Anbindung.
Was eine Tripletex-Verbindung vorab verlangt
Tripletex stellt drei Dinge vor eine Integration, und nur eines davon müssen Sie mehr als einmal tun.
- Ihr eigenes Consumer-Token, einmal
- Tripletex stellt ein Consumer-Token je Integration aus und nicht je Kunde, und Ihres ist das, was Ihr Produkt über alle hinweg ausweist. Sie beantragen es bei Tripletex und übergeben es uns einmal, und wir richten es auf Ihrem Mandanten ein. Nichts an diesem Schritt wiederholt sich je Kunde.
- Eine Testumgebung, die schnell kommt
- Tripletex betreibt eine eigene Testumgebung mit eigenen Consumer- und Employee-Tokens, und unsere kam schnell zurück, zusammen mit einer Testanmeldung. Maesn erreicht sie als eigenes Zielsystem, Sie können also dagegen bauen und testen, bevor ein echter Kunde beteiligt ist.
- Das Employee-Token Ihres Kunden, mit seinen Berechtigungen
- Jeder Kunde erzeugt sein eigenes Employee-Token in Tripletex unter den Benutzereinstellungen und dem API-Zugang, und dafür braucht es auf seiner Seite einen Administrator. Tripletex erwartet, dass diesem Token beim Erzeugen ein Satz Berechtigungen mitgegeben wird. Es lohnt sich also, Ihrem Kunden vorher zu sagen, welche Daten Sie lesen werden. Dieses Token ist der eine Wert, den er beim Verbinden eingibt, und es bleibt seines.
Wir gehen das Consumer-Token und die Objektliste mit Ihnen durch, bevor Sie mit dem Bauen anfangen.
Eine Tripletex-Buchung kommt in einer gemeinsamen Form
Tripletex trägt seine Buchungszeilen als Array am Buchungssatz, zählt in einem Feld, das es abkündigt, und führt neben der Währung, in der Sie gebucht haben, immer einen norwegischen Betrag mit. Alle drei reichen bis in Ihr Schema, es hilft also, sie zu kennen, bevor Sie etwas abbilden.
Die Gesamtzahl wird abgekündigt
Tripletex paginiert von sich aus, und sein Antwortumschlag trägt weiterhin ein Feld für die Größe des gesamten Ergebnisses, in der eigenen Dokumentation als veraltet gekennzeichnet. Am Konten-Endpunkt haben unsere Entwickler überhaupt keine Gesamtzahl zurückbekommen. Maesn paginiert diesen Lesezugriff selbst, statt einer Zahl zu vertrauen, die abgekündigt wird. Sie bekommen also in jedem Fall eine vollständige Liste.
Jeder Buchungssatz hat eine norwegische Seite
Tripletex bucht unter jeder von Ihnen gewählten Währung in norwegischen Kronen und zeigt beides. Die praktische Folge liegt auf dem Hinweg und nicht auf dem Rückweg: Einen Buchungssatz in Euro oder Dollar zu buchen heißt, einen Wechselkurs mitzusenden, denn das System muss diesen Buchungssatz auch in Kronen ausdrücken, bevor es ihn annimmt.
Was Sie lesen, kommt im gemeinsamen Common Data Model zurück, ein Buchungssatz aus Tripletex hat also dieselbe Form wie einer aus einem zehnmal so großen System, und der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden. Tripletex macht diese Abbildung leichter als die meisten: Sein Buchungssatz trägt seine Buchungszeilen als Array am Objekt, und das kommt dem nahe, wie das gemeinsame Modell einen ohnehin beschreibt. Ein langes Hauptbuch zu lesen nutzt dasselbe Paging und Filtern wie jedes andere System im Katalog, die Schleife auf Tripletex ist also die, die Sie schon geschrieben haben.
Was bis in Ihr Schema reicht, ist die Währung. Tripletex drückt jeden Buchungssatz unter der von Ihnen gewählten Währung zusätzlich in norwegischen Kronen aus und zeigt beide, in Euro oder Dollar zu buchen ist also nicht vollständig ohne einen Wechselkurs dazu. Das ist eine Entscheidung über Ihre eigenen Daten, bevor es eine Abbildungsfrage ist, und es ist dieselbe Entscheidung, ob Sie Tripletex über uns erreichen oder direkt. Innerhalb der Visma-Gruppe ist es auch das, was dieses System am stärksten von seinen Geschwistern auf der Visma-Integrationsübersicht unterscheidet.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
