Twinfield-Schnittstelle und API-Integration
Twinfield ist die Cloud-Buchhaltungsplattform von Wolters Kluwer, und sie ist um die Kanzlei herum gebaut statt um das einzelne Unternehmen: eine Anmeldung, viele Mandanten. Sie ist in den Niederlanden, Belgien, Luxemburg und UK weit verbreitet und bedient außerdem Deutschland und Frankreich. Binden Sie sie über Maesn an, und Sie erreichen sie mit derselben REST API und demselben Datenmodell wie jedes andere unterstützte System.
Twinfield spricht SOAP, über alle siebzehn Services
Drei Dinge an Twinfield landen bei Ihren Entwicklern, bevor sich der erste Datensatz bewegt: Das Protokoll ist SOAP, die Adresse hängt davon ab, auf welchem Cluster Ihr Kunde sitzt, und jede Anfrage muss eine Firma nennen. Hier steht, was jedes davon ist, und was Maesn davon abnimmt.
Eine REST-Schnittstelle über sie alle
Twinfield veröffentlicht siebzehn SOAP-Webservices, jeden mit eigener WSDL, und leitet die meiste Arbeit an Datensätzen über einen einzigen Sammelaufruf namens ProcessXml, der siebenundzwanzig verschiedene XML-Wurzelelemente annimmt. Maesn baut und liest dieses XML intern. Ihr Code sendet also eine JSON-Anfrage gegen dieselbe Schnittstelle, die Sie für jedes andere System benutzen.
Der Cluster, einmal je Mandant aufgelöst
Twinfield hostet Organisationen auf Clustern, und die Adresse des richtigen steht nicht im Token. Sie schicken das Access-Token an einen eigenen Validierungsendpunkt, lesen twf.clusterUrl aus der Antwort und benutzen sie für alles Weitere. Maesn erledigt das beim Onboarding und leitet jede Anfrage je Kunde an den richtigen Cluster.
Der CompanyCode einmal gesetzt und eingefügt
Die Dokumentation von Twinfield kennzeichnet ihn als Pflicht: Der SOAP-Header trägt neben dem Access-Token einen CompanyCode. Maesn legt diese Wahl in den Verbindungsablauf, in dem Ihr Kunde die Firma einmal auswählt, und fügt sie von da an in jede Anfrage ein. Keine Header-Logik in Twinfield-Form erreicht Ihre Seite.
In Ihrem Code kommen ein REST-Aufruf und ein Account-Key an. Der SOAP-Umschlag, die Cluster-Abfrage und der Firmen-Header bleiben hier, und das nächste System, das Sie hinzunehmen, antwortet auf derselben Schnittstelle.
Ein kurzes Gespräch genügt meist, um zu klären, ob Maesn zu Ihrem Anwendungsfall passt.
Findity bettet den Ausgabenabgleich über Buchhaltungssysteme hinweg ein
Findity ist eine Plattform für die Ausgabenverwaltung, die White-Label- und API-Produkte ausliefert. Ihre Kunden erreichen Buchhaltungssysteme also über Findity statt direkt. Ausgaben sind eines der Objekte, die Twinfield in beide Richtungen anbietet, und damit ist das derselbe Weg und kein vergleichbarer.
“Maesn hat uns geholfen, Integrationen zu Buchhaltungssystemen zu bauen, und wir können uns dadurch auf andere Prioritäten in unserer Roadmap konzentrieren. Besonders schätzen wir die Unterstützung, die wir jedes Mal bekommen haben, wenn wir erweiterte Funktionen in einer Integration brauchten, die Maesn für uns eingerichtet hat.”
Drei Gründe, die Twinfield-Schnittstelle über Maesn anzubinden
Twinfield direkt anzubinden ist ein Protokollprojekt, bevor es ein Integrationsprojekt ist. Es danach am Leben zu halten heißt, das Cluster-Routing, den Firmen-Header und ein Anfragebudget in Credits statt in Aufrufen zu besitzen, für ein System in einer Region.
Die Twinfield-eigene Arbeit bleibt hier
Den Umschlag bauen und lesen, die Cluster-Abfrage nach der Authentifizierung, der CompanyCode in jedem Header und die Verrechnung der Credits hinter der Ratenbegrenzung. Maesn hält alle vier je Mandant, und keines davon erreicht den Code, den Sie schreiben.
Eine Verbindung erreicht jede Firma
Eine Twinfield-Anmeldung kann Dutzende Mandanten halten, und einen zu lesen oder alle zu lesen ist derselbe Aufruf mit einer anderen Firma. Maesn verwahrt die Wahl je Verbindung und lässt Sie je Anfrage eine andere nennen. Eine Kanzlei mit vielen Büchern ist damit ein Parameter und keine zweite Integration.
Das nächste System kostet nichts
Sobald Twinfield läuft, antwortet jedes andere unterstützte Buchhaltungs- und ERP-System auf derselben Schnittstelle mit demselben Datenmodell. Ihre zweite Integration ist ein Konfigurationsschritt und kein zweites Protokoll.
Ausgaben reichen hier weiter, als die Objektliste vermuten lässt, und sie bringen eine Grenze mit, um die herum sich planen lässt. Ausgaben sind lesbar und schreibbar, der Beleg dahinter nicht: Bei sechs der sieben Systeme, die eine Ausgabe annehmen, reist die Datei in derselben Anfrage mit, und Twinfield ist in der Dokumentation die Ausnahme. Wenn Ihr Produkt das Bild speichert, rechnen Sie damit, dass es auf Ihrer Seite bleibt. Ausgabenabgleich führt diesen Unterschied System für System auf.
Eingetragen im Twinfield-Marketplace
Die meisten Anbieter hören bei der API auf. Maesn übernimmt die technische Seite und die Beziehung, und bei Twinfield beginnt die zweite früher als sonst, denn es gibt kein kostenloses Konto, gegen das Sie bauen können, während Sie warten.
Technische Unterstützung
Eine Integration gegen die Unified API und ein Datenmodell, identisch zu jedem anderen System, das Maesn unterstützt. Ihre Entwickler treffen hier auf dieselbe Schnittstelle wie beim nächsten System.
Unterstützung bei der Partnerschaft
Maesn führt Sie durch das Partner-Onboarding bei Twinfield, von den technischen Anforderungen bis zur Qualifizierung, statt Ihnen ein Formular und einen Link zu geben.
Eine Qualifizierung statt eines Formulars
Twinfield führt für die Integrationen, die es listet, eine individuelle Qualifizierung durch. Vor sein Umfeld zu treten ist also ein Gespräch und kein Absende-Knopf. Maesn geht die Anforderungen und das Verfahren mit Ihnen durch.
Das Publikum sind Kanzleien, nicht nur Unternehmen
Twinfield sitzt bei Kanzleien, die für viele Mandanten gleichzeitig die Bücher führen, und ein Eintrag stellt Ihr Produkt vor diese Beziehung. Es lohnt sich zu wissen, welcher Seite Sie verkaufen, denn eine Kanzlei kauft anders als das Unternehmen, für das sie abrechnet.
Die Sandbox kommt vor der Partnerschaft
Twinfield veröffentlicht kein kostenloses Testkonto, und eine eigene Umgebung zu bekommen heißt, eine Instanz zu kaufen. Die Dokumentation von Maesn nennt Twinfield ausdrücklich unter den Systemen, für die sie eine Sandbox bereitstellt. Der Bau kann also beginnen, während das Partnergespräch noch läuft.
Die Integration läuft unter dem Namen Ihres Produkts, und der Partnerstatus gehört Ihnen und nicht uns. Maesn ist die Schicht dahinter.
Wir gehen die Twinfield-Anforderungen und die Qualifizierung mit Ihnen durch.
Ein eigener Twinfield-Client, eine Firma, einmal gewählt
Twinfield authentifiziert über OpenID Connect auf OAuth 2.0, und die Anwendung, die Ihre Kunden freigeben, ist Ihre und nicht die von Maesn. Es ist eines der Systeme, die den interaktiven Ablauf fahren, denn eine Twinfield-Anmeldung kann mehrere Firmen erreichen, und jede Anfrage muss sagen, welche sie meint.
- OpenID Connect auf OAuth 2.0
- Authorization-Code-Ablauf, mit einem Client, den Sie registrieren
Eine Integration, jeder Kunde. Maesn verwahrt die Zugangsdaten und führt Handshake, Cluster-Abfrage und Firmenauswahl dahinter aus.
- Ihre Client-Zugangsdaten
- Client-ID, Client Secret und Abonnementschlüssel werden einmal eingereicht und danach für jede Verbindung benutzt. Der Token-Tausch läuft also hier statt in Ihrem Backend. Was Ihr Code hält, ist ein Account-Key je Kunde.
- Cluster und Firma, einmal aufgelöst
- Wenn das Token angekommen ist, muss der Cluster noch abgefragt und die Firma noch gewählt werden. Maesn erledigt beides beim Onboarding und verwahrt es je Mandant. Adresse und Header stehen also vor Ihrem ersten Aufruf fest und nicht bei jedem.
Die Token-Laufzeiten von Twinfield sind ungewöhnlich und einen eigenen Entwurf wert: Ein Zugriffstoken lebt eine Stunde, und das Refresh-Token dahinter wird für 788.940.000 Sekunden ausgestellt, also für fünfundzwanzig Jahre. Es rotiert bei Benutzung nicht. Das Risiko verlagert sich damit vom Verlieren eines Tokens zum Aufbewahren eines Tokens, denn Zugangsdaten, die das Projekt überleben, muss jemand so lange sicher verwahren. Ein Refresh kann außerdem aus Gründen fehlschlagen, die nichts mit dem Token zu tun haben, denn ein gesperrter Nutzer oder ein abgelaufenes Passwort auf der Twinfield-Seite liefern denselben Fehler.
- 1
Ihr Kunde startet in Ihrem Produkt
Sie schicken ihn in den Ablauf, und Maesn öffnet die Anmeldung von Twinfield. Der Zustimmungsbildschirm trägt den Namen Ihrer Anwendung, denn der Client ist auf Ihr Unternehmen registriert. Die Verbindung liest sich also als Ihre und nicht als die eines Dritten.
- 2
Er wählt die Firma einmal
Ein Twinfield-Nutzer kann Zugriff auf mehrere Firmen haben, und die API rät nicht zwischen ihnen. Die Auswahlseite fragt einmal, und die Antwort gilt gespeichert für jede folgende Anfrage. Je Aufruf können Sie sie trotzdem überschreiben, wenn Ihr Produkt zwischen Gesellschaften wechseln muss.
- 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.
Jedes System im Katalog authentifiziert anders, und bei Twinfield ist das Token der leichte Teil und die beiden Werte darum herum nicht. Der Cluster muss nachgeschlagen werden, nachdem das Token angekommen ist, die Firma muss jemand wählen, der weiß, welche gemeint ist, und beide müssen danach bei jedem Aufruf dabei sein. Dafür ist Unified Authentication da. Die Auswahlseite, die Speicherung je Mandant und das Refresh werden einmal für alle Systeme erledigt und nicht einmal je System, was Ihr Code trägt, ist also ein Account-Key.
Twinfield sendet keine Events, also fragen Sie ab
Kein Twinfield-Objekt sendet heute ein Event über Maesn, und auch die eigene Liste der Webservices von Twinfield enthält keinen Push-Mechanismus. Jeder seiner siebzehn Services beantwortet eine Anfrage, die Sie stellen. Die Änderungserkennung ist damit etwas, das Sie fahren, und nicht etwas, das ankommt.
Überhaupt nichts, und das ist eine Eigenschaft der Plattform und nicht dessen, was hier freigeschaltet ist. Das Nächstliegende, was sie veröffentlicht, ist ein Webservice, der gelöschte Buchungen auflistet, und auch das ist ein Aufruf, den Sie machen.
Ein geplanter Lesezugriff, mit demselben Filter und derselben Paginierung, die Sie für jedes andere System benutzen. Der Code, der Änderungen auf Twinfield erkennt, ist der Code, den Sie bereits geschrieben haben, nur auf einen anderen Account-Key gerichtet.
Das Intervall ist hier eine Budgetentscheidung und nicht nur eine Produktentscheidung, und das ist ungewöhnlich. Twinfield berechnet einen Credit je Lesezugriff und drei je Schreibzugriff aus einem Kontingent von 500 pro Minute je Client und Organisation. Eine Abfrageschleife, die zu eng läuft, konkurriert also mit den Schreibzugriffen, die sie stützen soll. Sie einmal mit diesem Wissen zu dimensionieren ist billiger, als es unter Last zu entdecken.
Ein System ohne Events ist die Stelle, an der die Kosten einer Integration je System am deutlichsten sichtbar werden: Sie schreiben eine Schleife zur Änderungserkennung für Twinfield und dann noch eine für das nächste System, mit eigener Filtersyntax und einer eigenen Vorstellung davon, was eine Seite ist. Ein Weg, zu filtern und zu paginieren nimmt diese Art von Arbeit weg, und was Sie über das Event-Modell verarbeiten und was Sie nach Zeitplan abholen, bleiben zwei Wege, von denen bei Twinfield heute nur einer verfügbar ist.
Warum die Schleife sorgfältig zu dimensionieren ist, liegt an diesem System. Twinfield rechnet in Credits statt in Aufrufen, ein Lesezugriff im Minutentakt zehrt also von demselben Kontingent wie die Schreibzugriffe, für die er da ist, und die Antwort, wenn das Kontingent aufgebraucht ist, ist eine Ablehnung, die Sie behandeln müssen. Ein Fehlerkontrakt verhindert, dass daraus eine Twinfield-förmige Verzweigung in Ihrem Code wird, und Asynchronous Processing ist der Ort, an den die langlaufenden Lesezugriffe gehen, sobald ein einzelner Aufruf nicht mehr die richtige Form ist.
Was eine Twinfield-Anbindung zuerst braucht
Das meiste davon wird entschieden, bevor Code läuft, und zwei der vier Punkte sind von der Sorte, die eine Stunde später auftaucht statt sofort. Vier Dinge sollten geklärt sein, bevor Sie anfangen.
- Ein Twinfield-Client, in deren Entwicklerportal registriert
- Sie legen ihn unter Clients an, und der Name, den Sie vergeben, ist der Name, den Ihre Kunden auf dem Zustimmungsbildschirm lesen. Es sollte also der Ihres Produkts sein. Das Client Secret wird einmal angezeigt. Die Redirect-URL ist der Callback von Maesn für Twinfield, und genau deshalb passiert der Code-Tausch hier statt in Ihrem Backend.
- Ein drittes Zugangsdatum neben Client-ID und Secret
- Die Einrichtung bei Maesn verlangt neben den zwei OAuth-Zugangsdaten einen Abonnementschlüssel. Das sollten Sie früh ansprechen und nicht erst zum Start, denn es ist der eine Punkt auf dieser Liste, der nicht im selben Schritt wie die anderen aus dem Entwicklerportal kommt.
- Der Scope offline_access, sonst gar kein Refresh-Token
- Twinfield gibt ein Refresh-Token nur zurück, wenn die Autorisierungsanfrage offline_access verlangt hat, und der Scope twf.organisationUser ist überhaupt nötig, um sich anzumelden. Ein Client, der ohne den ersten registriert ist, funktioniert eine Stunde lang einwandfrei und hört dann auf, und das ist die Art Fehler, die im Produktivbetrieb auffällt und nicht im Test.
- Ein Budget in Credits statt in Anfragen
- Twinfield zählt API-Credits und keine Aufrufe, und das ist nicht dasselbe: Ein Lesezugriff kostet einen Credit, ein Schreibzugriff drei. Die bindende Obergrenze sind 500 Credits je Minute für einen Client gegen eine Organisation, und genau diese Form hat eine Kundenintegration. Lesen und Schreiben gehen aus demselben Kontingent.
Wir gehen die Client-Registrierung und die Zugangsdaten mit Ihnen durch.
Eine Form für das Hauptbuch und die analytische Achse
Twinfield ist für Kanzleien gebaut, die viele Buchhaltungen gleichzeitig führen. Eine Anbindung erreicht deshalb das Hauptbuch und dazu die Achse, über die sich die Zahlen eines Mandanten von denen des nächsten trennen lassen. Beides kommt in der Form an, die Sie bereits verarbeiten.
Alles, was Sie anlegen, lässt sich nicht aktualisieren
Kunden, Lieferanten, Ausgaben und Buchungssätze lassen sich anlegen. Für kein Objekt ist das Aktualisieren freigeschaltet. Eine Korrektur ist also ein neuer Datensatz und keine Änderung am alten. Planen Sie Korrekturen, bevor Sie den ersten Schreibzugriff planen.
Die analytischen Objekte sind das Ungewöhnliche
Dimensionen und Projekte sind hier beide lesbar, und diese Kombination gibt es auf einem weiteren System im Katalog. Das folgt daraus, wie Twinfield benutzt wird: Eine Kanzlei, die für viele Gesellschaften Bücher führt, braucht die analytische Achse und nicht nur das Hauptbuch.
Standardmäßig löscht kein Objekt
Für kein Objekt ist Löschen freigeschaltet. Die Buchhaltungspraxis erwartet Korrekturen und Stornos ohnehin als neue Belege, planen Sie sie also so und nicht um ein Löschen herum, das Sie erst anfragen müssten.
Das Interessante an diesem System ist nicht, wie viel es erreicht, sondern was. Neben den Hauptbuchobjekten liegen Dimensionen und Projekte, die analytische Achse, über die eine Kanzlei die Bücher eines Mandanten von denen des nächsten innerhalb derselben Plattform trennt. Das folgt daraus, wofür das System da ist, und es ist der Grund, warum ein Auswertungs- oder Planungsprodukt hier mehr findet, als eine Objektliste allein vermuten lässt.
Alles, was eine Anbindung liest, kommt im gemeinsamen Common Data Model zurück, ein Lieferant aus Twinfield hat also dieselbe Form wie ein Lieferant aus jedem anderen unterstützten System, und der Code, den Sie hier schreiben, ist der Code, den Sie für das nächste wiederverwenden. Das zählt mehr als sonst auf einer Plattform, die für viele Einheiten gleichzeitig gebaut ist: Eine Firma zu lesen und alle zu lesen ist derselbe Aufruf mit einer anderen Firma, und was zurückkommt zu konsolidieren ist ein eigenes Problem und kein Twinfield-Problem.
Die schreibbaren Objekte schneiden nur in eine Richtung. Kunden, Lieferanten, Ausgaben und Buchungssätze lassen sich anlegen und keines davon danach aktualisieren, eine Korrektur ist also ein zweiter Datensatz und keine Änderung. Was als auf Anfrage markiert ist, ist der Unterschied zwischen dem, was freigeschaltet ist, und dem, was die Plattform dokumentiert, und auf Anfrage heißt nicht standardmäßig eingeschaltet statt nicht verfügbar. Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, oder sehen Sie sich jedes System im Katalog an, um zu sehen, wie dieselbe Frage anderswo beantwortet wird.
Sagen Sie uns, welche Objekte Ihr Anwendungsfall braucht, und wir bestätigen, was möglich ist.
